swarm_sdk 2.5.5 → 2.6.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6a4f3f78d9207417839e82926b9960b56f6217cf030db8c741f8ef01111c7866
-  data.tar.gz: 49b9bb1af8c79090dcb061dc519e9c9c286829f695feb02385be1a44082d8f24
+  metadata.gz: ce2f1c2ddb88cfb9a4fe7505fc0417494c2baf22a41678cbe7eb9085d96f136f
+  data.tar.gz: 5d5c8174d6f96d52f6855636d5fc7c485db6a0470e11d18ee2b5866fcd91431a
 SHA512:
-  metadata.gz: 4760b9d3c722515a641c28da4a0575b8695074fcf8de8ccea0f71a14f23e1f53bfab6eec846132318fe159f253f7d70c166d36aaf06eb13c437043eb1d3bf97d
-  data.tar.gz: 60b24194187ab0a14e532e44b06c47e562fbf6edea5e35f369823bbf697558f8dbd4705ed3c91aea8d061573eb21d45651c6d665a46e9c3121109e7cd1728f30
+  metadata.gz: 5e503eeda171b1840cabc10fccc5f98d1c4bcd75eba1782f885fd19cc09219b39850662c901793ff9e9d0cbfbdfcc9759071c782476bb793ab87f9ddd94c3ae9
+  data.tar.gz: 054e3a4db5ead9c96e2d332a1a85e9102bdaabe8e50c1e3163776789709289b5fbc73fce5f73b4af856c6e1ca0a3e6f5b3cbf4918f10f6a946c9ef6223384b12

data/lib/swarm_sdk/agent/builder.rb

@@ -49,7 +49,8 @@ module SwarmSDK
         @directory = "."
         @parameters = {}
         @headers = {}
-        @timeout = nil
+        @request_timeout = nil
+        @turn_timeout = nil
         @mcp_servers = []
         @disable_default_tools = nil # nil = include all default tools
         @bypass_permissions = false
@@ -112,11 +113,18 @@ module SwarmSDK
         @headers = header_hash
       end
 
-      # Set/get timeout
-      def timeout(seconds = :__not_provided__)
-        return @timeout if seconds == :__not_provided__
+      # Set/get request timeout
+      def request_timeout(seconds = :__not_provided__)
+        return @request_timeout if seconds == :__not_provided__
 
-        @timeout = seconds
+        @request_timeout = seconds
+      end
+
+      # Set/get turn timeout
+      def turn_timeout(seconds = :__not_provided__)
+        return @turn_timeout if seconds == :__not_provided__
+
+        @turn_timeout = seconds
       end
 
       # Add an MCP server configuration
@@ -242,8 +250,39 @@ module SwarmSDK
       end
 
       # Set delegation targets
-      def delegates_to(*agent_names)
-        @delegates_to.concat(agent_names)
+      #
+      # Supports multiple formats for flexibility:
+      #
+      # @example Simple array (backwards compatible)
+      #   delegates_to :frontend, :backend, :qa
+      #
+      # @example Hash with custom tool names
+      #   delegates_to frontend: "AskFrontend",
+      #                backend: "GetBackendHelp",
+      #                qa: "RequestReview"
+      #
+      # @example Mixed - some auto, some custom
+      #   delegates_to :frontend,
+      #                backend: "GetBackendHelp",
+      #                :qa
+      #
+      # @param agent_names_and_options [Array<Symbol, Hash>] Agent names and/or hash with custom tool names
+      # @return [void]
+      def delegates_to(*agent_names_and_options)
+        agent_names_and_options.each do |item|
+          case item
+          when Symbol, String
+            # Simple format: :frontend
+            @delegates_to << { agent: item.to_sym, tool_name: nil }
+          when Hash
+            # Hash format: { frontend: "AskFrontend", backend: nil }
+            item.each do |agent, tool_name|
+              @delegates_to << { agent: agent.to_sym, tool_name: tool_name }
+            end
+          else
+            raise ConfigurationError, "delegates_to accepts Symbols or Hashes, got #{item.class}"
+          end
+        end
       end
 
       # Add a hook (Ruby block OR shell command)
@@ -386,13 +425,22 @@ module SwarmSDK
         !@api_version.nil?
       end
 
-      # Check if timeout has been explicitly set
+      # Check if request_timeout has been explicitly set
+      #
+      # Used by Swarm::Builder to determine if all_agents request_timeout should apply.
+      #
+      # @return [Boolean] true if request_timeout was explicitly set
+      def request_timeout_set?
+        !@request_timeout.nil?
+      end
+
+      # Check if turn_timeout has been explicitly set
       #
-      # Used by Swarm::Builder to determine if all_agents timeout should apply.
+      # Used by Swarm::Builder to determine if all_agents turn_timeout should apply.
       #
-      # @return [Boolean] true if timeout was explicitly set
-      def timeout_set?
-        !@timeout.nil?
+      # @return [Boolean] true if turn_timeout was explicitly set
+      def turn_timeout_set?
+        !@turn_timeout.nil?
       end
 
       # Check if coding_agent has been explicitly set
@@ -448,7 +496,8 @@ module SwarmSDK
         agent_config[:context_window] = @context_window if @context_window
         agent_config[:parameters] = @parameters if @parameters.any?
         agent_config[:headers] = @headers if @headers.any?
-        agent_config[:timeout] = @timeout if @timeout
+        agent_config[:request_timeout] = @request_timeout if @request_timeout
+        agent_config[:turn_timeout] = @turn_timeout if @turn_timeout
         agent_config[:mcp_servers] = @mcp_servers if @mcp_servers.any?
         agent_config[:disable_default_tools] = @disable_default_tools unless @disable_default_tools.nil?
         agent_config[:bypass_permissions] = @bypass_permissions

data/lib/swarm_sdk/agent/chat.rb

@@ -122,7 +122,7 @@ module SwarmSDK
         max_concurrent_tools = definition[:max_concurrent_tools]
         base_url = definition[:base_url]
         api_version = definition[:api_version]
-        timeout = definition[:timeout] || SwarmSDK.config.agent_request_timeout
+        request_timeout = definition[:request_timeout] || SwarmSDK.config.agent_request_timeout
         assume_model_exists = definition[:assume_model_exists]
         system_prompt = definition[:system_prompt]
         parameters = definition[:parameters]
@@ -131,6 +131,9 @@ module SwarmSDK
         # Agent identifier (for plugin callbacks)
         @agent_name = agent_name
 
+        # Turn timeout (external timeout for entire ask() call)
+        @turn_timeout = definition[:turn_timeout]
+
         # Context manager for ephemeral messages
         @context_manager = ContextManager.new
 
@@ -162,7 +165,7 @@ module SwarmSDK
           provider_name: provider_name,
           base_url: base_url,
           api_version: api_version,
-          timeout: timeout,
+          timeout: request_timeout,
           assume_model_exists: assume_model_exists,
           max_concurrent_tools: max_concurrent_tools,
         )
@@ -461,48 +464,11 @@ module SwarmSDK
       # @return [RubyLLM::Message] LLM response
       def ask(prompt, **options)
         @ask_semaphore.acquire do
-          is_first = first_message?
-
-          # Collect system reminders to inject as ephemeral content
-          reminders = collect_system_reminders(prompt, is_first)
-
-          # Trigger user_prompt hook (with clean prompt, not reminders)
-          source = options.delete(:source) || "user"
-          final_prompt = prompt
-          if @hook_executor
-            hook_result = trigger_user_prompt(prompt, source: source)
-
-            if hook_result[:halted]
-              return RubyLLM::Message.new(
-                role: :assistant,
-                content: hook_result[:halt_message],
-                model_id: model_id,
-              )
-            end
-
-            final_prompt = hook_result[:modified_prompt] if hook_result[:modified_prompt]
-          end
-
-          # Add CLEAN user message to history (no reminders embedded)
-          @llm_chat.add_message(role: :user, content: final_prompt)
-
-          # Track reminders as ephemeral content for this LLM call only
-          # They'll be injected by around_llm_request hook but not stored
-          reminders.each do |reminder|
-            @context_manager.add_ephemeral_reminder(reminder, messages_array: @llm_chat.messages)
-          end
-
-          # Execute complete() which handles tool loop and ephemeral injection
-          response = execute_with_global_semaphore do
-            catch(:finish_agent) do
-              catch(:finish_swarm) do
-                @llm_chat.complete(**options)
-              end
-            end
+          if @turn_timeout
+            execute_with_turn_timeout(prompt, options)
+          else
+            execute_ask(prompt, options)
           end
-
-          # Handle finish markers from hooks
-          handle_finish_marker(response)
         end
       end
 
@@ -559,6 +525,103 @@ module SwarmSDK
 
       private
 
+      # Execute ask with turn timeout wrapper
+      def execute_with_turn_timeout(prompt, options)
+        task = Async::Task.current
+
+        # Use barrier to track child tasks spawned during this turn
+        # (includes RubyLLM's async tool execution when max_concurrent_tools is set)
+        barrier = Async::Barrier.new
+
+        begin
+          task.with_timeout(
+            @turn_timeout,
+            TurnTimeoutError,
+            "Agent turn timed out after #{@turn_timeout}s",
+          ) do
+            # Execute inside barrier to track child tasks
+            barrier.async do
+              execute_ask(prompt, options)
+            end.wait
+          end
+        rescue TurnTimeoutError
+          # Stop all child tasks
+          barrier.stop
+
+          emit_turn_timeout_event
+
+          # Return error message as response so caller can handle gracefully
+          # Format like other tool/delegation errors for natural flow
+          # This message goes to the swarm/caller, NOT added to agent's conversation history
+          RubyLLM::Message.new(
+            role: :assistant,
+            content: "Error: Request timed out after #{@turn_timeout}s. The agent did not complete its response within the time limit. Please try a simpler request or increase the turn timeout.",
+            model_id: model_id,
+          )
+        ensure
+          # Cleanup barrier if not already stopped
+          barrier.stop unless barrier.empty?
+        end
+      end
+
+      # Emit turn timeout event
+      def emit_turn_timeout_event
+        LogStream.emit(
+          type: "turn_timeout",
+          agent: @agent_name,
+          swarm_id: @agent_context&.swarm_id,
+          parent_swarm_id: @agent_context&.parent_swarm_id,
+          limit: @turn_timeout,
+          message: "Agent turn timed out after #{@turn_timeout}s",
+        )
+      end
+
+      # Execute ask without timeout (original ask implementation)
+      def execute_ask(prompt, options)
+        is_first = first_message?
+
+        # Collect system reminders to inject as ephemeral content
+        reminders = collect_system_reminders(prompt, is_first)
+
+        # Trigger user_prompt hook (with clean prompt, not reminders)
+        source = options.delete(:source) || "user"
+        final_prompt = prompt
+        if @hook_executor
+          hook_result = trigger_user_prompt(prompt, source: source)
+
+          if hook_result[:halted]
+            return RubyLLM::Message.new(
+              role: :assistant,
+              content: hook_result[:halt_message],
+              model_id: model_id,
+            )
+          end
+
+          final_prompt = hook_result[:modified_prompt] if hook_result[:modified_prompt]
+        end
+
+        # Add CLEAN user message to history (no reminders embedded)
+        @llm_chat.add_message(role: :user, content: final_prompt)
+
+        # Track reminders as ephemeral content for this LLM call only
+        # They'll be injected by around_llm_request hook but not stored
+        reminders.each do |reminder|
+          @context_manager.add_ephemeral_reminder(reminder, messages_array: @llm_chat.messages)
+        end
+
+        # Execute complete() which handles tool loop and ephemeral injection
+        response = execute_with_global_semaphore do
+          catch(:finish_agent) do
+            catch(:finish_swarm) do
+              @llm_chat.complete(**options)
+            end
+          end
+        end
+
+        # Handle finish markers from hooks
+        handle_finish_marker(response)
+      end
+
       # --- Tool Execution Hook ---
 
       # Setup around_tool_execution hook for SwarmSDK orchestration

data/lib/swarm_sdk/agent/definition.rb

@@ -24,7 +24,7 @@ module SwarmSDK
         :context_window,
         :directory,
         :tools,
-        :delegates_to,
+        :delegation_configs, # Full delegation config with tool names
         :system_prompt,
         :provider,
         :base_url,
@@ -32,7 +32,8 @@ module SwarmSDK
         :mcp_servers,
         :parameters,
         :headers,
-        :timeout,
+        :request_timeout,
+        :turn_timeout,
         :disable_default_tools,
         :coding_agent,
         :default_permissions,
@@ -74,9 +75,16 @@ module SwarmSDK
         @context_window = coerce_to_integer(config[:context_window]) # Explicit context window override
         @parameters = config[:parameters] || {}
         @headers = Utils.stringify_keys(config[:headers] || {})
-        @timeout = config[:timeout] || SwarmSDK.config.agent_request_timeout
+        @request_timeout = config[:request_timeout] || SwarmSDK.config.agent_request_timeout
         @bypass_permissions = config[:bypass_permissions] || false
         @max_concurrent_tools = config[:max_concurrent_tools]
+
+        # Use default from config unless explicitly set (including nil to disable)
+        @turn_timeout = if config.key?(:turn_timeout)
+          config[:turn_timeout] # Could be a number OR nil (to disable)
+        else
+          SwarmSDK.config.default_turn_timeout
+        end
         # Always assume model exists - SwarmSDK validates models separately using models.json
         # This prevents RubyLLM from trying to validate models in its registry
         @assume_model_exists = true
@@ -117,7 +125,8 @@ module SwarmSDK
         # Inject default write restrictions for security
         @tools = inject_default_write_permissions(@tools)
 
-        @delegates_to = Array(config[:delegates_to] || []).map(&:to_sym).uniq
+        # Parse delegation configuration (supports both simple arrays and custom tool names)
+        @delegation_configs = parse_delegation_config(config[:delegates_to])
         @mcp_servers = Array(config[:mcp_servers] || [])
 
         # Parse hooks configuration
@@ -127,6 +136,20 @@ module SwarmSDK
         validate!
       end
 
+      # Get agent names that this agent delegates to (backwards compatible)
+      #
+      # Returns an array of agent name symbols. This maintains backwards compatibility
+      # with existing code that expects delegates_to to be a simple array.
+      #
+      # @return [Array<Symbol>] Delegate agent names
+      #
+      # @example
+      #   agent_definition.delegates_to
+      #   # => [:frontend, :backend, :qa]
+      def delegates_to
+        @delegation_configs.map { |config| config[:agent] }
+      end
+
       # Get plugin-specific configuration
       #
       # Plugins store their configuration in the generic plugin_configs hash.
@@ -138,7 +161,7 @@ module SwarmSDK
       #
       # @example
       #   agent_definition.plugin_config(:memory)
-      #   # => { directory: "tmp/memory", mode: :researcher }
+      #   # => { directory: "tmp/memory", mode: :full_access }
       def plugin_config(plugin_name)
         @plugin_configs[plugin_name.to_sym] || @plugin_configs[plugin_name.to_s]
       end
@@ -152,7 +175,7 @@ module SwarmSDK
           context_window: @context_window,
           directory: @directory,
           tools: @tools,
-          delegates_to: @delegates_to,
+          delegates_to: @delegation_configs, # Serialize full config
           system_prompt: @system_prompt,
           provider: @provider,
           base_url: @base_url,
@@ -160,7 +183,8 @@ module SwarmSDK
           mcp_servers: @mcp_servers,
           parameters: @parameters,
           headers: @headers,
-          timeout: @timeout,
+          request_timeout: @request_timeout,
+          turn_timeout: @turn_timeout,
           bypass_permissions: @bypass_permissions,
           disable_default_tools: @disable_default_tools,
           coding_agent: @coding_agent,
@@ -276,6 +300,51 @@ module SwarmSDK
         File.expand_path(directory_config.to_s)
       end
 
+      # Parse delegation configuration
+      #
+      # Supports multiple formats for backwards compatibility and new features:
+      # 1. Simple array (backwards compatible): [:frontend, :backend]
+      # 2. Hash with custom tool names: { frontend: "AskFrontend", backend: nil }
+      # 3. Array of hashes: [{ agent: :frontend, tool_name: "AskFrontend" }]
+      #
+      # Returns normalized format: [{agent: :name, tool_name: "Custom" or nil}]
+      #
+      # @param delegation_config [nil, Array, Hash] Delegation configuration
+      # @return [Array<Hash>] Normalized delegation config
+      def parse_delegation_config(delegation_config)
+        return [] if delegation_config.nil?
+        return [] if delegation_config.respond_to?(:empty?) && delegation_config.empty?
+
+        # Handle array format (could be symbols or hashes)
+        if delegation_config.is_a?(Array)
+          delegation_config.flat_map do |item|
+            case item
+            when Symbol, String
+              # Simple format: :frontend → {agent: :frontend, tool_name: nil}
+              [{ agent: item.to_sym, tool_name: nil }]
+            when Hash
+              # Could be already normalized or hash format
+              if item.key?(:agent)
+                # Already normalized: {agent: :frontend, tool_name: "Custom"}
+                [item]
+              else
+                # Hash format in array: {frontend: "AskFrontend"}
+                item.map { |agent, tool_name| { agent: agent.to_sym, tool_name: tool_name } }
+              end
+            else
+              raise ConfigurationError, "Invalid delegation config format: #{item.inspect}"
+            end
+          end.uniq { |config| config[:agent] } # Remove duplicates by agent name
+        elsif delegation_config.is_a?(Hash)
+          # Hash format: {frontend: "AskFrontend", backend: nil}
+          delegation_config.map do |agent, tool_name|
+            { agent: agent.to_sym, tool_name: tool_name }
+          end
+        else
+          raise ConfigurationError, "delegates_to must be an Array or Hash, got #{delegation_config.class}"
+        end
+      end
+
       # Extract plugin-specific configuration keys from the config hash
       #
       # Standard SDK keys are filtered out, leaving only plugin-specific keys.
@@ -294,7 +363,8 @@ module SwarmSDK
           :context_window,
           :parameters,
           :headers,
-          :timeout,
+          :request_timeout,
+          :turn_timeout,
           :bypass_permissions,
           :max_concurrent_tools,
           :assume_model_exists,
@@ -465,6 +535,11 @@ module SwarmSDK
       def validate!
         raise ConfigurationError, "Agent '#{@name}' missing required 'description' field" unless @description
 
+        # Validate turn_timeout is positive if set
+        if @turn_timeout && @turn_timeout <= 0
+          raise ConfigurationError, "Agent '#{@name}' turn_timeout must be positive (got #{@turn_timeout})"
+        end
+
         # Validate api_version can only be set for OpenAI-compatible providers
         if @api_version
           openai_compatible = ["openai", "deepseek", "perplexity", "mistral", "openrouter"]

data/lib/swarm_sdk/builders/base_builder.rb

@@ -260,7 +260,8 @@ module SwarmSDK
         builder.context_window(config[:context_window]) if config[:context_window]
         builder.system_prompt(config[:system_prompt]) if config[:system_prompt]
         builder.directory(config[:directory]) if config[:directory]
-        builder.timeout(config[:timeout]) if config[:timeout]
+        builder.request_timeout(config[:request_timeout]) if config[:request_timeout]
+        builder.turn_timeout(config[:turn_timeout]) if config[:turn_timeout]
         builder.parameters(config[:parameters]) if config[:parameters]
         builder.headers(config[:headers]) if config[:headers]
         builder.coding_agent(config[:coding_agent]) unless config[:coding_agent].nil?
@@ -275,8 +276,17 @@ module SwarmSDK
           builder.tools(*tool_names)
         end
 
-        # Add delegates_to
-        builder.delegates_to(*config[:delegates_to]) if config[:delegates_to]&.any?
+        # Add delegates_to (handle both array and hash formats)
+        if config[:delegates_to]&.any?
+          delegation_config = config[:delegates_to]
+          if delegation_config.is_a?(Hash)
+            # Hash format: pass as single argument
+            builder.delegates_to(delegation_config)
+          elsif delegation_config.is_a?(Array)
+            # Array format: splat the array
+            builder.delegates_to(*delegation_config)
+          end
+        end
 
         # Add MCP servers
         config[:mcp_servers]&.each do |server|
@@ -332,11 +342,25 @@ module SwarmSDK
           when :tools
             merged[:tools] = Array(merged[:tools]) + Array(value)
           when :delegates_to
-            merged[:delegates_to] = Array(merged[:delegates_to]) + Array(value)
+            # Handle merging delegation configs (can be array or hash)
+            existing = merged[:delegates_to] || []
+            new_value = value || []
+
+            # Convert both to array of delegation configs for merging
+            existing_array = normalize_delegation_array(existing)
+            new_array = normalize_delegation_array(new_value)
+
+            merged[:delegates_to] = existing_array + new_array
           when :parameters
             merged[:parameters] = (merged[:parameters] || {}).merge(value || {})
           when :headers
             merged[:headers] = (merged[:headers] || {}).merge(value || {})
+          when :turn_timeout
+            # Agent-specific turn_timeout overrides all_agents
+            merged[key] = value
+          when :request_timeout
+            # Agent-specific request_timeout overrides all_agents
+            merged[key] = value
           else
             merged[key] = value
           end
@@ -350,6 +374,35 @@ module SwarmSDK
         merged
       end
 
+      # Normalize delegation config to array of hashes format
+      #
+      # Converts various delegation formats to normalized array for merging:
+      # - Array of symbols: [:frontend, :backend] → [{agent: :frontend, tool_name: nil}, ...]
+      # - Hash: {frontend: "Custom"} → [{agent: :frontend, tool_name: "Custom"}, ...]
+      # - Array of hashes: [{agent: :frontend, tool_name: "Custom"}] → unchanged
+      #
+      # @param delegation_config [Array, Hash] Delegation configuration
+      # @return [Array<Hash>] Normalized array of {agent:, tool_name:} hashes
+      def normalize_delegation_array(delegation_config)
+        return [] if delegation_config.nil? || (delegation_config.respond_to?(:empty?) && delegation_config.empty?)
+
+        case delegation_config
+        when Array
+          delegation_config.map do |item|
+            case item
+            when Symbol, String
+              { agent: item.to_sym, tool_name: nil }
+            when Hash
+              item.key?(:agent) ? item : item.map { |agent, tool_name| { agent: agent.to_sym, tool_name: tool_name } }
+            end
+          end.flatten
+        when Hash
+          delegation_config.map { |agent, tool_name| { agent: agent.to_sym, tool_name: tool_name } }
+        else
+          []
+        end
+      end
+
       # Apply all_agents defaults to an agent builder
       #
       # @param agent_builder [Agent::Builder] The agent builder to configure
@@ -372,8 +425,12 @@ module SwarmSDK
           agent_builder.api_version(all_agents_hash[:api_version])
         end
 
-        if all_agents_hash[:timeout] && !agent_builder.timeout_set?
-          agent_builder.timeout(all_agents_hash[:timeout])
+        if all_agents_hash[:request_timeout] && !agent_builder.request_timeout_set?
+          agent_builder.request_timeout(all_agents_hash[:request_timeout])
+        end
+
+        if all_agents_hash[:turn_timeout] && !agent_builder.turn_timeout_set?
+          agent_builder.turn_timeout(all_agents_hash[:turn_timeout])
         end
 
         if all_agents_hash[:parameters]

data/lib/swarm_sdk/config.rb

@@ -81,6 +81,8 @@ module SwarmSDK
       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 }],
+      default_execution_timeout: ["SWARM_SDK_DEFAULT_EXECUTION_TIMEOUT", -> { Defaults::Timeouts::EXECUTION_TIMEOUT_SECONDS }],
+      default_turn_timeout: ["SWARM_SDK_DEFAULT_TURN_TIMEOUT", -> { Defaults::Timeouts::TURN_TIMEOUT_SECONDS }],
     }.freeze
 
     # WebFetch and control settings

data/lib/swarm_sdk/configuration/parser.rb

@@ -28,7 +28,8 @@ module SwarmSDK
         :all_agents_hooks,
         :scratchpad_mode,
         :nodes,
-        :external_swarms
+        :external_swarms,
+        :execution_timeout
 
       # Initialize parser with YAML content and options
       #
@@ -54,6 +55,7 @@ module SwarmSDK
         @external_swarms = {}
         @nodes = {}
         @scratchpad_mode = :disabled
+        @execution_timeout = nil
       end
 
       def parse
@@ -88,7 +90,28 @@ module SwarmSDK
         return [] unless agent_config
 
         delegates = agent_config[:delegates_to] || []
-        Array(delegates).map(&:to_sym)
+
+        # Handle both array and hash formats for delegates_to
+        case delegates
+        when Array
+          # Array of symbols: [:frontend, :backend]
+          # OR array of hashes: [{agent: :frontend, tool_name: "Custom"}]
+          delegates.map do |item|
+            case item
+            when Symbol, String
+              item.to_sym
+            when Hash
+              # Extract agent name from hash format
+              agent_name = item[:agent] || item["agent"]
+              agent_name&.to_sym
+            end
+          end.compact # Remove nils from malformed hashes
+        when Hash
+          # Hash format: {frontend: "Custom", backend: nil}
+          delegates.keys.map(&:to_sym)
+        else
+          []
+        end
       end
 
       attr_reader :base_dir
@@ -134,6 +157,7 @@ module SwarmSDK
         @swarm_name = @root_config[:name]
         @swarm_id = @root_config[:id]
         @scratchpad_mode = parse_scratchpad_mode(@root_config[:scratchpad])
+        @execution_timeout = @root_config[:execution_timeout]
 
         load_all_agents_config
         load_hooks_config