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
44
 
# 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 = {}
  @extension_registry = Extensions::Registry.new
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:



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

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

#extension_registry ⇒ Object (readonly)

Returns the value of attribute extension_registry.



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

def extension_registry
  @extension_registry
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

#discover_extensions(directory) ⇒ Array<Extensions::Base>

Discover and register all extensions found in a directory.

Each child entry (subdirectory or file) is loaded through the appropriate adapter; entries that cannot be parsed are silently skipped.

Parameters:

  • directory (String) —

    directory to scan

Returns:



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

def discover_extensions(directory)
  Extensions::Loader.discover(directory).each do |extension|
    register_extension(extension)
  end
end

#load_extensions(path, adapter: nil) ⇒ Array<Extensions::Base>

Load one or more extensions from disk through an adapter.

Parameters:

  • path (String) —

    extension file, directory, or package root

  • adapter (Symbol, String, nil) (defaults to: nil) —

    optional explicit adapter name

Returns:



166
167
168
169
170
 
# File 'lib/agent_harness/configuration.rb', line 166

def load_extensions(path, adapter: nil)
  Extensions::Loader.load(path, adapter: adapter).each do |extension|
    register_extension(extension)
  end
end

#load_mcp_servers_file(path) ⇒ Object

Load MCP server definitions from a configuration file.

Parameters:

  • path (String) —

    file path



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

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:



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

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



248
249
250
 
# File 'lib/agent_harness/configuration.rb', line 248

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



240
241
242
 
# File 'lib/agent_harness/configuration.rb', line 240

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



232
233
234
 
# File 'lib/agent_harness/configuration.rb', line 232

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



224
225
226
 
# File 'lib/agent_harness/configuration.rb', line 224

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

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

Configure orchestration settings

Yields:

Returns:



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

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:



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

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

#register_extension(extension, as: nil) ⇒ Extensions::Base

Register a provider-agnostic runtime extension.

Parameters:

  • extension (Extensions::Base) —

    extension instance

  • as (Symbol, String, nil) (defaults to: nil) —

    optional registry key override

Returns:



156
157
158
159
 
# File 'lib/agent_harness/configuration.rb', line 156

def register_extension(extension, as: nil)
  @extension_registry.register(extension, as: as)
  extension
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:



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

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



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

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:



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

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

#resolve_extension(reference) ⇒ Extensions::Base?

Resolve a registered or inline extension reference.

Parameters:

Returns:



190
191
192
193
194
195
196
197
198
199
 
# File 'lib/agent_harness/configuration.rb', line 190

def resolve_extension(reference)
  case reference
  when nil
    nil
  when Extensions::Base
    reference
  else
    @extension_registry.fetch(reference)
  end
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:



205
206
207
208
209
210
211
212
213
214
215
216
217
218
 
# File 'lib/agent_harness/configuration.rb', line 205

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:



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

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



268
269
270
271
272
273
 
# File 'lib/agent_harness/configuration.rb', line 268

def valid?
  validate!
  true
rescue ConfigurationError
  false
end

#validate! ⇒ void

This method returns an undefined value.

Validate the configuration

Raises:



256
257
258
259
260
261
262
263
 
# File 'lib/agent_harness/configuration.rb', line 256

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