feat(zoo-gateway): settings UI, validation, and i18n (#345)

* feat(zoo-gateway): add provider types, handler, and model fetcher

Co-authored-by: Cursor <cursoragent@cursor.com>

* fix(zoo-gateway): respect readonly client, real version header, safer fetch

- Stop reassigning RouterProvider.client; thread Zoo enrichment headers
  through openAiHeaders so a single OpenAI client is used.
- Replace npm_package_version (never populated at extension runtime)
  with Package.version from the shared package shim.
- Default the model list to [] on a structurally broken response so we
  log and recover instead of crashing on response.data.data being
  undefined.
- Bypass inFlightRefresh de-duplication for zoo-gateway: a refresh
  triggered after sign-out/sign-in must not return the previous user's
  in-flight response.
- Add fetcher unit tests covering auth header, timeout, error
  redaction, and bad-response handling.

Co-authored-by: Cursor <cursoragent@cursor.com>

* test(zoo-gateway): mock cached-token + clear-token auth helpers

The downstream stack (settings-ui) calls getCachedZooCodeToken and
clearZooCodeToken from the auth handler. CI on stacked PRs merges base
into head so this spec runs against the cached-token-aware handler;
expand the auth module mock so the auth guard test exercises the real
throw path instead of vitest's missing-mock-export error.

Co-authored-by: Cursor <cursoragent@cursor.com>

* feat(zoo-gateway): add settings UI, validation, and i18n

Co-authored-by: Cursor <cursoragent@cursor.com>

* fix(zoo-gateway): dynamic dashboard URL and cached-token fallback

- Resolve ModelPicker serviceUrl from zooCodeBaseUrl so staging/dev
  environments link to the matching dashboard.
- Fall back to getCachedZooCodeToken() in the handler and model fetcher
  when the profile has not been seeded yet (auth before webview open).

Co-authored-by: Cursor <cursoragent@cursor.com>

* fix(deps): drop stale webview-ui package.json drift that broke frozen-lockfile installs

Co-authored-by: Cursor <cursoragent@cursor.com>

* fix(i18n): restore googleCloudCredentialsPathWarning and automaticFetch 'free' search hint dropped on rebase

Co-authored-by: Cursor <cursoragent@cursor.com>

* fix(zoo-gateway): pick default model from fetched list, prefer Sonnet 4.5

Resolves Sonnet 4.5 from the gateway model catalog instead of a static Vercel slug so test (Bedrock) and live accounts both get a valid default. Reassigns stale profile model IDs when they are not in the catalog.

Co-authored-by: Cursor <cursoragent@cursor.com>

* test(zoo-gateway): cover dynamic default model picker for codecov patch

Exports pickZooGatewayDefaultModelId so the helper is unit-testable and adds
component tests for the auto-default useEffect (no-op while catalog loads,
auto-pick on empty profile, repair stale id, no-op when valid).

Co-authored-by: Cursor <cursoragent@cursor.com>

* fix(i18n): restore UTF-8 for Google Cloud warning and model picker strings

Co-authored-by: Cursor <cursoragent@cursor.com>

* fix(zoo-gateway): settings UI sign-in button, validation tests, defer auth

Co-authored-by: Cursor <cursoragent@cursor.com>

* refactor(zoo-gateway): localize auth-state UX to provider component

Move the zoo-gateway sign-in error out of the shared form-validation effect
in ApiOptions and into ZooGateway.tsx, where it renders inline via
ApiErrorMessage. ApiOptions can then drop zooCodeIsAuthenticated from its
useEffect dependency list, and validateApiConfigurationExcludingModelErrors
short-circuits zoo-gateway entirely.

Also rename the inline isSonnet45ModelId helper to isClaudeSonnetModelId
and let pickZooGatewayDefaultModelId express the version-priority order
directly, so the helper has no version baked into its name.

Co-authored-by: Cursor <cursoragent@cursor.com>

* fix(zoo-gateway): enforce org provider check, simplify sign-in copy

The settings-form short-circuit for zoo-gateway also bypassed the
organization PROVIDER_NOT_ALLOWED check, so a workspace that disallows
zoo-gateway could not surface that error. Scope the short-circuit to
the keys/sign-in check only and let the org allowlist check run for
every provider.

Drop the quoted CTA from zooGatewaySignIn in all 18 locales: the
sign-in button is rendered immediately below the inline error, so a
duplicate label was just a drift hazard.

Co-authored-by: Cursor <cursoragent@cursor.com>

* refactor(webview): move provider model config + docs slugs out of ApiOptions

Lift the inline PROVIDER_MODEL_CONFIG map and the docs-slug lookup out
of ApiOptions.tsx into webview-ui/src/components/settings/utils/providerModelConfig.ts
behind getProviderModelConfig and getProviderDocsSlug helpers. ApiOptions
now reads provider-specific model fields, defaults, and docs slugs through
those helpers, leaving the component focused on rendering.

Co-authored-by: Cursor <cursoragent@cursor.com>

* fix(i18n): align French zooGatewaySignIn to formal vous register

validation.zooGatewaySignIn used "Connecte-toi" while
providers.zooGateway.signInDescription uses "Connectez-vous".
Use vous consistently across both strings.

Co-authored-by: Cursor <cursoragent@cursor.com>

---------

Co-authored-by: James Mtendamema <jmtendamema@geologicai.com>
Co-authored-by: Cursor <cursoragent@cursor.com>

Author: 3 people

src/api/providers/fetchers/__tests__/zoo-gateway.spec.ts

@@ -5,6 +5,10 @@ import axios from "axios"
 import { getZooGatewayModels, parseZooGatewayModel } from "../zoo-gateway"
 
 vitest.mock("axios")
+vitest.mock("../../../../services/zoo-code-auth", () => ({
+	getCachedZooCodeToken: vitest.fn(() => ""),
+	getZooCodeBaseUrl: vitest.fn(() => "https://example.test"),
+}))
 const mockedAxios = axios as any
 
 describe("Zoo Gateway Fetchers", () => {
@@ -134,7 +138,6 @@ describe("Zoo Gateway Fetchers", () => {
 			expect(Object.keys(models)).toEqual(["anthropic/claude-sonnet-4"])
 			expect(models["anthropic/claude-sonnet-4"].description).toBe("Claude Sonnet 4")
 		})
-
 		it("returns {} on a structurally broken response instead of throwing", async () => {
 			const consoleErrorSpy = vitest.spyOn(console, "error").mockImplementation(() => {})
 			mockedAxios.get.mockResolvedValueOnce({ data: { unexpected: true } })

webview-ui/src/components/settings/ApiOptions.tsx

@@ -9,36 +9,13 @@ import {
 	type ProviderSettings,
 	isRetiredProvider,
 	DEFAULT_CONSECUTIVE_MISTAKE_LIMIT,
-	openRouterDefaultModelId,
-	poeDefaultModelId,
-	requestyDefaultModelId,
-	litellmDefaultModelId,
-	openAiNativeDefaultModelId,
-	openAiCodexDefaultModelId,
-	anthropicDefaultModelId,
-	qwenCodeDefaultModelId,
-	geminiDefaultModelId,
-	deepSeekDefaultModelId,
-	moonshotDefaultModelId,
-	mistralDefaultModelId,
-	xaiDefaultModelId,
-	basetenDefaultModelId,
-	bedrockDefaultModelId,
-	vertexDefaultModelId,
-	sambaNovaDefaultModelId,
-	internationalZAiDefaultModelId,
-	mainlandZAiDefaultModelId,
-	fireworksDefaultModelId,
-	vercelAiGatewayDefaultModelId,
-	opencodeGoDefaultModelId,
-	minimaxDefaultModelId,
-	mimoDefaultModelId,
-	unboundDefaultModelId,
 } from "@roo-code/types"
 
 import {
 	getProviderServiceConfig,
 	getDefaultModelIdForProvider,
+	getProviderDocsSlug,
+	getProviderModelConfig,
 	getStaticModelsForProvider,
 	shouldUseGenericModelPicker,
 	handleModelChangeSideEffects,
@@ -95,6 +72,7 @@ import {
 	Fireworks,
 	VercelAiGateway,
 	OpenCodeGo,
+	ZooGateway,
 	MiniMax,
 	Mimo,
 } from "./providers"
@@ -268,6 +246,14 @@ const ApiOptions = ({
 			return
 		}
 
+		// Zoo Gateway renders its own auth-state error inline (sign-in card in
+		// ZooGateway.tsx) so it can react to zooCodeIsAuthenticated changes
+		// without re-running this effect or threading auth state through validation.
+		if (apiConfiguration.apiProvider === "zoo-gateway") {
+			setErrorMessage(undefined)
+			return
+		}
+
 		const apiValidationResult = validateApiConfigurationExcludingModelErrors(
 			apiConfiguration,
 			routerModels,
@@ -326,52 +312,7 @@ const ApiOptions = ({
 				}
 			}
 
-			// Define a mapping object that associates each provider with its model configuration
-			const PROVIDER_MODEL_CONFIG: Partial<
-				Record<
-					ProviderName,
-					{
-						field: keyof ProviderSettings
-						default?: string
-					}
-				>
-			> = {
-				openrouter: { field: "openRouterModelId", default: openRouterDefaultModelId },
-				requesty: { field: "requestyModelId", default: requestyDefaultModelId },
-				unbound: { field: "unboundModelId", default: unboundDefaultModelId },
-				litellm: { field: "litellmModelId", default: litellmDefaultModelId },
-				anthropic: { field: "apiModelId", default: anthropicDefaultModelId },
-				"openai-codex": { field: "apiModelId", default: openAiCodexDefaultModelId },
-				"qwen-code": { field: "apiModelId", default: qwenCodeDefaultModelId },
-				"openai-native": { field: "apiModelId", default: openAiNativeDefaultModelId },
-				gemini: { field: "apiModelId", default: geminiDefaultModelId },
-				deepseek: { field: "apiModelId", default: deepSeekDefaultModelId },
-				moonshot: { field: "apiModelId", default: moonshotDefaultModelId },
-				minimax: { field: "apiModelId", default: minimaxDefaultModelId },
-				mimo: { field: "apiModelId", default: mimoDefaultModelId },
-				mistral: { field: "apiModelId", default: mistralDefaultModelId },
-				xai: { field: "apiModelId", default: xaiDefaultModelId },
-				baseten: { field: "apiModelId", default: basetenDefaultModelId },
-				bedrock: { field: "apiModelId", default: bedrockDefaultModelId },
-				vertex: { field: "apiModelId", default: vertexDefaultModelId },
-				sambanova: { field: "apiModelId", default: sambaNovaDefaultModelId },
-				zai: {
-					field: "apiModelId",
-					default:
-						apiConfiguration.zaiApiLine === "china_coding"
-							? mainlandZAiDefaultModelId
-							: internationalZAiDefaultModelId,
-				},
-				fireworks: { field: "apiModelId", default: fireworksDefaultModelId },
-				poe: { field: "apiModelId", default: poeDefaultModelId },
-				"vercel-ai-gateway": { field: "vercelAiGatewayModelId", default: vercelAiGatewayDefaultModelId },
-				"opencode-go": { field: "opencodeGoModelId", default: opencodeGoDefaultModelId },
-				openai: { field: "openAiModelId" },
-				ollama: { field: "ollamaModelId" },
-				lmstudio: { field: "lmStudioModelId" },
-			}
-
-			const config = PROVIDER_MODEL_CONFIG[value]
+			const config = getProviderModelConfig(value, apiConfiguration)
 			if (config) {
 				validateAndResetModel(
 					value,
@@ -390,22 +331,14 @@ const ApiOptions = ({
 
 	const docs = useMemo(() => {
 		const provider = PROVIDERS.find(({ value }) => value === selectedProvider)
-		const name = provider?.label
-
-		if (!name) {
+		if (!provider) {
 			return undefined
 		}
 
-		// Get the URL slug - use custom mapping if available, otherwise use the provider key.
-		const slugs: Record<string, string> = {
-			"openai-native": "openai",
-			openai: "openai-compatible",
-		}
-
-		const slug = slugs[selectedProvider] || selectedProvider
+		const slug = getProviderDocsSlug(provider.value)
 		return {
 			url: buildDocLink(`providers/${slug}`, "provider_docs"),
-			name,
+			name: provider.label,
 		}
 	}, [selectedProvider])
 
@@ -702,6 +635,17 @@ const ApiOptions = ({
 						/>
 					)}
 
+					{selectedProvider === "zoo-gateway" && (
+						<ZooGateway
+							apiConfiguration={apiConfiguration}
+							setApiConfigurationField={setApiConfigurationField}
+							routerModels={routerModels}
+							organizationAllowList={organizationAllowList}
+							modelValidationError={modelValidationError}
+							simplifySettings={fromWelcomeView}
+						/>
+					)}
+
 					{selectedProvider === "fireworks" && (
 						<Fireworks
 							apiConfiguration={apiConfiguration}

webview-ui/src/components/settings/ModelPicker.tsx

@@ -35,6 +35,7 @@ type ModelIdKey = keyof Pick<
 	| "litellmModelId"
 	| "vercelAiGatewayModelId"
 	| "opencodeGoModelId"
+	| "zooGatewayModelId"
 	| "apiModelId"
 	| "ollamaModelId"
 	| "lmStudioModelId"

webview-ui/src/components/settings/__tests__/ApiOptions.spec.tsx

@@ -4,7 +4,7 @@ import { render, screen, fireEvent, within } from "@/utils/test-utils"
 import { QueryClient, QueryClientProvider } from "@tanstack/react-query"
 
 import { type ModelInfo, type ProviderSettings, openAiModelInfoSaneDefaults } from "@roo-code/types"
-import { openAiCodexDefaultModelId } from "@roo-code/types"
+import { openAiCodexDefaultModelId, zooGatewayDefaultModelId } from "@roo-code/types"
 
 import * as ExtensionStateContext from "@src/context/ExtensionStateContext"
 const { ExtensionStateContextProvider } = ExtensionStateContext
@@ -300,6 +300,28 @@ describe("ApiOptions", () => {
 		expect(mockSetApiConfigurationField).toHaveBeenCalledWith("apiModelId", openAiCodexDefaultModelId, false)
 	})
 
+	it("initializes zooGatewayModelId to its default when switching provider to zoo-gateway", () => {
+		// Regression: zoo-gateway was previously missing from PROVIDER_MODEL_CONFIG, so switching
+		// providers never seeded zooGatewayModelId. Configs were left without a model id, which
+		// blocked completion flows that require a dynamic-provider model id.
+		const mockSetApiConfigurationField = vi.fn()
+
+		renderApiOptions({
+			apiConfiguration: {
+				apiProvider: "anthropic",
+				// No prior zooGatewayModelId.
+			},
+			setApiConfigurationField: mockSetApiConfigurationField,
+		})
+
+		const providerSelectContainer = screen.getByTestId("provider-select")
+		const providerSelect = providerSelectContainer.querySelector("select") as HTMLSelectElement
+		fireEvent.change(providerSelect, { target: { value: "zoo-gateway" } })
+
+		expect(mockSetApiConfigurationField).toHaveBeenCalledWith("apiProvider", "zoo-gateway")
+		expect(mockSetApiConfigurationField).toHaveBeenCalledWith("zooGatewayModelId", zooGatewayDefaultModelId, false)
+	})
+
 	it("shows temperature and rate limit controls by default", () => {
 		renderApiOptions({
 			apiConfiguration: {},

webview-ui/src/components/settings/constants.ts

@@ -64,6 +64,7 @@ export const PROVIDERS = [
 	{ value: "fireworks", label: "Fireworks AI", proxy: false },
 	{ value: "vercel-ai-gateway", label: "Vercel AI Gateway", proxy: false },
 	{ value: "opencode-go", label: "Opencode Go", proxy: false },
+	{ value: "zoo-gateway", label: "Zoo Gateway", proxy: false },
 	{ value: "minimax", label: "MiniMax", proxy: false },
 	{ value: "mimo", label: "Xiaomi MiMo", proxy: false },
 	{ value: "baseten", label: "Baseten", proxy: false },

webview-ui/src/components/settings/providers/ZooGateway.tsx

@@ -0,0 +1,125 @@
+import { useEffect, useMemo } from "react"
+import {
+	type ProviderSettings,
+	type OrganizationAllowList,
+	type RouterModels,
+	zooGatewayDefaultModelId,
+} from "@roo-code/types"
+
+import { useExtensionState } from "@src/context/ExtensionStateContext"
+import { getZooCodeAuthUrl } from "@src/oauth/urls"
+import { useAppTranslation } from "@src/i18n/TranslationContext"
+import { VSCodeButtonLink } from "@src/components/common/VSCodeButtonLink"
+
+import { ModelPicker } from "../ModelPicker"
+import { ApiErrorMessage } from "../ApiErrorMessage"
+
+type ZooGatewayProps = {
+	apiConfiguration: ProviderSettings
+	setApiConfigurationField: (field: keyof ProviderSettings, value: ProviderSettings[keyof ProviderSettings]) => void
+	routerModels?: RouterModels
+	organizationAllowList: OrganizationAllowList
+	modelValidationError?: string
+	simplifySettings?: boolean
+}
+
+function isClaudeSonnetModelId(id: string) {
+	return /claude.*sonnet/i.test(id)
+}
+
+// Exported for unit tests. Picks the default Zoo Gateway model id, preferring
+// Claude Sonnet 4.5 → Sonnet 4 → first available Sonnet → first model overall.
+export function pickZooGatewayDefaultModelId(modelIds: string[]) {
+	if (modelIds.length === 0) {
+		return zooGatewayDefaultModelId
+	}
+
+	const sonnets = modelIds.filter(isClaudeSonnetModelId)
+	if (sonnets.length === 0) {
+		return modelIds[0]
+	}
+
+	return (
+		sonnets.find((id) => id === "anthropic/claude-sonnet-4.5") ??
+		sonnets.find((id) => id.includes("claude-sonnet-4.5")) ??
+		sonnets.find((id) => /sonnet-4[.-]5/i.test(id)) ??
+		sonnets.find((id) => /sonnet-4(?![.-]?\d)/i.test(id)) ??
+		sonnets[0]
+	)
+}
+
+export const ZooGateway = ({
+	apiConfiguration,
+	setApiConfigurationField,
+	routerModels,
+	organizationAllowList,
+	modelValidationError,
+	simplifySettings,
+}: ZooGatewayProps) => {
+	const { t } = useAppTranslation()
+	const { zooCodeIsAuthenticated, zooCodeUserEmail, zooCodeUserName, zooCodeBaseUrl, uriScheme, deviceName } =
+		useExtensionState()
+
+	const authUrl = getZooCodeAuthUrl(uriScheme, zooCodeBaseUrl, deviceName)
+	const resolvedDashboardBase = zooCodeBaseUrl?.replace(/\/$/, "") || "https://www.zoocode.dev"
+
+	const zooModels = useMemo(() => routerModels?.["zoo-gateway"] ?? {}, [routerModels])
+	const modelIds = useMemo(() => Object.keys(zooModels), [zooModels])
+	const resolvedDefaultModelId = useMemo(() => pickZooGatewayDefaultModelId(modelIds), [modelIds])
+
+	useEffect(() => {
+		if (modelIds.length === 0) {
+			return
+		}
+
+		const current = apiConfiguration.zooGatewayModelId
+		if (!current || !modelIds.includes(current)) {
+			setApiConfigurationField("zooGatewayModelId", resolvedDefaultModelId)
+		}
+	}, [apiConfiguration.zooGatewayModelId, modelIds, resolvedDefaultModelId, setApiConfigurationField])
+
+	return (
+		<>
+			<div className="flex flex-col gap-1 rounded-md border border-vscode-panel-border p-2">
+				<div className="flex items-center justify-between">
+					<label className="block text-sm font-medium">{t("settings:providers.zooGateway.account")}</label>
+					{zooCodeIsAuthenticated && zooCodeUserEmail && (
+						<span className="text-xs text-vscode-descriptionForeground">{zooCodeUserEmail}</span>
+					)}
+				</div>
+				{!zooCodeIsAuthenticated ? (
+					<div className="flex flex-col gap-1">
+						<ApiErrorMessage errorMessage={t("settings:validation.zooGatewaySignIn")} />
+						<p className="text-xs text-vscode-descriptionForeground">
+							{t("settings:providers.zooGateway.signInDescription")}
+						</p>
+						<VSCodeButtonLink href={authUrl} appearance="primary">
+							{t("settings:providers.zooGateway.signInButton")}
+						</VSCodeButtonLink>
+					</div>
+				) : (
+					<div className="flex items-center gap-1">
+						<span className="codicon codicon-check text-vscode-charts-green" />
+						<span className="text-xs text-vscode-descriptionForeground">
+							{zooCodeUserName
+								? t("settings:providers.zooGateway.authenticatedAs", { name: zooCodeUserName })
+								: t("settings:providers.zooGateway.authenticated")}
+						</span>
+					</div>
+				)}
+			</div>
+			<ModelPicker
+				apiConfiguration={apiConfiguration}
+				setApiConfigurationField={setApiConfigurationField}
+				defaultModelId={resolvedDefaultModelId}
+				models={zooModels}
+				modelIdKey="zooGatewayModelId"
+				serviceName="Zoo Gateway"
+				serviceUrl={`${resolvedDashboardBase}/dashboard/models`}
+				organizationAllowList={organizationAllowList}
+				errorMessage={modelValidationError}
+				simplifySettings={simplifySettings}
+			/>
+		</>
+	)
+}