Handle nested AI retry errors

Author: jahooma

common/src/util/__tests__/error-api-details.test.ts

@@ -0,0 +1,35 @@
+import { describe, expect, it } from 'bun:test'
+
+import { extractApiErrorDetails } from '../error'
+
+describe('extractApiErrorDetails', () => {
+  it('extracts structured details from nested retry errors', () => {
+    const apiError = new Error('Conflict') as Error & {
+      statusCode: number
+      responseBody: string
+    }
+    apiError.statusCode = 409
+    apiError.responseBody = JSON.stringify({
+      error: 'session_superseded',
+      message:
+        'Another instance of freebuff has taken over this session. Only one instance per account is allowed.',
+    })
+
+    const retryError = new Error(
+      'Failed after 4 attempts. Last error: Conflict',
+    ) as Error & {
+      lastError: unknown
+      errors: unknown[]
+    }
+    retryError.name = 'AI_RetryError'
+    retryError.lastError = apiError
+    retryError.errors = [apiError]
+
+    expect(extractApiErrorDetails(retryError)).toEqual({
+      statusCode: 409,
+      errorCode: 'session_superseded',
+      message:
+        'Another instance of freebuff has taken over this session. Only one instance per account is allowed.',
+    })
+  })
+})

common/src/util/error.ts

@@ -254,6 +254,93 @@ export function parseApiErrorResponseBody(responseBody: unknown): {
   }
 }
 
+export type ApiErrorDetails = ReturnType<typeof parseApiErrorResponseBody> & {
+  statusCode?: number
+}
+
+function getApiErrorCandidates(
+  error: unknown,
+  seen = new Set<object>(),
+): unknown[] {
+  if (!error || typeof error !== 'object') return [error]
+  if (seen.has(error)) return []
+  seen.add(error)
+
+  const candidates: unknown[] = [error]
+  const errorWithNested = error as {
+    lastError?: unknown
+    errors?: unknown[]
+    cause?: unknown
+  }
+
+  candidates.push(...getApiErrorCandidates(errorWithNested.lastError, seen))
+
+  if (Array.isArray(errorWithNested.errors)) {
+    for (const nestedError of [...errorWithNested.errors].reverse()) {
+      candidates.push(...getApiErrorCandidates(nestedError, seen))
+    }
+  }
+
+  candidates.push(...getApiErrorCandidates(errorWithNested.cause, seen))
+
+  return candidates
+}
+
+function getApiErrorStatusCode(error: unknown): number | undefined {
+  if (!error || typeof error !== 'object') return undefined
+
+  if ('statusCode' in error) {
+    const statusCode = (error as { statusCode: unknown }).statusCode
+    if (typeof statusCode === 'number') return statusCode
+  }
+
+  if ('status' in error) {
+    const status = (error as { status: unknown }).status
+    if (typeof status === 'number') return status
+  }
+
+  return undefined
+}
+
+function getApiErrorResponseBody(error: unknown): unknown {
+  if (!error || typeof error !== 'object') return undefined
+  if (!('responseBody' in error)) return undefined
+  return (error as { responseBody: unknown }).responseBody
+}
+
+function hasParsedApiErrorDetails(
+  details: ReturnType<typeof parseApiErrorResponseBody>,
+): boolean {
+  return (
+    details.errorCode !== undefined ||
+    details.message !== undefined ||
+    details.countryCode !== undefined ||
+    details.countryBlockReason !== undefined ||
+    details.ipPrivacySignals !== undefined
+  )
+}
+
+/**
+ * Extracts HTTP status and structured server error fields from API errors,
+ * including AI SDK RetryError wrappers whose useful APICallError is nested in
+ * `lastError` / `errors`.
+ */
+export function extractApiErrorDetails(error: unknown): ApiErrorDetails {
+  for (const candidate of getApiErrorCandidates(error)) {
+    const statusCode = getApiErrorStatusCode(candidate)
+    const parsed = parseApiErrorResponseBody(getApiErrorResponseBody(candidate))
+
+    if (statusCode !== undefined || hasParsedApiErrorDetails(parsed)) {
+      return {
+        ...parsed,
+        ...(statusCode !== undefined && { statusCode }),
+      }
+    }
+  }
+
+  return {}
+}
+
 // Extended error properties that various libraries add to Error objects
 interface ExtendedErrorProperties {
   status?: number
@@ -330,9 +417,7 @@ export function getErrorObject(
           ? extError.statusCode
           : undefined,
       code: typeof extError.code === 'string' ? extError.code : undefined,
-      rawError: options.includeRawError
-        ? safeStringify(error)
-        : undefined,
+      rawError: options.includeRawError ? safeStringify(error) : undefined,
       // API error fields
       responseBody,
       url: typeof extError.url === 'string' ? extError.url : undefined,

packages/agent-runtime/src/__tests__/loop-agent-steps.test.ts

@@ -1,9 +1,7 @@
 import * as analytics from '@codebuff/common/analytics'
 import { TEST_USER_ID } from '@codebuff/common/old-constants'
 import { createTestAgentRuntimeParams } from '@codebuff/common/testing/fixtures/agent-runtime'
-import {
-  clearMockedModules,
-} from '@codebuff/common/testing/mock-modules'
+import { clearMockedModules } from '@codebuff/common/testing/mock-modules'
 import { setupDbSpies } from '@codebuff/common/testing/mocks/database'
 import { getInitialSessionState } from '@codebuff/common/types/session-state'
 import { AbortError, promptSuccess } from '@codebuff/common/util/error'
@@ -20,7 +18,7 @@ import {
   mock,
   spyOn,
 } from 'bun:test'
-import { APICallError } from 'ai'
+import { APICallError, RetryError } from 'ai'
 import { z } from 'zod/v4'
 
 import { loopAgentSteps } from '../run-agent-step'
@@ -661,13 +659,15 @@ describe('loopAgentSteps - runAgentStep vs runProgrammaticStep behavior', () =>
     // Mock promptAiSdk to capture the n parameter
     loopAgentStepsBaseParams.promptAiSdk = async (params: any) => {
       agentStepN = params.n
-      return promptSuccess(JSON.stringify([
-        'Response 1',
-        'Response 2',
-        'Response 3',
-        'Response 4',
-        'Response 5',
-      ]))
+      return promptSuccess(
+        JSON.stringify([
+          'Response 1',
+          'Response 2',
+          'Response 3',
+          'Response 4',
+          'Response 5',
+        ]),
+      )
     }
 
     await loopAgentSteps({
@@ -972,7 +972,9 @@ describe('loopAgentSteps - runAgentStep vs runProgrammaticStep behavior', () =>
       expect(result.output.type).toBe('error')
       if (result.output.type === 'error') {
         // Should use the server's message, NOT the generic "Forbidden"
-        expect(result.output.message).toBe('Free mode is not available in your country.')
+        expect(result.output.message).toBe(
+          'Free mode is not available in your country.',
+        )
         // Should NOT have the 'Agent run error: ' prefix since message came from responseBody
         expect(result.output.message).not.toContain('Agent run error:')
         // Should propagate the error code so the CLI can match on it
@@ -1022,5 +1024,53 @@ describe('loopAgentSteps - runAgentStep vs runProgrammaticStep behavior', () =>
         expect(result.output.error).toBeUndefined()
       }
     })
+
+    it('should unwrap retry errors to propagate underlying 409 gate errors', async () => {
+      const llmOnlyTemplate = {
+        ...mockTemplate,
+        handleSteps: undefined,
+      }
+
+      const localAgentTemplates = {
+        'test-agent': llmOnlyTemplate,
+      }
+
+      const apiError = new APICallError({
+        statusCode: 409,
+        message: 'Conflict',
+        url: 'https://api.codebuff.com/v1/chat/completions',
+        requestBodyValues: {},
+        responseBody: JSON.stringify({
+          error: 'session_superseded',
+          message:
+            'Another instance of freebuff has taken over this session. Only one instance per account is allowed.',
+        }),
+        isRetryable: true,
+      })
+
+      loopAgentStepsBaseParams.promptAiSdkStream = async function* () {
+        throw new RetryError({
+          message: 'Failed after 4 attempts. Last error: Conflict',
+          reason: 'maxRetriesExceeded',
+          errors: [apiError],
+        })
+      }
+
+      const result = await loopAgentSteps({
+        ...loopAgentStepsBaseParams,
+        agentType: 'test-agent',
+        localAgentTemplates,
+      })
+
+      expect(result.output.type).toBe('error')
+      if (result.output.type === 'error') {
+        expect(result.output.message).toBe(
+          'Another instance of freebuff has taken over this session. Only one instance per account is allowed.',
+        )
+        expect(result.output.message).not.toContain('Agent run error:')
+        expect(result.output.error).toBe('session_superseded')
+        expect(result.output.statusCode).toBe(409)
+      }
+    })
   })
 })