feat(sdk): add retry logic with exponential backoff and disable AI SDK

retries

- Add SDK-level retry wrapper with exponential backoff (up to 3
attempts) - Add onRetry and onRetryExhausted callbacks for observability
- Convert prompt errors to NetworkError with proper error codes for
retry detection - Add comprehensive logging for all retry attempts and
outcomes

Author: brandonkachen

sdk/src/__tests__/run-with-retry.test.ts

@@ -0,0 +1,131 @@
+import { afterEach, describe, expect, it, mock, spyOn } from 'bun:test'
+
+import { ErrorCodes, NetworkError } from '../errors'
+import { run } from '../run'
+import * as runModule from '../run'
+
+import type { RunState } from '../run-state'
+
+const baseOptions = {
+  apiKey: 'test-key',
+  fingerprintId: 'fp',
+  agent: 'base',
+  prompt: 'hi',
+} as const
+
+describe('run retry wrapper', () => {
+  afterEach(() => {
+    mock.restore()
+  })
+
+  it('returns immediately on success without retrying', async () => {
+    const expectedState = { output: { type: 'success' } } as RunState
+    const runSpy = spyOn(runModule, 'runOnce').mockResolvedValueOnce(expectedState)
+
+    const result = await run(baseOptions)
+
+    expect(result).toBe(expectedState)
+    expect(runSpy).toHaveBeenCalledTimes(1)
+  })
+
+  it('retries once on retryable network error and then succeeds', async () => {
+    const expectedState = { output: { type: 'success' } } as RunState
+    const runSpy = spyOn(runModule, 'runOnce')
+      .mockRejectedValueOnce(
+        new NetworkError('temporary', ErrorCodes.NETWORK_ERROR),
+      )
+      .mockResolvedValueOnce(expectedState)
+
+    const result = await run({
+      ...baseOptions,
+      retry: { backoffBaseMs: 1, backoffMaxMs: 2 },
+    })
+
+    expect(result).toBe(expectedState)
+    expect(runSpy).toHaveBeenCalledTimes(2)
+  })
+
+  it('stops after max retries are exhausted', async () => {
+    const runSpy = spyOn(runModule, 'runOnce').mockRejectedValue(
+      new NetworkError('offline', ErrorCodes.NETWORK_ERROR),
+    )
+
+    await expect(
+      run({
+        ...baseOptions,
+        retry: { maxRetries: 1, backoffBaseMs: 1, backoffMaxMs: 1 },
+      }),
+    ).rejects.toBeInstanceOf(NetworkError)
+
+    // Initial attempt + one retry
+    expect(runSpy).toHaveBeenCalledTimes(2)
+  })
+
+  it('does not retry non-network errors', async () => {
+    const error = new Error('boom')
+    const runSpy = spyOn(runModule, 'runOnce').mockRejectedValue(error)
+
+    await expect(
+      run({
+        ...baseOptions,
+        retry: { maxRetries: 3, backoffBaseMs: 1, backoffMaxMs: 1 },
+      }),
+    ).rejects.toBe(error)
+
+    expect(runSpy).toHaveBeenCalledTimes(1)
+  })
+
+  it('skips retry when retry is false even for retryable errors', async () => {
+    const runSpy = spyOn(runModule, 'runOnce').mockRejectedValue(
+      new NetworkError('offline', ErrorCodes.NETWORK_ERROR),
+    )
+
+    await expect(
+      run({
+        ...baseOptions,
+        retry: false,
+      }),
+    ).rejects.toBeInstanceOf(NetworkError)
+
+    expect(runSpy).toHaveBeenCalledTimes(1)
+  })
+
+  it('retries when provided custom retryableErrorCodes set', async () => {
+    const expectedState = { output: { type: 'success' } } as RunState
+    const runSpy = spyOn(runModule, 'runOnce')
+      .mockRejectedValueOnce(
+        new NetworkError('temporary', ErrorCodes.SERVER_ERROR),
+      )
+      .mockResolvedValueOnce(expectedState)
+
+    const result = await run({
+      ...baseOptions,
+      retry: {
+        backoffBaseMs: 1,
+        backoffMaxMs: 2,
+        retryableErrorCodes: new Set([ErrorCodes.SERVER_ERROR]),
+      },
+    })
+
+    expect(result).toBe(expectedState)
+    expect(runSpy).toHaveBeenCalledTimes(2)
+  })
+
+  it('honors abort controller during backoff', async () => {
+    const runSpy = spyOn(runModule, 'runOnce').mockRejectedValue(
+      new NetworkError('offline', ErrorCodes.NETWORK_ERROR),
+    )
+    const controller = new AbortController()
+
+    const promise = run({
+      ...baseOptions,
+      retry: { backoffBaseMs: 20, backoffMaxMs: 20 },
+      abortController: controller,
+    })
+
+    controller.abort('cancelled')
+
+    await expect(promise).rejects.toHaveProperty('name', 'AbortError')
+    expect(runSpy).toHaveBeenCalledTimes(1)
+  })
+})

sdk/src/impl/database.ts

@@ -68,14 +68,16 @@ export async function getUserInfoFromApiKey<T extends UserColumn>(
     throw new NetworkError('Network request failed', ErrorCodes.NETWORK_ERROR, undefined, error)
   }
 
-  if (response.status === 401 || response.status === 403) {
+  if (response.status === 401 || response.status === 403 || response.status === 404) {
     logger.error(
       { apiKey, fields, status: response.status },
       'getUserInfoFromApiKey authentication failed',
     )
     // Don't cache auth failures - allow retry with potentially updated credentials
     delete userInfoCache[apiKey]
-    throw new AuthenticationError('Authentication failed', response.status)
+    // If the server returns 404 for invalid credentials, surface as 401 to callers
+    const normalizedStatus = response.status === 404 ? 401 : response.status
+    throw new AuthenticationError('Authentication failed', normalizedStatus)
   }
 
   if (response.status >= 500 && response.status <= 599) {

sdk/src/index.ts

@@ -2,7 +2,8 @@ export type * from '../../common/src/types/json'
 export type * from '../../common/src/types/messages/codebuff-message'
 export type * from '../../common/src/types/messages/data-content'
 export type * from '../../common/src/types/print-mode'
-export type * from './run'
+export { run } from './run'
+export type { RunOptions, RetryOptions } from './run'
 // Agent type exports
 export type { AgentDefinition } from '../../common/src/templates/initial-agents-dir/types/agent-definition'
 export type { ToolName } from '../../common/src/tools/constants'