claude_swarm 1.0.10 → 1.0.11

data/lib/swarm_sdk/agent_registry.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+module SwarmSDK
+  # Global registry for reusable agent definitions
+  #
+  # AgentRegistry allows declaring agents in separate files that can be
+  # referenced by name in swarm definitions. This promotes code reuse and
+  # separation of concerns - agent definitions can live in dedicated files
+  # while swarm configurations compose them together.
+  #
+  # ## Usage
+  #
+  # Register agents globally (typically in separate files):
+  #
+  #   # agents/backend.rb
+  #   SwarmSDK.agent :backend do
+  #     model "claude-sonnet-4"
+  #     description "Backend API developer"
+  #     system_prompt "You build REST APIs"
+  #     tools :Read, :Edit, :Bash
+  #   end
+  #
+  # Reference registered agents in swarm definitions:
+  #
+  #   # swarm.rb
+  #   SwarmSDK.build do
+  #     name "Dev Team"
+  #     lead :backend
+  #
+  #     agent :backend  # Pulls from registry
+  #   end
+  #
+  # ## Override Support
+  #
+  # Registered agents can be extended with additional configuration:
+  #
+  #   SwarmSDK.build do
+  #     name "Dev Team"
+  #     lead :backend
+  #
+  #     agent :backend do
+  #       # Registry config is applied first, then this block
+  #       tools :CustomTool  # Adds to tools from registry
+  #       delegates_to :database
+  #     end
+  #   end
+  #
+  # @note This registry is not thread-safe. In multi-threaded environments,
+  #   register all agents before spawning threads, or synchronize access
+  #   externally. For typical fiber-based async usage (the default in SwarmSDK),
+  #   this is not a concern.
+  #
+  class AgentRegistry
+    @agents = {}
+
+    class << self
+      # Register an agent definition block
+      #
+      # Stores a configuration block that will be executed when the agent
+      # is referenced in a swarm definition. The block receives an
+      # Agent::Builder context and can use all builder DSL methods.
+      #
+      # @param name [Symbol, String] Agent name (will be symbolized)
+      # @yield Agent configuration block using Agent::Builder DSL
+      # @return [void]
+      # @raise [ArgumentError] If no block is provided
+      # @raise [ArgumentError] If agent with same name is already registered
+      #
+      # @example Register a backend agent
+      #   SwarmSDK::AgentRegistry.register(:backend) do
+      #     model "claude-sonnet-4"
+      #     description "Backend developer"
+      #     tools :Read, :Edit, :Bash
+      #   end
+      #
+      # @example Register with MCP servers
+      #   SwarmSDK::AgentRegistry.register(:filesystem_agent) do
+      #     model "gpt-4"
+      #     description "File manager"
+      #     mcp_server :fs, type: :stdio, command: "npx", args: ["-y", "@modelcontextprotocol/server-filesystem"]
+      #   end
+      def register(name, &block)
+        raise ArgumentError, "Block required for agent registration" unless block_given?
+
+        sym_name = name.to_sym
+        if @agents.key?(sym_name)
+          raise ArgumentError,
+            "Agent '#{sym_name}' is already registered. " \
+              "Use SwarmSDK.clear_agent_registry! to reset, or choose a different name."
+        end
+
+        @agents[sym_name] = block
+      end
+
+      # Retrieve a registered agent block
+      #
+      # @param name [Symbol, String] Agent name
+      # @return [Proc, nil] The registration block or nil if not found
+      #
+      # @example
+      #   block = SwarmSDK::AgentRegistry.get(:backend)
+      #   builder.instance_eval(&block) if block
+      def get(name)
+        @agents[name.to_sym]
+      end
+
+      # Check if an agent is registered
+      #
+      # @param name [Symbol, String] Agent name
+      # @return [Boolean] true if agent is registered
+      #
+      # @example
+      #   if SwarmSDK::AgentRegistry.registered?(:backend)
+      #     puts "Backend agent is available"
+      #   end
+      def registered?(name)
+        @agents.key?(name.to_sym)
+      end
+
+      # List all registered agent names
+      #
+      # @return [Array<Symbol>] Names of all registered agents
+      #
+      # @example
+      #   SwarmSDK::AgentRegistry.names
+      #   # => [:backend, :frontend, :database]
+      def names
+        @agents.keys
+      end
+
+      # Clear all registrations
+      #
+      # Primarily useful for testing to ensure clean state between tests.
+      #
+      # @return [void]
+      #
+      # @example In test setup/teardown
+      #   def teardown
+      #     SwarmSDK::AgentRegistry.clear
+      #   end
+      def clear
+        @agents.clear
+      end
+    end
+  end
+end

data/lib/swarm_sdk/builders/base_builder.rb

@@ -64,11 +64,14 @@ module SwarmSDK
         @swarm_registry_config = builder.registrations
       end
 
-      # Define an agent with fluent API or load from markdown content
+      # Define an agent with fluent API, load from markdown, or reference registry
       #
-      # Supports two forms:
-      # 1. Inline DSL: agent :name do ... end
-      # 2. Markdown content: agent :name, <<~MD ... MD
+      # Supports multiple forms:
+      # 1. Registry lookup: agent :name (pulls from global registry)
+      # 2. Registry + overrides: agent :name do ... end (when registered)
+      # 3. Inline DSL: agent :name do ... end (when not registered)
+      # 4. Markdown content: agent :name, <<~MD ... MD
+      # 5. Markdown + overrides: agent :name, <<~MD do ... end
       #
       # @example Inline DSL
       #   agent :backend do
@@ -77,6 +80,15 @@ module SwarmSDK
       #     tools :Read, :Write
       #   end
       #
+      # @example Registry lookup (agent must be registered with SwarmSDK.agent)
+      #   agent :backend  # Pulls configuration from registry
+      #
+      # @example Registry + overrides
+      #   agent :backend do
+      #     # Base config from registry, then apply overrides
+      #     tools :CustomTool  # Adds to registry-defined tools
+      #   end
+      #
       # @example Markdown content
       #   agent :backend, <<~MD
       #     ---
@@ -87,19 +99,38 @@ module SwarmSDK
       #     You build APIs.
       #   MD
       def agent(name, content = nil, &block)
+        name = name.to_sym
+
         # Case 1: agent :name, <<~MD do ... end (markdown + overrides)
         if content.is_a?(String) && block_given? && markdown_content?(content)
           load_agent_from_markdown_with_overrides(content, name, &block)
+
         # Case 2: agent :name, <<~MD (markdown only)
         elsif content.is_a?(String) && !block_given? && markdown_content?(content)
           load_agent_from_markdown(content, name)
-        # Case 3: agent :name do ... end (inline DSL)
+
+        # Case 3: agent :name (registry lookup only - no content, no block)
+        elsif content.nil? && !block_given?
+          load_agent_from_registry(name)
+
+        # Case 4: agent :name do ... end (with registered agent - registry + overrides)
+        elsif content.nil? && block_given? && AgentRegistry.registered?(name)
+          load_agent_from_registry_with_overrides(name, &block)
+
+        # Case 5: agent :name do ... end (inline DSL - not registered)
         elsif block_given?
           builder = Agent::Builder.new(name)
           builder.instance_eval(&block)
           @agents[name] = builder
+
         else
-          raise ArgumentError, "Invalid agent definition. Use: agent :name { ... } OR agent :name, <<~MD ... MD OR agent :name, <<~MD do ... end"
+          raise ArgumentError,
+            "Invalid agent definition for '#{name}'. Use:\n  " \
+              "agent :#{name} { ... }           # Inline DSL\n  " \
+              "agent :#{name}                   # Registry lookup\n  " \
+              "agent :#{name} { ... }           # Registry + overrides (if registered)\n  " \
+              "agent :#{name}, <<~MD ... MD     # Markdown\n  " \
+              "agent :#{name}, <<~MD do ... end # Markdown + overrides"
         end
       end
 
@@ -138,6 +169,54 @@ module SwarmSDK
         str.start_with?("---") || str.include?("\n---\n")
       end
 
+      # Load an agent from the global registry
+      #
+      # Retrieves the registered agent block and executes it in the context
+      # of a new Agent::Builder.
+      #
+      # @param name [Symbol] Agent name
+      # @return [void]
+      # @raise [ConfigurationError] If agent is not registered
+      #
+      # @example
+      #   load_agent_from_registry(:backend)
+      def load_agent_from_registry(name)
+        registered_proc = AgentRegistry.get(name)
+        unless registered_proc
+          raise ConfigurationError,
+            "Agent '#{name}' not found in registry. " \
+              "Either define inline with `agent :#{name} do ... end` or " \
+              "register globally with `SwarmSDK.agent :#{name} do ... end`"
+        end
+
+        builder = Agent::Builder.new(name)
+        builder.instance_eval(&registered_proc)
+        @agents[name] = builder
+      end
+
+      # Load an agent from the registry with additional overrides
+      #
+      # Applies the registered configuration first, then executes the
+      # override block to customize the agent.
+      #
+      # @param name [Symbol] Agent name
+      # @yield Override block with additional configuration
+      # @return [void]
+      #
+      # @example
+      #   load_agent_from_registry_with_overrides(:backend) do
+      #     tools :CustomTool  # Adds to registry-defined tools
+      #   end
+      def load_agent_from_registry_with_overrides(name, &override_block)
+        registered_proc = AgentRegistry.get(name)
+        # Guaranteed to exist since we checked in the condition
+
+        builder = Agent::Builder.new(name)
+        builder.instance_eval(&registered_proc)  # Base config from registry
+        builder.instance_eval(&override_block)   # Apply overrides
+        @agents[name] = builder
+      end
+
       # Load an agent from markdown content
       #
       # Returns a hash of the agent config (not a Definition yet) so that
@@ -318,7 +397,7 @@ module SwarmSDK
       # @return [void]
       def validate_all_agents_filesystem_tools
         resolved_setting = if @allow_filesystem_tools.nil?
-          SwarmSDK.settings.allow_filesystem_tools
+          SwarmSDK.config.allow_filesystem_tools
         else
           @allow_filesystem_tools
         end
@@ -333,10 +412,10 @@ module SwarmSDK
         return if forbidden.empty?
 
         raise ConfigurationError,
-          "Filesystem tools are globally disabled (SwarmSDK.settings.allow_filesystem_tools = false) " \
+          "Filesystem tools are globally disabled (SwarmSDK.config.allow_filesystem_tools = false) " \
             "but all_agents configuration includes: #{forbidden.join(", ")}.\n\n" \
             "This is a system-wide security setting that cannot be overridden by swarm configuration.\n" \
-            "To use filesystem tools, set SwarmSDK.settings.allow_filesystem_tools = true before loading the swarm."
+            "To use filesystem tools, set SwarmSDK.config.allow_filesystem_tools = true before loading the swarm."
       end
 
       # Validate individual agent filesystem tools
@@ -345,7 +424,7 @@ module SwarmSDK
       # @return [void]
       def validate_agent_filesystem_tools
         resolved_setting = if @allow_filesystem_tools.nil?
-          SwarmSDK.settings.allow_filesystem_tools
+          SwarmSDK.config.allow_filesystem_tools
         else
           @allow_filesystem_tools
         end
@@ -373,10 +452,10 @@ module SwarmSDK
           next if forbidden.empty?
 
           raise ConfigurationError,
-            "Filesystem tools are globally disabled (SwarmSDK.settings.allow_filesystem_tools = false) " \
+            "Filesystem tools are globally disabled (SwarmSDK.config.allow_filesystem_tools = false) " \
               "but agent '#{agent_name}' attempts to use: #{forbidden.join(", ")}.\n\n" \
               "This is a system-wide security setting that cannot be overridden by swarm configuration.\n" \
-              "To use filesystem tools, set SwarmSDK.settings.allow_filesystem_tools = true before loading the swarm."
+              "To use filesystem tools, set SwarmSDK.config.allow_filesystem_tools = true before loading the swarm."
         end
       end
 

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

@@ -30,9 +30,18 @@ module SwarmSDK
         :nodes,
         :external_swarms
 
-      def initialize(yaml_content, base_dir:)
+      # 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
@@ -55,7 +64,7 @@ module SwarmSDK
         end
 
         @config = Utils.symbolize_keys(@config)
-        interpolate_env_vars!(@config)
+        interpolate_env_vars!(@config) if env_interpolation_enabled?
 
         validate_version
         detect_and_validate_type
@@ -86,6 +95,17 @@ module SwarmSDK
 
       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