Class: AgentHarness::Providers::Base

Inherits:
Object
  • Object
show all
Includes:
Extensions::DeepDupable, 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_lock_config, #auth_type, #build_mcp_flags, #capabilities, #chat_transport, #chat_transport_type, #config_file_content, #configuration_schema, #dangerous_mode_flags, #error_classification_patterns, #error_patterns, #execution_semantics, #fetch_mcp_servers, #health_status, included, metadata_package_name, #noisy_error_patterns, normalize_metadata_installation, normalize_metadata_source_type, normalize_metadata_version_requirement, #notify_hook_content, #session_flags, #smoke_test, #smoke_test_contract, #supported_mcp_transports, #supports_chat?, #supports_dangerous_mode?, #supports_mcp?, #supports_sessions?, #supports_text_mode?, #supports_token_counting?, #supports_tool_control?, #token_usage_from_api_response, #translate_error, #validate_config, #validate_mcp_servers!

Constructor Details

#initialize(config: nil, executor: nil, logger: nil, configuration: 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

  • configuration (Configuration, nil) (defaults to: nil) —

    parent configuration for extension/sub-agent resolution



81
82
83
84
85
86
 
# File 'lib/agent_harness/providers/base.rb', line 81

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

Instance Attribute Details

#config ⇒ Object (readonly)

Returns the value of attribute config.



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

def config
  @config
end

#executor ⇒ Object

Returns the value of attribute executor.



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

def executor
  @executor
end

#logger ⇒ Object (readonly)

Returns the value of attribute logger.



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

def logger
  @logger
end

Class Method Details

.smoke_test_contract ⇒ Object 



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

def smoke_test_contract
  nil
end

Instance Method Details

#api_key_env_var_names ⇒ Array<String>

Environment variable names that the provider’s CLI reads for API key authentication.

Returns:

  • (Array<String>) —

    env var names (empty by default)



368
 
# File 'lib/agent_harness/providers/base.rb', line 368

def api_key_env_var_names = []

#api_key_unset_vars ⇒ Array<String>

Environment variable names to unset when the caller supplies its own API key, preventing the CLI from reading stale or conflicting proxy/header variables.

Returns:

  • (Array<String>) —

    env var names (empty by default)



374
 
# File 'lib/agent_harness/providers/base.rb', line 374

def api_key_unset_vars = []

#cli_env_overrides ⇒ Hash{String => String}

Provider-specific environment variable overrides that the caller should set when invoking the CLI (e.g. feature flags or sandbox controls).

Returns:

  • (Hash{String => String}) —

    env var name => value (empty by default)



386
 
# File 'lib/agent_harness/providers/base.rb', line 386

def cli_env_overrides = {}

#configure(options = {}) ⇒ self

Configure the provider instance

Parameters:

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

    configuration options

Returns:

  • (self) 


92
93
94
95
 
# File 'lib/agent_harness/providers/base.rb', line 92

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

#display_name ⇒ String

Human-friendly display name

Returns:

  • (String) —

    display name



351
352
353
 
# File 'lib/agent_harness/providers/base.rb', line 351

def display_name
  name.capitalize
end

#name ⇒ String

Provider name for display

Returns:

  • (String) —

    display name



344
345
346
 
# File 'lib/agent_harness/providers/base.rb', line 344

def name
  self.class.provider_name.to_s
end

#parse_container_output(stdout:, stderr: "", exit_code: 0, duration: 0.0, **options) ⇒ Response

Parse raw container output into a Response.

This is the public interface for parsing CLI output captured from external execution (e.g. Docker containers) without going through send_message. It accepts the same data a CommandExecutor::Result holds and returns an AgentHarness::Response.

Parameters:

  • stdout (String) —

    captured standard output

  • stderr (String) (defaults to: "") —

    captured standard error

  • exit_code (Integer) (defaults to: 0) —

    process exit code

  • duration (Float) (defaults to: 0.0) —

    execution duration in seconds

  • options (Hash) —

    additional provider-specific options

Returns:



331
332
333
334
335
336
337
338
339
 
# File 'lib/agent_harness/providers/base.rb', line 331

def parse_container_output(stdout:, stderr: "", exit_code: 0, duration: 0.0, **options)
  result = CommandExecutor::Result.new(
    stdout: stdout,
    stderr: stderr,
    exit_code: exit_code,
    duration: duration
  )
  parse_response(result, duration: duration)
end

#parse_rate_limit_reset(text) ⇒ Time?

Parse rate-limit reset time from provider error output.

Providers that emit rate-limit reset times should override this method (or include RateLimitResetParsing for the common format).

Parameters:

  • text (String, nil) —

    error output text

Returns:

  • (Time, nil) —

    UTC reset time, or nil if not parseable



417
418
419
 
# File 'lib/agent_harness/providers/base.rb', line 417

def parse_rate_limit_reset(text)
  nil
end

#parse_test_error(output:, files: {}) ⇒ Hash?

Parse provider-specific error information from test output

Providers override this to extract structured error details from CLI output or sidecar files produced during a test invocation.

Parameters:

  • output (String) —

    the CLI stdout/stderr output

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

    mapping of logical names to file paths

Returns:

  • (Hash, nil) —

    structured error hash or nil if no error detected



406
407
408
 
# File 'lib/agent_harness/providers/base.rb', line 406

def parse_test_error(output:, files: {})
  nil
end

#plan_execution(prompt:, **options) ⇒ Hash

Return the provider CLI execution plan without executing it.

Parameters:

  • prompt (String) —

    the prompt to send

  • options (Hash) —

    additional options

Returns:

  • (Hash) —

    with :command, :env, and :preparation keys



205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
 
# File 'lib/agent_harness/providers/base.rb', line 205

def plan_execution(prompt:, **options)
  log_debug("plan_execution_start", prompt_length: prompt.length, options: options.keys)

  if options[:mode] == :text && !supports_text_mode?
    log_debug("text_mode_cli_fallback", provider: self.class.provider_name)
    options = options.except(:mode).merge(tools: :none)
  end

  if options[:tools] && !supports_tool_control?
    log_debug("tools_option_unsupported",
      provider: self.class.provider_name,
      tools: options[:tools])
    @logger&.warn(
      "[AgentHarness::#{self.class.provider_name}] tools option is not supported " \
      "by this provider and will be ignored"
    )
  end

  options = normalize_provider_runtime(options)

  extension_context = apply_extensions_to_prompt(prompt, options)
  prompt = extension_context.prompt
  options = extension_context.options
  options = normalize_sub_agent(options)
  prompt = apply_sub_agent_to_prompt(prompt, options[:translated_sub_agent])

  options = normalize_mcp_servers(options)
  validate_mcp_servers!(options[:mcp_servers]) if options[:mcp_servers]&.any?

  {
    command: build_command(prompt, options),
    env: build_env(options),
    preparation: build_execution_preparation(options)
  }
rescue ExtensionCompatibilityError, McpConfigurationError, McpUnsupportedError, McpTransportUnsupportedError
  raise
rescue => e
  handle_error(e, prompt: prompt, options: options)
ensure
  # build_command may call build_mcp_flags which creates tempfiles (and
  # in Docker even invokes the executor) via write_mcp_config_file.
  # Clean up so that planning has no lasting side effects.
  cleanup_mcp_tempfiles! if respond_to?(:cleanup_mcp_tempfiles!, true)
end

#preflight_check(env:, timeout: 10) ⇒ Hash

Run a lightweight provider-owned preflight check before committing to a full prompt execution.

Providers can override this to validate request-scoped connectivity, credentials, CLI version, or other fast-fail prerequisites.

Parameters:

  • env (Hash) —

    request-scoped environment overrides

  • timeout (Numeric) (defaults to: 10) —

    time budget in seconds

Returns:

  • (Hash) —

    with :healthy and optional :reason keys



430
431
432
 
# File 'lib/agent_harness/providers/base.rb', line 430

def preflight_check(env:, timeout: 10)
  {healthy: true}
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



361
362
363
 
# File 'lib/agent_harness/providers/base.rb', line 361

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

#send_chat_message(conversation: nil, messages: nil, tools: nil, stream: false, on_chat_chunk: nil, observer: nil, **options) {|Hash| ... } ⇒ Response

Send a multi-turn chat message via the provider’s chat transport.

Providers that support chat mode can accept either conversation: or messages: as the conversation history payload.

Structured streaming events are delivered through three channels:

  • on_chat_chunk proc (keyword argument)

  • observer object responding to on_chat_chunk

  • block (yield)

When multiple receivers are provided, all receive every event.

Parameters:

  • conversation (Array<Hash>, nil) (defaults to: nil) —

    message history

  • messages (Array<Hash>, nil) (defaults to: nil) —

    alias for conversation

  • tools (Array<Hash>, nil) (defaults to: nil) —

    tool/function definitions

  • stream (Boolean) (defaults to: false) —

    whether to stream the response

  • on_chat_chunk (Proc, nil) (defaults to: nil) —

    callback for structured streaming events

  • observer (#on_chat_chunk, nil) (defaults to: nil) —

    observer receiving streaming events

  • options (Hash) —

    additional options

Yields:

  • (Hash) —

    streaming chunks when stream: true

Returns:

Raises:



272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
 
# File 'lib/agent_harness/providers/base.rb', line 272

def send_chat_message(conversation: nil, messages: nil, tools: nil, stream: false,
  on_chat_chunk: nil, observer: nil, **options, &on_chunk)
  unless supports_chat?
    raise ProviderError, "#{name} does not support chat mode"
  end

  options = normalize_provider_runtime(options)
  options = normalize_sub_agent(options)
  runtime = options[:provider_runtime]
  conversation ||= messages
  raise ArgumentError, "conversation or messages is required" unless conversation
  tools = runtime.chat_tools if tools.nil? && runtime&.chat_tools

  transport = resolve_chat_transport(options)
  messages = format_messages_for_transport(conversation, transport)
  extension_context = apply_extensions_to_chat(messages, tools, options)
  messages = extension_context.messages
  tools = extension_context.tools
  options = extension_context.options
  messages = apply_sub_agent_to_messages(messages, options[:translated_sub_agent])
  validate_chat_mcp_servers!(options[:mcp_servers])
  transport_opts = chat_transport_options(runtime, options)
  transport_opts[:on_chat_chunk] = on_chat_chunk if on_chat_chunk
  transport_opts[:observer] = observer if observer

  response = transport.chat(
    messages: messages,
    tools: tools,
    stream: stream,
    **transport_opts,
    &on_chunk
  )

  response = apply_extensions_after_response(extension_context, response)

  track_tokens(response) if response.tokens
  log_debug("send_chat_message_complete", duration: response.duration, tokens: response.tokens)

  response
rescue ExtensionCompatibilityError, ProviderError, AuthenticationError, RateLimitError, TimeoutError
  raise
rescue => e
  last_msg = conversation&.last || messages&.last
  handle_error(e, prompt: (last_msg&.dig(:content) || last_msg&.dig("content")).to_s, options: options)
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:



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
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
 
# File 'lib/agent_harness/providers/base.rb', line 107

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

  # Text mode: fall back to CLI with tools disabled when the provider
  # does not have an HTTP text transport.  Providers that support text
  # mode (e.g. Anthropic) override send_message to intercept this
  # before reaching Base.
  if options[:mode] == :text && !supports_text_mode?
    log_debug("text_mode_cli_fallback", provider: self.class.provider_name)
    options = options.except(:mode).merge(tools: :none)
  end

  # Warn when tools option is passed to a provider that doesn't support it
  if options[:tools] && !supports_tool_control?
    log_debug("tools_option_unsupported",
      provider: self.class.provider_name,
      tools: options[:tools])
    @logger&.warn(
      "[AgentHarness::#{self.class.provider_name}] tools option is not supported " \
      "by this provider and will be ignored"
    )
  end

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

  # Capture execution options (callbacks, observer) before extensions
  # processing deep-dups the options hash, which would replace identity-
  # sensitive references (observers, procs) with clones.
  exec_opts = command_execution_options(options)

  extension_context = apply_extensions_to_prompt(prompt, options)
  prompt = extension_context.prompt
  options = extension_context.options
  options = normalize_sub_agent(options)
  prompt = apply_sub_agent_to_prompt(prompt, options[:translated_sub_agent])

  # 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,
    **exec_opts
  )
  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

  response = apply_extensions_after_response(extension_context, response)

  # Track tokens
  track_tokens(response) if response.tokens

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

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

#subscription_unset_vars ⇒ Array<String>

Environment variable names to unset when the caller uses subscription-based auth, ensuring the CLI does not pick up API-key or proxy variables that would conflict.

Returns:

  • (Array<String>) —

    env var names (empty by default)



380
 
# File 'lib/agent_harness/providers/base.rb', line 380

def subscription_unset_vars = []

#test_command_overrides ⇒ Array<String>

Additional CLI flags for health-check/test invocations

Providers override this to supply flags that should be appended when the CLI is invoked in a test or smoke-test context.

Returns:

  • (Array<String>) —

    extra CLI flags (empty by default)



394
395
396
 
# File 'lib/agent_harness/providers/base.rb', line 394

def test_command_overrides
  []
end