refactor: centralize retry constants and document error handling patterns

- Create sdk/src/retry-config.ts with all retry/connection timing constants
  - MAX_RETRIES_PER_MESSAGE, RETRY_BACKOFF_BASE_DELAY_MS, RETRY_BACKOFF_MAX_DELAY_MS
  - RECONNECTION_RETRY_DELAY_MS, RECONNECTION_MESSAGE_DURATION_MS
  - calculateBackoffDelay() helper and DEFAULT_RETRY_CONFIG type
- Add comprehensive error handling documentation to sdk/src/errors.ts
  - Document throwing pattern as standard approach
  - Explain when to use try/catch vs ErrorOr pattern
  - Document error types, codes, and retryability
- Update all imports across CLI and SDK to use centralized constants
  - cli/src/hooks/use-send-message.ts
  - cli/src/chat.tsx
  - cli/src/utils/ui-constants.ts
  - cli/src/__tests__/integration/reconnection-retry.test.ts
- Export all retry config constants from sdk/src/index.ts

Benefits:
- Single source of truth for timing configuration
- Consistent error handling patterns across codebase
- Type-safe constants with clear documentation
- Tests use same constants as production code

Author: brandonkachen

cli/src/__tests__/integration/reconnection-retry.test.ts

@@ -1,4 +1,9 @@
 import { describe, test, expect, beforeEach, mock } from 'bun:test'
+import {
+  MAX_RETRIES_PER_MESSAGE,
+  RETRY_BACKOFF_BASE_DELAY_MS,
+  RETRY_BACKOFF_MAX_DELAY_MS,
+} from '@codebuff/sdk'
 
 /**
  * Integration tests for reconnection and retry logic
@@ -153,7 +158,6 @@ describe('Reconnection and Retry Logic', () => {
     })
 
     test('should respect max retry attempts', async () => {
-      const MAX_RETRIES = 3
       const retryAttempts: Record<string, number> = {}
       const messageId = 'msg-1'
       let failedMessageMarked = false
@@ -164,7 +168,7 @@ describe('Reconnection and Retry Logic', () => {
 
       const attemptRetry = () => {
         const attempts = retryAttempts[messageId] ?? 0
-        if (attempts >= MAX_RETRIES) {
+        if (attempts >= MAX_RETRIES_PER_MESSAGE) {
           markMessageFailed(messageId, 'Maximum retry attempts reached')
           return false
         }
@@ -218,7 +222,7 @@ describe('Reconnection and Retry Logic', () => {
   })
 
   describe('Timeout Management', () => {
-    test('should cleanup timeout on unmount', () => {
+    test('should cleanup timeout on unmount', async () => {
       let timeoutRef: NodeJS.Timeout | null = null
       let cleanupCalled = false
 
@@ -252,12 +256,11 @@ describe('Reconnection and Retry Logic', () => {
       expect(timeoutRef).toBeNull()
 
       // Wait to ensure timeout doesn't fire
-      setTimeout(() => {
-        expect(timeoutFired).toBe(false)
-      }, 150)
+      await new Promise((resolve) => setTimeout(resolve, 150))
+      expect(timeoutFired).toBe(false)
     })
 
-    test('should replace existing timeout when setting new one', () => {
+    test('should replace existing timeout when setting new one', async () => {
       let timeoutRef: NodeJS.Timeout | null = null
       const callbacks: string[] = []
 
@@ -279,10 +282,9 @@ describe('Reconnection and Retry Logic', () => {
       }, 50)
 
       // Wait for second timeout to fire
-      setTimeout(() => {
-        expect(callbacks).toEqual(['second'])
-        expect(callbacks).not.toContain('first')
-      }, 120)
+      await new Promise((resolve) => setTimeout(resolve, 120))
+      expect(callbacks).toEqual(['second'])
+      expect(callbacks).not.toContain('first')
     })
   })
 
@@ -336,9 +338,6 @@ describe('Reconnection and Retry Logic', () => {
 
   describe('Backoff Strategy', () => {
     test('should implement exponential backoff for retries', () => {
-      const RETRY_BACKOFF_BASE_DELAY_MS = 1000
-      const RETRY_BACKOFF_MAX_DELAY_MS = 30000
-
       let backoffDelay = RETRY_BACKOFF_BASE_DELAY_MS
 
       const calculateNextBackoff = (hasMorePending: boolean) => {
@@ -351,20 +350,18 @@ describe('Reconnection and Retry Logic', () => {
       }
 
       // First retry - no backoff increase (no more pending)
-      expect(calculateNextBackoff(false)).toBe(1000)
+      expect(calculateNextBackoff(false)).toBe(RETRY_BACKOFF_BASE_DELAY_MS)
 
       // Subsequent retries with pending messages
       expect(calculateNextBackoff(true)).toBe(2000)
       expect(calculateNextBackoff(true)).toBe(4000)
-      expect(calculateNextBackoff(true)).toBe(8000)
-      expect(calculateNextBackoff(true)).toBe(16000)
-      expect(calculateNextBackoff(true)).toBe(30000) // Capped at max
+      expect(calculateNextBackoff(true)).toBe(RETRY_BACKOFF_MAX_DELAY_MS) // Capped at max (8000)
 
       // Should stay at max
-      expect(calculateNextBackoff(true)).toBe(30000)
+      expect(calculateNextBackoff(true)).toBe(RETRY_BACKOFF_MAX_DELAY_MS)
 
       // Reset when no more pending
-      expect(calculateNextBackoff(false)).toBe(1000)
+      expect(calculateNextBackoff(false)).toBe(RETRY_BACKOFF_BASE_DELAY_MS)
     })
   })
 })

cli/src/chat.tsx

@@ -50,12 +50,12 @@ import { loadLocalAgents } from './utils/local-agent-registry'
 import { buildMessageTree } from './utils/message-tree-utils'
 import { computeInputLayoutMetrics } from './utils/text-layout'
 import { createMarkdownPalette } from './utils/theme-system'
+import { BORDER_CHARS } from './utils/ui-constants'
+import { formatRetryBannerMessage } from './utils/error-messages'
 import {
-  BORDER_CHARS,
   RECONNECTION_MESSAGE_DURATION_MS,
   RECONNECTION_RETRY_DELAY_MS,
-} from './utils/ui-constants'
-import { formatRetryBannerMessage } from './utils/error-messages'
+} from '@codebuff/sdk'
 
 import type { ChatMessage, ContentBlock } from './types/chat'
 import type { SendMessageFn } from './types/contracts/send-message'

cli/src/hooks/use-send-message.ts

@@ -20,6 +20,9 @@ import {
   isNetworkError,
   ErrorCodes,
   RETRYABLE_ERROR_CODES,
+  MAX_RETRIES_PER_MESSAGE,
+  RETRY_BACKOFF_BASE_DELAY_MS,
+  RETRY_BACKOFF_MAX_DELAY_MS,
 } from '@codebuff/sdk'
 import {
   loadMostRecentChatState,
@@ -42,9 +45,9 @@ const hiddenToolNames = new Set<ToolName | 'spawn_agent_inline'>([
   'spawn_agents',
 ])
 
-const MAX_RETRIES_PER_MESSAGE = 3
-const RETRY_BACKOFF_BASE_DELAY_MS = 1_000
-const RETRY_BACKOFF_MAX_DELAY_MS = 8_000
+// Message retry configuration - imported from @codebuff/sdk/retry-config
+// MAX_RETRIES_PER_MESSAGE, RETRY_BACKOFF_BASE_DELAY_MS, RETRY_BACKOFF_MAX_DELAY_MS
+
 const MAX_FAILED_MESSAGES_TO_STORE = 50 // Limit memory usage for failed messages
 const FAILED_MESSAGE_TTL_MS = 5 * 60 * 1000 // 5 minutes - prune old failures
 

cli/src/utils/ui-constants.ts

@@ -14,9 +14,8 @@ export const BORDER_CHARS: BorderCharacters = {
   cross: '┼',
 }
 
-// Reconnection timing
-export const RECONNECTION_RETRY_DELAY_MS = 500
-export const RECONNECTION_MESSAGE_DURATION_MS = 2000
+// Reconnection timing constants moved to @codebuff/sdk/retry-config
+// Import RECONNECTION_RETRY_DELAY_MS and RECONNECTION_MESSAGE_DURATION_MS from @codebuff/sdk
 
 // Shimmer animation
 export const SHIMMER_INTERVAL_MS = 160

sdk/src/errors.ts

@@ -1,5 +1,62 @@
 /**
  * Custom error classes for the SDK
+ *
+ * ## Error Handling Philosophy
+ *
+ * This SDK uses a **consistent throwing pattern** for error handling:
+ * - All SDK functions throw typed errors (AuthenticationError, NetworkError, etc.)
+ * - Errors include a `code` property for programmatic error type checking
+ * - Error codes indicate whether the error is retryable
+ * - Optional ErrorOr wrappers available for functional programming style
+ *
+ * ## Error Types
+ *
+ * ### AuthenticationError (code: 'AUTH_FAILED')
+ * - Thrown for 401/403 HTTP responses
+ * - Indicates invalid credentials or expired tokens
+ * - NOT retryable - requires user intervention
+ *
+ * ### NetworkError (code: 'NETWORK_ERROR')
+ * - Thrown for connection failures, timeouts, 5xx errors
+ * - Indicates transient network or server issues
+ * - IS retryable - automatic retry is recommended
+ *
+ * ## Usage Patterns
+ *
+ * ### Pattern 1: Try/Catch with Error Code Checking (Recommended for most cases)
+ * ```typescript
+ * try {
+ *   const user = await getUserInfoFromApiKey({ apiKey, fields: ['id'], logger })
+ * } catch (error) {
+ *   if (isAuthenticationError(error)) {
+ *     // Handle auth failure - show login prompt
+ *   } else if (isNetworkError(error)) {
+ *     // Handle network error - schedule retry
+ *   }
+ * }
+ * ```
+ *
+ * ### Pattern 2: ErrorOr Functional Style (Optional)
+ * ```typescript
+ * const result = await getUserInfoFromApiKeySafe({ apiKey, fields: ['id'], logger })
+ * if (!result.success) {
+ *   // Handle error from result.error
+ * }
+ * // Use result.value
+ * ```
+ *
+ * ## Error Code Checking
+ *
+ * Use the provided type guards for safe error type checking:
+ * - `isAuthenticationError(error)` - Checks for AUTH_FAILED
+ * - `isNetworkError(error)` - Checks for NETWORK_ERROR
+ * - `isErrorWithCode(error)` - Checks if error has a code property
+ *
+ * Check `RETRYABLE_ERROR_CODES` set to determine if an error should trigger retry logic.
+ *
+ * ## Related
+ * - See `retry-config.ts` for retry timing and backoff configuration
+ * - See `ErrorOr` types from `@codebuff/common/util/error` for functional error handling
  */
 
 /**

sdk/src/index.ts

@@ -46,6 +46,21 @@ export {
 } from './errors'
 export type { ValidationResult, ValidateAgentsOptions } from './validate-agents'
 
+// Retry and connection configuration
+export {
+  MAX_RETRIES_PER_MESSAGE,
+  RETRY_BACKOFF_BASE_DELAY_MS,
+  RETRY_BACKOFF_MAX_DELAY_MS,
+  RECONNECTION_RETRY_DELAY_MS,
+  RECONNECTION_MESSAGE_DURATION_MS,
+  calculateBackoffDelay,
+  DEFAULT_RETRY_CONFIG,
+  type RetryConfig,
+} from './retry-config'
+
+// Re-export promise utilities and constants from common
+export { INITIAL_RETRY_DELAY } from '@codebuff/common/util/promise'
+
 // ErrorOr utilities
 export {
   failure,

sdk/src/retry-config.ts

@@ -0,0 +1,84 @@
+/**
+ * Centralized retry and connection configuration
+ *
+ * This file contains all constants related to retry logic, backoff strategies,
+ * and connection management across the SDK and CLI.
+ */
+
+/**
+ * Maximum number of retry attempts per message before giving up
+ * After this many failures, the message will be marked as failed
+ */
+export const MAX_RETRIES_PER_MESSAGE = 3
+
+/**
+ * Base delay for exponential backoff retry strategy (in milliseconds)
+ * First retry starts at this delay, then doubles with each subsequent retry
+ *
+ * Example progression: 1s → 2s → 4s → 8s (capped at max)
+ */
+export const RETRY_BACKOFF_BASE_DELAY_MS = 1_000
+
+/**
+ * Maximum delay for exponential backoff retry strategy (in milliseconds)
+ * Prevents backoff from growing unbounded during extended outages
+ */
+export const RETRY_BACKOFF_MAX_DELAY_MS = 8_000
+
+/**
+ * Delay before attempting to retry pending messages after reconnection (in milliseconds)
+ * Short delay allows connection to stabilize before retrying
+ */
+export const RECONNECTION_RETRY_DELAY_MS = 500
+
+/**
+ * Duration to show the reconnection success message (in milliseconds)
+ * Message is automatically hidden after this duration
+ */
+export const RECONNECTION_MESSAGE_DURATION_MS = 2_000
+
+/**
+ * Calculates the next backoff delay using exponential backoff strategy
+ *
+ * @param currentDelay - Current delay in milliseconds
+ * @param hasMorePending - Whether there are more pending operations
+ * @returns Next delay in milliseconds, capped at RETRY_BACKOFF_MAX_DELAY_MS
+ *
+ * @example
+ * ```typescript
+ * let delay = RETRY_BACKOFF_BASE_DELAY_MS
+ * delay = calculateBackoffDelay(delay, true)  // 2000ms
+ * delay = calculateBackoffDelay(delay, true)  // 4000ms
+ * delay = calculateBackoffDelay(delay, false) // 1000ms (reset)
+ * ```
+ */
+export function calculateBackoffDelay(
+  currentDelay: number,
+  hasMorePending: boolean,
+): number {
+  if (!hasMorePending) {
+    return RETRY_BACKOFF_BASE_DELAY_MS
+  }
+  return Math.min(currentDelay * 2, RETRY_BACKOFF_MAX_DELAY_MS)
+}
+
+/**
+ * Type representing retry configuration that can be customized
+ */
+export interface RetryConfig {
+  maxRetries: number
+  baseDelay: number
+  maxDelay: number
+  reconnectionDelay: number
+}
+
+/**
+ * Default retry configuration
+ * Can be used to create custom configurations
+ */
+export const DEFAULT_RETRY_CONFIG: RetryConfig = {
+  maxRetries: MAX_RETRIES_PER_MESSAGE,
+  baseDelay: RETRY_BACKOFF_BASE_DELAY_MS,
+  maxDelay: RETRY_BACKOFF_MAX_DELAY_MS,
+  reconnectionDelay: RECONNECTION_RETRY_DELAY_MS,
+}