swarm_memory 2.1.2 → 2.1.4

data/lib/swarm_sdk/swarm/agent_initializer.rb

@@ -14,16 +14,11 @@ module SwarmSDK
     # This encapsulates the complex initialization logic that was previously
     # embedded in Swarm#initialize_agents.
     class AgentInitializer
-      # rubocop:disable Metrics/ParameterLists
-      def initialize(swarm, agent_definitions, global_semaphore, hook_registry, scratchpad_storage, plugin_storages, config_for_hooks: nil)
-        # rubocop:enable Metrics/ParameterLists
+      # Initialize with swarm reference (all data accessible via swarm)
+      #
+      # @param swarm [Swarm] The parent swarm instance
+      def initialize(swarm)
         @swarm = swarm
-        @agent_definitions = agent_definitions
-        @global_semaphore = global_semaphore
-        @hook_registry = hook_registry
-        @scratchpad_storage = scratchpad_storage
-        @plugin_storages = plugin_storages
-        @config_for_hooks = config_for_hooks
         @agents = {}
         @agent_contexts = {}
       end
@@ -51,6 +46,39 @@ module SwarmSDK
       # Provide access to agent contexts for Swarm
       attr_reader :agent_contexts
 
+      # Initialize a single agent in isolation (for observer agents)
+      #
+      # Creates an isolated agent chat without delegation tools,
+      # suitable for observer agents that don't need to delegate.
+      # Reuses existing create_agent_chat infrastructure.
+      #
+      # @param agent_name [Symbol] Name of agent to initialize
+      # @return [Agent::Chat] Isolated agent chat instance
+      # @raise [ConfigurationError] If agent not found
+      #
+      # @example
+      #   initializer = AgentInitializer.new(swarm)
+      #   chat = initializer.initialize_isolated_agent(:profiler)
+      #   chat.ask("Analyze this prompt")
+      def initialize_isolated_agent(agent_name)
+        agent_def = @swarm.agent_definitions[agent_name]
+        raise ConfigurationError, "Agent '#{agent_name}' not found" unless agent_def
+
+        # Ensure plugin storages are created (needed by ToolConfigurator)
+        create_plugin_storages if @swarm.plugin_storages.empty?
+
+        # Reuse existing create_agent_chat infrastructure
+        tool_configurator = ToolConfigurator.new(
+          @swarm,
+          @swarm.scratchpad_storage,
+          @swarm.plugin_storages,
+        )
+
+        # Create chat using same method as pass_1_create_agents
+        # This gives us full tool setup, MCP servers, etc.
+        create_agent_chat(agent_name, agent_def, tool_configurator)
+      end
+
       # Create a tool that delegates work to another agent
       #
       # This method is public for testing delegation from Swarm.
@@ -68,24 +96,31 @@ module SwarmSDK
           delegate_chat: delegate_chat,
           agent_name: agent_name,
           swarm: @swarm,
-          hook_registry: @hook_registry,
           delegating_chat: delegating_chat,
         )
       end
 
       private
 
-      # Pass 1: Create all agent chat instances
+      # Pass 1: Create primary agent chat instances
       #
-      # This creates the Agent::Chat instances but doesn't wire them together yet.
-      # Each agent gets its own chat instance with configured tools.
+      # Only creates agents that will actually be used as primaries:
+      # - The lead agent
+      # - Agents with shared_across_delegations: true (shared delegates)
+      # - Agents not used as delegates (standalone agents)
+      #
+      # Agents that are ONLY delegates with shared_across_delegations: false
+      # are NOT created here - they'll be created as delegation instances in pass 2a.
       def pass_1_create_agents
         # Create plugin storages for agents
         create_plugin_storages
 
-        tool_configurator = ToolConfigurator.new(@swarm, @scratchpad_storage, @plugin_storages)
+        tool_configurator = ToolConfigurator.new(@swarm, @swarm.scratchpad_storage, @swarm.plugin_storages)
+
+        @swarm.agent_definitions.each do |name, agent_definition|
+          # Skip if this agent will only exist as delegation instances
+          next if should_skip_primary_creation?(name, agent_definition)
 
-        @agent_definitions.each do |name, agent_definition|
           chat = create_agent_chat(name, agent_definition, tool_configurator)
           @agents[name] = chat
 
@@ -94,46 +129,228 @@ module SwarmSDK
         end
       end
 
-      # Pass 2: Register agent delegation tools
+      # Pass 2: Create delegation instances and wire delegation tools
       #
-      # Now that all agents exist, we can create delegation tools
-      # that allow agents to call each other.
+      # This pass has three sub-steps that must happen in order:
+      # 2a. Create delegation instances (ONLY for agents with shared_across_delegations: false)
+      # 2b. Wire primary agents to delegation instances OR shared primaries
+      # 2c. Wire delegation instances to their delegates (nested delegation support)
       def pass_2_register_delegation_tools
-        @agent_definitions.each do |name, agent_definition|
-          register_delegation_tools(@agents[name], agent_definition.delegates_to, agent_name: name)
+        tool_configurator = ToolConfigurator.new(@swarm, @swarm.scratchpad_storage, @swarm.plugin_storages)
+
+        # Sub-pass 2a: Create delegation instances for isolated agents
+        @swarm.agent_definitions.each do |delegator_name, delegator_def|
+          delegator_def.delegates_to.each do |delegate_base_name|
+            delegate_base_name = delegate_base_name.to_sym
+
+            unless @swarm.agent_definitions.key?(delegate_base_name)
+              raise ConfigurationError,
+                "Agent '#{delegator_name}' delegates to unknown agent '#{delegate_base_name}'"
+            end
+
+            delegate_definition = @swarm.agent_definitions[delegate_base_name]
+
+            # Check isolation mode of the DELEGATE agent
+            # If delegate wants to be shared, skip instance creation (use primary)
+            next if delegate_definition.shared_across_delegations
+
+            # Create unique delegation instance (isolated mode)
+            instance_name = "#{delegate_base_name}@#{delegator_name}"
+
+            # V7.0: Use existing register_all_tools (no new method needed!)
+            delegation_chat = create_agent_chat_for_delegation(
+              instance_name: instance_name,
+              base_name: delegate_base_name,
+              agent_definition: delegate_definition,
+              tool_configurator: tool_configurator,
+            )
+
+            # Store in delegation_instances hash
+            @swarm.delegation_instances[instance_name] = delegation_chat
+          end
+        end
+
+        # Sub-pass 2b: Wire primary agents to delegation instances OR shared primaries OR registered swarms
+        @swarm.agent_definitions.each do |delegator_name, delegator_def|
+          delegator_chat = @agents[delegator_name]
+
+          # Skip if delegator doesn't exist as primary (wasn't created in pass_1)
+          next unless delegator_chat
+
+          delegator_def.delegates_to.each do |delegate_name|
+            wire_delegation(
+              delegator_name: delegator_name,
+              delegator_chat: delegator_chat,
+              delegate_name: delegate_name,
+              tool_configurator: tool_configurator,
+              create_nested_instances: false,
+            )
+          end
+        end
+
+        # Sub-pass 2c: Wire delegation instances to their delegates (nested delegation)
+        # Convert to array first to avoid "can't add key during iteration" error
+        @swarm.delegation_instances.to_a.each do |instance_name, delegation_chat|
+          base_name = extract_base_name(instance_name)
+          delegate_definition = @swarm.agent_definitions[base_name]
+
+          # Register delegation tools for THIS instance's delegates_to
+          delegate_definition.delegates_to.each do |nested_delegate_name|
+            wire_delegation(
+              delegator_name: instance_name.to_sym,
+              delegator_chat: delegation_chat,
+              delegate_name: nested_delegate_name,
+              tool_configurator: tool_configurator,
+              create_nested_instances: true,
+            )
+          end
         end
       end
 
+      # Wire a single delegation from one agent/instance to a delegate
+      #
+      # This is the unified logic for delegation wiring used by both:
+      # - Sub-pass 2b: Primary agents → delegates
+      # - Sub-pass 2c: Delegation instances → nested delegates
+      #
+      # @param delegator_name [Symbol, String] Name of the agent doing the delegating
+      # @param delegator_chat [Agent::Chat] Chat instance of the delegator
+      # @param delegate_name [Symbol, String] Name of the delegate target
+      # @param tool_configurator [ToolConfigurator] Tool configuration helper
+      # @param create_nested_instances [Boolean] Whether to create new instances for nested delegation
+      # @return [void]
+      def wire_delegation(delegator_name:, delegator_chat:, delegate_name:, tool_configurator:, create_nested_instances:)
+        delegate_name_str = delegate_name.to_s
+        delegate_name_sym = delegate_name.to_sym
+
+        # Check if target is a registered swarm
+        if @swarm.swarm_registry&.registered?(delegate_name_str)
+          wire_swarm_delegation(delegator_name, delegator_chat, delegate_name_str)
+        elsif @swarm.agent_definitions.key?(delegate_name_sym)
+          wire_agent_delegation(
+            delegator_name: delegator_name,
+            delegator_chat: delegator_chat,
+            delegate_name_sym: delegate_name_sym,
+            tool_configurator: tool_configurator,
+            create_nested_instances: create_nested_instances,
+          )
+        else
+          raise ConfigurationError,
+            "Agent '#{delegator_name}' delegates to unknown target '#{delegate_name_str}' (not a local agent or registered swarm)"
+        end
+      end
+
+      # Wire delegation to an external swarm
+      #
+      # @param delegator_name [Symbol, String] Name of the delegating agent
+      # @param delegator_chat [Agent::Chat] Chat instance of the delegator
+      # @param swarm_name [String] Name of the registered swarm
+      # @return [void]
+      def wire_swarm_delegation(delegator_name, delegator_chat, swarm_name)
+        tool = create_delegation_tool(
+          name: swarm_name,
+          description: "External swarm: #{swarm_name}",
+          delegate_chat: nil, # Swarm delegation - no direct chat
+          agent_name: delegator_name,
+          delegating_chat: delegator_chat,
+        )
+
+        delegator_chat.add_tool(tool)
+      end
+
+      # Wire delegation to a local agent
+      #
+      # Determines whether to use shared primary or isolated instance based on
+      # the delegate's shared_across_delegations setting.
+      #
+      # @param delegator_name [Symbol, String] Name of the delegating agent
+      # @param delegator_chat [Agent::Chat] Chat instance of the delegator
+      # @param delegate_name_sym [Symbol] Name of the delegate agent
+      # @param tool_configurator [ToolConfigurator] Tool configuration helper
+      # @param create_nested_instances [Boolean] Whether to create new instances if not found
+      # @return [void]
+      def wire_agent_delegation(delegator_name:, delegator_chat:, delegate_name_sym:, tool_configurator:, create_nested_instances:)
+        delegate_definition = @swarm.agent_definitions[delegate_name_sym]
+
+        # Determine which chat instance to use
+        target_chat = if delegate_definition.shared_across_delegations
+          # Shared mode: use primary agent (semaphore-protected)
+          @agents[delegate_name_sym]
+        else
+          # Isolated mode: use delegation instance
+          instance_name = "#{delegate_name_sym}@#{delegator_name}"
+
+          if create_nested_instances
+            # For nested delegation: create if not exists
+            @swarm.delegation_instances[instance_name] ||= create_agent_chat_for_delegation(
+              instance_name: instance_name,
+              base_name: delegate_name_sym,
+              agent_definition: delegate_definition,
+              tool_configurator: tool_configurator,
+            )
+          else
+            # For primary delegation: instance was pre-created in 2a
+            @swarm.delegation_instances[instance_name]
+          end
+        end
+
+        # Create delegation tool pointing to chosen instance
+        tool = create_delegation_tool(
+          name: delegate_name_sym.to_s,
+          description: delegate_definition.description,
+          delegate_chat: target_chat,
+          agent_name: delegator_name,
+          delegating_chat: delegator_chat,
+        )
+
+        delegator_chat.add_tool(tool)
+      end
+
       # Pass 3: Setup agent contexts
       #
       # Create Agent::Context for each agent to track delegations and metadata.
       # This is needed regardless of whether logging is enabled.
       def pass_3_setup_contexts
+        # Setup contexts for PRIMARY agents
         @agents.each do |agent_name, chat|
-          agent_definition = @agent_definitions[agent_name]
-          delegate_tool_names = agent_definition.delegates_to.map do |delegate_name|
-            "DelegateTaskTo#{delegate_name.to_s.capitalize}"
-          end
+          setup_agent_context(agent_name, @swarm.agent_definitions[agent_name], chat, is_delegation: false)
+        end
 
-          # Create agent context
-          context = Agent::Context.new(
-            name: agent_name,
-            delegation_tools: delegate_tool_names,
-            metadata: {},
-          )
-          @agent_contexts[agent_name] = context
+        # Setup contexts for DELEGATION instances
+        @swarm.delegation_instances.each do |instance_name, chat|
+          base_name = extract_base_name(instance_name)
+          agent_definition = @swarm.agent_definitions[base_name]
+          setup_agent_context(instance_name.to_sym, agent_definition, chat, is_delegation: true)
+        end
+      end
+
+      # Setup context for an agent (primary or delegation instance)
+      def setup_agent_context(agent_name, agent_definition, chat, is_delegation: false)
+        delegate_tool_names = agent_definition.delegates_to.map do |delegate_name|
+          Tools::Delegate.tool_name_for(delegate_name)
+        end
 
-          # Always set agent context (needed for delegation tracking)
-          chat.setup_context(context) if chat.respond_to?(:setup_context)
+        context = Agent::Context.new(
+          name: agent_name,
+          swarm_id: @swarm.swarm_id,
+          parent_swarm_id: @swarm.parent_swarm_id,
+          delegation_tools: delegate_tool_names,
+          metadata: { is_delegation_instance: is_delegation },
+        )
 
-          # Configure logging callbacks if logging is enabled
-          next unless LogStream.emitter
+        # Store context (only for primaries)
+        @agent_contexts[agent_name] = context unless is_delegation
 
-          chat.setup_logging if chat.respond_to?(:setup_logging)
+        # Always set agent context on chat
+        chat.setup_context(context) if chat.respond_to?(:setup_context)
 
-          # Emit validation warnings for this agent
-          emit_validation_warnings(agent_name, agent_definition)
-        end
+        # Configure logging if enabled
+        return unless LogStream.emitter
+
+        chat.setup_logging if chat.respond_to?(:setup_logging)
+
+        # Emit validation warnings (only for primaries, not each delegation instance)
+        emit_validation_warnings(agent_name, agent_definition) unless is_delegation
       end
 
       # Emit validation warnings as log events
@@ -166,34 +383,60 @@ module SwarmSDK
       #
       # Setup the callback system for each agent, integrating with RubyLLM callbacks.
       def pass_4_configure_hooks
+        # Configure hooks for PRIMARY agents
         @agents.each do |agent_name, chat|
-          agent_definition = @agent_definitions[agent_name]
+          configure_hooks_for_agent(agent_name, chat)
+        end
 
-          # Configure callback system (integrates with RubyLLM callbacks)
-          chat.setup_hooks(
-            registry: @hook_registry,
-            agent_definition: agent_definition,
-            swarm: @swarm,
-          ) if chat.respond_to?(:setup_hooks)
+        # Configure hooks for DELEGATION instances
+        @swarm.delegation_instances.each do |instance_name, chat|
+          configure_hooks_for_agent(instance_name.to_sym, chat)
         end
       end
 
+      # Configure hooks for an agent (primary or delegation instance)
+      def configure_hooks_for_agent(agent_name, chat)
+        base_name = extract_base_name(agent_name)
+        agent_definition = @swarm.agent_definitions[base_name]
+
+        chat.setup_hooks(
+          registry: @swarm.hook_registry,
+          agent_definition: agent_definition,
+          swarm: @swarm,
+        ) if chat.respond_to?(:setup_hooks)
+      end
+
       # Pass 5: Apply YAML hooks
       #
       # If the swarm was loaded from YAML with agent-specific hooks,
       # apply them now via HooksAdapter.
       def pass_5_apply_yaml_hooks
-        return unless @config_for_hooks
+        return unless @swarm.config_for_hooks
 
+        # Apply YAML hooks to PRIMARY agents
         @agents.each do |agent_name, chat|
-          agent_def = @config_for_hooks.agents[agent_name]
-          next unless agent_def&.hooks
+          apply_yaml_hooks_for_agent(agent_name, chat)
+        end
 
-          # Apply agent-specific hooks via Hooks::Adapter
-          Hooks::Adapter.apply_agent_hooks(chat, agent_name, agent_def.hooks, @swarm.name)
+        # Apply YAML hooks to DELEGATION instances
+        @swarm.delegation_instances.each do |instance_name, chat|
+          apply_yaml_hooks_for_agent(instance_name.to_sym, chat)
         end
       end
 
+      # Apply YAML hooks for an agent (primary or delegation instance)
+      def apply_yaml_hooks_for_agent(agent_name, chat)
+        base_name = extract_base_name(agent_name)
+        agent_config = @swarm.config_for_hooks.agents[base_name]
+        return unless agent_config
+
+        # Configuration.agents now returns hashes, not Definitions
+        hooks = agent_config.is_a?(Hash) ? agent_config[:hooks] : agent_config.hooks
+        return unless hooks&.any?
+
+        Hooks::Adapter.apply_agent_hooks(chat, agent_name, hooks, @swarm.name)
+      end
+
       # Create Agent::Chat instance with rate limiting
       #
       # @param agent_name [Symbol] Agent name
@@ -204,7 +447,7 @@ module SwarmSDK
         chat = Agent::Chat.new(
           definition: agent_definition.to_h,
           agent_name: agent_name,
-          global_semaphore: @global_semaphore,
+          global_semaphore: @swarm.global_semaphore,
         )
 
         # Set agent name on provider for logging (if provider supports it)
@@ -226,6 +469,50 @@ module SwarmSDK
         chat
       end
 
+      # Create a delegation-specific instance of an agent
+      #
+      # V7.0: Simplified - just calls register_all_tools with instance_name
+      #
+      # @param instance_name [String] Unique instance name ("base@delegator")
+      # @param base_name [Symbol] Base agent name (for definition lookup)
+      # @param agent_definition [Agent::Definition] Base agent definition
+      # @param tool_configurator [ToolConfigurator] Shared tool configurator
+      # @return [Agent::Chat] Delegation-specific chat instance
+      def create_agent_chat_for_delegation(instance_name:, base_name:, agent_definition:, tool_configurator:)
+        # Create chat with instance_name for isolated conversation + tool state
+        chat = Agent::Chat.new(
+          definition: agent_definition.to_h,
+          agent_name: instance_name.to_sym, # Full instance name for isolation
+          global_semaphore: @swarm.global_semaphore,
+        )
+
+        # Set provider agent name for logging
+        chat.provider.agent_name = instance_name if chat.provider.respond_to?(:agent_name=)
+
+        # V7.0 SIMPLIFIED: Just call register_all_tools with instance_name!
+        # Base name extraction happens automatically in create_plugin_tool
+        tool_configurator.register_all_tools(
+          chat: chat,
+          agent_name: instance_name.to_sym,
+          agent_definition: agent_definition,
+        )
+
+        # Register MCP servers (tracked by instance_name automatically)
+        if agent_definition.mcp_servers.any?
+          mcp_configurator = McpConfigurator.new(@swarm)
+          mcp_configurator.register_mcp_servers(
+            chat,
+            agent_definition.mcp_servers,
+            agent_name: instance_name,
+          )
+        end
+
+        # Notify plugins (use instance_name, plugins extract base_name if needed)
+        notify_plugins_agent_initialized(instance_name.to_sym, chat, agent_definition, tool_configurator)
+
+        chat
+      end
+
       # Register agent delegation tools
       #
       # Creates delegation tools that allow one agent to call another.
@@ -237,25 +524,38 @@ module SwarmSDK
         return if delegate_names.empty?
 
         delegate_names.each do |delegate_name|
-          delegate_name = delegate_name.to_sym
-
-          unless @agents.key?(delegate_name)
-            raise ConfigurationError, "Agent delegates to unknown agent '#{delegate_name}'"
-          end
-
-          # Create a tool that delegates to the specified agent
-          delegate_agent = @agents[delegate_name]
-          delegate_definition = @agent_definitions[delegate_name]
+          delegate_name_sym = delegate_name.to_sym
+          delegate_name_str = delegate_name.to_s
+
+          # Check if target is a local agent
+          if @agents.key?(delegate_name_sym)
+            # Delegate to local agent
+            delegate_agent = @agents[delegate_name_sym]
+            delegate_definition = @swarm.agent_definitions[delegate_name_sym]
+
+            tool = create_delegation_tool(
+              name: delegate_name_str,
+              description: delegate_definition.description,
+              delegate_chat: delegate_agent,
+              agent_name: agent_name,
+              delegating_chat: chat,
+            )
 
-          tool = create_delegation_tool(
-            name: delegate_name.to_s,
-            description: delegate_definition.description,
-            delegate_chat: delegate_agent,
-            agent_name: agent_name,
-            delegating_chat: chat,
-          )
+            chat.add_tool(tool)
+          elsif @swarm.swarm_registry&.registered?(delegate_name_str)
+            # Delegate to registered swarm
+            tool = create_delegation_tool(
+              name: delegate_name_str,
+              description: "External swarm: #{delegate_name_str}",
+              delegate_chat: nil, # Swarm delegation - no direct chat
+              agent_name: agent_name,
+              delegating_chat: chat,
+            )
 
-          chat.with_tool(tool)
+            chat.add_tool(tool)
+          else
+            raise ConfigurationError, "Agent '#{agent_name}' delegates to unknown target '#{delegate_name_str}' (not a local agent or registered swarm)"
+          end
         end
       end
 
@@ -267,7 +567,7 @@ module SwarmSDK
       # @return [void]
       def create_plugin_storages
         PluginRegistry.all.each do |plugin|
-          @agent_definitions.each do |agent_name, agent_definition|
+          @swarm.agent_definitions.each do |agent_name, agent_definition|
             # Check if this plugin needs storage for this agent
             next unless plugin.storage_enabled?(agent_definition)
 
@@ -282,25 +582,23 @@ module SwarmSDK
             storage = plugin.create_storage(agent_name: agent_name, config: parsed_config)
 
             # Store in plugin_storages: { plugin_name => { agent_name => storage } }
-            @plugin_storages[plugin.name] ||= {}
-            @plugin_storages[plugin.name][agent_name] = storage
+            @swarm.plugin_storages[plugin.name] ||= {}
+            @swarm.plugin_storages[plugin.name][agent_name] = storage
           end
         end
       end
 
       # Get plugin-specific config from agent definition
       #
-      # Plugins can store their config in agent definition under their plugin name.
-      # E.g., memory plugin looks for `agent_definition.memory`
+      # Uses the generic plugin_configs accessor to retrieve plugin-specific config.
+      # E.g., memory plugin config is accessed via `agent_definition.plugin_config(:memory)`
       #
       # @param agent_definition [Agent::Definition] Agent definition
       # @param plugin_name [Symbol] Plugin name
       # @return [Object, nil] Plugin config or nil
       def get_plugin_config(agent_definition, plugin_name)
-        # Try to call method named after plugin (e.g., .memory for :memory plugin)
-        if agent_definition.respond_to?(plugin_name)
-          agent_definition.public_send(plugin_name)
-        end
+        # Use generic plugin config accessor
+        agent_definition.plugin_config(plugin_name)
       end
 
       # Notify all plugins that an agent was initialized
@@ -315,7 +613,7 @@ module SwarmSDK
       def notify_plugins_agent_initialized(agent_name, chat, agent_definition, tool_configurator)
         PluginRegistry.all.each do |plugin|
           # Get plugin storage for this agent (if any)
-          plugin_storages = @plugin_storages[plugin.name] || {}
+          plugin_storages = @swarm.plugin_storages[plugin.name] || {}
           storage = plugin_storages[agent_name]
 
           # Build context for plugin
@@ -329,6 +627,57 @@ module SwarmSDK
           plugin.on_agent_initialized(agent_name: agent_name, agent: chat, context: context)
         end
       end
+
+      # Determine if we should skip creating a primary agent
+      #
+      # Skip if:
+      # - NOT the lead agent, AND
+      # - Has shared_across_delegations: false (isolated mode), AND
+      # - Is only referenced as a delegate (not used standalone)
+      #
+      # @param name [Symbol] Agent name
+      # @param agent_definition [Agent::Definition] Agent definition
+      # @return [Boolean] True if should skip primary creation
+      def should_skip_primary_creation?(name, agent_definition)
+        # Always create lead agent
+        return false if name == @swarm.lead_agent
+
+        # If shared mode, create primary (delegates will use it)
+        return false if agent_definition.shared_across_delegations
+
+        # Skip if only used as a delegate
+        only_referenced_as_delegate?(name)
+      end
+
+      # Check if an agent is only referenced as a delegate
+      #
+      # @param name [Symbol] Agent name
+      # @return [Boolean] True if only referenced as delegate
+      def only_referenced_as_delegate?(name)
+        # Check if any agent delegates to this one
+        referenced_as_delegate = @swarm.agent_definitions.any? do |_agent_name, definition|
+          definition.delegates_to.include?(name)
+        end
+
+        # Skip if referenced as delegate (and not lead, already checked above)
+        referenced_as_delegate
+      end
+
+      # Extract base agent name from instance name
+      #
+      # @param instance_name [Symbol, String] Instance name (may be delegation instance)
+      # @return [Symbol] Base agent name
+      def extract_base_name(instance_name)
+        instance_name.to_s.split("@").first.to_sym
+      end
+
+      # Check if instance name is a delegation instance
+      #
+      # @param instance_name [Symbol, String] Instance name
+      # @return [Boolean] True if delegation instance (contains '@')
+      def delegation_instance?(instance_name)
+        instance_name.to_s.include?("@")
+      end
     end
   end
 end