feat: centralize maxAttempts configuration via ExperimentFlags

This commit centralizes the retry attempt limits to be driven by the `ExperimentFlags.MAX_ATTEMPTS` flag or the user configuration, rather than being hardcoded throughout the codebase. The retry logic in `baseLlmClient`, `geminiChat`, `client`, and `web-fetch` has been updated to retrieve the `maxAttempts` setting directly from `Config`. It also addresses the removal of the previous 10-attempt cap in the Config initialization to allow tests simulating high retry limits to pass successfully.

Author: yunaseoul

packages/core/src/code_assist/experiments/flagNames.ts

@@ -20,6 +20,7 @@ export const ExperimentFlags = {
   PRO_MODEL_NO_ACCESS: 45768879,
   GEMINI_3_1_FLASH_LITE_LAUNCHED: 45771641,
   DEFAULT_REQUEST_TIMEOUT: 45773134,
+  MAX_ATTEMPTS: 45774515,
 } as const;
 
 export type ExperimentFlagName =

packages/core/src/config/config.test.ts

@@ -20,7 +20,6 @@ import {
   type SandboxConfig,
 } from './config.js';
 import { createMockSandboxConfig } from '@google/gemini-cli-test-utils';
-import { DEFAULT_MAX_ATTEMPTS } from '../utils/retry.js';
 import { ExperimentFlags } from '../code_assist/experiments/flagNames.js';
 import { debugLogger } from '../utils/debugLogger.js';
 import { ApprovalMode } from '../policy/types.js';
@@ -285,25 +284,25 @@ describe('Server Config (config.ts)', () => {
   };
 
   describe('maxAttempts', () => {
-    it('should default to DEFAULT_MAX_ATTEMPTS', () => {
+    it('should default to 10', () => {
       const config = new Config(baseParams);
-      expect(config.getMaxAttempts()).toBe(DEFAULT_MAX_ATTEMPTS);
+      expect(config.getMaxAttempts()).toBe(10);
     });
 
-    it('should use provided maxAttempts if <= DEFAULT_MAX_ATTEMPTS', () => {
+    it('should use provided maxAttempts if <= 10', () => {
       const config = new Config({
         ...baseParams,
         maxAttempts: 5,
       });
       expect(config.getMaxAttempts()).toBe(5);
     });
 
-    it('should cap maxAttempts at DEFAULT_MAX_ATTEMPTS', () => {
+    it('should use provided maxAttempts if > 10', () => {
       const config = new Config({
         ...baseParams,
         maxAttempts: 20,
       });
-      expect(config.getMaxAttempts()).toBe(DEFAULT_MAX_ATTEMPTS);
+      expect(config.getMaxAttempts()).toBe(20);
     });
   });
 

packages/core/src/config/config.ts

@@ -1326,10 +1326,7 @@ export class Config implements McpContext, AgentLoopContext {
     this.agentSessionNoninteractiveEnabled =
       params.adk?.agentSessionNoninteractiveEnabled ?? false;
     this.retryFetchErrors = params.retryFetchErrors ?? true;
-    this.maxAttempts = Math.min(
-      params.maxAttempts ?? DEFAULT_MAX_ATTEMPTS,
-      DEFAULT_MAX_ATTEMPTS,
-    );
+    this.maxAttempts = params.maxAttempts ?? DEFAULT_MAX_ATTEMPTS;
     this.disableYoloMode = params.disableYoloMode ?? false;
     this.rawOutput = params.rawOutput ?? false;
     this.acceptRawOutputRisk = params.acceptRawOutputRisk ?? false;
@@ -3309,6 +3306,14 @@ export class Config implements McpContext, AgentLoopContext {
   }
 
   getMaxAttempts(): number {
+    const flagVal =
+      this.experiments?.flags?.[ExperimentFlags.MAX_ATTEMPTS]?.intValue;
+    if (flagVal !== undefined) {
+      const parsed = parseInt(flagVal, 10);
+      if (!isNaN(parsed) && parsed > 0) {
+        return parsed;
+      }
+    }
     return this.maxAttempts;
   }
 

packages/core/src/core/baseLlmClient.test.ts

@@ -252,7 +252,7 @@ describe('BaseLlmClient', () => {
       expect(retryWithBackoff).toHaveBeenCalledWith(
         expect.any(Function),
         expect.objectContaining({
-          maxAttempts: 5,
+          maxAttempts: 3,
         }),
       );
     });

packages/core/src/core/baseLlmClient.ts

@@ -36,8 +36,6 @@ import {
   createAvailabilityContextProvider,
 } from '../availability/policyHelpers.js';
 
-const DEFAULT_MAX_ATTEMPTS = 5;
-
 /**
  * Options for the generateJson utility function.
  */
@@ -328,7 +326,9 @@ export class BaseLlmClient {
       return await retryWithBackoff(apiCall, {
         shouldRetryOnContent,
         maxAttempts:
-          availabilityMaxAttempts ?? maxAttempts ?? DEFAULT_MAX_ATTEMPTS,
+          availabilityMaxAttempts ??
+          maxAttempts ??
+          this.config.getMaxAttempts(),
         getAvailabilityContext,
         onPersistent429: this.config.isInteractive()
           ? (authType, error) =>
@@ -339,7 +339,9 @@ export class BaseLlmClient {
         retryFetchErrors: this.config.getRetryFetchErrors(),
         onRetry: (attempt, error, delayMs) => {
           const actualMaxAttempts =
-            availabilityMaxAttempts ?? maxAttempts ?? DEFAULT_MAX_ATTEMPTS;
+            availabilityMaxAttempts ??
+            maxAttempts ??
+            this.config.getMaxAttempts();
           const modelName = getDisplayString(currentModel);
           const errorType = getRetryErrorType(error);
 

packages/core/src/core/client.ts

@@ -1133,7 +1133,7 @@ export class GeminiClient {
         onPersistent429: onPersistent429Callback,
         onValidationRequired: onValidationRequiredCallback,
         authType: this.config.getContentGeneratorConfig()?.authType,
-        maxAttempts: availabilityMaxAttempts,
+        maxAttempts: availabilityMaxAttempts ?? this.config.getMaxAttempts(),
         retryFetchErrors: this.config.getRetryFetchErrors(),
         getAvailabilityContext,
         onRetry: (attempt, error, delayMs) => {

packages/core/src/core/geminiChat.test.ts

@@ -176,7 +176,7 @@ describe('GeminiChat', () => {
       },
       getContentGenerator: vi.fn().mockReturnValue(mockContentGenerator),
       getRetryFetchErrors: vi.fn().mockReturnValue(false),
-      getMaxAttempts: vi.fn().mockReturnValue(10),
+      getMaxAttempts: vi.fn().mockReturnValue(4),
       getUserTier: vi.fn().mockReturnValue(undefined),
       modelConfigService: {
         getResolvedConfig: vi.fn().mockImplementation((modelConfigKey) => {

packages/core/src/core/geminiChat.ts

@@ -78,16 +78,13 @@ export type StreamEvent =
  * Options for retrying mid-stream errors (e.g. invalid content or API disconnects).
  */
 interface MidStreamRetryOptions {
-  /** Total number of attempts to make (1 initial + N retries). */
-  maxAttempts: number;
   /** The base delay in milliseconds for backoff. */
   initialDelayMs: number;
   /** Whether to use exponential backoff instead of linear. */
   useExponentialBackoff: boolean;
 }
 
 const MID_STREAM_RETRY_OPTIONS: MidStreamRetryOptions = {
-  maxAttempts: 4, // 1 initial call + 3 retries mid-stream
   initialDelayMs: 1000,
   useExponentialBackoff: true,
 };
@@ -420,10 +417,8 @@ export class GeminiChat {
               : getRetryErrorType(error);
 
             if (isContentError || (isRetryable && !signal.aborted)) {
-              // The issue requests exactly 3 retries (4 attempts) for API errors during stream iteration.
-              // Regardless of the global maxAttempts (e.g. 10), we only want to retry these mid-stream API errors
-              // up to 3 times before finally throwing the error to the user.
-              const maxMidStreamAttempts = MID_STREAM_RETRY_OPTIONS.maxAttempts;
+              // We retry mid-stream API errors up to maxAttempts times before finally throwing the error to the user.
+              const maxMidStreamAttempts = this.context.config.getMaxAttempts();
 
               if (
                 attempt < maxAttempts - 1 &&

packages/core/src/tools/web-fetch.ts

@@ -309,6 +309,7 @@ class WebFetchToolInvocation extends BaseToolInvocation<
         return res;
       },
       {
+        maxAttempts: this.context.config.getMaxAttempts(),
         retryFetchErrors: this.context.config.getRetryFetchErrors(),
         onRetry: (attempt, error, delayMs) =>
           this.handleRetry(attempt, error, delayMs),
@@ -643,6 +644,7 @@ ${aggregatedContent}
           return res;
         },
         {
+          maxAttempts: this.context.config.getMaxAttempts(),
           retryFetchErrors: this.context.config.getRetryFetchErrors(),
           onRetry: (attempt, error, delayMs) =>
             this.handleRetry(attempt, error, delayMs),

packages/core/src/utils/retry.ts

@@ -17,25 +17,48 @@ import { getErrorStatus, ModelNotFoundError } from './httpErrors.js';
 import type { RetryAvailabilityContext } from '../availability/modelPolicy.js';
 
 export type { RetryAvailabilityContext };
+
+/**
+ * Global fallback for maximum retry attempts when not explicitly provided.
+ * Most callers should use config.getMaxAttempts() instead.
+ */
 export const DEFAULT_MAX_ATTEMPTS = 10;
 
+/**
+ * Options for the retryWithBackoff utility.
+ */
 export interface RetryOptions {
+  /**
+   * Total number of attempts (1 initial + N retries).
+   * Defaults to DEFAULT_MAX_ATTEMPTS (10) if not specified.
+   */
   maxAttempts: number;
+  /** Initial delay between retries in milliseconds. */
   initialDelayMs: number;
+  /** Maximum cumulative delay in milliseconds. */
   maxDelayMs: number;
+  /** Callback to determine if an error is retryable. */
   shouldRetryOnError: (error: Error, retryFetchErrors?: boolean) => boolean;
+  /** Callback to determine if the response content requires a retry. */
   shouldRetryOnContent?: (content: GenerateContentResponse) => boolean;
+  /** Handler for persistent 429 errors. */
   onPersistent429?: (
     authType?: string,
     error?: unknown,
   ) => Promise<string | boolean | null>;
+  /** Handler for quota validation requirements. */
   onValidationRequired?: (
     error: ValidationRequiredError,
   ) => Promise<'verify' | 'change_auth' | 'cancel'>;
+  /** Authentication type for logging. */
   authType?: string;
+  /** Whether to retry on generic fetch errors. */
   retryFetchErrors?: boolean;
+  /** Signal for cancellation. */
   signal?: AbortSignal;
+  /** Context provider for availability checks. */
   getAvailabilityContext?: () => RetryAvailabilityContext | undefined;
+  /** Callback fired on each retry attempt. */
   onRetry?: (attempt: number, error: unknown, delayMs: number) => void;
 }