@link-assistant/agent 0.6.2 → 0.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@link-assistant/agent",
-  "version": "0.6.2",
+  "version": "0.7.0",
   "description": "A minimal, public domain AI CLI agent compatible with OpenCode's JSON interface. Bun-only runtime.",
   "main": "src/index.js",
   "type": "module",

package/src/auth/plugins.ts

@@ -855,6 +855,10 @@ const GOOGLE_OAUTH_CLIENT_ID =
   '681255809395-oo8ft2oprdrnp9e3aqf6av3hmdib135j.apps.googleusercontent.com';
 const GOOGLE_OAUTH_CLIENT_SECRET = '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';
 const GOOGLE_OAUTH_SCOPES = [
+  // Note: We intentionally do NOT include generative-language.* scopes here
+  // because they are not registered for the Gemini CLI OAuth client (see issue #93).
+  // Instead, we rely on the fallback mechanism to use API keys when OAuth fails
+  // with scope errors (see issue #100).
   'https://www.googleapis.com/auth/cloud-platform',
   'https://www.googleapis.com/auth/userinfo.email',
   'https://www.googleapis.com/auth/userinfo.profile',
@@ -1260,12 +1264,363 @@ const GooglePlugin: AuthPlugin = {
       }
     }
 
+    /**
+     * Cloud Code API Configuration
+     *
+     * The official Gemini CLI uses Google's Cloud Code API (cloudcode-pa.googleapis.com)
+     * instead of the standard Generative Language API (generativelanguage.googleapis.com).
+     *
+     * The Cloud Code API:
+     * 1. Accepts `cloud-platform` OAuth scope (unlike generativelanguage.googleapis.com)
+     * 2. Handles subscription tier validation (FREE, STANDARD, etc.)
+     * 3. Proxies requests to the Generative Language API internally
+     *
+     * @see https://github.com/google-gemini/gemini-cli/blob/main/packages/core/src/code_assist/server.ts
+     * @see https://github.com/link-assistant/agent/issues/100
+     */
+    const CLOUD_CODE_ENDPOINT = 'https://cloudcode-pa.googleapis.com';
+    const CLOUD_CODE_API_VERSION = 'v1internal';
+
+    log.debug(() => ({
+      message: 'google oauth loader initialized',
+      cloudCodeEndpoint: CLOUD_CODE_ENDPOINT,
+      apiVersion: CLOUD_CODE_API_VERSION,
+    }));
+
+    /**
+     * Check if we have a fallback API key available.
+     * This allows trying API key authentication if Cloud Code API fails.
+     * See: https://github.com/link-assistant/agent/issues/100
+     */
+    const getFallbackApiKey = (): string | undefined => {
+      // Check for API key in environment variables
+      const envKey =
+        process.env['GOOGLE_GENERATIVE_AI_API_KEY'] ||
+        process.env['GEMINI_API_KEY'];
+
+      if (envKey) {
+        log.debug(() => ({
+          message: 'fallback api key available',
+          source: process.env['GOOGLE_GENERATIVE_AI_API_KEY']
+            ? 'GOOGLE_GENERATIVE_AI_API_KEY'
+            : 'GEMINI_API_KEY',
+          keyLength: envKey.length,
+        }));
+        return envKey;
+      }
+
+      log.debug(() => ({
+        message: 'no fallback api key available',
+        hint: 'Set GOOGLE_GENERATIVE_AI_API_KEY or GEMINI_API_KEY for fallback',
+      }));
+
+      // Check for API key in auth storage (async, so we need to handle this differently)
+      // For now, we only support env var fallback synchronously
+      return undefined;
+    };
+
+    /**
+     * Detect if an error is a scope-related authentication error.
+     * This is triggered when OAuth token doesn't have the required scopes.
+     */
+    const isScopeError = (response: Response): boolean => {
+      if (response.status !== 403) return false;
+      const wwwAuth = response.headers.get('www-authenticate') || '';
+      const isScope =
+        wwwAuth.includes('insufficient_scope') ||
+        wwwAuth.includes('ACCESS_TOKEN_SCOPE_INSUFFICIENT');
+
+      if (isScope) {
+        log.debug(() => ({
+          message: 'detected oauth scope error',
+          status: response.status,
+          wwwAuthenticate: wwwAuth.substring(0, 200),
+        }));
+      }
+
+      return isScope;
+    };
+
+    /**
+     * Transform a Generative Language API URL to Cloud Code API URL
+     *
+     * Input:  https://generativelanguage.googleapis.com/v1beta/models/gemini-2.0-flash:generateContent
+     * Output: https://cloudcode-pa.googleapis.com/v1internal:generateContent
+     *
+     * The Cloud Code API uses a different URL structure:
+     * - Model is passed in request body, not URL path
+     * - Method is directly after version: /v1internal:methodName
+     */
+    const transformToCloudCodeUrl = (url: string): string | null => {
+      try {
+        const parsed = new URL(url);
+        if (!parsed.hostname.includes('generativelanguage.googleapis.com')) {
+          log.debug(() => ({
+            message:
+              'url is not generativelanguage api, skipping cloud code transform',
+            hostname: parsed.hostname,
+          }));
+          return null; // Not a Generative Language API URL
+        }
+
+        // Extract the method from the path
+        // Path format: /v1beta/models/gemini-2.0-flash:generateContent
+        const pathMatch = parsed.pathname.match(/:(\w+)$/);
+        if (!pathMatch) {
+          log.debug(() => ({
+            message: 'could not extract method from url path',
+            pathname: parsed.pathname,
+          }));
+          return null; // Can't determine method
+        }
+
+        const method = pathMatch[1];
+        const cloudCodeUrl = `${CLOUD_CODE_ENDPOINT}/${CLOUD_CODE_API_VERSION}:${method}`;
+
+        log.debug(() => ({
+          message: 'transformed url to cloud code api',
+          originalUrl: url.substring(0, 100),
+          method,
+          cloudCodeUrl,
+        }));
+
+        return cloudCodeUrl;
+      } catch (error) {
+        log.debug(() => ({
+          message: 'failed to parse url for cloud code transform',
+          url: url.substring(0, 100),
+          error: String(error),
+        }));
+        return null;
+      }
+    };
+
+    /**
+     * Extract model name from Generative Language API URL
+     *
+     * Input:  https://generativelanguage.googleapis.com/v1beta/models/gemini-2.0-flash:generateContent
+     * Output: gemini-2.0-flash
+     */
+    const extractModelFromUrl = (url: string): string | null => {
+      try {
+        const parsed = new URL(url);
+        // Path format: /v1beta/models/gemini-2.0-flash:generateContent
+        const pathMatch = parsed.pathname.match(/\/models\/([^:]+):/);
+        const model = pathMatch ? pathMatch[1] : null;
+
+        log.debug(() => ({
+          message: 'extracted model from url',
+          pathname: parsed.pathname,
+          model,
+        }));
+
+        return model;
+      } catch (error) {
+        log.debug(() => ({
+          message: 'failed to extract model from url',
+          url: url.substring(0, 100),
+          error: String(error),
+        }));
+        return null;
+      }
+    };
+
+    /**
+     * Transform request body for Cloud Code API
+     *
+     * The Cloud Code API expects requests in this format:
+     * {
+     *   model: "gemini-2.0-flash",
+     *   project: "optional-project-id",
+     *   user_prompt_id: "optional-prompt-id",
+     *   request: { contents: [...], generationConfig: {...}, ... }
+     * }
+     *
+     * The standard AI SDK sends:
+     * { contents: [...], generationConfig: {...}, ... }
+     */
+    const transformRequestBody = (body: string, model: string): string => {
+      try {
+        const parsed = JSON.parse(body);
+
+        // Get project ID from environment if available
+        const projectId =
+          process.env['GOOGLE_CLOUD_PROJECT'] ||
+          process.env['GOOGLE_CLOUD_PROJECT_ID'];
+
+        // Wrap in Cloud Code API format
+        const cloudCodeRequest = {
+          model,
+          ...(projectId && { project: projectId }),
+          request: parsed,
+        };
+
+        log.debug(() => ({
+          message: 'transformed request body for cloud code api',
+          model,
+          hasProjectId: !!projectId,
+          originalBodyLength: body.length,
+          transformedBodyLength: JSON.stringify(cloudCodeRequest).length,
+        }));
+
+        return JSON.stringify(cloudCodeRequest);
+      } catch (error) {
+        log.debug(() => ({
+          message: 'failed to transform request body, using original',
+          error: String(error),
+        }));
+        return body; // Return original if parsing fails
+      }
+    };
+
+    /**
+     * Transform Cloud Code API response to standard format
+     *
+     * Cloud Code API returns:
+     * { response: { candidates: [...], ... }, traceId: "..." }
+     *
+     * Standard API returns:
+     * { candidates: [...], ... }
+     */
+    const transformResponseBody = async (
+      response: Response
+    ): Promise<Response> => {
+      const contentType = response.headers.get('content-type');
+      const isStreaming = contentType?.includes('text/event-stream');
+
+      log.debug(() => ({
+        message: 'transforming cloud code response',
+        status: response.status,
+        contentType,
+        isStreaming,
+      }));
+
+      // For streaming responses, we need to transform each chunk
+      if (isStreaming) {
+        // The Cloud Code API returns SSE with data: { response: {...} } format
+        // We need to transform each chunk to unwrap the response
+        const reader = response.body?.getReader();
+        if (!reader) {
+          log.debug(() => ({
+            message: 'no response body reader available for streaming',
+          }));
+          return response;
+        }
+
+        const encoder = new TextEncoder();
+        const decoder = new TextDecoder();
+        let chunkCount = 0;
+
+        const transformedStream = new ReadableStream({
+          async start(controller) {
+            try {
+              while (true) {
+                const { done, value } = await reader.read();
+                if (done) {
+                  log.debug(() => ({
+                    message: 'streaming response complete',
+                    totalChunks: chunkCount,
+                  }));
+                  controller.close();
+                  break;
+                }
+
+                const text = decoder.decode(value, { stream: true });
+                chunkCount++;
+
+                // Split by SSE event boundaries
+                const events = text.split('\n\n');
+                for (const event of events) {
+                  if (!event.trim()) continue;
+
+                  // Check if this is a data line
+                  if (event.startsWith('data: ')) {
+                    try {
+                      const jsonStr = event.slice(6).trim();
+                      if (jsonStr === '[DONE]') {
+                        controller.enqueue(encoder.encode(event + '\n\n'));
+                        continue;
+                      }
+
+                      const parsed = JSON.parse(jsonStr);
+
+                      // Unwrap Cloud Code response format if present
+                      const unwrapped = parsed.response || parsed;
+                      controller.enqueue(
+                        encoder.encode(
+                          'data: ' + JSON.stringify(unwrapped) + '\n\n'
+                        )
+                      );
+                    } catch {
+                      // If parsing fails, pass through as-is
+                      controller.enqueue(encoder.encode(event + '\n\n'));
+                    }
+                  } else {
+                    // Non-data lines (like event type), pass through
+                    controller.enqueue(encoder.encode(event + '\n\n'));
+                  }
+                }
+              }
+            } catch (error) {
+              log.debug(() => ({
+                message: 'error during streaming response transformation',
+                error: String(error),
+              }));
+              controller.error(error);
+            }
+          },
+        });
+
+        return new Response(transformedStream, {
+          status: response.status,
+          statusText: response.statusText,
+          headers: response.headers,
+        });
+      }
+
+      // For non-streaming responses, parse and unwrap
+      try {
+        const json = await response.json();
+        const unwrapped = json.response || json;
+
+        log.debug(() => ({
+          message: 'unwrapped non-streaming cloud code response',
+          hasResponseWrapper: !!json.response,
+          hasTraceId: !!json.traceId,
+        }));
+
+        return new Response(JSON.stringify(unwrapped), {
+          status: response.status,
+          statusText: response.statusText,
+          headers: response.headers,
+        });
+      } catch (error) {
+        log.debug(() => ({
+          message: 'failed to parse non-streaming response, returning original',
+          error: String(error),
+        }));
+        return response;
+      }
+    };
+
     return {
       apiKey: 'oauth-token-used-via-custom-fetch',
       async fetch(input: RequestInfo | URL, init?: RequestInit) {
         let currentAuth = await getAuth();
-        if (!currentAuth || currentAuth.type !== 'oauth')
+        if (!currentAuth || currentAuth.type !== 'oauth') {
+          log.debug(() => ({
+            message: 'no google oauth credentials, using standard fetch',
+          }));
           return fetch(input, init);
+        }
+
+        log.debug(() => ({
+          message: 'google oauth fetch initiated',
+          hasAccessToken: !!currentAuth?.access,
+          tokenExpiresIn: currentAuth
+            ? Math.round((currentAuth.expires - Date.now()) / 1000)
+            : 0,
+        }));
 
         // Refresh token if expired (with 5 minute buffer)
         const FIVE_MIN_MS = 5 * 60 * 1000;
@@ -1273,7 +1628,12 @@ const GooglePlugin: AuthPlugin = {
           !currentAuth.access ||
           currentAuth.expires < Date.now() + FIVE_MIN_MS
         ) {
-          log.info(() => ({ message: 'refreshing google oauth token' }));
+          log.info(() => ({
+            message: 'refreshing google oauth token',
+            reason: !currentAuth.access
+              ? 'no access token'
+              : 'token expiring soon',
+          }));
           const response = await fetch(GOOGLE_TOKEN_URL, {
             method: 'POST',
             headers: {
@@ -1288,10 +1648,21 @@ const GooglePlugin: AuthPlugin = {
           });
 
           if (!response.ok) {
+            const errorText = await response.text().catch(() => 'unknown');
+            log.error(() => ({
+              message: 'google oauth token refresh failed',
+              status: response.status,
+              error: errorText.substring(0, 200),
+            }));
             throw new Error(`Token refresh failed: ${response.status}`);
           }
 
           const json = await response.json();
+          log.debug(() => ({
+            message: 'google oauth token refreshed successfully',
+            expiresIn: json.expires_in,
+          }));
+
           await Auth.set('google', {
             type: 'oauth',
             // Google doesn't return a new refresh token on refresh
@@ -1307,18 +1678,180 @@ const GooglePlugin: AuthPlugin = {
           };
         }
 
-        // Google API uses Bearer token authentication
+        // Get the original URL
+        const originalUrl =
+          typeof input === 'string'
+            ? input
+            : input instanceof URL
+              ? input.toString()
+              : (input as Request).url;
+
+        log.debug(() => ({
+          message: 'processing google api request',
+          originalUrl: originalUrl.substring(0, 100),
+          method: init?.method || 'GET',
+        }));
+
+        // Try to transform to Cloud Code API URL
+        const cloudCodeUrl = transformToCloudCodeUrl(originalUrl);
+        const model = extractModelFromUrl(originalUrl);
+
+        // If this is a Generative Language API request, route through Cloud Code API
+        if (cloudCodeUrl && model) {
+          log.info(() => ({
+            message: 'routing google oauth request through cloud code api',
+            originalUrl: originalUrl.substring(0, 100) + '...',
+            cloudCodeUrl,
+            model,
+          }));
+
+          // Transform request body to Cloud Code format
+          let body = init?.body;
+          if (typeof body === 'string') {
+            body = transformRequestBody(body, model);
+          }
+
+          // Make request to Cloud Code API with Bearer token
+          const headers: Record<string, string> = {
+            ...(init?.headers as Record<string, string>),
+            Authorization: `Bearer ${currentAuth.access}`,
+            'x-goog-api-client': 'agent/0.6.3',
+          };
+          // Remove any API key header if present since we're using OAuth
+          delete headers['x-goog-api-key'];
+
+          log.debug(() => ({
+            message: 'sending request to cloud code api',
+            url: cloudCodeUrl,
+            hasBody: !!body,
+          }));
+
+          const cloudCodeResponse = await fetch(cloudCodeUrl, {
+            ...init,
+            body,
+            headers,
+          });
+
+          log.debug(() => ({
+            message: 'cloud code api response received',
+            status: cloudCodeResponse.status,
+            statusText: cloudCodeResponse.statusText,
+            contentType: cloudCodeResponse.headers.get('content-type'),
+          }));
+
+          // Check for errors and handle fallback
+          if (!cloudCodeResponse.ok) {
+            // Try to get error details for logging
+            const errorBody = await cloudCodeResponse
+              .clone()
+              .text()
+              .catch(() => 'unknown');
+            log.warn(() => ({
+              message: 'cloud code api returned error',
+              status: cloudCodeResponse.status,
+              statusText: cloudCodeResponse.statusText,
+              errorBody: errorBody.substring(0, 500),
+            }));
+
+            const fallbackApiKey = getFallbackApiKey();
+            if (fallbackApiKey) {
+              log.warn(() => ({
+                message:
+                  'cloud code api error, falling back to api key with standard api',
+                status: cloudCodeResponse.status,
+                fallbackTarget: originalUrl.substring(0, 100),
+              }));
+
+              // Fall back to standard API with API key
+              const apiKeyHeaders: Record<string, string> = {
+                ...(init?.headers as Record<string, string>),
+                'x-goog-api-key': fallbackApiKey,
+              };
+              delete apiKeyHeaders['Authorization'];
+
+              log.debug(() => ({
+                message: 'sending fallback request with api key',
+                url: originalUrl.substring(0, 100),
+              }));
+
+              return fetch(originalUrl, {
+                ...init,
+                headers: apiKeyHeaders,
+              });
+            }
+
+            log.error(() => ({
+              message: 'cloud code api error and no api key fallback available',
+              status: cloudCodeResponse.status,
+              hint: 'Set GOOGLE_GENERATIVE_AI_API_KEY or GEMINI_API_KEY environment variable for fallback',
+            }));
+
+            // No fallback available, return the error response
+            return cloudCodeResponse;
+          }
+
+          log.debug(() => ({
+            message: 'cloud code api request successful, transforming response',
+          }));
+
+          // Transform response back to standard format
+          return transformResponseBody(cloudCodeResponse);
+        }
+
+        // Not a Generative Language API request, use standard OAuth flow
+        log.debug(() => ({
+          message:
+            'not a generative language api request, using standard oauth',
+          url: originalUrl.substring(0, 100),
+        }));
+
         const headers: Record<string, string> = {
           ...(init?.headers as Record<string, string>),
           Authorization: `Bearer ${currentAuth.access}`,
         };
-        // Remove any API key header if present since we're using OAuth
         delete headers['x-goog-api-key'];
 
-        return fetch(input, {
+        const oauthResponse = await fetch(input, {
           ...init,
           headers,
         });
+
+        log.debug(() => ({
+          message: 'standard oauth response received',
+          status: oauthResponse.status,
+        }));
+
+        // Check if OAuth failed due to insufficient scopes
+        if (isScopeError(oauthResponse)) {
+          const fallbackApiKey = getFallbackApiKey();
+          if (fallbackApiKey) {
+            log.warn(() => ({
+              message:
+                'oauth scope error, falling back to api key authentication',
+              hint: 'This should not happen with Cloud Code API routing',
+              url: originalUrl.substring(0, 100),
+            }));
+
+            const apiKeyHeaders: Record<string, string> = {
+              ...(init?.headers as Record<string, string>),
+              'x-goog-api-key': fallbackApiKey,
+            };
+            delete apiKeyHeaders['Authorization'];
+
+            return fetch(input, {
+              ...init,
+              headers: apiKeyHeaders,
+            });
+          } else {
+            log.error(() => ({
+              message: 'oauth scope error and no api key fallback available',
+              hint: 'Set GOOGLE_GENERATIVE_AI_API_KEY or GEMINI_API_KEY environment variable',
+              url: originalUrl.substring(0, 100),
+            }));
+          }
+        }
+
+        return oauthResponse;
       },
     };
   },

package/src/file/ignore.ts

@@ -0,0 +1,30 @@
+export namespace FileIgnore {
+  export const PATTERNS = [
+    '.git',
+    'node_modules',
+    '.DS_Store',
+    '*.log',
+    'dist',
+    'build',
+    '.next',
+    '.nuxt',
+    '.output',
+    '.vercel',
+    '.netlify',
+    'coverage',
+    '.nyc_output',
+    '.cache',
+    '.tmp',
+    'tmp',
+    '*.tmp',
+    '*.swp',
+    '*.swo',
+    '*~',
+    '.env',
+    '.env.local',
+    '.env.*.local',
+    '.vscode',
+    '.idea',
+    '*.tsbuildinfo',
+  ];
+}

package/src/index.js

@@ -247,7 +247,7 @@ async function readSystemMessages(argv) {
 
 async function runAgentMode(argv, request) {
   // Log version and command info in verbose mode using lazy logging
-  Log.Default.lazy.info(() => ({
+  Log.Default.info(() => ({
     message: 'Agent started',
     version: pkg.version,
     command: process.argv.join(' '),
@@ -255,7 +255,7 @@ async function runAgentMode(argv, request) {
     scriptPath: import.meta.path,
   }));
   if (Flag.OPENCODE_DRY_RUN) {
-    Log.Default.lazy.info(() => ({
+    Log.Default.info(() => ({
       message: 'Dry run mode enabled',
       mode: 'dry-run',
     }));
@@ -318,7 +318,7 @@ async function runAgentMode(argv, request) {
 async function runContinuousAgentMode(argv) {
   const compactJson = argv['compact-json'] === true;
   // Log version and command info in verbose mode using lazy logging
-  Log.Default.lazy.info(() => ({
+  Log.Default.info(() => ({
     message: 'Agent started (continuous mode)',
     version: pkg.version,
     command: process.argv.join(' '),
@@ -326,7 +326,7 @@ async function runContinuousAgentMode(argv) {
     scriptPath: import.meta.path,
   }));
   if (Flag.OPENCODE_DRY_RUN) {
-    Log.Default.lazy.info(() => ({
+    Log.Default.info(() => ({
       message: 'Dry run mode enabled',
       mode: 'dry-run',
     }));

package/src/provider/google-cloudcode.ts

@@ -0,0 +1,384 @@
+/**
+ * Google Cloud Code API Client
+ *
+ * This module provides a client for Google's Cloud Code API (cloudcode-pa.googleapis.com),
+ * which is used by the official Gemini CLI for OAuth-authenticated requests.
+ *
+ * The Cloud Code API:
+ * 1. Accepts `cloud-platform` OAuth scope (unlike generativelanguage.googleapis.com)
+ * 2. Handles subscription tier validation (FREE, STANDARD, etc.)
+ * 3. Proxies requests to the Generative Language API internally
+ *
+ * @see https://github.com/google-gemini/gemini-cli/blob/main/packages/core/src/code_assist/server.ts
+ * @see https://github.com/link-assistant/agent/issues/100
+ */
+
+import { Log } from '../util/log';
+import { Auth } from '../auth';
+
+const log = Log.create({ service: 'google-cloudcode' });
+
+// Cloud Code API endpoints (from gemini-cli)
+const CODE_ASSIST_ENDPOINT = 'https://cloudcode-pa.googleapis.com';
+const CODE_ASSIST_API_VERSION = 'v1internal';
+
+// Google OAuth endpoints
+const GOOGLE_TOKEN_URL = 'https://oauth2.googleapis.com/token';
+const GOOGLE_OAUTH_CLIENT_ID =
+  '681255809395-oo8ft2oprdrnp9e3aqf6av3hmdib135j.apps.googleusercontent.com';
+const GOOGLE_OAUTH_CLIENT_SECRET = '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';
+
+/**
+ * User tier from Cloud Code API
+ */
+export enum UserTierId {
+  FREE = 'FREE',
+  STANDARD = 'STANDARD',
+  LEGACY = 'LEGACY',
+}
+
+/**
+ * Cloud Code API request format
+ */
+interface CloudCodeRequest {
+  model: string;
+  project?: string;
+  user_prompt_id?: string;
+  request: {
+    contents: Array<{
+      role: string;
+      parts: Array<{ text?: string; [key: string]: unknown }>;
+    }>;
+    systemInstruction?: {
+      role: string;
+      parts: Array<{ text?: string }>;
+    };
+    tools?: unknown[];
+    toolConfig?: unknown;
+    generationConfig?: {
+      temperature?: number;
+      topP?: number;
+      topK?: number;
+      maxOutputTokens?: number;
+      candidateCount?: number;
+      stopSequences?: string[];
+      responseMimeType?: string;
+      responseSchema?: unknown;
+      thinkingConfig?: {
+        thinkingBudget?: number;
+      };
+    };
+    safetySettings?: unknown[];
+  };
+}
+
+/**
+ * Cloud Code API response format
+ */
+interface CloudCodeResponse {
+  response: {
+    candidates: Array<{
+      content: {
+        role: string;
+        parts: Array<{
+          text?: string;
+          thought?: boolean;
+          functionCall?: unknown;
+          functionResponse?: unknown;
+        }>;
+      };
+      finishReason?: string;
+      safetyRatings?: unknown[];
+    }>;
+    usageMetadata?: {
+      promptTokenCount?: number;
+      candidatesTokenCount?: number;
+      totalTokenCount?: number;
+      thoughtsTokenCount?: number;
+      cachedContentTokenCount?: number;
+    };
+    modelVersion?: string;
+  };
+  traceId?: string;
+}
+
+/**
+ * Load Code Assist response (for user setup)
+ */
+interface LoadCodeAssistResponse {
+  cloudaicompanionProject?: string;
+  currentTier?: {
+    id: UserTierId;
+    name: string;
+    description: string;
+  };
+  allowedTiers?: Array<{
+    id: UserTierId;
+    name: string;
+    description: string;
+    isDefault?: boolean;
+    userDefinedCloudaicompanionProject?: boolean;
+  }>;
+}
+
+/**
+ * Onboard user response (for user setup)
+ */
+interface OnboardUserResponse {
+  done: boolean;
+  response?: {
+    cloudaicompanionProject?: {
+      id: string;
+    };
+  };
+}
+
+/**
+ * Google Cloud Code API client
+ *
+ * This client implements the same API used by the official Gemini CLI.
+ * It wraps OAuth authentication and provides methods for:
+ * - Setting up user (onboarding to FREE/STANDARD tier)
+ * - Generating content (streaming and non-streaming)
+ * - Counting tokens
+ */
+export class CloudCodeClient {
+  private accessToken: string;
+  private refreshToken: string;
+  private tokenExpiry: number;
+  private projectId?: string;
+  private userTier?: UserTierId;
+
+  constructor(
+    private auth: {
+      access: string;
+      refresh: string;
+      expires: number;
+    },
+    projectId?: string
+  ) {
+    this.accessToken = auth.access;
+    this.refreshToken = auth.refresh;
+    this.tokenExpiry = auth.expires;
+    this.projectId = projectId;
+  }
+
+  /**
+   * Refresh the OAuth access token if expired
+   */
+  private async ensureValidToken(): Promise<void> {
+    const FIVE_MIN_MS = 5 * 60 * 1000;
+    if (this.tokenExpiry > Date.now() + FIVE_MIN_MS) {
+      return; // Token is still valid
+    }
+
+    log.info(() => ({
+      message: 'refreshing google oauth token for cloud code',
+    }));
+
+    const response = await fetch(GOOGLE_TOKEN_URL, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/x-www-form-urlencoded',
+      },
+      body: new URLSearchParams({
+        client_id: GOOGLE_OAUTH_CLIENT_ID,
+        client_secret: GOOGLE_OAUTH_CLIENT_SECRET,
+        refresh_token: this.refreshToken,
+        grant_type: 'refresh_token',
+      }),
+    });
+
+    if (!response.ok) {
+      throw new Error(`Token refresh failed: ${response.status}`);
+    }
+
+    const json = await response.json();
+    this.accessToken = json.access_token;
+    this.tokenExpiry = Date.now() + json.expires_in * 1000;
+
+    // Update stored auth
+    await Auth.set('google', {
+      type: 'oauth',
+      refresh: this.refreshToken,
+      access: this.accessToken,
+      expires: this.tokenExpiry,
+    });
+  }
+
+  /**
+   * Make an authenticated request to the Cloud Code API
+   */
+  private async request<T>(
+    method: string,
+    body: unknown,
+    options: { stream?: boolean } = {}
+  ): Promise<T | Response> {
+    await this.ensureValidToken();
+
+    const url = `${CODE_ASSIST_ENDPOINT}/${CODE_ASSIST_API_VERSION}:${method}`;
+
+    const response = await fetch(url, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        Authorization: `Bearer ${this.accessToken}`,
+        'x-goog-api-client': 'agent/0.6.3',
+      },
+      body: JSON.stringify(body),
+    });
+
+    if (!response.ok) {
+      const errorText = await response.text();
+      log.error(() => ({
+        message: 'cloud code api error',
+        status: response.status,
+        error: errorText,
+      }));
+      throw new Error(
+        `Cloud Code API error: ${response.status} - ${errorText}`
+      );
+    }
+
+    if (options.stream) {
+      return response;
+    }
+
+    return response.json() as Promise<T>;
+  }
+
+  /**
+   * Load code assist to check user tier and project
+   */
+  async loadCodeAssist(): Promise<LoadCodeAssistResponse> {
+    const body = {
+      cloudaicompanionProject: this.projectId,
+      metadata: {
+        ideType: 'IDE_UNSPECIFIED',
+        platform: 'PLATFORM_UNSPECIFIED',
+        pluginType: 'GEMINI',
+        duetProject: this.projectId,
+      },
+    };
+
+    return this.request<LoadCodeAssistResponse>('loadCodeAssist', body);
+  }
+
+  /**
+   * Onboard user to a tier (FREE or STANDARD)
+   */
+  async onboardUser(tierId: UserTierId): Promise<OnboardUserResponse> {
+    const body = {
+      tierId,
+      cloudaicompanionProject:
+        tierId === UserTierId.FREE ? undefined : this.projectId,
+      metadata: {
+        ideType: 'IDE_UNSPECIFIED',
+        platform: 'PLATFORM_UNSPECIFIED',
+        pluginType: 'GEMINI',
+        ...(tierId !== UserTierId.FREE && { duetProject: this.projectId }),
+      },
+    };
+
+    return this.request<OnboardUserResponse>('onboardUser', body);
+  }
+
+  /**
+   * Setup user - check tier and onboard if necessary
+   */
+  async setupUser(): Promise<{ projectId?: string; userTier: UserTierId }> {
+    const loadRes = await this.loadCodeAssist();
+
+    // If user already has a tier, use it
+    if (loadRes.currentTier) {
+      this.userTier = loadRes.currentTier.id;
+      this.projectId = loadRes.cloudaicompanionProject || this.projectId;
+      return {
+        projectId: this.projectId,
+        userTier: this.userTier,
+      };
+    }
+
+    // Find the default tier to onboard to
+    let targetTier = UserTierId.FREE;
+    for (const tier of loadRes.allowedTiers || []) {
+      if (tier.isDefault) {
+        targetTier = tier.id;
+        break;
+      }
+    }
+
+    log.info(() => ({ message: 'onboarding user', tier: targetTier }));
+
+    // Poll onboardUser until done
+    let lroRes = await this.onboardUser(targetTier);
+    while (!lroRes.done) {
+      await new Promise((resolve) => setTimeout(resolve, 5000));
+      lroRes = await this.onboardUser(targetTier);
+    }
+
+    this.userTier = targetTier;
+    if (lroRes.response?.cloudaicompanionProject?.id) {
+      this.projectId = lroRes.response.cloudaicompanionProject.id;
+    }
+
+    return {
+      projectId: this.projectId,
+      userTier: this.userTier,
+    };
+  }
+
+  /**
+   * Generate content (non-streaming)
+   */
+  async generateContent(request: CloudCodeRequest): Promise<CloudCodeResponse> {
+    return this.request<CloudCodeResponse>('generateContent', request);
+  }
+
+  /**
+   * Generate content (streaming)
+   */
+  async generateContentStream(request: CloudCodeRequest): Promise<Response> {
+    return this.request<Response>('streamGenerateContent', request, {
+      stream: true,
+    }) as Promise<Response>;
+  }
+
+  /**
+   * Get project ID (may be set during setup)
+   */
+  getProjectId(): string | undefined {
+    return this.projectId;
+  }
+
+  /**
+   * Get user tier
+   */
+  getUserTier(): UserTierId | undefined {
+    return this.userTier;
+  }
+}
+
+/**
+ * Create a Cloud Code client from stored Google OAuth credentials
+ */
+export async function createCloudCodeClient(): Promise<CloudCodeClient | null> {
+  const auth = await Auth.get('google');
+  if (!auth || auth.type !== 'oauth') {
+    return null;
+  }
+
+  const projectId =
+    process.env['GOOGLE_CLOUD_PROJECT'] ||
+    process.env['GOOGLE_CLOUD_PROJECT_ID'];
+
+  return new CloudCodeClient(auth, projectId);
+}
+
+/**
+ * Check if Cloud Code API is available (user has OAuth credentials)
+ */
+export async function isCloudCodeAvailable(): Promise<boolean> {
+  const auth = await Auth.get('google');
+  return auth?.type === 'oauth';
+}