claude_swarm 1.0.9 → 1.0.11

data/lib/swarm_sdk/config.rb

@@ -0,0 +1,302 @@
+# frozen_string_literal: true
+
+module SwarmSDK
+  # Centralized configuration for SwarmSDK
+  #
+  # Config provides a single entry point for all SwarmSDK configuration,
+  # including API keys (proxied to RubyLLM), defaults override, and
+  # WebFetch settings.
+  #
+  # ## Priority Order
+  #
+  # Configuration values are resolved in this order:
+  # 1. Explicit value (set via SwarmSDK.configure)
+  # 2. Environment variable
+  # 3. Module default (from SwarmSDK::Defaults)
+  #
+  # ## API Key Proxying
+  #
+  # API keys are automatically proxied to RubyLLM.config when set,
+  # ensuring RubyLLM always has the correct credentials.
+  #
+  # @example Basic configuration
+  #   SwarmSDK.configure do |config|
+  #     config.openai_api_key = "sk-..."
+  #     config.default_model = "claude-sonnet-4"
+  #     config.agent_request_timeout = 600
+  #   end
+  #
+  # @example Testing setup
+  #   def setup
+  #     SwarmSDK.reset_config!
+  #   end
+  class Config
+    # API keys that proxy to RubyLLM.config
+    # Maps SwarmSDK config key => [RubyLLM config key, ENV variable]
+    API_KEY_MAPPINGS = {
+      openai_api_key: [:openai_api_key, "OPENAI_API_KEY"],
+      openai_api_base: [:openai_api_base, "OPENAI_API_BASE"],
+      openai_organization_id: [:openai_organization_id, "OPENAI_ORG_ID"],
+      openai_project_id: [:openai_project_id, "OPENAI_PROJECT_ID"],
+      anthropic_api_key: [:anthropic_api_key, "ANTHROPIC_API_KEY"],
+      gemini_api_key: [:gemini_api_key, "GEMINI_API_KEY"],
+      gemini_api_base: [:gemini_api_base, "GEMINI_API_BASE"],
+      vertexai_project_id: [:vertexai_project_id, "GOOGLE_CLOUD_PROJECT"],
+      vertexai_location: [:vertexai_location, "GOOGLE_CLOUD_LOCATION"],
+      deepseek_api_key: [:deepseek_api_key, "DEEPSEEK_API_KEY"],
+      mistral_api_key: [:mistral_api_key, "MISTRAL_API_KEY"],
+      perplexity_api_key: [:perplexity_api_key, "PERPLEXITY_API_KEY"],
+      openrouter_api_key: [:openrouter_api_key, "OPENROUTER_API_KEY"],
+      bedrock_api_key: [:bedrock_api_key, "AWS_ACCESS_KEY_ID"],
+      bedrock_secret_key: [:bedrock_secret_key, "AWS_SECRET_ACCESS_KEY"],
+      bedrock_region: [:bedrock_region, "AWS_REGION"],
+      bedrock_session_token: [:bedrock_session_token, "AWS_SESSION_TOKEN"],
+      ollama_api_base: [:ollama_api_base, "OLLAMA_API_BASE"],
+      gpustack_api_base: [:gpustack_api_base, "GPUSTACK_API_BASE"],
+      gpustack_api_key: [:gpustack_api_key, "GPUSTACK_API_KEY"],
+    }.freeze
+
+    # SwarmSDK defaults that can be overridden
+    # Maps config key => [ENV variable, default proc]
+    DEFAULTS_MAPPINGS = {
+      default_model: ["SWARM_SDK_DEFAULT_MODEL", -> { Defaults::Agent::MODEL }],
+      default_provider: ["SWARM_SDK_DEFAULT_PROVIDER", -> { Defaults::Agent::PROVIDER }],
+      agent_request_timeout: ["SWARM_SDK_AGENT_REQUEST_TIMEOUT", -> { Defaults::Timeouts::AGENT_REQUEST_SECONDS }],
+      bash_command_timeout: ["SWARM_SDK_BASH_COMMAND_TIMEOUT", -> { Defaults::Timeouts::BASH_COMMAND_MS }],
+      bash_command_max_timeout: ["SWARM_SDK_BASH_COMMAND_MAX_TIMEOUT", -> { Defaults::Timeouts::BASH_COMMAND_MAX_MS }],
+      web_fetch_timeout: ["SWARM_SDK_WEB_FETCH_TIMEOUT", -> { Defaults::Timeouts::WEB_FETCH_SECONDS }],
+      hook_shell_timeout: ["SWARM_SDK_HOOK_SHELL_TIMEOUT", -> { Defaults::Timeouts::HOOK_SHELL_SECONDS }],
+      transformer_command_timeout: ["SWARM_SDK_TRANSFORMER_COMMAND_TIMEOUT", -> { Defaults::Timeouts::TRANSFORMER_COMMAND_SECONDS }],
+      global_concurrency_limit: ["SWARM_SDK_GLOBAL_CONCURRENCY_LIMIT", -> { Defaults::Concurrency::GLOBAL_LIMIT }],
+      local_concurrency_limit: ["SWARM_SDK_LOCAL_CONCURRENCY_LIMIT", -> { Defaults::Concurrency::LOCAL_LIMIT }],
+      output_character_limit: ["SWARM_SDK_OUTPUT_CHARACTER_LIMIT", -> { Defaults::Limits::OUTPUT_CHARACTERS }],
+      read_line_limit: ["SWARM_SDK_READ_LINE_LIMIT", -> { Defaults::Limits::READ_LINES }],
+      line_character_limit: ["SWARM_SDK_LINE_CHARACTER_LIMIT", -> { Defaults::Limits::LINE_CHARACTERS }],
+      web_fetch_character_limit: ["SWARM_SDK_WEB_FETCH_CHARACTER_LIMIT", -> { Defaults::Limits::WEB_FETCH_CHARACTERS }],
+      glob_result_limit: ["SWARM_SDK_GLOB_RESULT_LIMIT", -> { Defaults::Limits::GLOB_RESULTS }],
+      scratchpad_entry_size_limit: ["SWARM_SDK_SCRATCHPAD_ENTRY_SIZE_LIMIT", -> { Defaults::Storage::ENTRY_SIZE_BYTES }],
+      scratchpad_total_size_limit: ["SWARM_SDK_SCRATCHPAD_TOTAL_SIZE_LIMIT", -> { Defaults::Storage::TOTAL_SIZE_BYTES }],
+      context_compression_threshold: ["SWARM_SDK_CONTEXT_COMPRESSION_THRESHOLD", -> { Defaults::Context::COMPRESSION_THRESHOLD_PERCENT }],
+      todowrite_reminder_interval: ["SWARM_SDK_TODOWRITE_REMINDER_INTERVAL", -> { Defaults::Context::TODOWRITE_REMINDER_INTERVAL }],
+      chars_per_token_prose: ["SWARM_SDK_CHARS_PER_TOKEN_PROSE", -> { Defaults::TokenEstimation::CHARS_PER_TOKEN_PROSE }],
+      chars_per_token_code: ["SWARM_SDK_CHARS_PER_TOKEN_CODE", -> { Defaults::TokenEstimation::CHARS_PER_TOKEN_CODE }],
+      mcp_log_level: ["SWARM_SDK_MCP_LOG_LEVEL", -> { Defaults::Logging::MCP_LOG_LEVEL }],
+    }.freeze
+
+    # WebFetch and control settings
+    # Maps config key => [ENV variable, default value]
+    SETTINGS_MAPPINGS = {
+      webfetch_provider: ["SWARM_SDK_WEBFETCH_PROVIDER", nil],
+      webfetch_model: ["SWARM_SDK_WEBFETCH_MODEL", nil],
+      webfetch_base_url: ["SWARM_SDK_WEBFETCH_BASE_URL", nil],
+      webfetch_max_tokens: ["SWARM_SDK_WEBFETCH_MAX_TOKENS", 4096],
+      allow_filesystem_tools: ["SWARM_SDK_ALLOW_FILESYSTEM_TOOLS", true],
+      env_interpolation: ["SWARM_SDK_ENV_INTERPOLATION", true],
+    }.freeze
+
+    class << self
+      # Get the singleton Config instance
+      #
+      # @return [Config] The singleton instance
+      def instance
+        @instance ||= new
+      end
+
+      # Reset the Config instance
+      #
+      # Clears all configuration including explicit values and cached ENV values.
+      # Use in tests to ensure clean state.
+      #
+      # @return [void]
+      def reset!
+        @instance = nil
+      end
+    end
+
+    # Initialize a new Config instance
+    #
+    # @note Use Config.instance instead of new for the singleton pattern
+    def initialize
+      @explicit_values = {}
+      @env_values = {}
+      @env_loaded = false
+      @env_mutex = Mutex.new
+    end
+
+    # ========== API Key Accessors (with RubyLLM proxying) ==========
+
+    # @!method openai_api_key
+    #   Get the OpenAI API key
+    #   @return [String, nil] The API key
+    #
+    # @!method openai_api_key=(value)
+    #   Set the OpenAI API key (proxied to RubyLLM)
+    #   @param value [String] The API key
+
+    API_KEY_MAPPINGS.each_key do |config_key|
+      ruby_llm_key, _ = API_KEY_MAPPINGS[config_key]
+
+      # Getter
+      define_method(config_key) do
+        ensure_env_loaded!
+        @explicit_values[config_key] || @env_values[config_key]
+      end
+
+      # Setter with RubyLLM proxying
+      define_method("#{config_key}=") do |value|
+        @explicit_values[config_key] = value
+        RubyLLM.config.public_send("#{ruby_llm_key}=", value) if value
+      end
+    end
+
+    # ========== Defaults Accessors (with module constant fallback) ==========
+
+    # @!method default_model
+    #   Get the default model
+    #   @return [String] The default model (falls back to Defaults::Agent::MODEL)
+    #
+    # @!method default_model=(value)
+    #   Set the default model
+    #   @param value [String] The default model
+
+    DEFAULTS_MAPPINGS.each_key do |config_key|
+      _env_key, default_proc = DEFAULTS_MAPPINGS[config_key]
+
+      # Getter with default fallback
+      define_method(config_key) do
+        ensure_env_loaded!
+        @explicit_values[config_key] || @env_values[config_key] || default_proc.call
+      end
+
+      # Setter
+      define_method("#{config_key}=") do |value|
+        @explicit_values[config_key] = value
+      end
+    end
+
+    # ========== Settings Accessors (WebFetch and control) ==========
+
+    # @!method webfetch_provider
+    #   Get the WebFetch LLM provider
+    #   @return [String, nil] The provider
+    #
+    # @!method allow_filesystem_tools
+    #   Get whether filesystem tools are allowed
+    #   @return [Boolean] true if allowed
+
+    SETTINGS_MAPPINGS.each_key do |config_key|
+      _env_key, default_value = SETTINGS_MAPPINGS[config_key]
+
+      # Getter with default fallback
+      define_method(config_key) do
+        ensure_env_loaded!
+        if @explicit_values.key?(config_key)
+          @explicit_values[config_key]
+        elsif @env_values.key?(config_key)
+          @env_values[config_key]
+        else
+          default_value
+        end
+      end
+
+      # Setter
+      define_method("#{config_key}=") do |value|
+        @explicit_values[config_key] = value
+      end
+    end
+
+    # ========== Convenience Methods ==========
+
+    # Check if WebFetch LLM processing is enabled
+    #
+    # WebFetch uses LLM processing when both provider and model are configured.
+    #
+    # @return [Boolean] true if WebFetch LLM is configured
+    def webfetch_llm_enabled?
+      !webfetch_provider.nil? && !webfetch_model.nil?
+    end
+
+    private
+
+    # Ensure ENV values are loaded (lazy loading with double-check locking)
+    #
+    # Thread-safe lazy loading of ENV values. Only loads once per Config instance.
+    #
+    # @return [void]
+    def ensure_env_loaded!
+      return if @env_loaded
+
+      @env_mutex.synchronize do
+        return if @env_loaded
+
+        load_env_values!
+        @env_loaded = true
+      end
+    end
+
+    # Load environment variable values
+    #
+    # Loads API keys (with RubyLLM proxying), defaults, and settings from ENV.
+    # Only loads values that haven't been explicitly set.
+    #
+    # @return [void]
+    def load_env_values!
+      # Load API keys and proxy to RubyLLM
+      API_KEY_MAPPINGS.each do |config_key, (ruby_llm_key, env_key)|
+        next if @explicit_values.key?(config_key)
+        next unless ENV.key?(env_key)
+
+        value = ENV[env_key]
+        @env_values[config_key] = value
+
+        # Proxy to RubyLLM
+        RubyLLM.config.public_send("#{ruby_llm_key}=", value)
+      end
+
+      # Load defaults (no RubyLLM proxy)
+      DEFAULTS_MAPPINGS.each do |config_key, (env_key, _default_proc)|
+        next if @explicit_values.key?(config_key)
+        next unless ENV.key?(env_key)
+
+        @env_values[config_key] = parse_env_value(ENV[env_key], config_key)
+      end
+
+      # Load settings (no RubyLLM proxy)
+      SETTINGS_MAPPINGS.each do |config_key, (env_key, _default_value)|
+        next if @explicit_values.key?(config_key)
+        next unless ENV.key?(env_key)
+
+        @env_values[config_key] = parse_env_value(ENV[env_key], config_key)
+      end
+    end
+
+    # Parse environment variable value to appropriate type
+    #
+    # Converts string ENV values to integers, floats, or booleans based on
+    # the configuration key pattern.
+    #
+    # @param value [String] The ENV value string
+    # @param key [Symbol] The configuration key
+    # @return [Integer, Float, Boolean, String] The parsed value
+    def parse_env_value(value, key)
+      case key
+      when :allow_filesystem_tools, :env_interpolation
+        # Convert string to boolean
+        case value.to_s.downcase
+        when "true", "yes", "1", "on", "enabled"
+          true
+        when "false", "no", "0", "off", "disabled"
+          false
+        else
+          true # Default to true if unrecognized
+        end
+      when /_timeout$/, /_limit$/, /_interval$/, /_threshold$/, :mcp_log_level, :webfetch_max_tokens
+        value.to_i
+      when /^chars_per_token/
+        value.to_f
+      else
+        value
+      end
+    end
+  end
+end

data/lib/swarm_sdk/configuration/parser.rb

@@ -0,0 +1,373 @@
+# frozen_string_literal: true
+
+module SwarmSDK
+  class Configuration
+    # Handles YAML parsing, validation, and normalization
+    #
+    # This class is responsible for:
+    # - Loading and parsing YAML content
+    # - Validating configuration structure
+    # - Normalizing data (symbolizing keys, env interpolation)
+    # - Detecting configuration type (swarm vs workflow)
+    # - Loading agents and nodes
+    # - Detecting circular dependencies
+    #
+    # After parsing, the parsed data can be translated to a Swarm/Workflow
+    # using the Translator class.
+    class Parser
+      ENV_VAR_WITH_DEFAULT_PATTERN = /\$\{([^:}]+)(:=([^}]*))?\}/
+
+      attr_reader :config_type,
+        :swarm_name,
+        :swarm_id,
+        :lead_agent,
+        :start_node,
+        :agents,
+        :all_agents_config,
+        :swarm_hooks,
+        :all_agents_hooks,
+        :scratchpad_mode,
+        :nodes,
+        :external_swarms
+
+      # Initialize parser with YAML content and options
+      #
+      # @param yaml_content [String] YAML configuration content
+      # @param base_dir [String, Pathname] Base directory for resolving paths
+      # @param env_interpolation [Boolean, nil] Whether to interpolate environment variables.
+      #   When nil, uses the global SwarmSDK.config.env_interpolation setting.
+      #   When true, interpolates ${VAR} and ${VAR:=default} patterns.
+      #   When false, skips interpolation entirely.
+      def initialize(yaml_content, base_dir:, env_interpolation: nil)
+        @yaml_content = yaml_content
+        @base_dir = Pathname.new(base_dir).expand_path
+        @env_interpolation = env_interpolation
+        @config_type = nil
+        @swarm_id = nil
+        @swarm_name = nil
+        @lead_agent = nil
+        @start_node = nil
+        @agents = {}
+        @all_agents_config = {}
+        @swarm_hooks = {}
+        @all_agents_hooks = {}
+        @external_swarms = {}
+        @nodes = {}
+        @scratchpad_mode = :disabled
+      end
+
+      def parse
+        @config = YAML.safe_load(@yaml_content, permitted_classes: [Symbol], aliases: true)
+
+        unless @config.is_a?(Hash)
+          raise ConfigurationError, "Invalid YAML syntax: configuration must be a Hash"
+        end
+
+        @config = Utils.symbolize_keys(@config)
+        interpolate_env_vars!(@config) if env_interpolation_enabled?
+
+        validate_version
+        detect_and_validate_type
+        load_common_config
+        load_type_specific_config
+        load_agents
+        load_nodes if @config_type == :workflow
+        detect_circular_dependencies
+
+        self
+      rescue Psych::SyntaxError => e
+        raise ConfigurationError, "Invalid YAML syntax: #{e.message}"
+      end
+
+      def agent_names
+        @agents.keys
+      end
+
+      def connections_for(agent_name)
+        agent_config = @agents[agent_name]
+        return [] unless agent_config
+
+        delegates = agent_config[:delegates_to] || []
+        Array(delegates).map(&:to_sym)
+      end
+
+      attr_reader :base_dir
+
+      private
+
+      # Check if environment variable interpolation is enabled
+      #
+      # Uses the local setting if explicitly set, otherwise falls back to global config.
+      #
+      # @return [Boolean] true if interpolation should be performed
+      def env_interpolation_enabled?
+        return @env_interpolation unless @env_interpolation.nil?
+
+        SwarmSDK.config.env_interpolation
+      end
+
+      def validate_version
+        version = @config[:version]
+        raise ConfigurationError, "Missing 'version' field in configuration" unless version
+        raise ConfigurationError, "SwarmSDK requires version: 2 configuration. Got version: #{version}" unless version == 2
+      end
+
+      def detect_and_validate_type
+        has_swarm = @config.key?(:swarm)
+        has_workflow = @config.key?(:workflow)
+
+        if has_swarm && has_workflow
+          raise ConfigurationError, "Cannot have both 'swarm:' and 'workflow:' keys. Use one or the other."
+        end
+
+        unless has_swarm || has_workflow
+          raise ConfigurationError, "Missing 'swarm:' or 'workflow:' key in configuration"
+        end
+
+        @config_type = has_swarm ? :swarm : :workflow
+        @root_config = @config[@config_type]
+      end
+
+      def load_common_config
+        raise ConfigurationError, "Missing 'name' field in #{@config_type} configuration" unless @root_config[:name]
+
+        @swarm_name = @root_config[:name]
+        @swarm_id = @root_config[:id]
+        @scratchpad_mode = parse_scratchpad_mode(@root_config[:scratchpad])
+
+        load_all_agents_config
+        load_hooks_config
+        load_external_swarms(@root_config[:swarms]) if @root_config[:swarms]
+      end
+
+      def load_type_specific_config
+        if @config_type == :swarm
+          load_swarm_config
+        else
+          load_workflow_config
+        end
+      end
+
+      def load_swarm_config
+        raise ConfigurationError, "Missing 'lead' field in swarm configuration" unless @root_config[:lead]
+        raise ConfigurationError, "Missing 'agents' field in swarm configuration" unless @root_config[:agents]
+
+        @lead_agent = @root_config[:lead].to_sym
+
+        if @root_config[:nodes] || @root_config[:start_node]
+          raise ConfigurationError, "Swarm configuration cannot have 'nodes' or 'start_node'. Use 'workflow:' key instead."
+        end
+      end
+
+      def load_workflow_config
+        raise ConfigurationError, "Missing 'start_node' field in workflow configuration" unless @root_config[:start_node]
+        raise ConfigurationError, "Missing 'nodes' field in workflow configuration" unless @root_config[:nodes]
+        raise ConfigurationError, "Missing 'agents' field in workflow configuration" unless @root_config[:agents]
+
+        @start_node = @root_config[:start_node].to_sym
+
+        if @root_config[:lead]
+          raise ConfigurationError, "Workflow configuration cannot have 'lead'. Use 'start_node' instead."
+        end
+      end
+
+      def load_all_agents_config
+        @all_agents_config = @root_config[:all_agents] || {}
+
+        if @all_agents_config[:disable_default_tools].is_a?(Array)
+          @all_agents_config[:disable_default_tools] = @all_agents_config[:disable_default_tools].map(&:to_sym)
+        end
+      end
+
+      def load_hooks_config
+        @swarm_hooks = Utils.symbolize_keys(@root_config[:hooks] || {})
+
+        if @root_config[:all_agents]
+          @all_agents_hooks = Utils.symbolize_keys(@root_config[:all_agents][:hooks] || {})
+        end
+      end
+
+      def load_external_swarms(swarms_config)
+        @external_swarms = {}
+        swarms_config.each do |name, config|
+          source = if config[:file]
+            file_path = if config[:file].start_with?("/")
+              config[:file]
+            else
+              (@base_dir / config[:file]).to_s
+            end
+            { type: :file, value: file_path }
+          elsif config[:yaml]
+            { type: :yaml, value: config[:yaml] }
+          elsif config[:swarm]
+            inline_config = {
+              version: 2,
+              swarm: config[:swarm],
+            }
+            yaml_string = Utils.hash_to_yaml(inline_config)
+            { type: :yaml, value: yaml_string }
+          else
+            raise ConfigurationError, "Swarm '#{name}' must specify either 'file:', 'yaml:', or 'swarm:' (inline definition)"
+          end
+
+          @external_swarms[name.to_sym] = {
+            source: source,
+            keep_context: config.fetch(:keep_context, true),
+          }
+        end
+      end
+
+      def load_agents
+        swarm_agents = @root_config[:agents]
+        raise ConfigurationError, "No agents defined" if swarm_agents.empty?
+
+        swarm_agents.each do |name, agent_config|
+          parsed_config = if agent_config.nil?
+            {}
+          elsif agent_config.is_a?(String)
+            { agent_file: agent_config }
+          elsif agent_config.is_a?(Hash) && agent_config[:agent_file]
+            agent_config
+          else
+            agent_config || {}
+          end
+
+          if parsed_config[:agent_file].nil? && parsed_config[:description].nil?
+            raise ConfigurationError,
+              "Agent '#{name}' missing required 'description' field"
+          end
+
+          @agents[name] = parsed_config
+        end
+
+        if @config_type == :swarm
+          unless @agents.key?(@lead_agent)
+            raise ConfigurationError, "Lead agent '#{@lead_agent}' not found in agents"
+          end
+        end
+      end
+
+      def load_nodes
+        @nodes = Utils.symbolize_keys(@root_config[:nodes])
+
+        unless @nodes.key?(@start_node)
+          raise ConfigurationError, "start_node '#{@start_node}' not found in nodes"
+        end
+
+        @nodes.each do |node_name, node_config|
+          unless node_config.is_a?(Hash)
+            raise ConfigurationError, "Node '#{node_name}' must be a hash"
+          end
+
+          if node_config[:agents]
+            unless node_config[:agents].is_a?(Array)
+              raise ConfigurationError, "Node '#{node_name}' agents must be an array"
+            end
+
+            node_config[:agents].each do |agent_config|
+              unless agent_config.is_a?(Hash) && agent_config[:agent]
+                raise ConfigurationError,
+                  "Node '#{node_name}' agents must be hashes with 'agent' key"
+              end
+
+              agent_sym = agent_config[:agent].to_sym
+              unless @agents.key?(agent_sym)
+                raise ConfigurationError,
+                  "Node '#{node_name}' references undefined agent '#{agent_config[:agent]}'"
+              end
+            end
+          end
+
+          next unless node_config[:dependencies]
+          unless node_config[:dependencies].is_a?(Array)
+            raise ConfigurationError, "Node '#{node_name}' dependencies must be an array"
+          end
+
+          node_config[:dependencies].each do |dep|
+            dep_sym = dep.to_sym
+            unless @nodes.key?(dep_sym)
+              raise ConfigurationError,
+                "Node '#{node_name}' depends on undefined node '#{dep}'"
+            end
+          end
+        end
+      end
+
+      def parse_scratchpad_mode(value)
+        return :disabled if value.nil?
+
+        value = value.to_sym if value.is_a?(String)
+
+        case value
+        when :enabled, :disabled, :per_node
+          value
+        else
+          raise ConfigurationError,
+            "Invalid scratchpad mode: #{value.inspect}. Use :enabled, :per_node, or :disabled"
+        end
+      end
+
+      def interpolate_env_vars!(obj)
+        case obj
+        when String
+          interpolate_env_string(obj)
+        when Hash
+          obj.transform_values! { |v| interpolate_env_vars!(v) }
+        when Array
+          obj.map! { |v| interpolate_env_vars!(v) }
+        else
+          obj
+        end
+      end
+
+      def interpolate_env_string(str)
+        str.gsub(ENV_VAR_WITH_DEFAULT_PATTERN) do |_match|
+          env_var = Regexp.last_match(1)
+          has_default = Regexp.last_match(2)
+          default_value = Regexp.last_match(3)
+
+          if ENV.key?(env_var)
+            ENV[env_var]
+          elsif has_default
+            default_value || ""
+          else
+            raise ConfigurationError, "Environment variable '#{env_var}' is not set"
+          end
+        end
+      end
+
+      def detect_circular_dependencies
+        @agents.each_key do |agent_name|
+          visited = Set.new
+          path = []
+          detect_cycle_from(agent_name, visited, path)
+        end
+      end
+
+      def detect_cycle_from(agent_name, visited, path)
+        return if visited.include?(agent_name)
+
+        if path.include?(agent_name)
+          cycle_start = path.index(agent_name)
+          cycle = path[cycle_start..] + [agent_name]
+          raise CircularDependencyError, "Circular dependency detected: #{cycle.join(" -> ")}"
+        end
+
+        path.push(agent_name)
+        connections_for(agent_name).each do |connection|
+          connection_sym = connection.to_sym
+
+          next if @external_swarms.key?(connection_sym)
+
+          unless @agents.key?(connection_sym)
+            raise ConfigurationError, "Agent '#{agent_name}' delegates to unknown target '#{connection}' (not a local agent or registered swarm)"
+          end
+
+          detect_cycle_from(connection_sym, visited, path)
+        end
+        path.pop
+        visited.add(agent_name)
+      end
+    end
+  end
+end