opencode-gemini-auth 1.1.4 → 1.1.6

package/package.json

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

package/src/plugin/auth.ts

@@ -6,6 +6,9 @@ export function isOAuthAuth(auth: AuthDetails): auth is OAuthAuthDetails {
   return auth.type === "oauth";
 }
 
+/**
+ * Splits a packed refresh string into its constituent refresh token and project IDs.
+ */
 export function parseRefreshParts(refresh: string): RefreshParts {
   const [refreshToken = "", projectId = "", managedProjectId = ""] = (refresh ?? "").split("|");
   return {
@@ -15,12 +18,18 @@ export function parseRefreshParts(refresh: string): RefreshParts {
   };
 }
 
+/**
+ * Serializes refresh token parts into the stored string format.
+ */
 export function formatRefreshParts(parts: RefreshParts): string {
   const projectSegment = parts.projectId ?? "";
   const base = `${parts.refreshToken}|${projectSegment}`;
   return parts.managedProjectId ? `${base}|${parts.managedProjectId}` : base;
 }
 
+/**
+ * Determines whether an access token is expired or missing, with buffer for clock skew.
+ */
 export function accessTokenExpired(auth: OAuthAuthDetails): boolean {
   if (!auth.access || typeof auth.expires !== "number") {
     return true;

package/src/plugin/cache.ts

@@ -3,11 +3,17 @@ import type { OAuthAuthDetails } from "./types";
 
 const authCache = new Map<string, OAuthAuthDetails>();
 
+/**
+ * Produces a stable cache key from a refresh token string.
+ */
 function normalizeRefreshKey(refresh?: string): string | undefined {
   const key = refresh?.trim();
   return key ? key : undefined;
 }
 
+/**
+ * Returns a cached auth snapshot when available, favoring unexpired tokens.
+ */
 export function resolveCachedAuth(auth: OAuthAuthDetails): OAuthAuthDetails {
   const key = normalizeRefreshKey(auth.refresh);
   if (!key) {
@@ -33,6 +39,9 @@ export function resolveCachedAuth(auth: OAuthAuthDetails): OAuthAuthDetails {
   return auth;
 }
 
+/**
+ * Stores the latest auth snapshot keyed by refresh token.
+ */
 export function storeCachedAuth(auth: OAuthAuthDetails): void {
   const key = normalizeRefreshKey(auth.refresh);
   if (!key) {
@@ -41,6 +50,9 @@ export function storeCachedAuth(auth: OAuthAuthDetails): void {
   authCache.set(key, auth);
 }
 
+/**
+ * Clears cached auth globally or for a specific refresh token.
+ */
 export function clearCachedAuth(refresh?: string): void {
   if (!refresh) {
     authCache.clear();

package/src/plugin/cli.ts

@@ -1,6 +1,9 @@
 import { createInterface } from "node:readline/promises";
 import { stdin as input, stdout as output } from "node:process";
 
+/**
+ * Prompts the user for a project ID via stdin/stdout.
+ */
 export async function promptProjectId(): Promise<string> {
   const rl = createInterface({ input, output });
   try {

package/src/plugin/debug.ts

@@ -28,10 +28,14 @@ interface GeminiDebugResponseMeta {
   body?: string;
   note?: string;
   error?: unknown;
+  headersOverride?: HeadersInit;
 }
 
 let requestCounter = 0;
 
+/**
+ * Begins a debug trace for a Gemini request, logging request metadata when debugging is enabled.
+ */
 export function startGeminiDebugRequest(meta: GeminiDebugRequestMeta): GeminiDebugContext | null {
   if (!debugEnabled) {
     return null;
@@ -56,6 +60,9 @@ export function startGeminiDebugRequest(meta: GeminiDebugRequestMeta): GeminiDeb
   return { id, streaming: meta.streaming, startedAt: Date.now() };
 }
 
+/**
+ * Logs response details for a previously started debug trace when debugging is enabled.
+ */
 export function logGeminiDebugResponse(
   context: GeminiDebugContext | null | undefined,
   response: Response,
@@ -70,7 +77,9 @@ export function logGeminiDebugResponse(
     `[Gemini Debug ${context.id}] Response ${response.status} ${response.statusText} (${durationMs}ms)`,
   );
   logDebug(
-    `[Gemini Debug ${context.id}] Response Headers: ${JSON.stringify(maskHeaders(response.headers))}`,
+    `[Gemini Debug ${context.id}] Response Headers: ${JSON.stringify(
+      maskHeaders(meta.headersOverride ?? response.headers),
+    )}`,
   );
 
   if (meta.note) {
@@ -88,6 +97,9 @@ export function logGeminiDebugResponse(
   }
 }
 
+/**
+ * Obscures sensitive headers and returns a plain object for logging.
+ */
 function maskHeaders(headers?: HeadersInit | Headers): Record<string, string> {
   if (!headers) {
     return {};
@@ -105,6 +117,9 @@ function maskHeaders(headers?: HeadersInit | Headers): Record<string, string> {
   return result;
 }
 
+/**
+ * Produces a short, type-aware preview of a request/response body for logs.
+ */
 function formatBodyPreview(body?: BodyInit | null): string | undefined {
   if (body == null) {
     return undefined;
@@ -129,6 +144,9 @@ function formatBodyPreview(body?: BodyInit | null): string | undefined {
   return `[${body.constructor?.name ?? typeof body} payload omitted]`;
 }
 
+/**
+ * Truncates long strings to a fixed preview length for logging.
+ */
 function truncateForLog(text: string): string {
   if (text.length <= MAX_BODY_PREVIEW_CHARS) {
     return text;
@@ -136,10 +154,16 @@ function truncateForLog(text: string): string {
   return `${text.slice(0, MAX_BODY_PREVIEW_CHARS)}... (truncated ${text.length - MAX_BODY_PREVIEW_CHARS} chars)`;
 }
 
+/**
+ * Writes a single debug line using the configured writer.
+ */
 function logDebug(line: string): void {
   logWriter(line);
 }
 
+/**
+ * Converts unknown error-like values into printable strings.
+ */
 function formatError(error: unknown): string {
   if (error instanceof Error) {
     return error.stack ?? error.message;
@@ -151,11 +175,17 @@ function formatError(error: unknown): string {
   }
 }
 
+/**
+ * Builds a timestamped log file path in the current working directory.
+ */
 function defaultLogFilePath(): string {
   const timestamp = new Date().toISOString().replace(/[:.]/g, "-");
   return join(cwd(), `gemini-debug-${timestamp}.log`);
 }
 
+/**
+ * Creates a line writer that appends to a file when provided.
+ */
 function createLogWriter(filePath?: string): (line: string) => void {
   if (!filePath) {
     return () => {};

package/src/plugin/project.ts

@@ -43,6 +43,9 @@ interface OnboardUserPayload {
 }
 
 class ProjectIdRequiredError extends Error {
+  /**
+   * Error raised when a required Google Cloud project is missing during Gemini onboarding.
+   */
   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.",
@@ -50,6 +53,9 @@ class ProjectIdRequiredError extends Error {
   }
 }
 
+/**
+ * Builds metadata headers required by the Code Assist API.
+ */
 function buildMetadata(projectId?: string): Record<string, string> {
   const metadata: Record<string, string> = {
     ideType: CODE_ASSIST_METADATA.ideType,
@@ -62,6 +68,9 @@ function buildMetadata(projectId?: string): Record<string, string> {
   return metadata;
 }
 
+/**
+ * Selects the default tier ID from the allowed tiers list.
+ */
 function getDefaultTierId(allowedTiers?: GeminiUserTier[]): string | undefined {
   if (!allowedTiers || allowedTiers.length === 0) {
     return undefined;
@@ -74,17 +83,26 @@ function getDefaultTierId(allowedTiers?: GeminiUserTier[]): string | undefined {
   return allowedTiers[0]?.id;
 }
 
+/**
+ * Promise-based delay utility.
+ */
 function wait(ms: number): Promise<void> {
   return new Promise(function (resolve) {
     setTimeout(resolve, ms);
   });
 }
 
+/**
+ * Generates a cache key for project context based on refresh token.
+ */
 function getCacheKey(auth: OAuthAuthDetails): string | undefined {
   const refresh = auth.refresh?.trim();
   return refresh ? refresh : undefined;
 }
 
+/**
+ * Clears cached project context results and pending promises, globally or for a refresh key.
+ */
 export function invalidateProjectContextCache(refresh?: string): void {
   if (!refresh) {
     projectContextPendingCache.clear();
@@ -95,6 +113,9 @@ export function invalidateProjectContextCache(refresh?: string): void {
   projectContextResultCache.delete(refresh);
 }
 
+/**
+ * Loads managed project information for the given access token and optional project.
+ */
 export async function loadManagedProject(
   accessToken: string,
   projectId?: string,
@@ -132,6 +153,9 @@ export async function loadManagedProject(
 }
 
 
+/**
+ * Onboards a managed project for the user, optionally retrying until completion.
+ */
 export async function onboardManagedProject(
   accessToken: string,
   tierId: string,
@@ -190,6 +214,9 @@ export async function onboardManagedProject(
   return undefined;
 }
 
+/**
+ * Resolves an effective project ID for the current auth state, caching results per refresh token.
+ */
 export async function ensureProjectContext(
   auth: OAuthAuthDetails,
   client: PluginClient,

package/src/plugin/request-helpers.ts

@@ -0,0 +1,196 @@
+const GEMINI_PREVIEW_LINK = "https://goo.gle/enable-preview-features";
+
+export interface GeminiApiError {
+  code?: number;
+  message?: string;
+  status?: string;
+  [key: string]: unknown;
+}
+
+/**
+ * Minimal representation of Gemini API responses we touch.
+ */
+export interface GeminiApiBody {
+  response?: unknown;
+  error?: GeminiApiError;
+  [key: string]: unknown;
+}
+
+/**
+ * Usage metadata exposed by Gemini responses. Fields are optional to reflect partial payloads.
+ */
+export interface GeminiUsageMetadata {
+  totalTokenCount?: number;
+  promptTokenCount?: number;
+  candidatesTokenCount?: number;
+  cachedContentTokenCount?: number;
+}
+
+/**
+ * Normalized thinking configuration accepted by Gemini.
+ */
+export interface ThinkingConfig {
+  thinkingBudget?: number;
+  includeThoughts?: boolean;
+}
+
+/**
+ * Ensures thinkingConfig is valid: includeThoughts only allowed when budget > 0.
+ */
+export function normalizeThinkingConfig(config: unknown): ThinkingConfig | undefined {
+  if (!config || typeof config !== "object") {
+    return undefined;
+  }
+
+  const record = config as Record<string, unknown>;
+  const budgetRaw = record.thinkingBudget ?? record.thinking_budget;
+  const includeRaw = record.includeThoughts ?? record.include_thoughts;
+
+  const thinkingBudget = typeof budgetRaw === "number" && Number.isFinite(budgetRaw) ? budgetRaw : undefined;
+  const includeThoughts = typeof includeRaw === "boolean" ? includeRaw : undefined;
+
+  const enableThinking = thinkingBudget !== undefined && thinkingBudget > 0;
+  const finalInclude = enableThinking ? includeThoughts ?? false : false;
+
+  if (!enableThinking && finalInclude === false && thinkingBudget === undefined && includeThoughts === undefined) {
+    return undefined;
+  }
+
+  const normalized: ThinkingConfig = {};
+  if (thinkingBudget !== undefined) {
+    normalized.thinkingBudget = thinkingBudget;
+  }
+  if (finalInclude !== undefined) {
+    normalized.includeThoughts = finalInclude;
+  }
+  return normalized;
+}
+
+/**
+ * Parses a Gemini API body; handles array-wrapped responses the API sometimes returns.
+ */
+export function parseGeminiApiBody(rawText: string): GeminiApiBody | null {
+  try {
+    const parsed = JSON.parse(rawText);
+    if (Array.isArray(parsed)) {
+      const firstObject = parsed.find((item: unknown) => typeof item === "object" && item !== null);
+      if (firstObject && typeof firstObject === "object") {
+        return firstObject as GeminiApiBody;
+      }
+      return null;
+    }
+
+    if (parsed && typeof parsed === "object") {
+      return parsed as GeminiApiBody;
+    }
+
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Extracts usageMetadata from a response object, guarding types.
+ */
+export function extractUsageMetadata(body: GeminiApiBody): GeminiUsageMetadata | null {
+  const usage = (body.response && typeof body.response === "object"
+    ? (body.response as { usageMetadata?: unknown }).usageMetadata
+    : undefined) as GeminiUsageMetadata | undefined;
+
+  if (!usage || typeof usage !== "object") {
+    return null;
+  }
+
+  const asRecord = usage as Record<string, unknown>;
+  const toNumber = (value: unknown): number | undefined =>
+    typeof value === "number" && Number.isFinite(value) ? value : undefined;
+
+  return {
+    totalTokenCount: toNumber(asRecord.totalTokenCount),
+    promptTokenCount: toNumber(asRecord.promptTokenCount),
+    candidatesTokenCount: toNumber(asRecord.candidatesTokenCount),
+    cachedContentTokenCount: toNumber(asRecord.cachedContentTokenCount),
+  };
+}
+
+/**
+ * Walks SSE lines to find a usage-bearing response chunk.
+ */
+export function extractUsageFromSsePayload(payload: string): GeminiUsageMetadata | null {
+  const lines = payload.split("\n");
+  for (const line of lines) {
+    if (!line.startsWith("data:")) {
+      continue;
+    }
+    const jsonText = line.slice(5).trim();
+    if (!jsonText) {
+      continue;
+    }
+    try {
+      const parsed = JSON.parse(jsonText);
+      if (parsed && typeof parsed === "object") {
+        const usage = extractUsageMetadata({ response: (parsed as Record<string, unknown>).response });
+        if (usage) {
+          return usage;
+        }
+      }
+    } catch {
+      continue;
+    }
+  }
+  return null;
+}
+
+/**
+ * Enhances 404 errors for Gemini 3 models with a direct preview-access message.
+ */
+export function rewriteGeminiPreviewAccessError(
+  body: GeminiApiBody,
+  status: number,
+  requestedModel?: string,
+): GeminiApiBody | null {
+  if (!needsPreviewAccessOverride(status, body, requestedModel)) {
+    return null;
+  }
+
+  const error: GeminiApiError = body.error ?? {};
+  const trimmedMessage = typeof error.message === "string" ? error.message.trim() : "";
+  const messagePrefix = trimmedMessage.length > 0
+    ? trimmedMessage
+    : "Gemini 3 preview features are not enabled for this account.";
+  const enhancedMessage = `${messagePrefix} Request preview access at ${GEMINI_PREVIEW_LINK} before using Gemini 3 models.`;
+
+  return {
+    ...body,
+    error: {
+      ...error,
+      message: enhancedMessage,
+    },
+  };
+}
+
+function needsPreviewAccessOverride(
+  status: number,
+  body: GeminiApiBody,
+  requestedModel?: string,
+): boolean {
+  if (status !== 404) {
+    return false;
+  }
+
+  if (isGeminiThreeModel(requestedModel)) {
+    return true;
+  }
+
+  const errorMessage = typeof body.error?.message === "string" ? body.error.message : "";
+  return isGeminiThreeModel(errorMessage);
+}
+
+function isGeminiThreeModel(target?: string): boolean {
+  if (!target) {
+    return false;
+  }
+
+  return /gemini[\s-]?3/i.test(target);
+}

package/src/plugin/request.ts

@@ -1,32 +1,31 @@
-import {
-  CODE_ASSIST_HEADERS,
-  GEMINI_CODE_ASSIST_ENDPOINT,
-} from "../constants";
+import { CODE_ASSIST_HEADERS, GEMINI_CODE_ASSIST_ENDPOINT } from "../constants";
 import { logGeminiDebugResponse, type GeminiDebugContext } from "./debug";
+import {
+  extractUsageFromSsePayload,
+  extractUsageMetadata,
+  normalizeThinkingConfig,
+  parseGeminiApiBody,
+  rewriteGeminiPreviewAccessError,
+  type GeminiApiBody,
+  type GeminiUsageMetadata,
+} from "./request-helpers";
 
 const STREAM_ACTION = "streamGenerateContent";
 const MODEL_FALLBACKS: Record<string, string> = {
   "gemini-2.5-flash-image": "gemini-2.5-flash",
 };
-const GEMINI_PREVIEW_LINK = "https://goo.gle/enable-preview-features";
-
-interface GeminiApiError {
-  code?: number;
-  message?: string;
-  status?: string;
-  [key: string]: unknown;
-}
-
-interface GeminiApiBody {
-  response?: unknown;
-  error?: GeminiApiError;
-  [key: string]: unknown;
-}
-
+/**
+ * Detects Gemini/Generative Language API requests by URL.
+ * @param input Request target passed to fetch.
+ * @returns True when the URL targets generativelanguage.googleapis.com.
+ */
 export function isGenerativeLanguageRequest(input: RequestInfo): input is string {
   return typeof input === "string" && input.includes("generativelanguage.googleapis.com");
 }
 
+/**
+ * Rewrites SSE payloads so downstream consumers see only the inner `response` objects.
+ */
 function transformStreamingPayload(payload: string): string {
   return payload
     .split("\n")
@@ -49,6 +48,10 @@ function transformStreamingPayload(payload: string): string {
     .join("\n");
 }
 
+/**
+ * Rewrites OpenAI-style requests into Gemini Code Assist shape, normalizing model, headers,
+ * optional cached_content, and thinking config. Also toggles streaming mode for SSE actions.
+ */
 export function prepareGeminiRequest(
   input: RequestInfo,
   init: RequestInit | undefined,
@@ -100,11 +103,48 @@ export function prepareGeminiRequest(
       } else {
         const requestPayload: Record<string, unknown> = { ...parsedBody };
 
+        const rawGenerationConfig = requestPayload.generationConfig as Record<string, unknown> | undefined;
+        const normalizedThinking = normalizeThinkingConfig(rawGenerationConfig?.thinkingConfig);
+        if (normalizedThinking) {
+          if (rawGenerationConfig) {
+            rawGenerationConfig.thinkingConfig = normalizedThinking;
+            requestPayload.generationConfig = rawGenerationConfig;
+          } else {
+            requestPayload.generationConfig = { thinkingConfig: normalizedThinking };
+          }
+        } else if (rawGenerationConfig?.thinkingConfig) {
+          delete rawGenerationConfig.thinkingConfig;
+          requestPayload.generationConfig = rawGenerationConfig;
+        }
+
         if ("system_instruction" in requestPayload) {
           requestPayload.systemInstruction = requestPayload.system_instruction;
           delete requestPayload.system_instruction;
         }
 
+        const cachedContentFromExtra =
+          typeof requestPayload.extra_body === "object" && requestPayload.extra_body
+            ? (requestPayload.extra_body as Record<string, unknown>).cached_content ??
+              (requestPayload.extra_body as Record<string, unknown>).cachedContent
+            : undefined;
+        const cachedContent =
+          (requestPayload.cached_content as string | undefined) ??
+          (requestPayload.cachedContent as string | undefined) ??
+          (cachedContentFromExtra as string | undefined);
+        if (cachedContent) {
+          requestPayload.cachedContent = cachedContent;
+        }
+
+        delete requestPayload.cached_content;
+        delete requestPayload.cachedContent;
+        if (requestPayload.extra_body && typeof requestPayload.extra_body === "object") {
+          delete (requestPayload.extra_body as Record<string, unknown>).cached_content;
+          delete (requestPayload.extra_body as Record<string, unknown>).cachedContent;
+          if (Object.keys(requestPayload.extra_body as Record<string, unknown>).length === 0) {
+            delete requestPayload.extra_body;
+          }
+        }
+
         if ("model" in requestPayload) {
           delete requestPayload.model;
         }
@@ -142,6 +182,10 @@ export function prepareGeminiRequest(
   };
 }
 
+/**
+ * Normalizes Gemini responses: applies retry headers, extracts cache usage into headers,
+ * rewrites preview errors, flattens streaming payloads, and logs debug metadata.
+ */
 export async function transformGeminiResponse(
   response: Response,
   streaming: boolean,
@@ -162,35 +206,77 @@ export async function transformGeminiResponse(
   try {
     const text = await response.text();
     const headers = new Headers(response.headers);
+    
+    if (!response.ok && text) {
+      try {
+        const errorBody = JSON.parse(text);
+        if (errorBody?.error?.details && Array.isArray(errorBody.error.details)) {
+          const retryInfo = errorBody.error.details.find(
+            (detail: any) => detail['@type'] === 'type.googleapis.com/google.rpc.RetryInfo'
+          );
+          
+          if (retryInfo?.retryDelay) {
+            const match = retryInfo.retryDelay.match(/^([\d.]+)s$/);
+            if (match && match[1]) {
+              const retrySeconds = parseFloat(match[1]);
+              if (!isNaN(retrySeconds) && retrySeconds > 0) {
+                const retryAfterSec = Math.ceil(retrySeconds).toString();
+                const retryAfterMs = Math.ceil(retrySeconds * 1000).toString();
+                headers.set('Retry-After', retryAfterSec);
+                headers.set('retry-after-ms', retryAfterMs);
+              }
+            }
+          }
+        }
+      } catch (parseError) {
+      }
+    }
+    
     const init = {
       status: response.status,
       statusText: response.statusText,
       headers,
     };
 
+    const usageFromSse = streaming && isEventStreamResponse ? extractUsageFromSsePayload(text) : null;
+    const parsed: GeminiApiBody | null = !streaming || !isEventStreamResponse ? parseGeminiApiBody(text) : null;
+    const patched = parsed ? rewriteGeminiPreviewAccessError(parsed, response.status, requestedModel) : null;
+    const effectiveBody = patched ?? parsed ?? undefined;
+
+    const usage = usageFromSse ?? (effectiveBody ? extractUsageMetadata(effectiveBody) : null);
+    if (usage?.cachedContentTokenCount !== undefined) {
+      headers.set("x-gemini-cached-content-token-count", String(usage.cachedContentTokenCount));
+      if (usage.totalTokenCount !== undefined) {
+        headers.set("x-gemini-total-token-count", String(usage.totalTokenCount));
+      }
+      if (usage.promptTokenCount !== undefined) {
+        headers.set("x-gemini-prompt-token-count", String(usage.promptTokenCount));
+      }
+      if (usage.candidatesTokenCount !== undefined) {
+        headers.set("x-gemini-candidates-token-count", String(usage.candidatesTokenCount));
+      }
+    }
+
     logGeminiDebugResponse(debugContext, response, {
       body: text,
       note: streaming ? "Streaming SSE payload" : undefined,
+      headersOverride: headers,
     });
 
     if (streaming && response.ok && isEventStreamResponse) {
       return new Response(transformStreamingPayload(text), init);
     }
 
-    const parsed = parseGeminiApiBody(text);
     if (!parsed) {
       return new Response(text, init);
     }
 
-    const patched = rewriteGeminiPreviewAccessError(parsed, response.status, requestedModel);
-    const effectiveBody = patched ?? parsed;
-
-    if (effectiveBody.response !== undefined) {
+    if (effectiveBody?.response !== undefined) {
       return new Response(JSON.stringify(effectiveBody.response), init);
     }
 
     if (patched) {
-      return new Response(JSON.stringify(effectiveBody), init);
+      return new Response(JSON.stringify(patched), init);
     }
 
     return new Response(text, init);
@@ -203,76 +289,3 @@ export async function transformGeminiResponse(
     return response;
   }
 }
-
-function rewriteGeminiPreviewAccessError(
-  body: GeminiApiBody,
-  status: number,
-  requestedModel?: string,
-): GeminiApiBody | null {
-  if (!needsPreviewAccessOverride(status, body, requestedModel)) {
-    return null;
-  }
-
-  const error: GeminiApiError = body.error ?? {};
-  const trimmedMessage = typeof error.message === "string" ? error.message.trim() : "";
-  const messagePrefix = trimmedMessage.length > 0
-    ? trimmedMessage
-    : "Gemini 3 preview features are not enabled for this account.";
-  const enhancedMessage = `${messagePrefix} Request preview access at ${GEMINI_PREVIEW_LINK} before using Gemini 3 models.`;
-
-  return {
-    ...body,
-    error: {
-      ...error,
-      message: enhancedMessage,
-    },
-  };
-}
-
-function needsPreviewAccessOverride(
-  status: number,
-  body: GeminiApiBody,
-  requestedModel?: string,
-): boolean {
-  if (status !== 404) {
-    return false;
-  }
-
-  if (isGeminiThreeModel(requestedModel)) {
-    return true;
-  }
-
-  const errorMessage = typeof body.error?.message === "string" ? body.error.message : "";
-  return isGeminiThreeModel(errorMessage);
-}
-
-function isGeminiThreeModel(target?: string): boolean {
-  if (!target) {
-    return false;
-  }
-
-  return /gemini[\s-]?3/i.test(target);
-}
-
-function parseGeminiApiBody(rawText: string): GeminiApiBody | null {
-  try {
-    const parsed = JSON.parse(rawText);
-    if (Array.isArray(parsed)) {
-      const firstObject = parsed.find(function (item: unknown) {
-        return typeof item === "object" && item !== null;
-      });
-      if (firstObject && typeof firstObject === "object") {
-        return firstObject as GeminiApiBody;
-      }
-      return null;
-    }
-
-    if (parsed && typeof parsed === "object") {
-      return parsed as GeminiApiBody;
-    }
-
-    return null;
-  } catch {
-    return null;
-  }
-}

package/src/plugin/server.ts

@@ -24,8 +24,8 @@ const redirectUri = new URL(GEMINI_REDIRECT_URI);
 const callbackPath = redirectUri.pathname || "/";
 
 /**
- * Start a lightweight HTTP server that listens for the Gemini OAuth redirect.
- * Returns a listener object that resolves with the callback once received.
+ * Starts a lightweight HTTP server that listens for the Gemini OAuth redirect
+ * and resolves with the captured callback URL.
  */
 export async function startOAuthListener(
   { timeoutMs = 5 * 60 * 1000 }: OAuthListenerOptions = {},
@@ -206,7 +206,6 @@ const successResponse = `<!DOCTYPE html>
 
     resolveCallback(url);
 
-    // Close the server after handling the first valid callback.
     setImmediate(() => {
       server.close();
     });

package/src/plugin/token.ts

@@ -19,6 +19,9 @@ interface OAuthErrorPayload {
   error_description?: string;
 }
 
+/**
+ * Parses OAuth error payloads returned by Google token endpoints, tolerating varied shapes.
+ */
 function parseOAuthErrorPayload(text: string | undefined): { code?: string; description?: string } {
   if (!text) {
     return {};
@@ -55,6 +58,9 @@ function parseOAuthErrorPayload(text: string | undefined): { code?: string; desc
   }
 }
 
+/**
+ * Refreshes a Gemini OAuth access token, updates persisted credentials, and handles revocation.
+ */
 export async function refreshAccessToken(
   auth: OAuthAuthDetails,
   client: PluginClient,
@@ -83,7 +89,7 @@ export async function refreshAccessToken(
       try {
         errorText = await response.text();
       } catch {
-        // Ignore body parsing failures; we'll fall back to status only.
+        errorText = undefined;
       }
 
       const { code, description } = parseOAuthErrorPayload(errorText);

package/src/plugin.ts

@@ -21,6 +21,10 @@ import type {
   Provider,
 } from "./plugin/types";
 
+/**
+ * Registers the Gemini OAuth provider for Opencode, handling auth, request rewriting,
+ * debug logging, and response normalization for Gemini Code Assist endpoints.
+ */
 export const GeminiCLIOAuthPlugin = async (
   { client }: PluginContext,
 ): Promise<PluginResult> => ({
@@ -66,6 +70,9 @@ export const GeminiCLIOAuthPlugin = async (
             return fetch(input, init);
           }
 
+          /**
+           * Ensures we have a usable project context for the current auth snapshot.
+           */
           async function resolveProjectContext(): Promise<ProjectContextResult> {
             try {
               return await ensureProjectContext(authRecord, client);
@@ -115,29 +122,46 @@ export const GeminiCLIOAuthPlugin = async (
         authorize: async () => {
           console.log("\n=== Google Gemini OAuth Setup ===");
 
+          const isHeadless = !!(
+            process.env.SSH_CONNECTION ||
+            process.env.SSH_CLIENT ||
+            process.env.SSH_TTY ||
+            process.env.OPENCODE_HEADLESS
+          );
+
           let listener: OAuthListener | null = null;
-          try {
-            listener = await startOAuthListener();
-            const { host } = new URL(GEMINI_REDIRECT_URI);
-            console.log("1. You'll be asked to sign in to your Google account and grant permission.");
-            console.log(
-              `2. We'll automatically capture the browser redirect on http://${host}. No need to paste anything back here.`,
-            );
-            console.log("3. Once you see the 'Authentication complete' page in your browser, return to this terminal.");
-          } catch (error) {
+          if (!isHeadless) {
+            try {
+              listener = await startOAuthListener();
+              const { host } = new URL(GEMINI_REDIRECT_URI);
+              console.log("1. You'll be asked to sign in to your Google account and grant permission.");
+              console.log(
+                `2. We'll automatically capture the browser redirect on http://${host}. No need to paste anything back here.`,
+              );
+              console.log("3. Once you see the 'Authentication complete' page in your browser, return to this terminal.");
+            } catch (error) {
+              console.log("1. You'll be asked to sign in to your Google account and grant permission.");
+              console.log("2. After you approve, the browser will try to redirect to a 'localhost' page.");
+              console.log(
+                "3. This page will show an error like 'This site can't be reached'. This is perfectly normal and means it worked!",
+              );
+              console.log(
+                "4. Once you see that error, copy the entire URL from the address bar, paste it back here, and press Enter.",
+              );
+              if (error instanceof Error) {
+                console.log(`\nWarning: Couldn't start the local callback listener (${error.message}). Falling back to manual copy/paste.`);
+              } else {
+                console.log("\nWarning: Couldn't start the local callback listener. Falling back to manual copy/paste.");
+              }
+            }
+          } else {
+            console.log("Headless environment detected. Using manual OAuth flow.");
             console.log("1. You'll be asked to sign in to your Google account and grant permission.");
-            console.log("2. After you approve, the browser will try to redirect to a 'localhost' page.");
+            console.log("2. After you approve, the browser will redirect to a 'localhost' URL.");
             console.log(
-              "3. This page will show an error like 'This site can’t be reached'. This is perfectly normal and means it worked!",
+              "3. Copy the ENTIRE URL from your browser's address bar (it will look like: http://localhost:8085/oauth2callback?code=...&state=...)",
             );
-            console.log(
-              "4. Once you see that error, copy the entire URL from the address bar, paste it back here, and press Enter.",
-            );
-            if (error instanceof Error) {
-              console.log(`\nWarning: Couldn't start the local callback listener (${error.message}). Falling back to manual copy/paste.`);
-            } else {
-              console.log("\nWarning: Couldn't start the local callback listener. Falling back to manual copy/paste.");
-            }
+            console.log("4. Paste the URL back here and press Enter.");
           }
           console.log("\n");
 
@@ -173,7 +197,6 @@ export const GeminiCLIOAuthPlugin = async (
                   try {
                     await listener?.close();
                   } catch {
-                    // Ignore close errors.
                   }
                 }
               },