Class: AgentHarness::Configuration

Inherits:
Object
  • Object
show all
Defined in:
lib/agent_harness/configuration.rb

Overview

Configuration for AgentHarness

Supports configuration via Ruby DSL, YAML files, and environment variables. Configuration sources are merged with priority: Ruby DSL > YAML > Environment.

Examples:

Ruby DSL configuration

AgentHarness.configure do |config|
  config.logger = Logger.new(STDOUT)
  config.default_provider = :cursor
  config.fallback_providers = [:claude, :gemini]

  config.provider :claude do |p|
    p.enabled = true
    p.timeout = 600
  end
end

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize ⇒ Configuration

Returns a new instance of Configuration.



28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
 
# File 'lib/agent_harness/configuration.rb', line 28

def initialize
  @logger = nil # Will use null logger if not set
  @log_level = :info
  @default_provider = :cursor
  @fallback_providers = []
  @command_executor = nil # Lazy-initialized
  @config_file_path = nil
  @default_timeout = 300
  @providers = {}
  @orchestration_config = OrchestrationConfig.new
  @callbacks = CallbackRegistry.new
  @custom_provider_classes = {}
  @sub_agents = {}
  @tool_registry = ToolRegistry.new
  @mcp_servers = {}
end

Instance Attribute Details

#callbacks ⇒ Object (readonly)

Returns the value of attribute callbacks.



25
26
27
 
# File 'lib/agent_harness/configuration.rb', line 25

def callbacks
  @callbacks
end

#command_executor ⇒ CommandExecutor

Get or lazily initialize the command executor

Returns:



48
49
50
 
# File 'lib/agent_harness/configuration.rb', line 48

def command_executor
  @command_executor ||= CommandExecutor.new(logger: @logger)
end

#config_file_path ⇒ Object

Returns the value of attribute config_file_path.



22
23
24
 
# File 'lib/agent_harness/configuration.rb', line 22

def config_file_path
  @config_file_path
end

#custom_provider_classes ⇒ Object (readonly)

Returns the value of attribute custom_provider_classes.



25
26
27
 
# File 'lib/agent_harness/configuration.rb', line 25

def custom_provider_classes
  @custom_provider_classes
end

#default_provider ⇒ Object

Returns the value of attribute default_provider.



21
22
23
 
# File 'lib/agent_harness/configuration.rb', line 21

def default_provider
  @default_provider
end

#default_timeout ⇒ Object

Returns the value of attribute default_timeout.



22
23
24
 
# File 'lib/agent_harness/configuration.rb', line 22

def default_timeout
  @default_timeout
end

#fallback_providers ⇒ Object

Returns the value of attribute fallback_providers.



21
22
23
 
# File 'lib/agent_harness/configuration.rb', line 21

def fallback_providers
  @fallback_providers
end

#log_level ⇒ Object

Returns the value of attribute log_level.



21
22
23
 
# File 'lib/agent_harness/configuration.rb', line 21

def log_level
  @log_level
end

#logger ⇒ Object

Returns the value of attribute logger.



21
22
23
 
# File 'lib/agent_harness/configuration.rb', line 21

def logger
  @logger
end

#mcp_servers ⇒ Object

Returns the value of attribute mcp_servers.



26
27
28
 
# File 'lib/agent_harness/configuration.rb', line 26

def mcp_servers
  @mcp_servers
end

#orchestration_config ⇒ Object (readonly)

Returns the value of attribute orchestration_config.



25
26
27
 
# File 'lib/agent_harness/configuration.rb', line 25

def orchestration_config
  @orchestration_config
end

#providers ⇒ Object (readonly)

Returns the value of attribute providers.



25
26
27
 
# File 'lib/agent_harness/configuration.rb', line 25

def providers
  @providers
end

#sub_agents ⇒ Object (readonly)

Returns the value of attribute sub_agents.



26
27
28
 
# File 'lib/agent_harness/configuration.rb', line 26

def sub_agents
  @sub_agents
end

#tool_registry ⇒ Object (readonly)

Returns the value of attribute tool_registry.



26
27
28
 
# File 'lib/agent_harness/configuration.rb', line 26

def tool_registry
  @tool_registry
end

Instance Method Details

#load_mcp_servers_file(path) ⇒ Object

Load MCP server definitions from a configuration file.

Parameters:

  • path (String) —

    file path



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

def load_mcp_servers_file(path)
  loaded = McpConfigLoader.load_file(path)
  @mcp_servers = loaded.each_with_object({}) { |s, h| h[s.name.to_sym] = s }
end

#load_sub_agents(path) ⇒ Array<SubAgentConfig>

Load sub-agent definitions from a YAML or Markdown file.

Parameters:

  • path (String) —

    file path

Returns:



116
117
118
119
120
 
# File 'lib/agent_harness/configuration.rb', line 116

def load_sub_agents(path)
  SubAgentFileLoader.load(path).each do |sub_agent|
    @sub_agents[sub_agent.name] = sub_agent
  end
end

#on_circuit_close {|Hash| ... } ⇒ void

This method returns an undefined value.

Register callback for circuit close events

Yields:

  • (Hash) —

    event data with :provider



197
198
199
 
# File 'lib/agent_harness/configuration.rb', line 197

def on_circuit_close(&block)
  @callbacks.register(:circuit_close, block)
end

#on_circuit_open {|Hash| ... } ⇒ void

This method returns an undefined value.

Register callback for circuit open events

Yields:

  • (Hash) —

    event data with :provider, :failure_count



189
190
191
 
# File 'lib/agent_harness/configuration.rb', line 189

def on_circuit_open(&block)
  @callbacks.register(:circuit_open, block)
end

#on_provider_switch {|Hash| ... } ⇒ void

This method returns an undefined value.

Register callback for provider switch events

Yields:

  • (Hash) —

    event data with :from_provider, :to_provider, :reason



181
182
183
 
# File 'lib/agent_harness/configuration.rb', line 181

def on_provider_switch(&block)
  @callbacks.register(:provider_switch, block)
end

#on_tokens_used {|TokenEvent| ... } ⇒ void

This method returns an undefined value.

Register callback for token usage events

Yields:

  • (TokenEvent) —

    called when tokens are used



173
174
175
 
# File 'lib/agent_harness/configuration.rb', line 173

def on_tokens_used(&block)
  @callbacks.register(:tokens_used, block)
end

#orchestration {|OrchestrationConfig| ... } ⇒ OrchestrationConfig

Configure orchestration settings

Yields:

Returns:



56
57
58
59
 
# File 'lib/agent_harness/configuration.rb', line 56

def orchestration(&block)
  yield(@orchestration_config) if block_given?
  @orchestration_config
end

#provider(name) {|ProviderConfig| ... } ⇒ ProviderConfig

Configure a provider

Parameters:

  • name (Symbol, String) —

    the provider name

Yields:

Returns:



66
67
68
69
70
 
# File 'lib/agent_harness/configuration.rb', line 66

def provider(name, &block)
  config = ProviderConfig.new(name)
  yield(config) if block_given?
  @providers[name.to_sym] = config
end

#register_mcp_server(name, definition = nil, **attributes) ⇒ McpServer

Register a named MCP server for later reference by sub-agents.

Parameters:

  • name (Symbol, String) —

    server name

  • definition (Hash, McpServer, nil) (defaults to: nil) —

    server definition

  • attributes (Hash) —

    server attributes

Returns:



138
139
140
141
142
143
144
145
146
147
148
 
# File 'lib/agent_harness/configuration.rb', line 138

def register_mcp_server(name, definition = nil, **attributes)
  server = if definition.is_a?(McpServer)
    definition
  else
    payload = (definition || attributes).dup
    payload[:name] ||= name.to_s
    McpServer.from_hash(payload)
  end

  @mcp_servers[name.to_sym] = server
end

#register_provider(name, klass) ⇒ void

This method returns an undefined value.

Register a custom provider class

Parameters:

  • name (Symbol, String) —

    the provider name

  • klass (Class) —

    the provider class



77
78
79
 
# File 'lib/agent_harness/configuration.rb', line 77

def register_provider(name, klass)
  @custom_provider_classes[name.to_sym] = klass
end

#register_tool(name, description: nil, **provider_mappings) ⇒ ToolDefinition

Register a generic tool definition that sub-agents can reference.

Parameters:

  • name (Symbol, String) —

    tool name

  • description (String, nil) (defaults to: nil) —

    tool description

  • provider_mappings (Hash) —

    provider-specific mappings

Returns:



128
129
130
 
# File 'lib/agent_harness/configuration.rb', line 128

def register_tool(name, description: nil, **provider_mappings)
  @tool_registry.register(name, description: description, **provider_mappings)
end

#resolve_sub_agent(reference) ⇒ SubAgentConfig?

Resolve a named or inline sub-agent definition.

Parameters:

  • reference (Symbol, String, Hash, SubAgentConfig, nil) —

    sub-agent reference

Returns:



154
155
156
157
158
159
160
161
162
163
164
165
166
167
 
# File 'lib/agent_harness/configuration.rb', line 154

def resolve_sub_agent(reference)
  case reference
  when nil
    nil
  when SubAgentConfig
    reference
  when Hash
    SubAgentConfig.from_hash(reference)
  else
    @sub_agents.fetch(reference.to_sym) do
      raise ConfigurationError, "Unknown sub-agent: #{reference}"
    end
  end
end

#sub_agent(name, attributes = {}) {|Hash| ... } ⇒ SubAgentConfig

Configure a provider-agnostic sub-agent definition.

Parameters:

  • name (Symbol, String) —

    sub-agent name

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

    sub-agent attributes

Yields:

  • (Hash) —

    mutable attributes hash before validation

Returns:



103
104
105
106
107
108
109
110
 
# File 'lib/agent_harness/configuration.rb', line 103

def sub_agent(name, attributes = {})
  attributes = attributes.dup
  yield(attributes) if block_given?
  attributes[:name] = name

  config = SubAgentConfig.from_hash(attributes)
  @sub_agents[config.name] = config
end

#valid? ⇒ Boolean

Check if configuration is valid

Returns:

  • (Boolean) —

    true if valid



217
218
219
220
221
222
 
# File 'lib/agent_harness/configuration.rb', line 217

def valid?
  validate!
  true
rescue ConfigurationError
  false
end

#validate! ⇒ void

This method returns an undefined value.

Validate the configuration

Raises:



205
206
207
208
209
210
211
212
 
# File 'lib/agent_harness/configuration.rb', line 205

def validate!
  errors = []

  errors << "No providers configured" if @providers.empty?
  errors << "Default provider '#{@default_provider}' not configured" unless @providers[@default_provider]

  raise ConfigurationError, errors.join(", ") unless errors.empty?
end