feat: normalize thinkingConfig

- Expose Gemini cache hits and allow cached_content passthrough
- Normalize thinkingConfig to avoid invalid includeThoughts errors
- Cleanup

Author: jenslys

package.json

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

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,7 +122,6 @@ export const GeminiCLIOAuthPlugin = async (
         authorize: async () => {
           console.log("\n=== Google Gemini OAuth Setup ===");
 
-          // Detect headless/SSH environment
           const isHeadless = !!(
             process.env.SSH_CONNECTION ||
             process.env.SSH_CLIENT ||
@@ -191,7 +197,6 @@ export const GeminiCLIOAuthPlugin = async (
                   try {
                     await listener?.close();
                   } catch {
-                    // Ignore close errors.
                   }
                 }
               },

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;

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();

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 {

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,17 +144,26 @@ 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;
   }
   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 () => {};

src/plugin/project.ts

@@ -43,13 +43,19 @@ 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.",
     );
   }
 }
 
+/**
+ * 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,