feat: raise default per-step LLM retry budget to 10 attempts (#1740)

* feat: raise default per-step LLM retry budget to 10 attempts

The default of 3 attempts only produced ~1.5s of backoff (0.5s/1s), so
sustained provider overload (429) surfaced to the user almost
immediately. With 10 attempts the exponential ramp (500ms base, x2,
32s cap, 25% jitter) waits out multi-minute overload windows before
failing the turn. Applies to both agent-core (chatWithRetry) and
agent-core-v2 (stepRetry service); loop_control.max_retries_per_step
still overrides.

* test(agent-core): pin retry-dependent tests to the new default budget

- error-paths: the warn-log attempt field now reads 1/10 with the
  default 10-attempt budget
- goal-session pause tests: every LLM call throws a retryable error, so
  the default 10-attempt backoff (~2min) blew the 5s test timeout; pin
  maxRetriesPerStep=1 since the pause behavior does not depend on the
  retry count

Author: sailist

.changeset/default-step-retries-10.md

@@ -0,0 +1,5 @@
+---
+"@moonshot-ai/kimi-code": patch
+---
+
+Increase the default per-step LLM retry budget from 3 to 10 attempts, so transient provider failures (429 / overload) are retried with exponential backoff for a few minutes before the turn fails. Tune with `loop_control.max_retries_per_step` in config.toml.

docs/en/configuration/config-files.md

@@ -52,7 +52,7 @@ effort = "high"
 keep = "all"
 
 [loop_control]
-max_retries_per_step = 3
+max_retries_per_step = 10
 reserved_context_size = 50000
 
 [background]
@@ -198,7 +198,7 @@ You can also switch models temporarily without touching the config file — by s
 | Field | Type | Default | Description |
 | --- | --- | --- | --- |
 | `max_steps_per_turn` | `integer` | — | Maximum steps per turn; unset or `0` means unlimited |
-| `max_retries_per_step` | `integer` | `3` | Maximum retries after a step failure |
+| `max_retries_per_step` | `integer` | `10` | Maximum retries after a step failure |
 | `reserved_context_size` | `integer` | — | Number of tokens reserved for model output; automatic compaction is triggered when the remaining context window falls below this value |
 
 ## `background`

docs/zh/configuration/config-files.md

@@ -52,7 +52,7 @@ effort = "high"
 keep = "all"
 
 [loop_control]
-max_retries_per_step = 3
+max_retries_per_step = 10
 reserved_context_size = 50000
 
 [background]
@@ -198,7 +198,7 @@ display_name = "Kimi for Coding (custom)"
 | 字段 | 类型 | 默认值 | 说明 |
 | --- | --- | --- | --- |
 | `max_steps_per_turn` | `integer` | — | 单轮最大步数；不设或设为 `0` 则无上限 |
-| `max_retries_per_step` | `integer` | `3` | 单步失败后的最大重试次数 |
+| `max_retries_per_step` | `integer` | `10` | 单步失败后的最大重试次数 |
 | `reserved_context_size` | `integer` | — | 预留给模型输出的 token 数；上下文窗口剩余量低于此值时触发自动压缩 |
 
 ## `background`

packages/agent-core-v2/src/_base/utils/retry.ts

@@ -6,7 +6,11 @@
 
 import { abortable } from '#/_base/utils/abort';
 
-export const DEFAULT_MAX_RETRY_ATTEMPTS = 3;
+// Default retry budget per step: 10 attempts (9 retries). Kept in sync with
+// v1 (`agent-core/loop/retry.ts`): the exponential ramp below climbs 0.5s,
+// 1s, 2s … up to the 32s cap, giving roughly 2–3 minutes of total wait to
+// ride out a typical provider overload window (sustained 429s).
+export const DEFAULT_MAX_RETRY_ATTEMPTS = 10;
 
 const BASE_DELAY_MS = 500;
 const MAX_DELAY_MS = 32_000;

packages/agent-core-v2/test/agent/stepRetry/stepRetry.test.ts

@@ -70,7 +70,7 @@ describe('stepRetry plugin', () => {
           step: 1,
           failedAttempt: 1,
           nextAttempt: 2,
-          maxAttempts: 3,
+          maxAttempts: 10,
           delayMs: expect.any(Number),
           errorName: 'APIConnectionError',
           errorMessage: 'terminated',
@@ -102,11 +102,11 @@ describe('stepRetry plugin', () => {
     const result = await runTurn(1);
 
     expect(result.type).toBe('failed');
-    expect(calls).toBe(3);
-    expect(rpcEvents('turn.step.retrying')).toHaveLength(2);
+    expect(calls).toBe(10);
+    expect(rpcEvents('turn.step.retrying')).toHaveLength(9);
     expect(rpcEvents('turn.step.interrupted')).toEqual([
       expect.objectContaining({
-        args: expect.objectContaining({ reason: 'error', step: 3 }),
+        args: expect.objectContaining({ reason: 'error', step: 10 }),
       }),
     ]);
   });
@@ -221,7 +221,7 @@ describe('stepRetry plugin', () => {
 
     const first = await runTurn(1);
     expect(first.type).toBe('failed');
-    expect(calls).toBe(3);
+    expect(calls).toBe(10);
 
     failing = false;
     const second = await runTurn(2);

packages/agent-core/src/loop/retry.ts

@@ -7,14 +7,17 @@ import type { LoopEventDispatcher } from './events';
 import { isAbortError } from './errors';
 import type { LLM, LLMChatParams, LLMChatResponse } from './llm';
 
-export const DEFAULT_MAX_RETRY_ATTEMPTS = 3;
+// Default retry budget per step: 10 attempts (9 retries). With the
+// exponential ramp below the backoff climbs 0.5s, 1s, 2s … up to the 32s
+// cap, giving roughly 2–3 minutes of total wait — enough to ride out a
+// typical provider overload window (sustained 429s) instead of surfacing
+// the error after a couple of quick retries.
+export const DEFAULT_MAX_RETRY_ATTEMPTS = 10;
 
 const BASE_DELAY_MS = 500;
-// Per-attempt backoff cap (32s). With the default 3 attempts the ramp
-// (0.5s, 1s) never reaches the cap, so interactive runs are unaffected; it
-// only matters for high-attempt configs (e.g. eval harnesses with
-// `max_retries_per_step = 10`), where it lets retries ride out multi-minute
-// provider overload instead of giving up after a few seconds of backoff.
+// Per-attempt backoff cap (32s). The default 10-attempt ramp reaches the
+// cap on the 7th retry, so most of the budget is spent at the cap waiting
+// out multi-minute provider overload.
 const MAX_DELAY_MS = 32_000;
 const RETRY_FACTOR = 2;
 // Up to 25% jitter on top of the exponential base to avoid herd retries.

packages/agent-core/test/agent/turn.test.ts

@@ -2107,7 +2107,7 @@ describe('Agent turn flow', () => {
     const payloads = requestLogs.map((entry) => entry.payload as Record<string, unknown>);
     expect(payloads[0]).toMatchObject({ turnStep: '0.1' });
     expect(payloads[0]).not.toHaveProperty('attempt');
-    expect(payloads[1]).toMatchObject({ turnStep: '0.1', attempt: '2/3' });
+    expect(payloads[1]).toMatchObject({ turnStep: '0.1', attempt: '2/10' });
   });
 
   it('force-refreshes OAuth credentials on video upload 401 and surfaces the provider auth error when replay 401', async () => {

packages/agent-core/test/harness/goal-session.test.ts

@@ -478,9 +478,19 @@ describe('goal session end-to-end', () => {
   it('pauses the goal on provider rate limits', async () => {
     const sessionDir = await makeTempDir();
     const events: Array<Record<string, unknown>> = [];
-    const { session, agent } = await setupSession(sessionDir, events, ['GetGoal'], async () => {
-      throw new APIStatusError(429, 'Rate limited', 'req-429');
-    });
+    // Pin the retry budget to 1 attempt: the pause behavior under test does
+    // not depend on retries, and the default 10-attempt backoff would blow
+    // the test timeout.
+    const { session, agent } = await setupSession(
+      sessionDir,
+      events,
+      ['GetGoal'],
+      async () => {
+        throw new APIStatusError(429, 'Rate limited', 'req-429');
+      },
+      undefined,
+      { providers: {}, loopControl: { maxRetriesPerStep: 1 } },
+    );
     const api = new SessionAPIImpl(session);
     await api.createGoal({ agentId: 'main', objective: 'work' });
 
@@ -495,9 +505,19 @@ describe('goal session end-to-end', () => {
   it('pauses the goal on provider connection errors', async () => {
     const sessionDir = await makeTempDir();
     const events: Array<Record<string, unknown>> = [];
-    const { session, agent } = await setupSession(sessionDir, events, ['GetGoal'], async () => {
-      throw new APIConnectionError('socket hang up');
-    });
+    // Pin the retry budget to 1 attempt: the pause behavior under test does
+    // not depend on retries, and the default 10-attempt backoff would blow
+    // the test timeout.
+    const { session, agent } = await setupSession(
+      sessionDir,
+      events,
+      ['GetGoal'],
+      async () => {
+        throw new APIConnectionError('socket hang up');
+      },
+      undefined,
+      { providers: {}, loopControl: { maxRetriesPerStep: 1 } },
+    );
     const api = new SessionAPIImpl(session);
     await api.createGoal({ agentId: 'main', objective: 'work' });
 

packages/agent-core/test/loop/error-paths.e2e.test.ts

@@ -58,7 +58,7 @@ describe('runTurn — error paths', () => {
         message: 'llm request failed',
         payload: {
           turnStep: 'turn-1.1',
-          attempt: '1/3',
+          attempt: '1/10',
           model: 'fake-model',
           errorName: 'Error',
           errorMessage: 'upstream blew up',

packages/agent-core/test/loop/retry.test.ts

@@ -9,7 +9,7 @@ import { describe, expect, it } from 'vitest';
 import type { KimiConfig } from '#/config';
 import { ErrorCodes, KimiError } from '#/errors';
 import type { LLM, LLMChatParams, LLMChatResponse } from '#/loop/llm';
-import { chatWithRetry, retryBackoffDelays } from '#/loop/retry';
+import { chatWithRetry, DEFAULT_MAX_RETRY_ATTEMPTS, retryBackoffDelays } from '#/loop/retry';
 import { ProviderManager } from '#/session/provider-manager';
 
 function okResponse(): LLMChatResponse {
@@ -57,7 +57,7 @@ describe('chatWithRetry: terminated stream drops', () => {
 
     expect(seenFields).toEqual([
       { projection: 'strict', turnStep: 't.1' },
-      { projection: 'strict', turnStep: 't.1', attempt: '2/3' },
+      { projection: 'strict', turnStep: 't.1', attempt: '2/10' },
     ]);
   });
 
@@ -168,7 +168,7 @@ describe('retryBackoffDelays', () => {
     expect(maxSeen).toBeGreaterThan(30_000);
   });
 
-  it('keeps default-attempt retries quick so interactive runs are not slowed', () => {
+  it('keeps low-attempt configs quick so latency-sensitive runs are not slowed', () => {
     // 3 attempts -> 2 delays at the bottom of the ramp (~0.5s / ~1s before
     // jitter); their sum stays small.
     const delays = retryBackoffDelays(3);
@@ -177,6 +177,39 @@ describe('retryBackoffDelays', () => {
   });
 });
 
+describe('chatWithRetry: default retry budget', () => {
+  it('retries up to DEFAULT_MAX_RETRY_ATTEMPTS before giving up', async () => {
+    // A sustained 429 carries a 1ms server retry-after so the test exercises
+    // the full default budget without sleeping through the real backoff.
+    let calls = 0;
+    const captured: Array<{ type: string }> = [];
+    const llm: LLM = {
+      systemPrompt: '',
+      modelName: 'mock',
+      isRetryableError: (e) => isRetryableGenerateError(e),
+      async chat(): Promise<LLMChatResponse> {
+        calls += 1;
+        throw new APIProviderRateLimitError('rate limited', null, 1);
+      },
+    };
+    const input = makeInput(llm, new AbortController().signal);
+
+    await expect(
+      chatWithRetry({
+        ...input,
+        dispatchEvent: async (event) => {
+          captured.push(event as { type: string });
+        },
+      }),
+    ).rejects.toMatchObject({ name: 'APIProviderRateLimitError' });
+
+    expect(calls).toBe(DEFAULT_MAX_RETRY_ATTEMPTS);
+    expect(captured.filter((e) => e.type === 'step.retrying')).toHaveLength(
+      DEFAULT_MAX_RETRY_ATTEMPTS - 1,
+    );
+  });
+});
+
 describe('chatWithRetry: honors server retry-after', () => {
   it('uses the error retryAfterMs as the retry delay instead of the backoff', async () => {
     let calls = 0;