context.json

{
  "files_to_modify": {
    "backend": [
      "apps/backend/core/error_classifier.py",
      "apps/backend/core/error_utils.py",
      "apps/backend/agents/session.py",
      "apps/backend/core/client.py"
    ]
  },
  "files_to_create": {
    "backend": [
      "apps/backend/core/error_codes.py",
      "apps/backend/core/typed_errors.py",
      "apps/backend/core/error_detection.py",
      "tests/test_sdk_error_wrapping.py"
    ],
    "docs": [
      "docs/error-handling.md"
    ]
  },
  "files_to_reference": [
    "apps/backend/core/error_classifier.py",
    "apps/backend/core/error_utils.py",
    "apps/backend/core/providers/exceptions.py",
    "apps/backend/agents/session.py",
    "tests/test_error_classifier.py"
  ],
  "patterns": {
    "error_classification": "ErrorClassifier class uses regex patterns to match error strings. Has SDKErrorCategory enum with categories like AUTH_INVALID, RATE_LIMITED, etc.",
    "error_utils": "Helper functions like is_rate_limit_error(), is_auth_error() use string matching with .lower() and 'in' checks",
    "exception_pattern": "Custom exceptions inherit from Exception, use descriptive class names, may have custom attributes",
    "enum_pattern": "SDKErrorCategory uses class-based enum with string values. Use auto() for automatic value assignment.",
    "test_pattern": "Tests use pytest, organize into classes by function, use fixtures for setup"
  },
  "existing_implementations": {
    "error_classifier": {
      "description": "Found ErrorClassifier in core/error_classifier.py with string-based pattern matching",
      "relevant_files": [
        "apps/backend/core/error_classifier.py"
      ],
      "details": "Has SDKErrorCategory enum (AUTH_INVALID, AUTH_EXPIRED, RATE_LIMITED, etc.). Uses regex patterns stored in module-level lists (_AUTH_PATTERNS, _RATE_LIMIT_PATTERNS). classify_exception() and classify_response() methods do string matching."
    },
    "error_utils": {
      "description": "Found error utility functions in core/error_utils.py",
      "relevant_files": [
        "apps/backend/core/error_utils.py"
      ],
      "details": "Functions like is_tool_concurrency_error(), is_rate_limit_error(), is_authentication_error() all use string checking: error_str = str(error).lower(); return 'pattern' in error_str. Fragile and error-prone."
    },
    "custom_exceptions": {
      "description": "Found many custom exception classes throughout codebase",
      "relevant_files": [
        "apps/backend/core/providers/exceptions.py",
        "apps/backend/core/worktree.py",
        "apps/backend/agents/process_isolator.py"
      ],
      "details": "ProviderError, ProviderNotInstalled, ProviderConfigError, WorktreeError, AgentProcessError, etc. All inherit from Exception but don't have error_code field."
    },
    "error_usage": {
      "description": "ErrorClassifier used in agents/session.py for error classification",
      "relevant_files": [
        "apps/backend/agents/session.py"
      ],
      "details": "Imports ErrorClassifier, likely used for detecting and handling SDK errors during agent sessions"
    }
  }
}