opencode-gemini-auth 1.0.9 → 1.1.0

package/README.md

@@ -38,3 +38,50 @@ echo "Plugin update script finished successfully.")
 ```bash
 opencode  # Reinstalls latest
 ```
+
+## Local Development
+
+First, clone the repository and install dependencies:
+
+```bash
+git clone https://github.com/jenslys/opencode-gemini-auth.git
+cd opencode-gemini-auth
+bun install
+```
+
+When you want Opencode to use a local checkout of this plugin, point the
+`plugin` entry in your config to the folder via a `file://` URL:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": ["file:///absolute/path/to/opencode-gemini-auth"]
+}
+```
+
+Replace `/absolute/path/to/opencode-gemini-auth` with the absolute path to
+your local clone.
+
+## Debugging Gemini Requests
+
+Set `OPENCODE_GEMINI_DEBUG=1` in the environment when you run an Opencode
+command to capture every Gemini request/response that this plugin issues. When
+enabled, the plugin writes to a timestamped `gemini-debug-<ISO>.log` file in
+your current working directory so the CLI output stays clean.
+
+```bash
+OPENCODE_GEMINI_DEBUG=1 opencode
+```
+
+The logger shows the transformed URL, HTTP method, sanitized headers (the
+`Authorization` header is redacted), whether the call used streaming, and a
+truncated preview (2 KB) of both the request and response bodies. This is handy
+when diagnosing "Bad Request" responses from Gemini. Remember that payloads may
+still include parts of your prompt or response, so only enable this flag when
+you're comfortable keeping that information in the generated log file.
+
+**404s on `gemini-2.5-flash-image`.** Opencode fires internal
+summarization/title requests at `gemini-2.5-flash-image`. The plugin
+automatically remaps those payloads to `gemini-2.5-flash`, eliminating the extra
+404s for accounts without image access. If you still see a 404, confirm your
+project actually has access to the fallback model.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "opencode-gemini-auth",
   "module": "index.ts",
-  "version": "1.0.9",
+  "version": "1.1.0",
   "author": "jenslys",
   "repository": "https://github.com/jenslys/opencode-gemini-auth",
   "files": [

package/src/constants.ts

@@ -32,3 +32,8 @@ export const CODE_ASSIST_HEADERS = {
   "X-Goog-Api-Client": "gl-node/22.17.0",
   "Client-Metadata": "ideType=IDE_UNSPECIFIED,platform=PLATFORM_UNSPECIFIED,pluginType=GEMINI",
 } as const;
+
+/**
+ * Provider identifier shared between the plugin loader and credential store.
+ */
+export const GEMINI_PROVIDER_ID = "google";

package/src/plugin/cache.ts

@@ -0,0 +1,53 @@
+import { accessTokenExpired } from "./auth";
+import type { OAuthAuthDetails } from "./types";
+
+const authCache = new Map<string, OAuthAuthDetails>();
+
+function normalizeRefreshKey(refresh?: string): string | undefined {
+  const key = refresh?.trim();
+  return key ? key : undefined;
+}
+
+export function resolveCachedAuth(auth: OAuthAuthDetails): OAuthAuthDetails {
+  const key = normalizeRefreshKey(auth.refresh);
+  if (!key) {
+    return auth;
+  }
+
+  const cached = authCache.get(key);
+  if (!cached) {
+    authCache.set(key, auth);
+    return auth;
+  }
+
+  if (!accessTokenExpired(auth)) {
+    authCache.set(key, auth);
+    return auth;
+  }
+
+  if (!accessTokenExpired(cached)) {
+    return cached;
+  }
+
+  authCache.set(key, auth);
+  return auth;
+}
+
+export function storeCachedAuth(auth: OAuthAuthDetails): void {
+  const key = normalizeRefreshKey(auth.refresh);
+  if (!key) {
+    return;
+  }
+  authCache.set(key, auth);
+}
+
+export function clearCachedAuth(refresh?: string): void {
+  if (!refresh) {
+    authCache.clear();
+    return;
+  }
+  const key = normalizeRefreshKey(refresh);
+  if (key) {
+    authCache.delete(key);
+  }
+}

package/src/plugin/debug.ts

@@ -0,0 +1,168 @@
+import { createWriteStream } from "node:fs";
+import { join } from "node:path";
+import { cwd, env } from "node:process";
+
+const DEBUG_FLAG = env.OPENCODE_GEMINI_DEBUG ?? "";
+const MAX_BODY_PREVIEW_CHARS = 2000;
+const debugEnabled = DEBUG_FLAG.trim() === "1";
+const logFilePath = debugEnabled ? defaultLogFilePath() : undefined;
+const logWriter = createLogWriter(logFilePath);
+
+export interface GeminiDebugContext {
+  id: string;
+  streaming: boolean;
+  startedAt: number;
+}
+
+interface GeminiDebugRequestMeta {
+  originalUrl: string;
+  resolvedUrl: string;
+  method?: string;
+  headers?: HeadersInit;
+  body?: BodyInit | null;
+  streaming: boolean;
+  projectId?: string;
+}
+
+interface GeminiDebugResponseMeta {
+  body?: string;
+  note?: string;
+  error?: unknown;
+}
+
+let requestCounter = 0;
+
+export function startGeminiDebugRequest(meta: GeminiDebugRequestMeta): GeminiDebugContext | null {
+  if (!debugEnabled) {
+    return null;
+  }
+
+  const id = `GEMINI-${++requestCounter}`;
+  const method = meta.method ?? "GET";
+  logDebug(`[Gemini Debug ${id}] ${method} ${meta.resolvedUrl}`);
+  if (meta.originalUrl && meta.originalUrl !== meta.resolvedUrl) {
+    logDebug(`[Gemini Debug ${id}] Original URL: ${meta.originalUrl}`);
+  }
+  if (meta.projectId) {
+    logDebug(`[Gemini Debug ${id}] Project: ${meta.projectId}`);
+  }
+  logDebug(`[Gemini Debug ${id}] Streaming: ${meta.streaming ? "yes" : "no"}`);
+  logDebug(`[Gemini Debug ${id}] Headers: ${JSON.stringify(maskHeaders(meta.headers))}`);
+  const bodyPreview = formatBodyPreview(meta.body);
+  if (bodyPreview) {
+    logDebug(`[Gemini Debug ${id}] Body Preview: ${bodyPreview}`);
+  }
+
+  return { id, streaming: meta.streaming, startedAt: Date.now() };
+}
+
+export function logGeminiDebugResponse(
+  context: GeminiDebugContext | null | undefined,
+  response: Response,
+  meta: GeminiDebugResponseMeta = {},
+): void {
+  if (!debugEnabled || !context) {
+    return;
+  }
+
+  const durationMs = Date.now() - context.startedAt;
+  logDebug(
+    `[Gemini Debug ${context.id}] Response ${response.status} ${response.statusText} (${durationMs}ms)`,
+  );
+  logDebug(
+    `[Gemini Debug ${context.id}] Response Headers: ${JSON.stringify(maskHeaders(response.headers))}`,
+  );
+
+  if (meta.note) {
+    logDebug(`[Gemini Debug ${context.id}] Note: ${meta.note}`);
+  }
+
+  if (meta.error) {
+    logDebug(`[Gemini Debug ${context.id}] Error: ${formatError(meta.error)}`);
+  }
+
+  if (meta.body) {
+    logDebug(
+      `[Gemini Debug ${context.id}] Response Body Preview: ${truncateForLog(meta.body)}`,
+    );
+  }
+}
+
+function maskHeaders(headers?: HeadersInit | Headers): Record<string, string> {
+  if (!headers) {
+    return {};
+  }
+
+  const result: Record<string, string> = {};
+  const parsed = headers instanceof Headers ? headers : new Headers(headers);
+  parsed.forEach((value, key) => {
+    if (key.toLowerCase() === "authorization") {
+      result[key] = "[redacted]";
+    } else {
+      result[key] = value;
+    }
+  });
+  return result;
+}
+
+function formatBodyPreview(body?: BodyInit | null): string | undefined {
+  if (body == null) {
+    return undefined;
+  }
+
+  if (typeof body === "string") {
+    return truncateForLog(body);
+  }
+
+  if (body instanceof URLSearchParams) {
+    return truncateForLog(body.toString());
+  }
+
+  if (typeof Blob !== "undefined" && body instanceof Blob) {
+    return `[Blob size=${body.size}]`;
+  }
+
+  if (typeof FormData !== "undefined" && body instanceof FormData) {
+    return "[FormData payload omitted]";
+  }
+
+  return `[${body.constructor?.name ?? typeof body} payload omitted]`;
+}
+
+function truncateForLog(text: string): string {
+  if (text.length <= MAX_BODY_PREVIEW_CHARS) {
+    return text;
+  }
+  return `${text.slice(0, MAX_BODY_PREVIEW_CHARS)}... (truncated ${text.length - MAX_BODY_PREVIEW_CHARS} chars)`;
+}
+
+function logDebug(line: string): void {
+  logWriter(line);
+}
+
+function formatError(error: unknown): string {
+  if (error instanceof Error) {
+    return error.stack ?? error.message;
+  }
+  try {
+    return JSON.stringify(error);
+  } catch {
+    return String(error);
+  }
+}
+
+function defaultLogFilePath(): string {
+  const timestamp = new Date().toISOString().replace(/[:.]/g, "-");
+  return join(cwd(), `gemini-debug-${timestamp}.log`);
+}
+
+function createLogWriter(filePath?: string): (line: string) => void {
+  if (!filePath) {
+    return () => {};
+  }
+
+  const stream = createWriteStream(filePath, { flags: "a" });
+  return (line: string) => {
+    stream.write(`${line}\n`);
+  };
+}

package/src/plugin/project.ts

@@ -1,6 +1,7 @@
 import {
   CODE_ASSIST_HEADERS,
   GEMINI_CODE_ASSIST_ENDPOINT,
+  GEMINI_PROVIDER_ID,
 } from "../constants";
 import { formatRefreshParts, parseRefreshParts } from "./auth";
 import type {
@@ -12,6 +13,73 @@ import type {
 const projectContextResultCache = new Map<string, ProjectContextResult>();
 const projectContextPendingCache = new Map<string, Promise<ProjectContextResult>>();
 
+const CODE_ASSIST_METADATA = {
+  ideType: "IDE_UNSPECIFIED",
+  platform: "PLATFORM_UNSPECIFIED",
+  pluginType: "GEMINI",
+} as const;
+
+interface GeminiUserTier {
+  id?: string;
+  isDefault?: boolean;
+  userDefinedCloudaicompanionProject?: boolean;
+}
+
+interface LoadCodeAssistPayload {
+  cloudaicompanionProject?: string;
+  currentTier?: {
+    id?: string;
+  };
+  allowedTiers?: GeminiUserTier[];
+}
+
+interface OnboardUserPayload {
+  done?: boolean;
+  response?: {
+    cloudaicompanionProject?: {
+      id?: string;
+    };
+  };
+}
+
+class ProjectIdRequiredError extends Error {
+  constructor() {
+    super(
+      "Google Gemini requires a Google Cloud project. Enable the Gemini for Google Cloud API on a project you control, rerun `opencode auth login`, and supply that project ID when prompted.",
+    );
+  }
+}
+
+function buildMetadata(projectId?: string): Record<string, string> {
+  const metadata: Record<string, string> = {
+    ideType: CODE_ASSIST_METADATA.ideType,
+    platform: CODE_ASSIST_METADATA.platform,
+    pluginType: CODE_ASSIST_METADATA.pluginType,
+  };
+  if (projectId) {
+    metadata.duetProject = projectId;
+  }
+  return metadata;
+}
+
+function getDefaultTierId(allowedTiers?: GeminiUserTier[]): string | undefined {
+  if (!allowedTiers || allowedTiers.length === 0) {
+    return undefined;
+  }
+  for (const tier of allowedTiers) {
+    if (tier?.isDefault) {
+      return tier.id;
+    }
+  }
+  return allowedTiers[0]?.id;
+}
+
+function wait(ms: number): Promise<void> {
+  return new Promise(function (resolve) {
+    setTimeout(resolve, ms);
+  });
+}
+
 function getCacheKey(auth: OAuthAuthDetails): string | undefined {
   const refresh = auth.refresh?.trim();
   return refresh ? refresh : undefined;
@@ -27,11 +95,18 @@ export function invalidateProjectContextCache(refresh?: string): void {
   projectContextResultCache.delete(refresh);
 }
 
-export async function loadManagedProject(accessToken: string): Promise<{
-  managedProjectId?: string;
-  needsOnboarding: boolean;
-}> {
+export async function loadManagedProject(
+  accessToken: string,
+  projectId?: string,
+): Promise<LoadCodeAssistPayload | null> {
   try {
+    const metadata = buildMetadata(projectId);
+
+    const requestBody: Record<string, unknown> = { metadata };
+    if (projectId) {
+      requestBody.cloudaicompanionProject = projectId;
+    }
+
     const response = await fetch(
       `${GEMINI_CODE_ASSIST_ENDPOINT}/v1internal:loadCodeAssist`,
       {
@@ -41,134 +116,78 @@ export async function loadManagedProject(accessToken: string): Promise<{
           Authorization: `Bearer ${accessToken}`,
           ...CODE_ASSIST_HEADERS,
         },
-        body: JSON.stringify({
-          metadata: {
-            ideType: "IDE_UNSPECIFIED",
-            platform: "PLATFORM_UNSPECIFIED",
-            pluginType: "GEMINI",
-          },
-        }),
+        body: JSON.stringify(requestBody),
       },
     );
 
     if (!response.ok) {
-      return { needsOnboarding: false };
+      return null;
     }
 
-    const payload = (await response.json()) as {
-      cloudaicompanionProject?: string;
-      currentTier?: string;
-    };
-
-    if (payload.cloudaicompanionProject) {
-      return {
-        managedProjectId: payload.cloudaicompanionProject,
-        needsOnboarding: false,
-      };
-    }
-
-    return { needsOnboarding: !payload.currentTier };
+    return (await response.json()) as LoadCodeAssistPayload;
   } catch (error) {
     console.error("Failed to load Gemini managed project:", error);
-    return { needsOnboarding: false };
+    return null;
   }
 }
 
-export async function pollOperation(
+
+export async function onboardManagedProject(
   accessToken: string,
-  operationName: string,
+  tierId: string,
+  projectId?: string,
   attempts = 10,
-  intervalMs = 2000,
+  delayMs = 5000,
 ): Promise<string | undefined> {
-  for (let attempt = 0; attempt < attempts; attempt += 1) {
-    await new Promise((resolve) => setTimeout(resolve, intervalMs));
+  const metadata = buildMetadata(projectId);
+  const requestBody: Record<string, unknown> = {
+    tierId,
+    metadata,
+  };
 
+  if (tierId !== "FREE") {
+    if (!projectId) {
+      throw new ProjectIdRequiredError();
+    }
+    requestBody.cloudaicompanionProject = projectId;
+  }
+
+  for (let attempt = 0; attempt < attempts; attempt += 1) {
     try {
       const response = await fetch(
-        `${GEMINI_CODE_ASSIST_ENDPOINT}/v1internal/operations/${operationName}`,
+        `${GEMINI_CODE_ASSIST_ENDPOINT}/v1internal:onboardUser`,
         {
-          method: "GET",
+          method: "POST",
           headers: {
+            "Content-Type": "application/json",
             Authorization: `Bearer ${accessToken}`,
+            ...CODE_ASSIST_HEADERS,
           },
+          body: JSON.stringify(requestBody),
         },
       );
 
       if (!response.ok) {
-        continue;
+        return undefined;
       }
 
-      const payload = (await response.json()) as {
-        done?: boolean;
-        response?: {
-          cloudaicompanionProject?: {
-            id?: string;
-          };
-        };
-      };
-
-      const projectId = payload.response?.cloudaicompanionProject?.id;
+      const payload = (await response.json()) as OnboardUserPayload;
+      const managedProjectId = payload.response?.cloudaicompanionProject?.id;
+      if (payload.done && managedProjectId) {
+        return managedProjectId;
+      }
       if (payload.done && projectId) {
         return projectId;
       }
     } catch (error) {
-      console.error("Failed to poll Gemini onboarding operation:", error);
-    }
-  }
-  return undefined;
-}
-
-export async function onboardManagedProject(
-  accessToken: string,
-): Promise<string | undefined> {
-  try {
-    const response = await fetch(
-      `${GEMINI_CODE_ASSIST_ENDPOINT}/v1internal:onboardUser`,
-      {
-        method: "POST",
-        headers: {
-          "Content-Type": "application/json",
-          Authorization: `Bearer ${accessToken}`,
-          ...CODE_ASSIST_HEADERS,
-        },
-        body: JSON.stringify({
-          tierId: "FREE",
-          metadata: {
-            ideType: "IDE_UNSPECIFIED",
-            platform: "PLATFORM_UNSPECIFIED",
-            pluginType: "GEMINI",
-          },
-        }),
-      },
-    );
-
-    if (!response.ok) {
+      console.error("Failed to onboard Gemini managed project:", error);
       return undefined;
     }
 
-    const payload = (await response.json()) as {
-      done?: boolean;
-      name?: string;
-      response?: {
-        cloudaicompanionProject?: {
-          id?: string;
-        };
-      };
-    };
-
-    if (payload.done && payload.response?.cloudaicompanionProject?.id) {
-      return payload.response.cloudaicompanionProject.id;
-    }
-
-    if (!payload.done && payload.name) {
-      return pollOperation(accessToken, payload.name);
-    }
-
-    return undefined;
-  } catch (error) {
-    console.error("Failed to onboard Gemini managed project:", error);
-    return undefined;
+    await wait(delayMs);
   }
+
+  return undefined;
 }
 
 export async function ensureProjectContext(
@@ -201,13 +220,43 @@ export async function ensureProjectContext(
       };
     }
 
-    const loadResult = await loadManagedProject(accessToken);
-    let managedProjectId = loadResult.managedProjectId;
+    const loadPayload = await loadManagedProject(accessToken, parts.projectId);
+    if (loadPayload?.cloudaicompanionProject) {
+      const managedProjectId = loadPayload.cloudaicompanionProject;
+      const updatedAuth: OAuthAuthDetails = {
+        ...auth,
+        refresh: formatRefreshParts({
+          refreshToken: parts.refreshToken,
+          projectId: parts.projectId,
+          managedProjectId,
+        }),
+      };
+
+      await client.auth.set({
+        path: { id: GEMINI_PROVIDER_ID },
+        body: updatedAuth,
+      });
+
+      return { auth: updatedAuth, effectiveProjectId: managedProjectId };
+    }
+
+    if (!loadPayload) {
+      throw new ProjectIdRequiredError();
+    }
+
+    const currentTierId = loadPayload.currentTier?.id ?? undefined;
+    if (currentTierId && currentTierId !== "FREE") {
+      throw new ProjectIdRequiredError();
+    }
+
+    const defaultTierId = getDefaultTierId(loadPayload.allowedTiers);
+    const tierId = defaultTierId ?? "FREE";
 
-    if (!managedProjectId && loadResult.needsOnboarding) {
-      managedProjectId = await onboardManagedProject(accessToken);
+    if (tierId !== "FREE") {
+      throw new ProjectIdRequiredError();
     }
 
+    const managedProjectId = await onboardManagedProject(accessToken, tierId, parts.projectId);
     if (managedProjectId) {
       const updatedAuth: OAuthAuthDetails = {
         ...auth,
@@ -219,14 +268,14 @@ export async function ensureProjectContext(
       };
 
       await client.auth.set({
-        path: { id: "gemini-cli" },
+        path: { id: GEMINI_PROVIDER_ID },
         body: updatedAuth,
       });
 
       return { auth: updatedAuth, effectiveProjectId: managedProjectId };
     }
 
-    return { auth, effectiveProjectId: "" };
+    throw new ProjectIdRequiredError();
   };
 
   if (!cacheKey) {

package/src/plugin/request.ts

@@ -2,8 +2,12 @@ import {
   CODE_ASSIST_HEADERS,
   GEMINI_CODE_ASSIST_ENDPOINT,
 } from "../constants";
+import { logGeminiDebugResponse, type GeminiDebugContext } from "./debug";
 
 const STREAM_ACTION = "streamGenerateContent";
+const MODEL_FALLBACKS: Record<string, string> = {
+  "gemini-2.5-flash-image": "gemini-2.5-flash",
+};
 
 export function isGenerativeLanguageRequest(input: RequestInfo): input is string {
   return typeof input === "string" && input.includes("generativelanguage.googleapis.com");
@@ -60,23 +64,26 @@ export function prepareGeminiRequest(
     };
   }
 
-  const [, model, action] = match;
-  const streaming = action === STREAM_ACTION;
-  const transformedUrl = `${GEMINI_CODE_ASSIST_ENDPOINT}/v1internal:${action}${
+  const [, rawModel = "", rawAction = ""] = match;
+  const effectiveModel = MODEL_FALLBACKS[rawModel] ?? rawModel;
+  const streaming = rawAction === STREAM_ACTION;
+  const transformedUrl = `${GEMINI_CODE_ASSIST_ENDPOINT}/v1internal:${rawAction}${
     streaming ? "?alt=sse" : ""
   }`;
 
   let body = baseInit.body;
   if (typeof baseInit.body === "string" && baseInit.body) {
-    const trimmedPayload = baseInit.body.trim();
-    const looksCodeAssistPayload =
-      trimmedPayload.startsWith("{") &&
-      trimmedPayload.includes('"project"') &&
-      trimmedPayload.includes('"request"');
+    try {
+      const parsedBody = JSON.parse(baseInit.body) as Record<string, unknown>;
+      const isWrapped = typeof parsedBody.project === "string" && "request" in parsedBody;
 
-    if (!looksCodeAssistPayload) {
-      try {
-        const parsedBody = JSON.parse(baseInit.body) as Record<string, unknown>;
+      if (isWrapped) {
+        const wrappedBody = {
+          ...parsedBody,
+          model: effectiveModel,
+        } as Record<string, unknown>;
+        body = JSON.stringify(wrappedBody);
+      } else {
         const requestPayload: Record<string, unknown> = { ...parsedBody };
 
         if ("system_instruction" in requestPayload) {
@@ -90,14 +97,14 @@ export function prepareGeminiRequest(
 
         const wrappedBody = {
           project: projectId,
-          model,
+          model: effectiveModel,
           request: requestPayload,
         };
 
         body = JSON.stringify(wrappedBody);
-      } catch (error) {
-        console.error("Failed to transform Gemini request body:", error);
       }
+    } catch (error) {
+      console.error("Failed to transform Gemini request body:", error);
     }
   }
 
@@ -123,9 +130,13 @@ export function prepareGeminiRequest(
 export async function transformGeminiResponse(
   response: Response,
   streaming: boolean,
+  debugContext?: GeminiDebugContext | null,
 ): Promise<Response> {
   const contentType = response.headers.get("content-type") ?? "";
   if (!streaming && !contentType.includes("application/json")) {
+    logGeminiDebugResponse(debugContext, response, {
+      note: "Non-JSON response (body omitted)",
+    });
     return response;
   }
 
@@ -138,6 +149,11 @@ export async function transformGeminiResponse(
       headers,
     };
 
+    logGeminiDebugResponse(debugContext, response, {
+      body: text,
+      note: streaming ? "Streaming SSE payload" : undefined,
+    });
+
     if (streaming) {
       return new Response(transformStreamingPayload(text), init);
     }
@@ -149,6 +165,10 @@ export async function transformGeminiResponse(
 
     return new Response(text, init);
   } catch (error) {
+    logGeminiDebugResponse(debugContext, response, {
+      error,
+      note: "Failed to transform Gemini response",
+    });
     console.error("Failed to transform Gemini response:", error);
     return response;
   }

package/src/plugin/token.test.ts

@@ -0,0 +1,74 @@
+import { beforeEach, describe, expect, it, mock } from "bun:test";
+
+import { GEMINI_PROVIDER_ID } from "../constants";
+import { refreshAccessToken } from "./token";
+import type { OAuthAuthDetails, PluginClient } from "./types";
+
+const baseAuth: OAuthAuthDetails = {
+  type: "oauth",
+  refresh: "refresh-token|project-123",
+  access: "old-access",
+  expires: Date.now() - 1000,
+};
+
+function createClient() {
+  return {
+    auth: {
+      set: mock(async () => {}),
+    },
+  } as PluginClient & {
+    auth: { set: ReturnType<typeof mock<(input: any) => Promise<void>>> };
+  };
+}
+
+describe("refreshAccessToken", () => {
+  beforeEach(() => {
+    mock.restore();
+  });
+
+  it("updates the caller but skips persisting when refresh token is unchanged", async () => {
+    const client = createClient();
+    const fetchMock = mock(async () => {
+      return new Response(
+        JSON.stringify({
+          access_token: "new-access",
+          expires_in: 3600,
+        }),
+        { status: 200 },
+      );
+    });
+    (globalThis as { fetch: typeof fetch }).fetch = fetchMock as unknown as typeof fetch;
+
+    const result = await refreshAccessToken(baseAuth, client);
+
+    expect(result?.access).toBe("new-access");
+    expect(client.auth.set.mock.calls.length).toBe(0);
+  });
+
+  it("persists when Google rotates the refresh token", async () => {
+    const client = createClient();
+    const fetchMock = mock(async () => {
+      return new Response(
+        JSON.stringify({
+          access_token: "next-access",
+          expires_in: 3600,
+          refresh_token: "rotated-token",
+        }),
+        { status: 200 },
+      );
+    });
+    (globalThis as { fetch: typeof fetch }).fetch = fetchMock as unknown as typeof fetch;
+
+    const result = await refreshAccessToken(baseAuth, client);
+
+    expect(result?.access).toBe("next-access");
+    expect(client.auth.set.mock.calls.length).toBe(1);
+    expect(client.auth.set.mock.calls[0]?.[0]).toEqual({
+      path: { id: GEMINI_PROVIDER_ID },
+      body: expect.objectContaining({
+        type: "oauth",
+        refresh: expect.stringContaining("rotated-token"),
+      }),
+    });
+  });
+});

package/src/plugin/token.ts

@@ -1,5 +1,10 @@
-import { GEMINI_CLIENT_ID, GEMINI_CLIENT_SECRET } from "../constants";
+import {
+  GEMINI_CLIENT_ID,
+  GEMINI_CLIENT_SECRET,
+  GEMINI_PROVIDER_ID,
+} from "../constants";
 import { formatRefreshParts, parseRefreshParts } from "./auth";
+import { clearCachedAuth, storeCachedAuth } from "./cache";
 import { invalidateProjectContextCache } from "./project";
 import type { OAuthAuthDetails, PluginClient, RefreshParts } from "./types";
 
@@ -101,7 +106,7 @@ export async function refreshAccessToken(
             }),
           };
           await client.auth.set({
-            path: { id: "gemini-cli" },
+            path: { id: GEMINI_PROVIDER_ID },
             body: clearedAuth,
           });
         } catch (storeError) {
@@ -131,12 +136,19 @@ export async function refreshAccessToken(
       refresh: formatRefreshParts(refreshedParts),
     };
 
-    await client.auth.set({
-      path: { id: "gemini-cli" },
-      body: updatedAuth,
-    });
+    storeCachedAuth(updatedAuth);
     invalidateProjectContextCache(auth.refresh);
 
+    const refreshTokenRotated =
+      typeof payload.refresh_token === "string" && payload.refresh_token !== parts.refreshToken;
+
+    if (refreshTokenRotated) {
+      await client.auth.set({
+        path: { id: GEMINI_PROVIDER_ID },
+        body: updatedAuth,
+      });
+    }
+
     return updatedAuth;
   } catch (error) {
     console.error("Failed to refresh Gemini access token due to an unexpected error:", error);

package/src/plugin.ts

@@ -1,9 +1,10 @@
-import { GEMINI_REDIRECT_URI } from "./constants";
+import { GEMINI_PROVIDER_ID, GEMINI_REDIRECT_URI } from "./constants";
 import { authorizeGemini, exchangeGemini } from "./gemini/oauth";
 import type { GeminiTokenExchangeResult } from "./gemini/oauth";
 import { accessTokenExpired, isOAuthAuth } from "./plugin/auth";
 import { promptProjectId } from "./plugin/cli";
 import { ensureProjectContext } from "./plugin/project";
+import { startGeminiDebugRequest } from "./plugin/debug";
 import {
   isGenerativeLanguageRequest,
   prepareGeminiRequest,
@@ -16,6 +17,7 @@ import type {
   LoaderResult,
   PluginContext,
   PluginResult,
+  ProjectContextResult,
   Provider,
 } from "./plugin/types";
 
@@ -23,7 +25,7 @@ export const GeminiCLIOAuthPlugin = async (
   { client }: PluginContext,
 ): Promise<PluginResult> => ({
   auth: {
-    provider: "google",
+    provider: GEMINI_PROVIDER_ID,
     loader: async (getAuth: GetAuth, provider: Provider): Promise<LoaderResult | null> => {
       const auth = await getAuth();
       if (!isOAuthAuth(auth)) {
@@ -64,7 +66,18 @@ export const GeminiCLIOAuthPlugin = async (
             return fetch(input, init);
           }
 
-          const projectContext = await ensureProjectContext(authRecord, client);
+          async function resolveProjectContext(): Promise<ProjectContextResult> {
+            try {
+              return await ensureProjectContext(authRecord, client);
+            } catch (error) {
+              if (error instanceof Error) {
+                console.error(error.message);
+              }
+              throw error;
+            }
+          }
+
+          const projectContext = await resolveProjectContext();
 
           const { request, init: transformedInit, streaming } = prepareGeminiRequest(
             input,
@@ -73,8 +86,20 @@ export const GeminiCLIOAuthPlugin = async (
             projectContext.effectiveProjectId,
           );
 
+          const originalUrl = toUrlString(input);
+          const resolvedUrl = toUrlString(request);
+          const debugContext = startGeminiDebugRequest({
+            originalUrl,
+            resolvedUrl,
+            method: transformedInit.method,
+            headers: transformedInit.headers,
+            body: transformedInit.body,
+            streaming,
+            projectId: projectContext.effectiveProjectId,
+          });
+
           const response = await fetch(request, transformedInit);
-          return transformGeminiResponse(response, streaming);
+          return transformGeminiResponse(response, streaming, debugContext);
         },
       };
     },
@@ -180,7 +205,7 @@ export const GeminiCLIOAuthPlugin = async (
         },
       },
       {
-        provider: "google",
+        provider: GEMINI_PROVIDER_ID,
         label: "Manually enter API Key",
         type: "api",
       },
@@ -189,3 +214,14 @@ export const GeminiCLIOAuthPlugin = async (
 });
 
 export const GoogleOAuthPlugin = GeminiCLIOAuthPlugin;
+
+function toUrlString(value: RequestInfo): string {
+  if (typeof value === "string") {
+    return value;
+  }
+  const candidate = (value as Request).url;
+  if (candidate) {
+    return candidate;
+  }
+  return value.toString();
+}