@dexwox-labs/a2a-core/src/errors.ts

Core types, validation and telemetry for Google's Agent-to-Agent (A2A) protocol - shared foundation for client and server implementations

/**
 * @module Errors
 * @description Error classes and error codes for the A2A protocol
 */

/**
 * Standard error class for A2A SDK
 * 
 * This is the base error class for all errors in the A2A SDK. It includes
 * an error code and optional data payload for additional context.
 * The implementation matches the Python SDK for cross-language compatibility.
 * 
 * @example
 * ```typescript
 * // Create a basic error
 * const error = new A2AError('Something went wrong', -32000);
 * 
 * // Create an error with additional context data
 * const errorWithData = new A2AError(
 *   'Failed to process task', 
 *   -32014, 
 *   { taskId: '123', reason: 'Invalid input' }
 * );
 * 
 * // Error can be serialized to JSON
 * console.log(JSON.stringify(error));
 * // {"code":-32000,"message":"Something went wrong"}
 * ```
 */
export class A2AError extends Error {
  /**
   * Creates a new A2A error
   * 
   * @param message - Error message describing what went wrong
   * @param code - Numeric error code (typically negative, see ERROR_CODES)
   * @param data - Optional additional context data for the error
   */
  constructor(
    message: string, 
    public readonly code: number,
    public readonly data?: Record<string, unknown>
  ) {
    super(message);
    this.name = 'A2AError';
    // Fix prototype chain for proper instanceof checks
    Object.setPrototypeOf(this, A2AError.prototype);
  }

  /**
   * Converts the error to a JSON-serializable object
   * 
   * @returns JSON representation of the error
   */
  toJSON() {
    return {
      code: this.code,
      message: this.message,
      ...(this.data && { data: this.data })
    };
  }
}

/**
 * Task-specific error classes
 */

/**
 * Error thrown when attempting to transition a task to an invalid state
 * 
 * This error occurs when trying to change a task's state in a way that
 * violates the task state machine rules (e.g., trying to mark a failed
 * task as completed).
 * 
 * @example
 * ```typescript
 * throw new InvalidTaskStateError(
 *   'Cannot transition from FAILED to COMPLETED'
 * );
 * ```
 */
export class InvalidTaskStateError extends A2AError {
  /**
   * Creates a new invalid task state error
   * 
   * @param message - Description of the invalid state transition
   */
  constructor(message: string) {
    super(message, ERROR_CODES.INVALID_TASK_STATE);
  }
}

/**
 * Error thrown when a requested task cannot be found
 * 
 * This error occurs when attempting to access or modify a task that
 * doesn't exist or is no longer available.
 * 
 * @example
 * ```typescript
 * throw new TaskNotFoundError('task-123');
 * ```
 */
export class TaskNotFoundError extends A2AError {
  /**
   * Creates a new task not found error
   * 
   * @param taskId - ID of the task that couldn't be found
   */
  constructor(taskId: string) {
    super(`Task ${taskId} not found`, ERROR_CODES.TASK_NOT_FOUND);
  }
}

/**
 * Error thrown when attempting to modify a task that is already completed
 * 
 * This error occurs when trying to update or modify a task that has
 * already reached its completed state.
 * 
 * @example
 * ```typescript
 * throw new TaskAlreadyCompletedError('task-123');
 * ```
 */
export class TaskAlreadyCompletedError extends A2AError {
  /**
   * Creates a new task already completed error
   * 
   * @param taskId - ID of the completed task
   */
  constructor(taskId: string) {
    super(`Task ${taskId} is already completed`, ERROR_CODES.TASK_ALREADY_COMPLETED);
  }
}

/**
 * Error thrown when attempting to work with a task that was canceled
 * 
 * This error occurs when trying to access or modify a task that has
 * been canceled by the user or system.
 * 
 * @example
 * ```typescript
 * throw new TaskCanceledError('task-123');
 * ```
 */
export class TaskCanceledError extends A2AError {
  /**
   * Creates a new task canceled error
   * 
   * @param taskId - ID of the canceled task
   */
  constructor(taskId: string) {
    super(`Task ${taskId} was canceled`, ERROR_CODES.TASK_CANCELED);
  }
}

/**
 * Error thrown when a task has failed to complete successfully
 * 
 * This error occurs when a task encounters an error during execution
 * and cannot be completed.
 * 
 * @example
 * ```typescript
 * throw new TaskFailedError('task-123', 'Invalid input data');
 * ```
 */
export class TaskFailedError extends A2AError {
  /**
   * Creates a new task failed error
   * 
   * @param taskId - ID of the failed task
   * @param reason - Reason for the failure
   */
  constructor(taskId: string, reason: string) {
    super(`Task ${taskId} failed: ${reason}`, ERROR_CODES.TASK_FAILED);
  }
}

/**
 * Standard error codes for the A2A protocol
 * 
 * These error codes are standardized across all A2A SDK implementations
 * (JavaScript, Python, etc.) to ensure consistent error handling.
 * 
 * Error code ranges:
 * - Task errors: -32000 to -32049
 * - Queue errors: -32050 to -32099
 * 
 * @example
 * ```typescript
 * // Check for a specific error code
 * if (error.code === ERROR_CODES.TASK_NOT_FOUND) {
 *   console.log('The requested task does not exist');
 * }
 * ```
 */
export const ERROR_CODES = {
  // Task errors (-32000 to -32049)
  /** Error code for invalid task state transitions (-32010) */
  INVALID_TASK_STATE: -32010,
  /** Error code for task not found (-32011) */
  TASK_NOT_FOUND: -32011,
  /** Error code for attempting to modify a completed task (-32012) */
  TASK_ALREADY_COMPLETED: -32012,
  /** Error code for attempting to work with a canceled task (-32013) */
  TASK_CANCELED: -32013,
  /** Error code for a task that failed to complete (-32014) */
  TASK_FAILED: -32014,

  // Queue errors (-32050 to -32099)
  /** Error code for when a queue already exists (-32050) */
  QUEUE_EXISTS: -32050,
  /** Error code for when a required queue doesn't exist (-32051) */
  NO_QUEUE: -32051,
} as const;