Class: AgentHarness::Providers::Base

Inherits:
Object
  • Object
show all
Includes:
Adapter
Defined in:
lib/agent_harness/providers/base.rb

Overview

Base class for all providers

Provides common functionality for provider implementations including command execution, error handling, and response parsing.

Examples:

Implementing a provider

class MyProvider < AgentHarness::Providers::Base
  class << self
    def provider_name
      :my_provider
    end

    def binary_name
      "my-cli"
    end

    def available?
      system("which my-cli > /dev/null 2>&1")
    end
  end
end

Constant Summary collapse

DEFAULT_SMOKE_TEST_CONTRACT = 
{
  prompt: "Reply with exactly OK.",
  expected_output: "OK",
  timeout: 30,
  require_output: true,
  success_message: "Smoke test passed"
}.freeze
COMMON_ERROR_PATTERNS =

Common error patterns shared across providers that use standard HTTP-style error responses. Providers with unique patterns (e.g. Anthropic, GitHub Copilot) override error_patterns entirely.

{
  rate_limited: [
    /rate.?limit/i,
    /too.?many.?requests/i,
    /\b429\b/
  ],
  auth_expired: [
    /invalid.*api.*key/i,
    /unauthorized/i,
    /authentication/i
  ],
  quota_exceeded: [
    /quota.*exceeded/i,
    /insufficient.*quota/i,
    /billing/i
  ],
  transient: [
    /timeout/i,
    /connection.*error/i,
    /service.*unavailable/i,
    /\b503\b/,
    /\b502\b/
  ]
}.tap { |patterns| patterns.each_value(&:freeze) }.freeze

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Adapter

#auth_type, #build_mcp_flags, #capabilities, #configuration_schema, #dangerous_mode_flags, #error_patterns, #execution_semantics, #fetch_mcp_servers, #health_status, included, metadata_package_name, normalize_metadata_installation, normalize_metadata_source_type, normalize_metadata_version_requirement, #parse_rate_limit_reset, #session_flags, #smoke_test, #smoke_test_contract, #supported_mcp_transports, #supports_dangerous_mode?, #supports_mcp?, #supports_sessions?, #validate_config, #validate_mcp_servers!

Constructor Details

#initialize(config: nil, executor: nil, logger: nil) ⇒ Base

Initialize the provider

Parameters:

  • config (ProviderConfig, nil) (defaults to: nil) —

    provider configuration

  • executor (CommandExecutor, nil) (defaults to: nil) —

    command executor

  • logger (Logger, nil) (defaults to: nil) —

    logger instance



79
80
81
82
83
 
# File 'lib/agent_harness/providers/base.rb', line 79

def initialize(config: nil, executor: nil, logger: nil)
  @config = config || ProviderConfig.new(self.class.provider_name)
  @executor = executor || AgentHarness.configuration.command_executor
  @logger = logger || AgentHarness.logger
end

Instance Attribute Details

#config ⇒ Object (readonly)

Returns the value of attribute config.



65
66
67
 
# File 'lib/agent_harness/providers/base.rb', line 65

def config
  @config
end

#executor ⇒ Object

Returns the value of attribute executor.



66
67
68
 
# File 'lib/agent_harness/providers/base.rb', line 66

def executor
  @executor
end

#logger ⇒ Object (readonly)

Returns the value of attribute logger.



65
66
67
 
# File 'lib/agent_harness/providers/base.rb', line 65

def logger
  @logger
end

Class Method Details

.smoke_test_contract ⇒ Object 



69
70
71
 
# File 'lib/agent_harness/providers/base.rb', line 69

def smoke_test_contract
  nil
end

Instance Method Details

#configure(options = {}) ⇒ self

Configure the provider instance

Parameters:

  • options (Hash) (defaults to: {}) —

    configuration options

Returns:

  • (self) 


89
90
91
92
 
# File 'lib/agent_harness/providers/base.rb', line 89

def configure(options = {})
  @config.merge!(options)
  self
end

#display_name ⇒ String

Human-friendly display name

Returns:

  • (String) —

    display name



174
175
176
 
# File 'lib/agent_harness/providers/base.rb', line 174

def display_name
  name.capitalize
end

#name ⇒ String

Provider name for display

Returns:

  • (String) —

    display name



167
168
169
 
# File 'lib/agent_harness/providers/base.rb', line 167

def name
  self.class.provider_name.to_s
end

#sandboxed_environment? ⇒ Boolean

Whether the provider is running inside a sandboxed (Docker) environment

Providers can use this to adjust execution flags, e.g. skipping nested sandboxing when already inside a container.

Returns:

  • (Boolean) —

    true when the executor is a DockerCommandExecutor



184
185
186
 
# File 'lib/agent_harness/providers/base.rb', line 184

def sandboxed_environment?
  @executor.is_a?(DockerCommandExecutor)
end

#send_message(prompt:, **options) ⇒ Response

Main send_message implementation

Parameters:

  • prompt (String) —

    the prompt to send

  • options (Hash) —

    additional options

Options Hash (**options):

  • :provider_runtime (ProviderRuntime, Hash, nil) —

    per-request runtime overrides (model, base_url, api_provider, env, flags, metadata). A plain Hash is automatically coerced into a ProviderRuntime. Providers can derive request-scoped execution preparation from this runtime to materialize config files or other bootstrap state.

Returns:



104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
 
# File 'lib/agent_harness/providers/base.rb', line 104

def send_message(prompt:, **options)
  log_debug("send_message_start", prompt_length: prompt.length, options: options.keys)

  # Coerce provider_runtime from Hash if needed
  options = normalize_provider_runtime(options)

  # Normalize and validate MCP servers
  options = normalize_mcp_servers(options)
  validate_mcp_servers!(options[:mcp_servers]) if options[:mcp_servers]&.any?

  # Build command
  command = build_command(prompt, options)
  preparation = build_execution_preparation(options)

  # Calculate timeout
  timeout = options[:timeout] || @config.timeout || default_timeout

  # Execute command
  start_time = Time.now
  result = execute_with_timeout(
    command,
    timeout: timeout,
    env: build_env(options),
    preparation: preparation,
    **command_execution_options(options)
  )
  duration = Time.now - start_time

  # Parse response
  response = parse_response(result, duration: duration)
  runtime = options[:provider_runtime]
  # Runtime model is a per-request override and always takes precedence
  # over both the config-level model and whatever parse_response returned.
  # This is intentional: callers use runtime overrides to route a single
  # provider instance through different backends on each request.
  if runtime&.model
    response = Response.new(
      output: response.output,
      exit_code: response.exit_code,
      duration: response.duration,
      provider: response.provider,
      model: runtime.model,
      tokens: response.tokens,
      metadata: response.metadata,
      error: response.error
    )
  end

  # Track tokens
  track_tokens(response) if response.tokens

  log_debug("send_message_complete", duration: duration, tokens: response.tokens)

  response
rescue McpConfigurationError, McpUnsupportedError, McpTransportUnsupportedError
  raise
rescue => e
  handle_error(e, prompt: prompt, options: options)
end