swarm_sdk 2.1.3 → 2.2.0

data/lib/swarm_sdk/swarm/builder.rb

@@ -37,22 +37,32 @@ module SwarmSDK
       #     agent :backend { ... }
       #   end
       class << self
-        def build(&block)
-          builder = new
+        def build(allow_filesystem_tools: nil, &block)
+          builder = new(allow_filesystem_tools: allow_filesystem_tools)
           builder.instance_eval(&block)
           builder.build_swarm
         end
       end
 
-      def initialize
+      def initialize(allow_filesystem_tools: nil)
+        @swarm_id = nil
         @swarm_name = nil
         @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_enabled = true # Default: enabled
+        @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
@@ -65,11 +75,29 @@ module SwarmSDK
         @lead_agent = agent_name
       end
 
-      # Enable or disable shared scratchpad
+      # Configure scratchpad mode
+      #
+      # For NodeOrchestrator: :enabled (shared across nodes), :per_node (isolated), or :disabled
+      # For regular Swarm: :enabled or :disabled
+      #
+      # @param mode [Symbol, Boolean] Scratchpad mode
+      def scratchpad(mode)
+        @scratchpad = mode
+      end
+
+      # Register external swarms for composable swarms
+      #
+      # @example
+      #   swarms do
+      #     register "code_review", file: "./swarms/code_review.rb"
+      #     register "testing", file: "./swarms/testing.yml", keep_context: false
+      #   end
       #
-      # @param enabled [Boolean] Whether to enable scratchpad tools
-      def use_scratchpad(enabled)
-        @scratchpad_enabled = enabled
+      # @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
@@ -196,6 +224,12 @@ module SwarmSDK
       def build_swarm
         raise ConfigurationError, "Swarm name not set. Use: name 'My Swarm'" unless @swarm_name
 
+        # Validate all_agents 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)
@@ -211,6 +245,26 @@ module SwarmSDK
 
       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
@@ -310,8 +364,27 @@ module SwarmSDK
       #
       # @return [Swarm] Configured swarm instance
       def build_single_swarm
-        # Create swarm using SDK
-        swarm = Swarm.new(name: @swarm_name, scratchpad_enabled: @scratchpad_enabled)
+        # Validate swarm_id is set if external swarms are registered (required for composable swarms)
+        if @swarm_registry_config.any? && @swarm_id.nil?
+          raise ConfigurationError, "Swarm id must be set using id(...) when using composable swarms"
+        end
+
+        # Create swarm using SDK (swarm_id auto-generates if nil)
+        swarm = Swarm.new(
+          name: @swarm_name,
+          swarm_id: @swarm_id,
+          scratchpad_mode: @scratchpad,
+          allow_filesystem_tools: @allow_filesystem_tools,
+        )
+
+        # Setup swarm registry if external swarms are registered
+        if @swarm_registry_config.any?
+          registry = SwarmRegistry.new(parent_swarm_id: @swarm_id)
+          @swarm_registry_config.each do |reg|
+            registry.register(reg[:name], source: reg[:source], keep_context: reg[:keep_context])
+          end
+          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
@@ -375,13 +448,20 @@ module SwarmSDK
         end
 
         # Create node orchestrator
-        NodeOrchestrator.new(
+        orchestrator = NodeOrchestrator.new(
           swarm_name: @swarm_name,
+          swarm_id: @swarm_id,
           agent_definitions: agent_definitions,
           nodes: @nodes,
           start_node: @start_node,
-          scratchpad_enabled: @scratchpad_enabled,
+          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
@@ -582,6 +662,122 @@ 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
   end
 end

data/lib/swarm_sdk/swarm/swarm_registry_builder.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module SwarmSDK
+  class Swarm
+    # Builder for swarm registry in DSL
+    #
+    # Supports registering external swarms for composable swarms pattern.
+    #
+    # @example
+    #   swarms do
+    #     register "code_review", file: "./swarms/code_review.rb"
+    #     register "testing", file: "./swarms/testing.yml", keep_context: false
+    #   end
+    #
+    # @example Inline swarm definition
+    #   swarms do
+    #     register "tester" do
+    #       lead :tester
+    #       agent :tester do
+    #         model "gpt-4o-mini"
+    #         system "You test code"
+    #       end
+    #     end
+    #   end
+    #
+    class SwarmRegistryBuilder
+      attr_reader :registrations
+
+      def initialize
+        @registrations = []
+      end
+
+      # Register a swarm from file, YAML string, or inline block
+      #
+      # @param name [String, Symbol] Registration name
+      # @param file [String, nil] Path to swarm file (.rb or .yml)
+      # @param yaml [String, nil] YAML content string
+      # @param keep_context [Boolean] Whether to preserve conversation state (default: true)
+      # @yield Optional block for inline swarm definition
+      # @raise [ArgumentError] If neither file, yaml, nor block provided
+      def register(name, file: nil, yaml: nil, keep_context: true, &block)
+        # Validate that exactly one source is provided
+        sources = [file, yaml, block].compact
+        if sources.empty?
+          raise ArgumentError, "register '#{name}' requires either file:, yaml:, or a block"
+        elsif sources.size > 1
+          raise ArgumentError, "register '#{name}' accepts only one of: file:, yaml:, or block (got #{sources.size})"
+        end
+
+        # Determine source type and store
+        source = if file
+          { type: :file, value: file }
+        elsif yaml
+          { type: :yaml, value: yaml }
+        else
+          { type: :block, value: block }
+        end
+
+        @registrations << {
+          name: name.to_s,
+          source: source,
+          keep_context: keep_context,
+        }
+      end
+    end
+  end
+end

data/lib/swarm_sdk/swarm/tool_configurator.rb

@@ -17,10 +17,6 @@ module SwarmSDK
         :Read,
         :Grep,
         :Glob,
-        :TodoWrite,
-        :Think,
-        :WebFetch,
-        :Clock,
       ].freeze
 
       # Scratchpad tools (added if scratchpad is enabled)
@@ -30,6 +26,17 @@ module SwarmSDK
         :ScratchpadList,
       ].freeze
 
+      # Filesystem tools that can be globally disabled for security
+      FILESYSTEM_TOOLS = [
+        :Read,
+        :Write,
+        :Edit,
+        :MultiEdit,
+        :Grep,
+        :Glob,
+        :Bash,
+      ].freeze
+
       def initialize(swarm, scratchpad_storage, plugin_storages = {})
         @swarm = swarm
         @scratchpad_storage = scratchpad_storage
@@ -144,6 +151,19 @@ module SwarmSDK
       # @param agent_name [Symbol] Agent name
       # @param agent_definition [AgentDefinition] Agent definition
       def register_explicit_tools(chat, tool_configs, agent_name:, agent_definition:)
+        # Validate filesystem tools if globally disabled
+        unless @swarm.allow_filesystem_tools
+          # Extract tool names from hashes and convert to symbols for comparison
+          forbidden = tool_configs.map { |tc| tc[:name].to_sym }.select { |name| FILESYSTEM_TOOLS.include?(name) }
+          unless 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
+
         tool_configs.each do |tool_config|
           tool_name = tool_config[:name]
           permissions_config = tool_config[:permissions]
@@ -177,6 +197,9 @@ module SwarmSDK
         # Register core default tools (unless disabled)
         if agent_definition.disable_default_tools != true
           DEFAULT_TOOLS.each do |tool_name|
+            # Skip filesystem tools if globally disabled
+            next if !@swarm.allow_filesystem_tools && FILESYSTEM_TOOLS.include?(tool_name)
+
             register_tool_if_not_disabled(chat, tool_name, explicit_tool_names, agent_name, agent_definition)
           end
 
@@ -229,15 +252,21 @@ module SwarmSDK
         plugin = PluginRegistry.plugin_for_tool(tool_name)
         raise ConfigurationError, "Tool #{tool_name} is not provided by any plugin" unless plugin
 
-        # Get plugin storage for this agent
+        # V7.0: Extract base name for storage lookup (handles delegation instances)
+        # For primary agents: :tester → :tester (no change)
+        # For delegation instances: "tester@frontend" → :tester (extracts base)
+        base_name = agent_name.to_s.split("@").first.to_sym
+
+        # Get plugin storage using BASE NAME (shared across instances)
         plugin_storages = @plugin_storages[plugin.name] || {}
-        storage = plugin_storages[agent_name]
+        storage = plugin_storages[base_name] # ← Changed from agent_name to base_name
 
         # Build context for tool creation
+        # Pass full agent_name for tool state tracking (TodoWrite, ReadTracker, etc.)
         context = {
-          agent_name: agent_name,
+          agent_name: agent_name, # Full instance name for tool's use
           directory: directory,
-          storage: storage,
+          storage: storage, # Shared storage by base name
           agent_definition: agent_definition,
           chat: chat,
           tool_configurator: self,
@@ -303,15 +332,21 @@ module SwarmSDK
       def tool_disabled?(tool_name, disable_config)
         return false if disable_config.nil?
 
+        # Normalize tool_name to symbol for comparison
+        tool_name_sym = tool_name.to_sym
+
         if disable_config == true
           # Disable all default tools
           true
         elsif disable_config.is_a?(Symbol)
           # Single tool name
-          disable_config == tool_name
+          disable_config == tool_name_sym
+        elsif disable_config.is_a?(String)
+          # Single tool name as string (from YAML)
+          disable_config.to_sym == tool_name_sym
         elsif disable_config.is_a?(Array)
-          # Disable only tools in the array
-          disable_config.include?(tool_name)
+          # Disable only tools in the array - normalize to symbols for comparison
+          disable_config.map(&:to_sym).include?(tool_name_sym)
         else
           false
         end