outcome-cli 1.0.0

package/src/utils/errors.ts

@@ -0,0 +1,442 @@
+/**
+ * Custom Error Types - Structured error handling for the Earnd Bounty Engine
+ *
+ * Provides typed error classes for different failure scenarios:
+ * - ValidationError: Invalid outcome/agent schemas, malformed data
+ * - ExecutionError: Model API failures, timeouts, network issues
+ * - LimitError: Cost ceiling, attempt limit, time limit exceeded
+ * - SystemError: Infrastructure failures, Durable Object issues
+ *
+ * @module utils/errors
+ * @see Requirements 5.4, 10.4
+ */
+
+/**
+ * Error codes for structured error handling.
+ */
+export enum ErrorCode {
+  // Validation errors (1xxx)
+  VALIDATION_SCHEMA_INVALID = 'VALIDATION_SCHEMA_INVALID',
+  VALIDATION_FIELD_MISSING = 'VALIDATION_FIELD_MISSING',
+  VALIDATION_FIELD_INVALID = 'VALIDATION_FIELD_INVALID',
+  VALIDATION_DATA_MALFORMED = 'VALIDATION_DATA_MALFORMED',
+
+  // Execution errors (2xxx)
+  EXECUTION_MODEL_FAILURE = 'EXECUTION_MODEL_FAILURE',
+  EXECUTION_TIMEOUT = 'EXECUTION_TIMEOUT',
+  EXECUTION_NETWORK_ERROR = 'EXECUTION_NETWORK_ERROR',
+  EXECUTION_RETRY_EXHAUSTED = 'EXECUTION_RETRY_EXHAUSTED',
+
+  // Limit errors (3xxx)
+  LIMIT_COST_EXCEEDED = 'LIMIT_COST_EXCEEDED',
+  LIMIT_ATTEMPTS_EXCEEDED = 'LIMIT_ATTEMPTS_EXCEEDED',
+  LIMIT_TIME_EXCEEDED = 'LIMIT_TIME_EXCEEDED',
+  LIMIT_GLOBAL_SPEND_EXCEEDED = 'LIMIT_GLOBAL_SPEND_EXCEEDED',
+
+  // System errors (4xxx)
+  SYSTEM_INFRASTRUCTURE_FAILURE = 'SYSTEM_INFRASTRUCTURE_FAILURE',
+  SYSTEM_STATE_CORRUPTION = 'SYSTEM_STATE_CORRUPTION',
+  SYSTEM_UNKNOWN_ERROR = 'SYSTEM_UNKNOWN_ERROR',
+}
+
+/**
+ * Structured error response format.
+ * Used for consistent error reporting across the system.
+ *
+ * @see design.md - Error Response Format
+ */
+export interface ErrorResponse {
+  /** Error code for programmatic handling */
+  code: ErrorCode | string;
+  /** Human-readable error message */
+  message: string;
+  /** Additional context about the error */
+  details?: Record<string, unknown>;
+  /** Whether the error is potentially recoverable */
+  recoverable: boolean;
+}
+
+/**
+ * Base class for all Earnd Bounty Engine errors.
+ * Extends Error with structured response format.
+ */
+export abstract class EarndError extends Error {
+  /** Error code for programmatic handling */
+  abstract readonly code: ErrorCode;
+  /** Whether the error is potentially recoverable */
+  abstract readonly recoverable: boolean;
+  /** Additional context about the error */
+  readonly details?: Record<string, unknown>;
+
+  constructor(message: string, details?: Record<string, unknown>) {
+    super(message);
+    this.name = this.constructor.name;
+    this.details = details;
+
+    // Maintains proper stack trace for where error was thrown
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, this.constructor);
+    }
+  }
+
+  /**
+   * Converts the error to a structured ErrorResponse.
+   */
+  toResponse(): ErrorResponse {
+    return {
+      code: this.code,
+      message: this.message,
+      details: this.details,
+      recoverable: this.recoverable,
+    };
+  }
+}
+
+/**
+ * Validation Error - Invalid schemas, malformed data
+ *
+ * Thrown when:
+ * - Outcome/agent schemas are invalid
+ * - Required fields are missing
+ * - Data fails validation rules
+ *
+ * @see Requirements 5.4 - Fail closed on unverifiable data
+ */
+export class ValidationError extends EarndError {
+  readonly code: ErrorCode;
+  readonly recoverable = false; // Validation errors require fixing the input
+
+  constructor(
+    message: string,
+    code: ErrorCode = ErrorCode.VALIDATION_SCHEMA_INVALID,
+    details?: Record<string, unknown>
+  ) {
+    super(message, details);
+    this.code = code;
+  }
+
+  /**
+   * Creates a ValidationError for a missing field.
+   */
+  static missingField(fieldName: string, context?: string): ValidationError {
+    return new ValidationError(
+      `Missing required field: ${fieldName}${context ? ` in ${context}` : ''}`,
+      ErrorCode.VALIDATION_FIELD_MISSING,
+      { field: fieldName, context }
+    );
+  }
+
+  /**
+   * Creates a ValidationError for an invalid field value.
+   */
+  static invalidField(
+    fieldName: string,
+    reason: string,
+    value?: unknown
+  ): ValidationError {
+    return new ValidationError(
+      `Invalid field "${fieldName}": ${reason}`,
+      ErrorCode.VALIDATION_FIELD_INVALID,
+      { field: fieldName, reason, value }
+    );
+  }
+
+  /**
+   * Creates a ValidationError for malformed data.
+   */
+  static malformedData(message: string, details?: Record<string, unknown>): ValidationError {
+    return new ValidationError(message, ErrorCode.VALIDATION_DATA_MALFORMED, details);
+  }
+}
+
+/**
+ * Execution Error - Model API failures, timeouts, network issues
+ *
+ * Thrown when:
+ * - Model API calls fail
+ * - Network requests timeout
+ * - Retries are exhausted
+ *
+ * These errors may be recoverable with retry logic.
+ */
+export class ExecutionError extends EarndError {
+  readonly code: ErrorCode;
+  readonly recoverable: boolean;
+
+  constructor(
+    message: string,
+    code: ErrorCode = ErrorCode.EXECUTION_MODEL_FAILURE,
+    recoverable = true,
+    details?: Record<string, unknown>
+  ) {
+    super(message, details);
+    this.code = code;
+    this.recoverable = recoverable;
+  }
+
+  /**
+   * Creates an ExecutionError for a model API failure.
+   */
+  static modelFailure(
+    provider: string,
+    reason: string,
+    details?: Record<string, unknown>
+  ): ExecutionError {
+    return new ExecutionError(
+      `Model API failure (${provider}): ${reason}`,
+      ErrorCode.EXECUTION_MODEL_FAILURE,
+      true,
+      { provider, reason, ...details }
+    );
+  }
+
+  /**
+   * Creates an ExecutionError for a timeout.
+   */
+  static timeout(operation: string, durationMs: number): ExecutionError {
+    return new ExecutionError(
+      `Operation timed out: ${operation} after ${durationMs}ms`,
+      ErrorCode.EXECUTION_TIMEOUT,
+      true,
+      { operation, durationMs }
+    );
+  }
+
+  /**
+   * Creates an ExecutionError for a network error.
+   */
+  static networkError(message: string, details?: Record<string, unknown>): ExecutionError {
+    return new ExecutionError(
+      `Network error: ${message}`,
+      ErrorCode.EXECUTION_NETWORK_ERROR,
+      true,
+      details
+    );
+  }
+
+  /**
+   * Creates an ExecutionError when retries are exhausted.
+   */
+  static retryExhausted(
+    operation: string,
+    attempts: number,
+    lastError?: string
+  ): ExecutionError {
+    return new ExecutionError(
+      `Retries exhausted for ${operation} after ${attempts} attempts${lastError ? `: ${lastError}` : ''}`,
+      ErrorCode.EXECUTION_RETRY_EXHAUSTED,
+      false, // No more retries possible
+      { operation, attempts, lastError }
+    );
+  }
+}
+
+/**
+ * Limit Error - Cost ceiling, attempt limit, time limit exceeded
+ *
+ * Thrown when:
+ * - Agent exceeds cost ceiling
+ * - Agent exceeds attempt limit
+ * - Agent exceeds time limit
+ * - Global spend ceiling is exceeded
+ *
+ * @see Requirements 10.4 - Fail closed with no payout on limit exceeded
+ */
+export class LimitError extends EarndError {
+  readonly code: ErrorCode;
+  readonly recoverable = false; // Limit errors mean termination
+
+  constructor(
+    message: string,
+    code: ErrorCode = ErrorCode.LIMIT_COST_EXCEEDED,
+    details?: Record<string, unknown>
+  ) {
+    super(message, details);
+    this.code = code;
+  }
+
+  /**
+   * Creates a LimitError for cost ceiling exceeded.
+   */
+  static costExceeded(
+    agentId: string,
+    spent: number,
+    ceiling: number
+  ): LimitError {
+    return new LimitError(
+      `Agent ${agentId} exceeded cost ceiling: ${spent} > ${ceiling} tokens`,
+      ErrorCode.LIMIT_COST_EXCEEDED,
+      { agentId, spent, ceiling }
+    );
+  }
+
+  /**
+   * Creates a LimitError for attempts exceeded.
+   */
+  static attemptsExceeded(
+    agentId: string,
+    attempts: number,
+    maxAttempts: number
+  ): LimitError {
+    return new LimitError(
+      `Agent ${agentId} exceeded attempt limit: ${attempts} >= ${maxAttempts}`,
+      ErrorCode.LIMIT_ATTEMPTS_EXCEEDED,
+      { agentId, attempts, maxAttempts }
+    );
+  }
+
+  /**
+   * Creates a LimitError for time limit exceeded.
+   */
+  static timeExceeded(
+    agentId: string,
+    elapsedMs: number,
+    limitMs: number
+  ): LimitError {
+    return new LimitError(
+      `Agent ${agentId} exceeded time limit: ${elapsedMs}ms >= ${limitMs}ms`,
+      ErrorCode.LIMIT_TIME_EXCEEDED,
+      { agentId, elapsedMs, limitMs }
+    );
+  }
+
+  /**
+   * Creates a LimitError for global spend ceiling exceeded.
+   */
+  static globalSpendExceeded(
+    totalSpent: number,
+    ceiling: number
+  ): LimitError {
+    return new LimitError(
+      `Global spend ceiling exceeded: ${totalSpent} > ${ceiling}`,
+      ErrorCode.LIMIT_GLOBAL_SPEND_EXCEEDED,
+      { totalSpent, ceiling }
+    );
+  }
+}
+
+/**
+ * System Error - Infrastructure failures, state corruption
+ *
+ * Thrown when:
+ * - Cloudflare Worker/Durable Object failures
+ * - State corruption detected
+ * - Unknown system errors occur
+ *
+ * These errors typically require operator intervention.
+ */
+export class SystemError extends EarndError {
+  readonly code: ErrorCode;
+  readonly recoverable = false; // System errors require intervention
+
+  constructor(
+    message: string,
+    code: ErrorCode = ErrorCode.SYSTEM_UNKNOWN_ERROR,
+    details?: Record<string, unknown>
+  ) {
+    super(message, details);
+    this.code = code;
+  }
+
+  /**
+   * Creates a SystemError for infrastructure failure.
+   */
+  static infrastructureFailure(
+    component: string,
+    reason: string,
+    details?: Record<string, unknown>
+  ): SystemError {
+    return new SystemError(
+      `Infrastructure failure in ${component}: ${reason}`,
+      ErrorCode.SYSTEM_INFRASTRUCTURE_FAILURE,
+      { component, reason, ...details }
+    );
+  }
+
+  /**
+   * Creates a SystemError for state corruption.
+   */
+  static stateCorruption(
+    context: string,
+    details?: Record<string, unknown>
+  ): SystemError {
+    return new SystemError(
+      `State corruption detected: ${context}`,
+      ErrorCode.SYSTEM_STATE_CORRUPTION,
+      { context, ...details }
+    );
+  }
+
+  /**
+   * Creates a SystemError from an unknown error.
+   */
+  static fromUnknown(error: unknown): SystemError {
+    const message = error instanceof Error ? error.message : String(error);
+    const stack = error instanceof Error ? error.stack : undefined;
+    return new SystemError(
+      `Unknown system error: ${message}`,
+      ErrorCode.SYSTEM_UNKNOWN_ERROR,
+      { originalMessage: message, stack }
+    );
+  }
+}
+
+/**
+ * Type guard to check if an error is an EarndError.
+ */
+export function isEarndError(error: unknown): error is EarndError {
+  return error instanceof EarndError;
+}
+
+/**
+ * Type guard to check if an error is a ValidationError.
+ */
+export function isValidationError(error: unknown): error is ValidationError {
+  return error instanceof ValidationError;
+}
+
+/**
+ * Type guard to check if an error is an ExecutionError.
+ */
+export function isExecutionError(error: unknown): error is ExecutionError {
+  return error instanceof ExecutionError;
+}
+
+/**
+ * Type guard to check if an error is a LimitError.
+ */
+export function isLimitError(error: unknown): error is LimitError {
+  return error instanceof LimitError;
+}
+
+/**
+ * Type guard to check if an error is a SystemError.
+ */
+export function isSystemError(error: unknown): error is SystemError {
+  return error instanceof SystemError;
+}
+
+/**
+ * Converts any error to an ErrorResponse.
+ * Useful for consistent error handling at API boundaries.
+ */
+export function toErrorResponse(error: unknown): ErrorResponse {
+  if (isEarndError(error)) {
+    return error.toResponse();
+  }
+
+  if (error instanceof Error) {
+    return {
+      code: ErrorCode.SYSTEM_UNKNOWN_ERROR,
+      message: error.message,
+      details: { name: error.name, stack: error.stack },
+      recoverable: false,
+    };
+  }
+
+  return {
+    code: ErrorCode.SYSTEM_UNKNOWN_ERROR,
+    message: String(error),
+    recoverable: false,
+  };
+}

package/src/utils/index.ts

@@ -0,0 +1,37 @@
+/**
+ * Utils Module - Shared utilities for the Earnd Bounty Engine
+ *
+ * @module utils
+ */
+
+export {
+  type LogResult,
+  type LogEntry,
+  type LogEntryInput,
+  log,
+  getLogs,
+  getAgentLogs,
+  clearLogs,
+  clearAllLogs,
+  getTotalLogCount,
+  formatLogsForCli,
+  logSuccess,
+  logFailure,
+  logPending,
+} from './logger.js';
+
+export {
+  ErrorCode,
+  type ErrorResponse,
+  EarndError,
+  ValidationError,
+  ExecutionError,
+  LimitError,
+  SystemError,
+  isEarndError,
+  isValidationError,
+  isExecutionError,
+  isLimitError,
+  isSystemError,
+  toErrorResponse,
+} from './errors.js';