Module: AgentHarness::ErrorTaxonomy

Defined in:
lib/agent_harness/error_taxonomy.rb

Overview

Error classification system for categorizing and handling errors

Provides a standardized way to classify errors from different providers into actionable categories for retry logic, provider switching, and error reporting.

Constant Summary collapse

CATEGORIES =

Error categories with their metadata

{
  rate_limited: {
    description: "Rate limit exceeded",
    action: :switch_provider,
    retryable: false
  },
  auth_expired: {
    description: "Authentication failed or expired",
    action: :reauthenticate,
    retryable: false
  },
  quota_exceeded: {
    description: "Usage quota exceeded",
    action: :switch_provider,
    retryable: false
  },
  transient: {
    description: "Temporary error",
    action: :retry_with_backoff,
    retryable: true
  },
  permanent: {
    description: "Unrecoverable error",
    action: :escalate,
    retryable: false
  },
  timeout: {
    description: "Operation timed out",
    action: :retry_with_backoff,
    retryable: true
  },
  idle_timeout: {
    description: "Operation exceeded idle timeout",
    action: :escalate,
    retryable: false
  },
  sandbox_failure: {
    description: "Sandbox setup failed",
    action: :escalate,
    retryable: false
  },
  unknown: {
    description: "Unknown error",
    action: :retry_with_backoff,
    retryable: true
  }
}.freeze

Class Method Summary collapse

Class Method Details

.action_for(category) ⇒ Symbol

Get recommended action for error category

Parameters:

  • category (Symbol) —

    the error category

Returns:

  • (Symbol) —

    recommended action



92
93
94
 
# File 'lib/agent_harness/error_taxonomy.rb', line 92

def action_for(category)
  CATEGORIES.dig(category, :action) || :escalate
end

.categories ⇒ Array<Symbol>

Get all category names

Returns:

  • (Array<Symbol>) —

    list of category names



115
116
117
 
# File 'lib/agent_harness/error_taxonomy.rb', line 115

def categories
  CATEGORIES.keys
end

.classify(error, patterns = {}) ⇒ Symbol

Classify an error based on provider patterns

Parameters:

  • error (Exception) —

    the error to classify

  • patterns (Hash<Symbol, Array<Regexp>>) (defaults to: {}) —

    provider-specific patterns

Returns:

  • (Symbol) —

    error category



65
66
67
68
69
70
71
72
73
74
75
76
77
78
 
# File 'lib/agent_harness/error_taxonomy.rb', line 65

def classify(error, patterns = {})
  return :idle_timeout if error.is_a?(IdleTimeoutError)
  return :timeout if error.is_a?(TimeoutError)

  message = error.message.to_s.downcase

  # Check provider-specific patterns first
  patterns.each do |category, regexes|
    return category if regexes.any? { |r| message.match?(r) }
  end

  # Fall back to generic patterns
  classify_generic(message)
end

.classify_message(message) ⇒ Symbol

Classify a message string into error category

Parameters:

  • message (String) —

    the error message

Returns:

  • (Symbol) —

    error category



84
85
86
 
# File 'lib/agent_harness/error_taxonomy.rb', line 84

def classify_message(message)
  classify_generic(message.to_s.downcase)
end

.description_for(category) ⇒ String

Get description for error category

Parameters:

  • category (Symbol) —

    the error category

Returns:

  • (String) —

    human-readable description



108
109
110
 
# File 'lib/agent_harness/error_taxonomy.rb', line 108

def description_for(category)
  CATEGORIES.dig(category, :description) || "Unknown error"
end

.retryable?(category) ⇒ Boolean

Check if error category is retryable

Parameters:

  • category (Symbol) —

    the error category

Returns:

  • (Boolean) —

    true if the error can be retried



100
101
102
 
# File 'lib/agent_harness/error_taxonomy.rb', line 100

def retryable?(category)
  CATEGORIES.dig(category, :retryable) || false
end