feat: refactor network status handling and add message retry system

- Separate auth and validation status tracking for graceful degradation
- Add retry mechanism with exponential backoff (max 3 attempts)
- Improve error handling and user feedback in offline banner
- Extract UI timing constants for better maintainability
- Update tests to reflect new network status behavior

Author: brandonkachen

cli/src/app.tsx

@@ -183,7 +183,7 @@ export const App = ({
             dense
           />
         </box>
-        {validationErrors.length > 0 && networkStatus.isOnline && (
+        {validationErrors.length > 0 && networkStatus.validation.isReachable && (
           <box style={{ flexDirection: 'column', gap: 0 }}>
             {createValidationErrorBlocks({
               errors: validationErrors,
@@ -210,14 +210,14 @@ export const App = ({
     isAgentListCollapsed,
     validationErrors,
     separatorWidth,
-    networkStatus.isOnline,
+    networkStatus.validation.isReachable,
   ])
 
   // Only show login modal for actual authentication failures, not network errors
   if (
     requireAuth !== null &&
     isAuthenticated === false &&
-    networkStatus.isOnline // Only require login when we're online
+    networkStatus.auth.isReachable // Only require login when auth is reachable
   ) {
     return (
       <LoginModal

cli/src/chat.tsx

@@ -42,7 +42,11 @@ 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 {
+  BORDER_CHARS,
+  RECONNECTION_MESSAGE_DURATION_MS,
+  RECONNECTION_RETRY_DELAY_MS,
+} from './utils/ui-constants'
 
 import type { ChatMessage, ContentBlock } from './types/chat'
 import type { SendMessageFn } from './types/contracts/send-message'
@@ -219,11 +223,11 @@ export const Chat = ({
         clearTimeout(reconnectionTimeoutRef.current)
       }
 
-      // Hide the message after 2 seconds
+      // Hide the message after the configured duration
       reconnectionTimeoutRef.current = setTimeout(() => {
         setShowReconnectionMessage(false)
         reconnectionTimeoutRef.current = null
-      }, 2000)
+      }, RECONNECTION_MESSAGE_DURATION_MS)
     }
 
     // Always trigger retry check (for both initial connection and reconnection)
@@ -560,6 +564,21 @@ export const Chat = ({
     continueChatId,
   })
 
+  const offlineBannerMessage = useMemo(() => {
+    const baseMessage = `⚠️ Network Error: ${
+      networkStatus.error?.message ?? 'Connection lost'
+    }`
+    const retryMessage =
+      pendingRetryCount > 0
+        ? ` • ${pendingRetryCount} message${
+            pendingRetryCount === 1 ? '' : 's'
+          } will retry when the connection is restored`
+        : ''
+    const guidance =
+      ' • Verify your API key or network connection before retrying.'
+    return `${baseMessage}${retryMessage}${guidance}`
+  }, [networkStatus.error, pendingRetryCount])
+
   sendMessageRef.current = sendMessage
   retryPendingMessagesRef.current = retryPendingMessages
   processFailedMessagesRef.current = processFailedMessages
@@ -569,13 +588,13 @@ export const Chat = ({
     if (connectionEstablished > 0 && pendingRetryCount > 0) {
       logger.info(
         { pendingRetryCount, connectionEstablished },
-        `[RETRY-EFFECT] CONDITIONS MET! Will retry ${pendingRetryCount} pending message(s) after 500ms delay...`
+        `[RETRY-EFFECT] CONDITIONS MET! Will retry ${pendingRetryCount} pending message(s) after ${RECONNECTION_RETRY_DELAY_MS}ms delay...`
       )
       // Small delay to ensure the connection is fully established
       const timer = setTimeout(() => {
         logger.info('[RETRY-EFFECT] Calling retryPendingMessages()')
         retryPendingMessagesRef.current?.()
-      }, 500)
+      }, RECONNECTION_RETRY_DELAY_MS)
       return () => {
         clearTimeout(timer)
       }
@@ -864,7 +883,9 @@ export const Chat = ({
   )
 
   const validationBanner = useValidationBanner({
-    liveValidationErrors: networkStatus.isOnline ? validationErrors : [],
+    liveValidationErrors: networkStatus.validation.isReachable
+      ? validationErrors
+      : [],
     loadedAgentsData,
     theme,
   })
@@ -1063,11 +1084,16 @@ export const Chat = ({
             paddingBottom: 1,
             paddingLeft: 1,
             paddingRight: 1,
-            backgroundColor: '#333333',
+            backgroundColor: theme.surface ?? theme.background ?? '#333333',
           }}
         >
-          <text style={{ fg: '#FFA500', wrapMode: 'word' }}>
-            ⚠️ Network Error: {networkStatus.error.message}
+          <text
+            style={{
+              fg: theme.warning ?? theme.foreground,
+              wrapMode: 'word',
+            }}
+          >
+            {offlineBannerMessage}
           </text>
         </box>
       )}

cli/src/components/shimmer-text.tsx

@@ -2,6 +2,7 @@ import { TextAttributes } from '@opentui/core'
 import React, { useEffect, useMemo, useState } from 'react'
 
 import { useTheme } from '../hooks/use-theme'
+import { SHIMMER_INTERVAL_MS } from '../utils/ui-constants'
 
 const clamp = (value: number, min: number, max: number): number =>
   Math.min(max, Math.max(min, value))
@@ -130,7 +131,7 @@ const generatePaletteFromPrimary = (
 
 export const ShimmerText = ({
   text,
-  interval = 180,
+  interval = SHIMMER_INTERVAL_MS,
   colors,
   primaryColor,
 }: {
@@ -145,7 +146,7 @@ export const ShimmerText = ({
   const numChars = chars.length
 
   if (numChars === 0) {
-    return null
+    return <></>
   }
 
   useEffect(() => {

cli/src/hooks/__tests__/use-network-status.test.ts

@@ -1,8 +1,5 @@
-import { describe, expect, test, beforeEach, afterEach, spyOn } from 'bun:test'
-import { renderHook } from '@testing-library/react'
-import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
-import React from 'react'
-import { useNetworkStatus } from '../use-network-status'
+import { describe, expect, test, spyOn } from 'bun:test'
+import { useNetworkStatus, type NetworkStatus } from '../use-network-status'
 import * as useAuthQueryModule from '../use-auth-query'
 
 /**
@@ -60,7 +57,7 @@ describe('useNetworkStatus', () => {
       mockUseAuthQuery.mockRestore()
     })
 
-    test('detects validation network errors', () => {
+    test('reports validation degradation without marking offline', () => {
       const mockAuthQuery = {
         error: null,
         isError: false,
@@ -75,10 +72,12 @@ describe('useNetworkStatus', () => {
         validationNetworkError: 'Failed to connect to validation API',
       })
 
-      expect(result.isOnline).toBe(false)
+      expect(result.isOnline).toBe(true)
       expect(result.error).not.toBeNull()
       expect(result.error?.source).toBe('validation')
       expect(result.error?.message).toBe('Failed to connect to validation API')
+      expect(result.validation.isReachable).toBe(false)
+      expect(result.auth.isReachable).toBe(true)
 
       // Restore original
       mockUseAuthQuery.mockRestore()
@@ -137,44 +136,31 @@ describe('useNetworkStatus', () => {
   })
 
   describe('type definitions', () => {
-    test('NetworkStatus type is correctly defined', () => {
-      type NetworkStatus =
-        | { isOnline: true; error: null }
-        | { isOnline: false; error: { source: 'auth' | 'validation' | 'unknown'; message: string } }
-
-      const onlineStatus: NetworkStatus = {
+    test('NetworkStatus shape includes auth and validation fields', () => {
+      const status: NetworkStatus = {
         isOnline: true,
         error: null,
+        auth: { isReachable: true, error: null },
+        validation: { isReachable: false, error: 'Validation unavailable' },
       }
 
-      const offlineStatus: NetworkStatus = {
-        isOnline: false,
-        error: {
-          source: 'auth',
-          message: 'Network error',
-        },
-      }
-
-      expect(onlineStatus.isOnline).toBe(true)
-      expect(onlineStatus.error).toBeNull()
-      expect(offlineStatus.isOnline).toBe(false)
-      expect(offlineStatus.error.source).toBe('auth')
+      expect(status.isOnline).toBe(true)
+      expect(status.error).toBeNull()
+      expect(status.auth.isReachable).toBe(true)
+      expect(status.validation.isReachable).toBe(false)
+      expect(status.validation.error).toBe('Validation unavailable')
     })
 
     test('error sources are exhaustive', () => {
-      const sources = ['auth', 'validation', 'unknown']
-
-      sources.forEach(source => {
-        const status = {
-          isOnline: false,
-          error: {
-            source: source as 'auth' | 'validation' | 'unknown',
-            message: 'Test error',
-          },
-        }
-
-        expect(['auth', 'validation', 'unknown']).toContain(status.error.source)
+      const sources: Array<NetworkStatus['error']> = [
+        { source: 'auth', message: 'Auth down' },
+        { source: 'validation', message: 'Validation down' },
+        { source: 'unknown', message: 'Unknown' },
+      ]
+
+      sources.forEach((error) => {
+        expect(['auth', 'validation', 'unknown']).toContain(error?.source)
       })
     })
   })
-})
+})

cli/src/hooks/use-network-status.ts

@@ -1,51 +1,68 @@
-import { useState, useEffect, useCallback } from 'react'
 import { useAuthQuery } from './use-auth-query'
 import { isNetworkError } from '@codebuff/sdk'
 
-export type NetworkStatus =
-  | { isOnline: true; error: null }
-  | { isOnline: false; error: { source: 'auth' | 'validation' | 'unknown'; message: string } }
+export type NetworkStatusErrorSource = 'auth' | 'validation' | 'unknown'
+
+export interface NetworkStatusDetails {
+  isReachable: boolean
+  error: string | null
+}
+
+export interface NetworkStatus {
+  isOnline: boolean
+  error: { source: NetworkStatusErrorSource; message: string } | null
+  auth: NetworkStatusDetails
+  validation: NetworkStatusDetails
+}
 
 interface UseNetworkStatusOptions {
   validationNetworkError?: string | null
 }
 
 /**
  * Unified hook for network status detection.
- * Consolidates network error detection from auth and validation into a single source of truth.
+ * Keeps login/auth logic responsive even if the validation service is degraded.
  */
-export function useNetworkStatus(options: UseNetworkStatusOptions = {}): NetworkStatus {
+export function useNetworkStatus(
+  options: UseNetworkStatusOptions = {},
+): NetworkStatus {
   const { validationNetworkError } = options
   const authQuery = useAuthQuery()
 
-  // Check auth query for network errors
-  const authNetworkError = authQuery.error && isNetworkError(authQuery.error)
-    ? authQuery.error.message || 'Unable to reach server'
-    : null
-
-  // Determine overall network status
-  if (authNetworkError) {
-    return {
-      isOnline: false,
-      error: {
-        source: 'auth',
-        message: authNetworkError,
-      },
-    }
+  const authNetworkError =
+    authQuery.error && isNetworkError(authQuery.error)
+      ? authQuery.error.message || 'Unable to reach server'
+      : null
+
+  const authStatus: NetworkStatusDetails = {
+    isReachable: authNetworkError == null,
+    error: authNetworkError,
   }
 
-  if (validationNetworkError) {
-    return {
-      isOnline: false,
-      error: {
-        source: 'validation',
-        message: validationNetworkError,
-      },
+  const validationStatus: NetworkStatusDetails = {
+    isReachable: !validationNetworkError,
+    error: validationNetworkError ?? null,
+  }
+
+  let consolidatedError: NetworkStatus['error'] = null
+
+  if (!authStatus.isReachable) {
+    consolidatedError = {
+      source: 'auth',
+      message: authStatus.error ?? 'Unable to reach server',
+    }
+  } else if (!validationStatus.isReachable) {
+    consolidatedError = {
+      source: 'validation',
+      message:
+        validationStatus.error ?? 'Validation service is temporarily unavailable',
     }
   }
 
   return {
-    isOnline: true,
-    error: null,
+    isOnline: authStatus.isReachable,
+    error: consolidatedError,
+    auth: authStatus,
+    validation: validationStatus,
   }
-}
+}