swarm_sdk 2.1.3 → 2.2.0

data/lib/swarm_sdk/swarm/agent_initializer.rb

@@ -69,16 +69,23 @@ module SwarmSDK
           agent_name: agent_name,
           swarm: @swarm,
           hook_registry: @hook_registry,
+          call_stack: @swarm.delegation_call_stack,
+          swarm_registry: @swarm.swarm_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
@@ -86,6 +93,9 @@ module SwarmSDK
         tool_configurator = ToolConfigurator.new(@swarm, @scratchpad_storage, @plugin_storages)
 
         @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)
+
           chat = create_agent_chat(name, agent_definition, tool_configurator)
           @agents[name] = chat
 
@@ -94,13 +104,159 @@ 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, @scratchpad_storage, @plugin_storages)
+
+        # Sub-pass 2a: Create delegation instances for isolated agents
+        @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 @agent_definitions.key?(delegate_base_name)
+              raise ConfigurationError,
+                "Agent '#{delegator_name}' delegates to unknown agent '#{delegate_base_name}'"
+            end
+
+            delegate_definition = @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
+        @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_base_name|
+            delegate_base_name_str = delegate_base_name.to_s
+
+            # Check if target is a registered swarm
+            if @swarm.swarm_registry&.registered?(delegate_base_name_str)
+              # Create delegation tool for swarm
+              tool = create_delegation_tool(
+                name: delegate_base_name_str,
+                description: "External swarm: #{delegate_base_name_str}",
+                delegate_chat: nil, # Swarm delegation - no direct chat
+                agent_name: delegator_name,
+                delegating_chat: delegator_chat,
+              )
+
+              delegator_chat.with_tool(tool)
+            elsif @agent_definitions.key?(delegate_base_name)
+              # Delegate to local agent
+              delegate_definition = @agent_definitions[delegate_base_name]
+
+              # Determine which chat instance to use
+              target_chat = if delegate_definition.shared_across_delegations
+                # Shared mode: use primary agent (old behavior)
+                @agents[delegate_base_name]
+              else
+                # Isolated mode: use delegation instance
+                instance_name = "#{delegate_base_name}@#{delegator_name}"
+                @swarm.delegation_instances[instance_name]
+              end
+
+              # Create delegation tool pointing to chosen instance
+              tool = create_delegation_tool(
+                name: delegate_base_name.to_s,
+                description: delegate_definition.description,
+                delegate_chat: target_chat, # ← Isolated instance OR shared primary
+                agent_name: delegator_name,
+                delegating_chat: delegator_chat,
+              )
+
+              delegator_chat.with_tool(tool)
+            else
+              raise ConfigurationError, "Agent '#{delegator_name}' delegates to unknown target '#{delegate_base_name_str}' (not a local agent or registered swarm)"
+            end
+          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 = @agent_definitions[base_name]
+
+          # Register delegation tools for THIS instance's delegates_to
+          delegate_definition.delegates_to.each do |nested_delegate_name|
+            nested_delegate_name_sym = nested_delegate_name.to_sym
+            nested_delegate_name_str = nested_delegate_name.to_s
+
+            # Check if target is a registered swarm
+            if @swarm.swarm_registry&.registered?(nested_delegate_name_str)
+              # Create delegation tool for swarm
+              nested_tool = create_delegation_tool(
+                name: nested_delegate_name_str,
+                description: "External swarm: #{nested_delegate_name_str}",
+                delegate_chat: nil, # Swarm delegation - no direct chat
+                agent_name: instance_name.to_sym,
+                delegating_chat: delegation_chat,
+              )
+
+              delegation_chat.with_tool(nested_tool)
+            elsif @agent_definitions.key?(nested_delegate_name_sym)
+              # Delegate to local agent
+              nested_definition = @agent_definitions[nested_delegate_name_sym]
+
+              # Determine target: shared primary OR isolated instance
+              target_chat = if nested_definition.shared_across_delegations
+                # Shared mode: point to primary (semaphore-protected)
+                @agents[nested_delegate_name_sym]
+              else
+                # Isolated mode: delegation instances also get isolated nested delegates
+                # Create unique instance for this delegation chain
+                nested_instance_name = "#{nested_delegate_name}@#{instance_name}"
+
+                # Check if already created in 2a (if delegator also delegates to this agent)
+                @swarm.delegation_instances[nested_instance_name] ||= create_agent_chat_for_delegation(
+                  instance_name: nested_instance_name,
+                  base_name: nested_delegate_name_sym,
+                  agent_definition: nested_definition,
+                  tool_configurator: tool_configurator,
+                )
+              end
+
+              # Create delegation tool
+              nested_tool = create_delegation_tool(
+                name: nested_delegate_name.to_s,
+                description: nested_definition.description,
+                delegate_chat: target_chat, # ← Isolated OR shared
+                agent_name: instance_name.to_sym,
+                delegating_chat: delegation_chat,
+              )
+
+              delegation_chat.with_tool(nested_tool)
+            else
+              raise ConfigurationError,
+                "Delegation instance '#{instance_name}' delegates to unknown target '#{nested_delegate_name_str}' (not a local agent or registered swarm)"
+            end
+          end
         end
       end
 
@@ -109,31 +265,46 @@ module SwarmSDK
       # 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, @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 = @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|
+          "DelegateTaskTo#{delegate_name.to_s.capitalize}"
+        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,18 +337,29 @@ 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 = @agent_definitions[base_name]
+
+        chat.setup_hooks(
+          registry: @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,
@@ -185,15 +367,30 @@ module SwarmSDK
       def pass_5_apply_yaml_hooks
         return unless @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 = @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
@@ -226,6 +423,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: @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 +478,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 = @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.with_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.with_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
 
@@ -329,6 +583,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 = @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

data/lib/swarm_sdk/swarm/all_agents_builder.rb

@@ -33,6 +33,7 @@ module SwarmSDK
         @parameters = nil
         @headers = nil
         @coding_agent = nil
+        @disable_default_tools = nil
       end
 
       # Set model for all agents
@@ -75,6 +76,15 @@ module SwarmSDK
         @coding_agent = enabled
       end
 
+      # Disable default tools for all agents
+      #
+      # @param value [Boolean, Array<Symbol>]
+      #   - true: Disable ALL default tools
+      #   - Array of symbols: Disable specific tools (e.g., [:Think, :TodoWrite])
+      def disable_default_tools(value)
+        @disable_default_tools = value
+      end
+
       # Add tools that all agents will have
       def tools(*tool_names)
         @tools_list.concat(tool_names)
@@ -92,6 +102,7 @@ module SwarmSDK
           :pre_tool_use,
           :post_tool_use,
           :user_prompt,
+          :agent_step,
           :agent_stop,
           :first_message,
           :pre_delegation,
@@ -108,7 +119,11 @@ module SwarmSDK
 
       # Configure permissions for all agents
       #
-      # @example
+      # Supports two forms:
+      # 1. Block form (DSL): permissions do ... end
+      # 2. Direct hash (internal/YAML): set_permissions_hash(hash)
+      #
+      # @example Block form
       #   permissions do
       #     Write.allow_paths "tmp/**/*"
       #     Write.deny_paths "tmp/secrets/**"
@@ -118,6 +133,17 @@ module SwarmSDK
         @permissions_config = PermissionsBuilder.build(&block)
       end
 
+      # Set permissions directly from hash (for YAML translation)
+      #
+      # This is intentionally separate from permissions() to keep the DSL clean.
+      # Called by Configuration when translating YAML permissions.
+      #
+      # @param hash [Hash] Permissions configuration hash
+      # @return [void]
+      def permissions_hash=(hash)
+        @permissions_config = hash || {}
+      end
+
       # Convert to hash for merging with agent configs
       #
       # @return [Hash] Configuration hash
@@ -131,6 +157,7 @@ module SwarmSDK
           parameters: @parameters,
           headers: @headers,
           coding_agent: @coding_agent,
+          disable_default_tools: @disable_default_tools,
           tools: @tools_list,
           permissions: @permissions_config,
         }.compact