src — errors

Module: src-errors Cohesion: 0.80 Members: 0

src — errors

The src/errors module provides a comprehensive and centralized system for error handling, classification, and recovery within the Code Buddy application. It defines a custom error hierarchy, implements robust crash handling for unexpected shutdowns, and offers an intelligent error recovery mechanism for common operational issues.

This module aims to:

1. Core Error Hierarchy

At the heart of the error system is CodeBuddyError, a custom base class that extends Node.js's native Error. All application-specific errors inherit from CodeBuddyError, ensuring a consistent structure and additional metadata.

src/errors/base-error.ts

CodeBuddyError This class serves as the foundation for all custom errors. It adds several key properties:

It also includes a toJSON() method for easy serialization of error details.

src/errors/index.ts - Utility Functions

This file aggregates all error exports and provides several utility functions for working with errors:

Error Hierarchy Diagram

classDiagram
    Error <|-- CodeBuddyError
    CodeBuddyError <|-- ApiError
    CodeBuddyError <|-- ContextLimitExceededError
    CodeBuddyError <|-- ToolExecutionError
    ApiError <|-- RateLimitError
    ApiError <|-- AuthenticationError

2. Specific Error Types

The module defines several specialized error classes, each extending CodeBuddyError and adding domain-specific properties.

src/errors/agent-error.ts

Errors related to the agent's operational constraints or user interaction:

src/errors/tool-error.ts

Errors specific to tool usage and execution:

src/errors/provider-error.ts

Errors originating from external API providers:

3. Error Recovery System

The error-recovery.ts module provides a sophisticated system for classifying errors and attempting automatic recovery. It's designed for handled errors within the application's operational flow, offering a more graceful response than simply crashing.

src/errors/error-recovery.ts

ErrorRecoveryManager (Singleton) This class manages error classification, recovery strategies, and provides formatted messages.

Error Recovery Flow

graph TD
    A[Application Code] --> B{Throw Error}
    B --> C[getErrorRecoveryManager().handleError(error)]
    C --> D[classifyError(error)]
    D -- ClassifiedError --> E{Is Recoverable?}
    E -- Yes --> F[Apply Recovery Strategies]
    F -- Strategy Success --> G[Emit 'recovered' event]
    F -- Strategy Fail --> H[Emit 'unrecoverable' event]
    E -- No --> H
    H --> I[Log & Display Error]

4. Crash Handling

The crash-handler.ts module is responsible for gracefully handling unhandled exceptions and process signals (like SIGINT, SIGTERM) that would otherwise lead to an abrupt application termination. Its primary goal is to preserve session state and provide recovery options.

src/errors/crash-handler.ts

CrashHandler (Singleton) This class manages the process of saving crash context and restoring the terminal state.

5. Crash Recovery

The crash-recovery.ts module works in conjunction with crash-handler.ts to detect and offer recovery from previous unclean shutdowns at application startup.

src/errors/crash-recovery.ts

6. Integration and Usage

This robust error management system is critical for Code Buddy's stability, user experience, and maintainability, providing clear error context for developers and graceful recovery options for users.