Claude Code: Fix import structure - decouple error_handlers from app

- Remove module-level sys.path manipulation from error_handlers.py
- Add register_error_handlers(app) function for explicit handler registration
- Move sys.path setup to app.py where it belongs
- This eliminates potential circular import issues

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

app.py

@@ -15,20 +15,39 @@ import uuid
 import logging
 from datetime import datetime
 from enum import Enum
+from pathlib import Path
+from typing import Any, Optional
+from contextlib import asynccontextmanager
+
+import uvicorn
 from fastapi import FastAPI, HTTPException, BackgroundTasks, WebSocket, WebSocketDisconnect, Request
 from fastapi.responses import JSONResponse, FileResponse
 from fastapi.staticfiles import StaticFiles
 from fastapi.middleware import Middleware
 from starlette.middleware.base import BaseHTTPMiddleware
-from pathlib import Path
-from typing import Any, Optional
-from contextlib import asynccontextmanager
-import uvicorn
-from error_handlers import (
-    http_exception_handler,
-    value_error_handler,
-    generic_exception_handler,
-)
+
+# ============================================================================
+# SYS.PATH SETUP (must happen before other imports)
+# ============================================================================
+
+# Set up sys.path for agents imports at module load time
+# This ensures `from agents import brain_minimal` works regardless of import order
+# Dynamic path resolution with fallbacks for different Docker contexts
+_script_dir = Path(os.path.abspath(os.path.dirname(__file__)))  # Absolute path of this script
+
+# Try multiple possible locations for .openclaw directory
+_possible_openclaw_paths = [
+    _script_dir / ".openclaw",           # /app/.openclaw (legacy/flat structure)
+    _script_dir / "openclaw" / ".openclaw",  # /app/openclaw/.openclaw (nested structure)
+    Path("/app/openclaw/.openclaw"),     # Absolute Docker path (nested)
+    Path("/app/.openclaw"),              # Absolute Docker path (flat)
+]
+
+# Add all valid paths to sys.path
+for path_dir in _possible_openclaw_paths:
+    path_str = str(path_dir)
+    if path_str not in sys.path and path_dir.exists():
+        sys.path.insert(0, path_str)
 
 # ============================================================================
 # CONFIGURATION & LOGGING
@@ -744,10 +763,9 @@ app = FastAPI(
     lifespan=lifespan
 )
 
-# Register exception handlers
-app.add_exception_handler(HTTPException, http_exception_handler)
-app.add_exception_handler(ValueError, value_error_handler)
-app.add_exception_handler(Exception, generic_exception_handler)
+# Register exception handlers (import here to avoid circular dependency)
+from error_handlers import register_error_handlers
+register_error_handlers(app)
 
 # Add request logging middleware
 app.add_middleware(RequestLoggingMiddleware)

error_handlers.py

@@ -2,6 +2,9 @@
 """
 Error handling utilities for HuggingClaw - Cain.
 Provides specific exception handlers for common operations.
+
+NOTE: This module is intentionally decoupled from app.py to avoid circular imports.
+Exception handlers are registered via register_error_handlers(app) function.
 """
 import json
 import os
@@ -11,7 +14,7 @@ import traceback
 from datetime import datetime
 from pathlib import Path
 from typing import Dict, Any, Optional
-from fastapi import HTTPException, Request
+from fastapi import FastAPI, HTTPException, Request
 from fastapi.responses import JSONResponse
 
 # Dedicated error logger for exception tracking
@@ -31,25 +34,6 @@ error_logger = logging.getLogger("cain.errors")
 error_logger.setLevel(logging.ERROR)
 error_logger.addHandler(error_handler)
 
-# CRITICAL: Set up sys.path for agents imports at module load time
-# This ensures `from agents import brain_minimal` works regardless of import order
-# Dynamic path resolution with fallbacks for different Docker contexts
-_script_dir = Path(os.path.abspath(os.path.dirname(__file__)))  # Absolute path of this script
-
-# Try multiple possible locations for .openclaw directory
-_possible_openclaw_paths = [
-    _script_dir / ".openclaw",           # /app/.openclaw (legacy/flat structure)
-    _script_dir / "openclaw" / ".openclaw",  # /app/openclaw/.openclaw (nested structure)
-    Path("/app/openclaw/.openclaw"),     # Absolute Docker path (nested)
-    Path("/app/.openclaw"),              # Absolute Docker path (flat)
-]
-
-# Add all valid paths to sys.path
-for path_dir in _possible_openclaw_paths:
-    path_str = str(path_dir)
-    if path_str not in sys.path and path_dir.exists():
-        sys.path.insert(0, path_str)
-
 
 def log_exception(exc: Exception, request: Request = None) -> None:
     """
@@ -378,3 +362,18 @@ def write_cain_status(status_data: Dict[str, Any]) -> bool:
     except (PermissionError, OSError, json.JSONDecodeError) as e:
         print(f"Error writing status file: {e}")
         return False
+
+
+def register_error_handlers(app: FastAPI) -> None:
+    """
+    Register exception handlers with the FastAPI app.
+
+    This function-based registration avoids circular imports by not importing
+    app at module level. Call this after creating the FastAPI app instance.
+
+    Args:
+        app: The FastAPI application instance.
+    """
+    app.add_exception_handler(HTTPException, http_exception_handler)
+    app.add_exception_handler(ValueError, value_error_handler)
+    app.add_exception_handler(Exception, generic_exception_handler)