swarm_sdk 2.2.0 → 2.3.0

data/lib/swarm_sdk/swarm/builder.rb

@@ -28,7 +28,7 @@ module SwarmSDK
     #   end
     #
     #   swarm.execute("Build auth API")
-    class Builder
+    class Builder < Builders::BaseBuilder
       # Main entry point for DSL
       #
       # @example
@@ -45,29 +45,10 @@ module SwarmSDK
       end
 
       def initialize(allow_filesystem_tools: nil)
-        @swarm_id = nil
-        @swarm_name = nil
+        super
         @lead_agent = nil
-        @agents = {}
-        @all_agents_config = nil
         @swarm_hooks = []
-        @swarm_registry_config = [] # NEW - stores register() calls for composable swarms
-        @nodes = {}
-        @start_node = nil
-        @scratchpad = :disabled # Default: disabled
-        @allow_filesystem_tools = allow_filesystem_tools
-      end
-
-      # Set swarm ID
-      #
-      # @param swarm_id [String] Unique identifier for this swarm
-      def id(swarm_id)
-        @swarm_id = swarm_id
-      end
-
-      # Set swarm name
-      def name(swarm_name)
-        @swarm_name = swarm_name
+        @observer_configs = []
       end
 
       # Set lead agent
@@ -75,75 +56,42 @@ module SwarmSDK
         @lead_agent = agent_name
       end
 
-      # Configure scratchpad mode
+      # Define observer agent behavior
       #
-      # For NodeOrchestrator: :enabled (shared across nodes), :per_node (isolated), or :disabled
-      # For regular Swarm: :enabled or :disabled
+      # Configures an agent to run in parallel with main execution,
+      # triggered by specific events. The block defines event handlers.
       #
-      # @param mode [Symbol, Boolean] Scratchpad mode
-      def scratchpad(mode)
-        @scratchpad = mode
-      end
-
-      # Register external swarms for composable swarms
+      # @param agent_name [Symbol] Name of agent to use as observer (must be defined)
+      # @param options [Hash] Optional observer settings (timeout, max_concurrent, etc.)
+      # @yield Observer configuration block
       #
-      # @example
-      #   swarms do
-      #     register "code_review", file: "./swarms/code_review.rb"
-      #     register "testing", file: "./swarms/testing.yml", keep_context: false
+      # @example Basic observer
+      #   observer :profiler do
+      #     on :swarm_start do |event|
+      #       "Analyze this prompt: #{event[:prompt]}"
+      #     end
       #   end
       #
-      # @yield Block containing register() calls
-      def swarms(&block)
-        builder = SwarmRegistryBuilder.new
-        builder.instance_eval(&block)
-        @swarm_registry_config = builder.registrations
-      end
-
-      # Define an agent with fluent API or load from markdown content
-      #
-      # Supports two forms:
-      # 1. Inline DSL: agent :name do ... end
-      # 2. Markdown content: agent :name, <<~MD ... MD
-      #
-      # The name parameter is always required. If the markdown has a name field
-      # in frontmatter, it will be replaced by the name parameter.
-      #
-      # @example Inline DSL
-      #   agent :backend do
-      #     model "gpt-5"
-      #     system_prompt "You build APIs"
-      #     tools :Read, :Write
-      #
-      #     hook :pre_tool_use, matcher: "Bash" do |ctx|
-      #       # Inline validation logic!
+      # @example Observer with options
+      #   observer :monitor, timeout: 120 do
+      #     on :tool_call do |event|
+      #       next unless event[:tool_name] == "Bash"
+      #       "Check command: #{event[:arguments][:command]}"
       #     end
       #   end
-      #
-      # @example Markdown content
-      #   agent :backend, <<~MD
-      #     ---
-      #     description: "Backend developer"
-      #     model: "gpt-4"
-      #     ---
-      #
-      #     You build APIs.
-      #   MD
-      def agent(name, content = nil, &block)
-        # 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)
-        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"
+      def observer(agent_name, **options, &block)
+        unless @agents.key?(agent_name)
+          raise ConfigurationError,
+            "Observer agent '#{agent_name}' not defined. " \
+              "Define the agent first with `agent :#{agent_name} do ... end`"
         end
+
+        config = Observer::Config.new(agent_name)
+        config.options.merge!(options) if options.any?
+        builder = Observer::Builder.new(agent_name, config)
+        builder.instance_eval(&block)
+
+        @observer_configs << config
       end
 
       # Add swarm-level hook (swarm_start, swarm_stop only)
@@ -164,202 +112,21 @@ module SwarmSDK
         @swarm_hooks << { event: event, command: command, timeout: timeout, block: block }
       end
 
-      # Configure all agents with a block
-      #
-      # @example
-      #   all_agents do
-      #     tools :Read, :Write
-      #
-      #     hook :pre_tool_use, matcher: "Write" do |ctx|
-      #       # Validation for all agents
-      #     end
-      #   end
-      def all_agents(&block)
-        builder = AllAgentsBuilder.new
-        builder.instance_eval(&block)
-        @all_agents_config = builder
-      end
-
-      # Define a node (mini-swarm execution stage)
-      #
-      # Nodes enable multi-stage workflows where different agent teams
-      # collaborate in sequence. Each node is an independent swarm execution.
-      #
-      # @param name [Symbol] Node name
-      # @yield Block for node configuration
-      # @return [void]
-      #
-      # @example Solo agent node
-      #   node :planning do
-      #     agent(:architect)
-      #   end
-      #
-      # @example Multi-agent node with delegation
-      #   node :implementation do
-      #     agent(:backend).delegates_to(:tester, :database)
-      #     agent(:tester).delegates_to(:database)
-      #     agent(:database)
-      #     after :planning
-      #   end
-      def node(name, &block)
-        builder = Node::Builder.new(name)
-        builder.instance_eval(&block)
-        @nodes[name] = builder
-      end
-
-      # Set the starting node for workflow execution
-      #
-      # Required when nodes are defined. Specifies which node to execute first.
-      #
-      # @param name [Symbol] Name of starting node
-      # @return [void]
-      #
-      # @example
-      #   start_node :planning
-      def start_node(name)
-        @start_node = name.to_sym
-      end
-
-      # Build the actual Swarm instance or NodeOrchestrator
+      # Build the actual Swarm instance
       def build_swarm
         raise ConfigurationError, "Swarm name not set. Use: name 'My Swarm'" unless @swarm_name
+        raise ConfigurationError, "No agents defined. Use: agent :name { ... }" if @agents.empty?
+        raise ConfigurationError, "Lead agent not set. Use: lead :agent_name" unless @lead_agent
 
-        # Validate all_agents filesystem tools BEFORE building
+        # Validate filesystem tools BEFORE building
         validate_all_agents_filesystem_tools if @all_agents_config
-
-        # Validate individual agent filesystem tools BEFORE building
         validate_agent_filesystem_tools
 
-        # Check if nodes are defined
-        if @nodes.any?
-          # Node-based workflow (agents optional for agent-less workflows)
-          build_node_orchestrator
-        else
-          # Traditional single-swarm execution (requires agents and lead)
-          raise ConfigurationError, "No agents defined. Use: agent :name { ... }" if @agents.empty?
-          raise ConfigurationError, "Lead agent not set. Use: lead :agent_name" unless @lead_agent
-
-          build_single_swarm
-        end
+        build_single_swarm
       end
 
       private
 
-      # Normalize scratchpad mode parameter
-      #
-      # Accepts symbols: :enabled, :per_node, or :disabled
-      #
-      # @param value [Symbol, String] Scratchpad mode (strings from YAML converted to symbols)
-      # @return [Symbol] Normalized mode (:enabled, :per_node, or :disabled)
-      # @raise [ConfigurationError] If value is invalid
-      def normalize_scratchpad_mode(value)
-        # Convert strings from YAML to symbols
-        value = value.to_sym if value.is_a?(String)
-
-        case value
-        when :enabled, :per_node, :disabled
-          value
-        else
-          raise ConfigurationError,
-            "Invalid scratchpad mode: #{value.inspect}. Use :enabled, :per_node, or :disabled"
-        end
-      end
-
-      # Check if a string is markdown content (has frontmatter)
-      #
-      # @param str [String] String to check
-      # @return [Boolean] true if string contains markdown frontmatter
-      def markdown_content?(str)
-        str.start_with?("---") || str.include?("\n---\n")
-      end
-
-      # Load an agent from markdown content
-      #
-      # Returns a hash of the agent config (not a Definition yet) so that
-      # all_agents config can be applied later in the build process.
-      #
-      # @param content [String] Markdown content with frontmatter
-      # @param name_override [Symbol, nil] Optional name to override frontmatter name
-      # @return [void]
-      def load_agent_from_markdown(content, name_override = nil)
-        # Parse markdown content - will extract name from frontmatter if not overridden
-        definition = MarkdownParser.parse(content, name_override)
-
-        # Store the config hash (not Definition) so all_agents can be applied
-        # We'll wrap this in a special marker so we know it came from markdown
-        @agents[definition.name] = { __file_config__: definition.to_h }
-      end
-
-      # Load an agent from markdown content with DSL overrides
-      #
-      # This allows loading from a file and then overriding specific settings:
-      #   agent :reviewer, File.read("reviewer.md") do
-      #     provider :openai
-      #     model "gpt-4o"
-      #   end
-      #
-      # @param content [String] Markdown content with frontmatter
-      # @param name_override [Symbol, nil] Optional name to override frontmatter name
-      # @yield Block with DSL overrides
-      # @return [void]
-      def load_agent_from_markdown_with_overrides(content, name_override = nil, &block)
-        # Parse markdown content first
-        definition = MarkdownParser.parse(content, name_override)
-
-        # Create a builder with the markdown config
-        builder = Agent::Builder.new(definition.name)
-
-        # Apply markdown settings to builder (these become the base)
-        apply_definition_to_builder(builder, definition.to_h)
-
-        # Apply DSL overrides (these override the markdown settings)
-        builder.instance_eval(&block)
-
-        # Store the builder (not file config) so overrides are preserved
-        @agents[definition.name] = builder
-      end
-
-      # Apply agent definition hash to a builder
-      #
-      # @param builder [Agent::Builder] Builder to configure
-      # @param config [Hash] Configuration hash from definition
-      # @return [void]
-      def apply_definition_to_builder(builder, config)
-        builder.description(config[:description]) if config[:description]
-        builder.model(config[:model]) if config[:model]
-        builder.provider(config[:provider]) if config[:provider]
-        builder.base_url(config[:base_url]) if config[:base_url]
-        builder.api_version(config[:api_version]) if config[:api_version]
-        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.parameters(config[:parameters]) if config[:parameters]
-        builder.headers(config[:headers]) if config[:headers]
-        builder.coding_agent(config[:coding_agent]) unless config[:coding_agent].nil?
-        # Don't apply assume_model_exists from markdown - let DSL overrides or auto-enable handle it
-        # builder.assume_model_exists(config[:assume_model_exists]) unless config[:assume_model_exists].nil?
-        builder.bypass_permissions(config[:bypass_permissions]) if config[:bypass_permissions]
-        builder.disable_default_tools(config[:disable_default_tools]) unless config[:disable_default_tools].nil?
-
-        # Add tools from markdown
-        if config[:tools]&.any?
-          # Extract tool names from the tools array (which may be hashes with permissions)
-          tool_names = config[:tools].map do |tool|
-            tool.is_a?(Hash) ? tool[:name] : tool
-          end
-          builder.tools(*tool_names)
-        end
-
-        # Add delegates_to
-        builder.delegates_to(*config[:delegates_to]) if config[:delegates_to]&.any?
-
-        # Add MCP servers
-        config[:mcp_servers]&.each do |server|
-          builder.mcp_server(server[:name], **server.except(:name))
-        end
-      end
-
       # Build a traditional single-swarm execution
       #
       # @return [Swarm] Configured swarm instance
@@ -386,20 +153,9 @@ module SwarmSDK
           swarm.swarm_registry = registry
         end
 
-        # Merge all_agents config into each agent (including file-loaded ones)
-        merge_all_agents_config_into_agents if @all_agents_config
-
-        # Build definitions and add to swarm
-        # Handle both Agent::Builder (inline DSL) and file configs (from files)
-        @agents.each do |agent_name, agent_builder_or_config|
-          definition = if agent_builder_or_config.is_a?(Hash) && agent_builder_or_config.key?(:__file_config__)
-            # File-loaded agent config (with all_agents merged)
-            Agent::Definition.new(agent_name, agent_builder_or_config[:__file_config__])
-          else
-            # Builder object (from inline DSL) - convert to definition
-            agent_builder_or_config.to_definition
-          end
-
+        # Build agent definitions and add to swarm
+        agent_definitions = build_agent_definitions
+        agent_definitions.each_value do |definition|
           swarm.add_agent(definition)
         end
 
@@ -407,198 +163,21 @@ module SwarmSDK
         swarm.lead = @lead_agent
 
         # Apply swarm hooks (Ruby blocks)
-        # These are swarm-level hooks (swarm_start, swarm_stop)
         @swarm_hooks.each do |hook_config|
           apply_swarm_hook(swarm, hook_config)
         end
 
         # Apply all_agents hooks (Ruby blocks)
-        # These become swarm-level default callbacks that apply to all agents
         @all_agents_config&.hooks&.each do |hook_config|
           apply_all_agents_hook(swarm, hook_config)
         end
 
-        # NOTE: Agent-specific hooks are already stored in Agent::Definition.callbacks
-        # They'll be applied automatically during agent initialization (pass_4_configure_hooks)
-        # This ensures they're applied at the right time, after LogStream is set up
+        # Add observer configurations to swarm
+        @observer_configs.each { |c| swarm.add_observer_config(c) }
 
         swarm
       end
 
-      # Build a node-based workflow orchestrator
-      #
-      # @return [NodeOrchestrator] Configured orchestrator
-      def build_node_orchestrator
-        raise ConfigurationError, "start_node required when nodes are defined. Use: start_node :name" unless @start_node
-
-        # Merge all_agents config into each agent (applies to all nodes)
-        merge_all_agents_config_into_agents if @all_agents_config
-
-        # Build agent definitions
-        # Handle both Agent::Builder (inline DSL) and file configs (from files)
-        agent_definitions = {}
-        @agents.each do |agent_name, agent_builder_or_config|
-          agent_definitions[agent_name] = if agent_builder_or_config.is_a?(Hash) && agent_builder_or_config.key?(:__file_config__)
-            # File-loaded agent config (with all_agents merged)
-            Agent::Definition.new(agent_name, agent_builder_or_config[:__file_config__])
-          else
-            # Builder object (from inline DSL) - convert to definition
-            agent_builder_or_config.to_definition
-          end
-        end
-
-        # Create node orchestrator
-        orchestrator = NodeOrchestrator.new(
-          swarm_name: @swarm_name,
-          swarm_id: @swarm_id,
-          agent_definitions: agent_definitions,
-          nodes: @nodes,
-          start_node: @start_node,
-          scratchpad: @scratchpad,
-          allow_filesystem_tools: @allow_filesystem_tools,
-        )
-
-        # Pass swarm registry config to orchestrator if external swarms registered
-        orchestrator.swarm_registry_config = @swarm_registry_config if @swarm_registry_config.any?
-
-        orchestrator
-      end
-
-      # Merge all_agents configuration into each agent
-      #
-      # All_agents values are used as defaults - agent-specific values override.
-      # This applies to both inline DSL agents (Builder) and file-loaded agents (config hash).
-      #
-      # @return [void]
-      def merge_all_agents_config_into_agents
-        return unless @all_agents_config
-
-        all_agents_hash = @all_agents_config.to_h
-
-        @agents.each_value do |agent_builder_or_config|
-          if agent_builder_or_config.is_a?(Hash) && agent_builder_or_config.key?(:__file_config__)
-            # File-loaded agent - merge into the config hash
-            file_config = agent_builder_or_config[:__file_config__]
-
-            # Merge all_agents into file config (file config overrides)
-            # Use same merge strategy as Configuration class
-            merged_config = merge_all_agents_into_config(all_agents_hash, file_config)
-
-            # Update the stored config
-            agent_builder_or_config[:__file_config__] = merged_config
-          else
-            # Builder object (inline DSL agent)
-            agent_builder = agent_builder_or_config
-
-            # Apply all_agents defaults that haven't been set at agent level
-            # Agent values override all_agents values
-            apply_all_agents_defaults(agent_builder, all_agents_hash)
-
-            # Merge tools (prepend all_agents tools)
-            all_agents_tools = @all_agents_config.tools_list
-            agent_builder.prepend_tools(*all_agents_tools) if all_agents_tools.any?
-
-            # Pass all_agents permissions as default_permissions
-            if @all_agents_config.permissions_config.any?
-              agent_builder.default_permissions = @all_agents_config.permissions_config
-            end
-          end
-        end
-      end
-
-      # Merge all_agents config into file-loaded agent config
-      #
-      # Follows same merge strategy as Configuration class:
-      # - Arrays (tools, delegates_to): Concatenate (all_agents + file)
-      # - Hashes (parameters, headers): Merge (file values override)
-      # - Scalars (model, provider, etc.): File overrides
-      #
-      # @param all_agents_hash [Hash] All_agents configuration
-      # @param file_config [Hash] File-loaded agent configuration
-      # @return [Hash] Merged configuration
-      def merge_all_agents_into_config(all_agents_hash, file_config)
-        merged = all_agents_hash.dup
-
-        file_config.each do |key, value|
-          case key
-          when :tools
-            # Concatenate tools: all_agents.tools + file.tools
-            merged[:tools] = Array(merged[:tools]) + Array(value)
-          when :delegates_to
-            # Concatenate delegates_to
-            merged[:delegates_to] = Array(merged[:delegates_to]) + Array(value)
-          when :parameters
-            # Merge parameters: file values override all_agents
-            merged[:parameters] = (merged[:parameters] || {}).merge(value || {})
-          when :headers
-            # Merge headers: file values override all_agents
-            merged[:headers] = (merged[:headers] || {}).merge(value || {})
-          else
-            # For everything else, file value overrides all_agents value
-            merged[key] = value
-          end
-        end
-
-        # Pass all_agents permissions as default_permissions
-        if all_agents_hash[:permissions] && !merged[:default_permissions]
-          merged[:default_permissions] = all_agents_hash[:permissions]
-        end
-
-        merged
-      end
-
-      # Apply all_agents defaults to an agent builder
-      #
-      # Only sets values that haven't been explicitly set at the agent level.
-      # This implements the override semantics: agent values take precedence.
-      #
-      # @param agent_builder [Agent::Builder] The agent builder to configure
-      # @param all_agents_hash [Hash] All_agents configuration
-      # @return [void]
-      def apply_all_agents_defaults(agent_builder, all_agents_hash)
-        # Model: only set if agent hasn't explicitly set it
-        if all_agents_hash[:model] && !agent_builder.model_set?
-          agent_builder.model(all_agents_hash[:model])
-        end
-
-        # Provider: only set if agent hasn't set it
-        if all_agents_hash[:provider] && !agent_builder.provider_set?
-          agent_builder.provider(all_agents_hash[:provider])
-        end
-
-        # Base URL: only set if agent hasn't set it
-        if all_agents_hash[:base_url] && !agent_builder.base_url_set?
-          agent_builder.base_url(all_agents_hash[:base_url])
-        end
-
-        # API Version: only set if agent hasn't set it
-        if all_agents_hash[:api_version] && !agent_builder.api_version_set?
-          agent_builder.api_version(all_agents_hash[:api_version])
-        end
-
-        # Timeout: only set if agent hasn't set it
-        if all_agents_hash[:timeout] && !agent_builder.timeout_set?
-          agent_builder.timeout(all_agents_hash[:timeout])
-        end
-
-        # Parameters: merge (all_agents + agent, agent values override)
-        if all_agents_hash[:parameters]
-          merged_params = all_agents_hash[:parameters].merge(agent_builder.parameters)
-          agent_builder.parameters(merged_params)
-        end
-
-        # Headers: merge (all_agents + agent, agent values override)
-        if all_agents_hash[:headers]
-          merged_headers = all_agents_hash[:headers].merge(agent_builder.headers)
-          agent_builder.headers(merged_headers)
-        end
-
-        # Coding_agent: only set if agent hasn't set it
-        if !all_agents_hash[:coding_agent].nil? && !agent_builder.coding_agent_set?
-          agent_builder.coding_agent(all_agents_hash[:coding_agent])
-        end
-      end
-
       def apply_swarm_hook(swarm, config)
         event = config[:event]
 
@@ -644,7 +223,7 @@ module SwarmSDK
       end
 
       def build_hook_input(context, event)
-        # Build JSON input for shell hooks (similar to HooksAdapter)
+        # Build JSON input for shell hooks
         base = { event: event.to_s }
 
         case event
@@ -662,122 +241,9 @@ module SwarmSDK
           base
         end
       end
-
-      # Validate all_agents filesystem tools
-      #
-      # Raises ConfigurationError if filesystem tools are globally disabled
-      # but all_agents configuration includes them.
-      #
-      # @raise [ConfigurationError] If filesystem tools are disabled and all_agents has them
-      # @return [void]
-      def validate_all_agents_filesystem_tools
-        # Resolve the effective setting
-        resolved_setting = if @allow_filesystem_tools.nil?
-          SwarmSDK.settings.allow_filesystem_tools
-        else
-          @allow_filesystem_tools
-        end
-
-        return if resolved_setting # If true, allow everything
-        return unless @all_agents_config&.tools_list&.any?
-
-        forbidden = @all_agents_config.tools_list.select do |tool|
-          SwarmSDK::Swarm::ToolConfigurator::FILESYSTEM_TOOLS.include?(tool.to_sym)
-        end
-
-        return if forbidden.empty?
-
-        raise ConfigurationError,
-          "Filesystem tools are globally disabled (SwarmSDK.settings.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."
-      end
-
-      # Validate individual agent filesystem tools
-      #
-      # Raises ConfigurationError if filesystem tools are globally disabled
-      # but any agent attempts to use them.
-      #
-      # @raise [ConfigurationError] If filesystem tools are disabled and any agent has them
-      # @return [void]
-      def validate_agent_filesystem_tools
-        # Resolve the effective setting
-        resolved_setting = if @allow_filesystem_tools.nil?
-          SwarmSDK.settings.allow_filesystem_tools
-        else
-          @allow_filesystem_tools
-        end
-
-        return if resolved_setting # If true, allow everything
-
-        # Check each agent for forbidden tools
-        @agents.each do |agent_name, agent_builder_or_config|
-          # Extract tool list from either Builder or file config
-          tools_list = if agent_builder_or_config.is_a?(Hash) && agent_builder_or_config.key?(:__file_config__)
-            # File-loaded agent
-            agent_builder_or_config[:__file_config__][:tools] || []
-          elsif agent_builder_or_config.is_a?(Agent::Builder)
-            # Builder object - use tools_list method
-            agent_builder_or_config.tools_list
-          else
-            []
-          end
-
-          # Extract tool names (they might be hashes with permissions) and convert to symbols
-          tool_names = tools_list.map do |tool|
-            name = tool.is_a?(Hash) ? tool[:name] : tool
-            name.to_sym
-          end
-
-          # Find forbidden tools
-          forbidden = tool_names.select do |tool|
-            SwarmSDK::Swarm::ToolConfigurator::FILESYSTEM_TOOLS.include?(tool)
-          end
-
-          next if forbidden.empty?
-
-          raise ConfigurationError,
-            "Filesystem tools are globally disabled (SwarmSDK.settings.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."
-        end
-      end
     end
 
-    # Helper class for swarms block in DSL
-    #
-    # Provides a clean API for registering external swarms within the swarms { } block.
-    # Supports three registration methods:
-    # 1. File path: register "name", file: "./swarm.rb"
-    # 2. YAML string: register "name", yaml: "version: 2\n..."
-    # 3. Inline block: register "name" do ... end
-    #
-    # @example From file
-    #   swarms do
-    #     register "code_review", file: "./swarms/code_review.rb"
-    #   end
-    #
-    # @example From YAML string
-    #   swarms do
-    #     yaml_content = File.read("testing.yml")
-    #     register "testing", yaml: yaml_content, keep_context: false
-    #   end
-    #
-    # @example Inline block
-    #   swarms do
-    #     register "testing", keep_context: false do
-    #       id "testing_team"
-    #       name "Testing Team"
-    #       lead :tester
-    #       agent :tester do
-    #         model "gpt-4o-mini"
-    #         system "You test code"
-    #       end
-    #     end
-    #   end
-    #
-    # NOTE: SwarmRegistryBuilder is now in swarm_registry_builder.rb for Zeitwerk
+    # Helper class for swarms block in DSL (kept in this file for reference)
+    # Actual implementation is in swarm_registry_builder.rb for Zeitwerk
   end
 end