refactor(agent): isolate Google tool credentials

Remove Gemini chat routing. Resolve Google AI keys only when media or browser tools run.

Rename the key and expose provider purposes through accessible info tooltips.

Author: iamjr15

apps/agent-worker/src/durable-objects/agent-run-mastra-stream.ts

@@ -113,7 +113,6 @@ async function prepareMastraContext(options: MastraStreamOptions): Promise<Prepa
     composioConfigured: Boolean(toolCredentials.composioApiKey),
     exaConfigured: Boolean(toolCredentials.exaApiKey),
     firecrawlConfigured: Boolean(toolCredentials.firecrawlApiKey),
-    googleMediaConfigured: Boolean(toolCredentials.googleMediaApiKey),
   });
   return { ...userSkillContext, toolCredentials };
 }
@@ -217,10 +216,7 @@ function agentRequestContext(
     exaApiKey: toolCredentials.exaApiKey,
     firecrawlApiKey: toolCredentials.firecrawlApiKey,
     globalMemory: input.globalMemory,
-    googleApiKey:
-      credential.transportProvider === "google"
-        ? credential.apiKey
-        : toolCredentials.googleMediaApiKey,
+    googleToolApiKeyResolver: toolCredentials.googleToolApiKeyResolver,
     llmProvider: credential.transportProvider,
     modelId: credential.transportModelId,
     openaiApiKey: credential.transportProvider === "openai" ? credential.apiKey : undefined,

apps/agent-worker/src/durable-objects/agent-tool-credentials.ts

@@ -3,14 +3,12 @@ import type { AgentRunEnv } from "./agent-run-env";
 import type { StartRunInput } from "./agent-run-schemas";
 import type { ComposioRuntimeCredentials } from "./composio-provider";
 import { resolveComposioRuntimeCredentials } from "./composio-provider";
-import type { MediaCredentials } from "./media-provider";
-import { resolveMediaCredentials } from "./media-provider";
+import { createGoogleToolApiKeyResolver, type GoogleToolApiKeyResolver } from "./media-provider";
 import type { ResearchCredentials } from "./research-provider";
 import { resolveResearchCredentials } from "./research-provider";
 
 export type AgentToolCredentials = ComposioRuntimeCredentials &
-  MediaCredentials &
-  ResearchCredentials;
+  ResearchCredentials & { googleToolApiKeyResolver: GoogleToolApiKeyResolver };
 
 export async function resolveAgentToolCredentials(input: {
   env: AgentRunEnv;
@@ -26,11 +24,15 @@ export async function resolveAgentToolCredentials(input: {
     input.run,
     input.logger,
   );
-  input.setRunStage("Resolving media providers.");
-  const mediaCredentials = await resolveMediaCredentials(input.env, input.run, input.logger);
+  input.setRunStage("Preparing Google tool access.");
+  const googleToolApiKeyResolver = createGoogleToolApiKeyResolver(
+    input.env,
+    input.run,
+    input.logger,
+  );
   return {
     ...composioCredentials,
-    ...mediaCredentials,
     ...researchCredentials,
+    googleToolApiKeyResolver,
   };
 }

apps/agent-worker/src/durable-objects/llm-provider.ts

@@ -161,7 +161,7 @@ function resolveModelRequest(model: LogicalModelId): RequestedModel {
   } catch (error) {
     throw new APIError(400, "request_body_invalid", "Unsupported model selection.", {
       details: { message: error instanceof Error ? error.message : "Unknown model error" },
-      hint: "Use a supported Anthropic, Google Gemini, OpenAI, DeepSeek, or OpenRouter model id.",
+      hint: "Use a supported Anthropic, OpenAI, DeepSeek, or OpenRouter model id.",
       retriable: false,
     });
   }
@@ -301,9 +301,6 @@ function providerLabel(provider: LlmProvider): string {
   if (provider === "openai") {
     return "OpenAI";
   }
-  if (provider === "google") {
-    return "Google Gemini";
-  }
   if (provider === "deepseek") {
     return "DeepSeek";
   }

apps/agent-worker/src/durable-objects/media-provider.ts

@@ -10,32 +10,42 @@ interface MediaProviderEnv {
   HYPERDRIVE: Hyperdrive;
 }
 
-interface MediaProviderInput {
+interface GoogleToolProviderInput {
   userId: string;
 }
 
-export interface MediaCredentials {
-  googleMediaApiKey?: string | undefined;
+export type GoogleToolApiKeyResolver = () => Promise<string | undefined>;
+
+export function createGoogleToolApiKeyResolver(
+  env: MediaProviderEnv,
+  input: GoogleToolProviderInput,
+  logger: ReturnType<typeof createLogger>,
+): GoogleToolApiKeyResolver {
+  let resolution: Promise<string | undefined> | undefined;
+  return () => {
+    resolution ??= resolveGoogleToolApiKey(env, input, logger);
+    return resolution;
+  };
 }
 
-export async function resolveMediaCredentials(
+async function resolveGoogleToolApiKey(
   env: MediaProviderEnv,
-  input: MediaProviderInput,
+  input: GoogleToolProviderInput,
   logger: ReturnType<typeof createLogger>,
-): Promise<MediaCredentials> {
+): Promise<string | undefined> {
   return withUserDb(
     env,
     toUserId(input.userId),
     async ({ transaction }) => {
       const googleMediaApiKey = await transaction((db) => getProviderKey(db, "google"));
-      logger.info("byok_media_provider_key_checked", { google: Boolean(googleMediaApiKey) });
-      return googleMediaApiKey ? { googleMediaApiKey } : {};
+      logger.info("byok_google_tool_key_checked", { configured: Boolean(googleMediaApiKey) });
+      return googleMediaApiKey ?? undefined;
     },
     (dbHandle) =>
       closeDatabaseBestEffort({
         dbHandle,
         logger,
-        operation: "resolve_media_credentials",
+        operation: "resolve_google_tool_key",
       }),
   );
 }

apps/web/src/components/settings/models-panel-model.ts

@@ -28,7 +28,6 @@ export const SETTINGS_KEY_PROVIDERS = [
 export const MODEL_KEY_PROVIDERS = new Set<Provider>([
   "anthropic",
   "deepseek",
-  "google",
   "openai",
   "openrouter",
 ]);
@@ -44,7 +43,7 @@ const PROVIDER_LABELS = {
   deepseek: "DeepSeek",
   exa: "Exa",
   firecrawl: "Firecrawl",
-  google: "Gemini",
+  google: "Google AI",
   openai: "OpenAI",
   openrouter: "OpenRouter",
 } satisfies Record<Provider, string>;

apps/web/src/components/settings/provider-key-model.ts

@@ -10,14 +10,20 @@ export type ProviderKeyFormValues = z.infer<typeof ProviderKeyFormSchema>;
 export type ProviderKeyEditorStatus = "deleting" | "idle" | "saving";
 export type SecretVisibility = "hidden" | "visible";
 
-export const PROVIDER_META: Record<Provider, { label: string }> = {
-  anthropic: { label: "Anthropic" },
-  deepseek: { label: "DeepSeek" },
-  exa: { label: "Exa" },
-  firecrawl: { label: "Firecrawl" },
-  google: { label: "Gemini" },
-  openai: { label: "OpenAI" },
-  openrouter: { label: "OpenRouter" },
+export const PROVIDER_META: Record<Provider, { description: string; label: string }> = {
+  anthropic: { description: "Agent models and browser automation.", label: "Anthropic" },
+  deepseek: { description: "Optional personal key for DeepSeek models.", label: "DeepSeek" },
+  exa: { description: "Web research and source discovery.", label: "Exa" },
+  firecrawl: { description: "Web search, scraping, and extraction.", label: "Firecrawl" },
+  google: {
+    description: "Tools only: images, Veo video, and browser automation.",
+    label: "Google AI",
+  },
+  openai: { description: "Agent models and browser automation.", label: "OpenAI" },
+  openrouter: {
+    description: "Alternative routing for supported agent models.",
+    label: "OpenRouter",
+  },
 };
 
 export function providerPanelId(provider: Provider): string {

apps/web/src/components/settings/provider-keys-list.tsx

@@ -1,6 +1,8 @@
 import type { Provider, ProviderKeySummary } from "@cheatcode/types/api";
 import type { FormEventHandler } from "react";
 import type { FieldError, UseFormRegister, UseFormWatch } from "react-hook-form";
+import { Info } from "@/components/ui";
+import { CheatcodeTooltip } from "@/components/ui/cheatcode-tooltip";
 import { cn } from "@/lib/ui/cn";
 import { ProviderKeyEditor } from "./provider-key-editor";
 import {
@@ -124,11 +126,26 @@ function ProviderKeyRowHeader({
   provider: Provider;
   summary: ProviderKeySummary | undefined;
 }) {
+  const meta = PROVIDER_META[provider];
   return (
     <div className="flex min-h-8 items-center justify-between">
-      <h2 className="truncate font-medium text-[14px] text-foreground" id={providerTabId(provider)}>
-        {PROVIDER_META[provider].label} API Key
-      </h2>
+      <div className="flex min-w-0 items-center gap-1.5">
+        <h2
+          className="min-w-0 truncate font-medium text-[14px] text-foreground"
+          id={providerTabId(provider)}
+        >
+          {meta.label} API Key
+        </h2>
+        <CheatcodeTooltip label={meta.description} side="top">
+          <button
+            aria-label={`About ${meta.label} API key`}
+            className="inline-flex size-6 shrink-0 cursor-help items-center justify-center rounded-full text-muted-foreground transition-colors hover:bg-secondary hover:text-foreground focus-visible:ring-2 focus-visible:ring-ring/50"
+            type="button"
+          >
+            <Info aria-hidden="true" className="size-3.5" />
+          </button>
+        </CheatcodeTooltip>
+      </div>
       {isExpanded ? null : (
         <div className="ml-4 flex items-center gap-2">
           <button

apps/web/src/components/ui/icons.ts

@@ -26,6 +26,7 @@ export {
   Globe,
   Image,
   Inbox,
+  Info,
   LifeBuoy,
   Link,
   Loader2,

apps/web/src/components/ui/index.ts

@@ -27,6 +27,7 @@ export {
   Globe,
   Image,
   Inbox,
+  Info,
   LifeBuoy,
   Link,
   Loader2,

packages/agent-core/README.md

@@ -21,8 +21,8 @@ Sandbox and artifact capabilities cross tool-domain boundaries only through
 Single-consumer data, document, and media implementations live under
 `src/tools/`. Data tools profile and normalize bounded tabular inputs and render
 deterministic SVG/Recharts output. Document tools generate sandbox-side PPTX,
-DOCX, XLSX, and PDF source against `/opt/cheatcode-doc-runtime`. Media tools use
-the active request's Google BYOK key for image/video work. All three receive
+DOCX, XLSX, and PDF source against `/opt/cheatcode-doc-runtime`. Media and Google-backed
+browser tools resolve the user's Google AI BYOK key lazily when invoked. All three receive
 sandbox and R2 artifact capabilities through request-scoped contracts; they do
 not read environment variables, persist credentials, or log keys.
 
@@ -52,9 +52,9 @@ pnpm --filter @cheatcode/agent-core typecheck
 Provider keys are supplied through BYOK runtime context, not module scope.
 `resolveRequestedLlmTransport` returns an `LlmTransportSelection`: its provider and bare
 model ID are SDK transport inputs, never the durable product model attribution.
-Google model selections use `google/<Gemini model id>`, for example
-`google/gemini-2.5-flash`. OpenRouter model selections use
-`openrouter/<OpenRouter model id>`, for example `openrouter/openrouter/auto`.
+OpenRouter model selections use `openrouter/<OpenRouter model id>`, for example
+`openrouter/openrouter/auto`. Google AI keys are tool credentials for image/video
+generation and browser automation; `google/<model id>` is not an agent-model route.
 
 Mastra storage is intentionally execution-only and in-memory. AgentRun Durable
 Objects and Postgres own durable run and transcript state. Workflows that receive