refactor: make error code field required and add standard error codes

- Make code field required in PrintModeError schema
- Add ErrorCodes constants (AUTH_FAILED, NETWORK_ERROR, VALIDATION_ERROR, etc.)
- Update all error creation sites to include appropriate error codes
- Remove all `as any` type casting for error.code
- Update tests to include error codes
- All TypeScript checks pass

Author: brandonkachen

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

@@ -1204,7 +1204,7 @@ export const useSendMessage = ({
             // Handle error events from SDK
             if (event.type === 'error') {
               logger.error(
-                { errorMessage: event.message },
+                { errorMessage: event.message, code: event.code },
                 'SDK error event received',
               )
               currentRunContextRef.current = null
@@ -1239,14 +1239,8 @@ export const useSendMessage = ({
               )
 
               // Track failed messages for batch retry on reconnection (avoids state update cascade)
-              const errorMsg = event.message || ''
               const isConnectionError =
-                !isConnectedRef.current ||
-                (typeof errorMsg === 'string' &&
-                  (errorMsg.includes('Failed to start agent run') ||
-                    errorMsg.includes('Unable to connect') ||
-                    errorMsg.includes('network') ||
-                    errorMsg.includes('fetch failed')))
+                !isConnectedRef.current || event.code === 'NETWORK_ERROR'
 
               if (isConnectionError && userMessageId && content && agentMode) {
                 failedDueToConnectionRef.current[userMessageId] = {
@@ -1917,25 +1911,9 @@ export const useSendMessage = ({
 
           logger.warn({ errorMessage }, 'Agent run failed')
 
-          // Track failed messages for batch retry on reconnection (avoids state update cascade)
-          const isConnectionError =
-            !isConnectedRef.current ||
-            (typeof errorMessage === 'string' &&
-              (errorMessage.includes('Unable to connect') ||
-                errorMessage.includes('network') ||
-                errorMessage.includes('fetch failed') ||
-                errorMessage.includes('connection')))
-
-          if (isConnectionError && userMessageId && content && agentMode) {
-            logger.info(
-              { userMessageId },
-              '[RUNSTATE-ERROR] Tracking message for retry on reconnection',
-            )
-            failedDueToConnectionRef.current[userMessageId] = {
-              content,
-              agentMode,
-            }
-          }
+          // Note: Connection errors should be caught as thrown NetworkError exceptions
+          // in the catch block below, not through runState.output.type === 'error'.
+          // If we get here with an error output, it's likely a non-retryable error.
 
           return
         }

common/src/types/print-mode.ts

@@ -12,6 +12,8 @@ export type PrintModeStart = z.infer<typeof printModeStartSchema>
 export const printModeErrorSchema = z.object({
   type: z.literal('error'),
   message: z.string(),
+  // Machine-readable error code for consistent error handling
+  code: z.string(),
 })
 export type PrintModeError = z.infer<typeof printModeErrorSchema>
 

common/src/util/error.ts

@@ -76,22 +76,27 @@ export type ExtendedErrorObject = ErrorObject & {
 export function failureWithCode(error: unknown): Failure<ExtendedErrorObject> {
   if (error instanceof Error) {
     const base = getErrorObject(error)
-    const anyErr = error as any
-
     const enriched: ExtendedErrorObject = {
       ...base,
     }
 
-    if (typeof anyErr.code === 'string') {
-      enriched.code = anyErr.code
+    // Safely extract code, status, and originalError if present
+    const errorWithMetadata = error as Error & {
+      code?: string
+      status?: number
+      originalError?: unknown
+    }
+
+    if (typeof errorWithMetadata.code === 'string') {
+      enriched.code = errorWithMetadata.code
     }
 
-    if (typeof anyErr.status === 'number') {
-      enriched.status = anyErr.status
+    if (typeof errorWithMetadata.status === 'number') {
+      enriched.status = errorWithMetadata.status
     }
 
-    if ('originalError' in anyErr) {
-      enriched.originalError = anyErr.originalError
+    if ('originalError' in errorWithMetadata) {
+      enriched.originalError = errorWithMetadata.originalError
     }
 
     return {

packages/agent-runtime/src/tool-stream-parser.ts

@@ -110,6 +110,7 @@ export async function* processStreamWithTags(params: {
       onResponseChunk({
         type: 'error',
         message: errorMessage,
+        code: 'VALIDATION_ERROR',
       })
       onError('parse_error', errorMessage)
       return

packages/agent-runtime/src/tools/stream-parser.ts

@@ -206,7 +206,13 @@ export async function processStreamWithTools(
       onResponseChunk(chunk.text)
       fullResponseChunks.push(chunk.text)
     } else if (chunk.type === 'error') {
-      onResponseChunk(chunk)
+      // Ensure error has a code field
+      const code = 'code' in chunk && typeof chunk.code === 'string' ? chunk.code : 'INTERNAL_ERROR'
+      onResponseChunk({
+        type: 'error',
+        message: chunk.message,
+        code,
+      })
     } else {
       chunk satisfies never
     }

sdk/src/__tests__/client.test.ts

@@ -148,7 +148,7 @@ describe('CodebuffClient', () => {
       // Trigger the default error handler
       const defaultHandler = client.options.handleEvent
       if (defaultHandler) {
-        defaultHandler({ type: 'error', message: 'Test error' })
+        defaultHandler({ type: 'error', message: 'Test error', code: 'TEST_ERROR' })
       }
 
       expect(consoleErrorSpy).toHaveBeenCalledTimes(2) // Error message + tip
@@ -199,7 +199,7 @@ describe('CodebuffClient', () => {
 
       // Trigger the handler
       if (client.options.handleEvent) {
-        client.options.handleEvent({ type: 'error', message: 'Test' })
+        client.options.handleEvent({ type: 'error', message: 'Test', code: 'TEST_ERROR' })
       }
 
       // Custom handler should be called, not console.error
@@ -216,7 +216,7 @@ describe('CodebuffClient', () => {
 
       const defaultHandler = client.options.handleEvent
       if (defaultHandler) {
-        defaultHandler({ type: 'error', message: 'Connection failed' })
+        defaultHandler({ type: 'error', message: 'Connection failed', code: 'NETWORK_ERROR' })
       }
 
       const calls = consoleErrorSpy.mock.calls

sdk/src/errors.ts

@@ -2,6 +2,20 @@
  * Custom error classes for the SDK
  */
 
+/**
+ * Standard error codes used throughout the SDK
+ */
+export const ErrorCodes = {
+  AUTH_FAILED: 'AUTH_FAILED',
+  NETWORK_ERROR: 'NETWORK_ERROR',
+  VALIDATION_ERROR: 'VALIDATION_ERROR',
+  INTERNAL_ERROR: 'INTERNAL_ERROR',
+  INVALID_RESPONSE: 'INVALID_RESPONSE',
+  USER_NOT_FOUND: 'USER_NOT_FOUND',
+} as const
+
+export type ErrorCode = typeof ErrorCodes[keyof typeof ErrorCodes]
+
 /**
  * Sanitizes error messages by removing unhelpful system messages
  */

sdk/src/run.ts

@@ -20,7 +20,7 @@ import { glob } from './tools/glob'
 import { listDirectory } from './tools/list-directory'
 import { getFiles } from './tools/read-files'
 import { runTerminalCommand } from './tools/run-terminal-command'
-import { NetworkError } from './errors'
+import { NetworkError, ErrorCodes } from './errors'
 
 import type { CustomToolDefinition } from './custom-tool'
 import type { RunState } from './run-state'
@@ -245,9 +245,9 @@ export async function run({
     return getCancelledRunState()
   }
 
-  async function onError(error: { message: string }) {
+  async function onError(error: { message: string; code: string }) {
     if (handleEvent) {
-      await handleEvent({ type: 'error', message: error.message })
+      await handleEvent({ type: 'error', message: error.message, code: error.code })
     }
   }
 
@@ -435,7 +435,7 @@ export async function run({
     },
     sendAction: ({ action }) => {
       if (action.type === 'action-error') {
-        onError({ message: action.message })
+        onError({ message: action.message, code: ErrorCodes.INTERNAL_ERROR })
         return
       }
       if (action.type === 'response-chunk') {
@@ -497,15 +497,15 @@ export async function run({
   if (!userInfoResult.success) {
     const err = userInfoResult.error
     const errorMessage = err.message || 'Failed to resolve user information from API key'
-    await onError({ message: errorMessage })
+    await onError({ message: errorMessage, code: err.code ?? ErrorCodes.INTERNAL_ERROR })
     clearStreamTimeout()
     return getCancelledRunState(errorMessage)
   }
 
   const userInfo = userInfoResult.value
   if (!userInfo) {
     const errorMessage = 'Invalid API key or user not found'
-    await onError({ message: errorMessage })
+    await onError({ message: errorMessage, code: ErrorCodes.USER_NOT_FOUND })
     clearStreamTimeout()
     return getCancelledRunState(errorMessage)
   }
@@ -538,7 +538,7 @@ export async function run({
         return
       }
       const errorMessage = error.message || String(error)
-      await onError({ message: errorMessage })
+      await onError({ message: errorMessage, code: ErrorCodes.NETWORK_ERROR })
       settleResolve(getCancelledRunState(errorMessage))
     })
   } catch (error) {
@@ -698,11 +698,11 @@ async function handlePromptResponse({
 }: {
   action: ServerAction<'prompt-response'> | ServerAction<'prompt-error'>
   resolve: (value: RunReturnType) => any
-  onError: (error: { message: string }) => void
+  onError: (error: { message: string; code: string }) => void
   initialSessionState: SessionState
 }) {
   if (action.type === 'prompt-error') {
-    onError({ message: action.message })
+    onError({ message: action.message, code: ErrorCodes.INTERNAL_ERROR })
     resolve({
       sessionState: initialSessionState,
       output: {
@@ -720,7 +720,7 @@ async function handlePromptResponse({
         JSON.stringify(parsedOutput.error.issues),
         'If this issues persists, please contact support@codebuff.com',
       ].join('\n')
-      onError({ message })
+      onError({ message, code: ErrorCodes.INVALID_RESPONSE })
       resolve({
         sessionState: initialSessionState,
         output: {
@@ -744,6 +744,7 @@ async function handlePromptResponse({
     action satisfies never
     onError({
       message: 'Internal error: prompt response type not handled',
+      code: ErrorCodes.INTERNAL_ERROR,
     })
     resolve({
       sessionState: initialSessionState,