feat(sdk): improve error handling and surface SDK errors

- Add ErrorOr utilities and SdkErrorObject type to public exports -
Create database-safe wrapper with ErrorOr return types - Update run() to
use safe database calls and handle errors gracefully - Improve
validateAgents error handling for network failures - Wrap validation API
errors in NetworkError with proper metadata

Author: brandonkachen

sdk/src/error-or.ts

@@ -0,0 +1,43 @@
+import { failure, getErrorObject, type ErrorObject, type Failure } from '../../common/src/util/error'
+
+// SDK-level error object that preserves optional code/status when present on Error instances
+export type SdkErrorObject = ErrorObject & {
+  code?: string
+  status?: number
+  originalError?: unknown
+}
+
+/**
+ * Wrap an unknown error into a Failure<SdkErrorObject>, preserving `code`, `status`, and `originalError`
+ * when present on known SDK error types like NetworkError or AuthenticationError.
+ */
+export function failureWithCode(error: unknown): Failure<SdkErrorObject> {
+  if (error instanceof Error) {
+    const base = getErrorObject(error)
+    const anyErr = error as any
+
+    const enriched: SdkErrorObject = {
+      ...base,
+    }
+
+    if (typeof anyErr.code === 'string') {
+      enriched.code = anyErr.code
+    }
+
+    if (typeof anyErr.status === 'number') {
+      enriched.status = anyErr.status
+    }
+
+    if ('originalError' in anyErr) {
+      enriched.originalError = anyErr.originalError
+    }
+
+    return {
+      success: false,
+      error: enriched,
+    }
+  }
+
+  // Fallback to base failure, which will still give us an ErrorObject
+  return failure(error)
+}

sdk/src/impl/database-safe.ts

@@ -0,0 +1,29 @@
+import { getUserInfoFromApiKey } from './database'
+import { failureWithCode, type SdkErrorObject } from '../error-or'
+import type {
+  GetUserInfoFromApiKeyInput,
+  UserColumn,
+} from '@codebuff/common/types/contracts/database'
+import type { ErrorOr } from '@codebuff/common/util/error'
+
+type User = {
+  id: string
+  email: string
+  discord_id: string | null
+}
+
+export type GetUserInfoFromApiKeySafeError = SdkErrorObject
+
+export async function getUserInfoFromApiKeySafe<T extends UserColumn>(
+  params: GetUserInfoFromApiKeyInput<T>,
+): Promise<ErrorOr<{ [K in T]: User[K] } | null, GetUserInfoFromApiKeySafeError>> {
+  try {
+    const result = await getUserInfoFromApiKey<T>(params)
+    return {
+      success: true,
+      value: result,
+    }
+  } catch (error) {
+    return failureWithCode(error)
+  }
+}

sdk/src/index.ts

@@ -26,6 +26,7 @@ export { formatState } from '../../common/src/websockets/websocket-client'
 export type { ReadyState } from '../../common/src/websockets/websocket-client'
 
 export { getUserInfoFromApiKey } from './impl/database'
+export { getUserInfoFromApiKeySafe } from './impl/database-safe'
 
 export { validateAgents } from './validate-agents'
 
@@ -42,6 +43,10 @@ export {
 } from './errors'
 export type { ValidationResult, ValidateAgentsOptions } from './validate-agents'
 
+// ErrorOr utilities
+export { failureWithCode, type SdkErrorObject } from './error-or'
+export type { ErrorOr, Success, Failure } from '@codebuff/common/util/error'
+
 export type { CodebuffFileSystem } from '@codebuff/common/types/filesystem'
 
 export { runTerminalCommand } from './tools/run-terminal-command'

sdk/src/run.ts

@@ -11,7 +11,7 @@ import { AgentOutputSchema } from '@codebuff/common/types/session-state'
 import { cloneDeep } from 'lodash'
 
 import { getAgentRuntimeImpl } from './impl/agent-runtime'
-import { getUserInfoFromApiKey } from './impl/database'
+import { getUserInfoFromApiKeySafe } from './impl/database-safe'
 import { initialSessionState, applyOverridesToSessionState } from './run-state'
 import { filterXml } from './tool-xml-filter'
 import { changeFile } from './tools/change-file'
@@ -488,11 +488,21 @@ export async function run({
   const promptId = Math.random().toString(36).substring(2, 15)
 
   // Send input
-  const userInfo = await getUserInfoFromApiKey({
+  const userInfoResult = await getUserInfoFromApiKeySafe({
     ...agentRuntimeImpl,
     apiKey,
     fields: ['id'],
   })
+
+  if (!userInfoResult.success) {
+    const err = userInfoResult.error
+    const errorMessage = err.message || 'Failed to resolve user information from API key'
+    await onError({ message: errorMessage })
+    clearStreamTimeout()
+    return getCancelledRunState(errorMessage)
+  }
+
+  const userInfo = userInfoResult.value
   if (!userInfo) {
     const errorMessage = 'Invalid API key or user not found'
     await onError({ message: errorMessage })

sdk/src/validate-agents.ts

@@ -30,6 +30,22 @@ export interface ValidateAgentsOptions {
   websiteUrl?: string
 }
 
+function buildValidationApiNetworkError(params: {
+  message: string
+  status?: number
+  original?: unknown
+}): NetworkError {
+  // For 5xx errors, use "Server error" prefix to match test expectations
+  // For network failures, use "Failed to connect" prefix
+  const prefix = params.status && params.status >= 500 ? 'Server error' : 'Failed to connect to validation API'
+  const baseMessage = `${prefix}: ${params.message}`
+  const wrapped = new NetworkError(baseMessage, {
+    status: params.status,
+    originalError: params.original,
+  })
+  return wrapped
+}
+
 /**
  * Validates an array of agent definitions.
  *
@@ -63,7 +79,7 @@ export async function validateAgents(
   for (const [index, definition] of definitions.entries()) {
     // Handle null/undefined gracefully
     if (!definition) {
-      agentTemplates[`agent_${index}`] = definition
+      agentTemplates[`agent_${index}`] = definition as AgentDefinition
       continue
     }
     // Use index to ensure duplicates aren't overwritten
@@ -96,14 +112,28 @@ export async function validateAgents(
       })
 
       if (!response.ok) {
-        const errorData = await response.json().catch(() => ({}))
+        let errorData: any = {}
+        try {
+          errorData = await response.json()
+        } catch {
+          // ignore JSON parse errors, we'll fall back to status text
+        }
         const errorMessage =
           (errorData as any).error ||
           `HTTP ${response.status}: ${response.statusText}`
 
-        // For 5xx errors, throw network error
+        // For 5xx errors, throw a NetworkError with original error metadata
         if (response.status >= 500) {
-          throw new NetworkError(`Server error: ${errorMessage}`, { status: response.status })
+          const original = {
+            status: response.status,
+            statusText: response.statusText,
+            body: errorData,
+          }
+          throw buildValidationApiNetworkError({
+            message: errorMessage,
+            status: response.status,
+            original,
+          })
         }
 
         // For client errors (4xx), return as validation errors
@@ -122,11 +152,14 @@ export async function validateAgents(
       const data = await response.json()
       validationErrors = data.validationErrors || []
     } catch (error) {
-      const errorMessage =
-        error instanceof Error ? error.message : String(error)
+      const message = error instanceof Error ? error.message : String(error)
 
-      // Throw network errors instead of returning them as validation errors
-      throw new NetworkError(`Failed to connect to validation API: ${errorMessage}`, { originalError: error })
+      // Wrap all network failures in a NetworkError that includes the original error
+      const networkError = buildValidationApiNetworkError({
+        message,
+        original: error,
+      })
+      throw networkError
     }
   } else {
     // Local validation: use common package validation logic