swarm_sdk 2.2.0 → 2.4.0

data/lib/swarm_sdk/tools/registry.rb

@@ -5,24 +5,51 @@ module SwarmSDK
     # Registry for built-in SwarmSDK tools
     #
     # Maps tool names (symbols) to their RubyLLM::Tool classes.
-    # Provides validation and lookup functionality for tool registration.
+    # Provides validation, lookup, and factory functionality for tool registration.
+    #
+    # ## Tool Creation Pattern
+    #
+    # Tools register themselves with their creation requirements via the `tool_factory` method.
+    # This eliminates the need for a giant case statement in ToolConfigurator.
+    #
+    # Tools fall into three categories:
+    # 1. **No params**: Simple tools with no initialization requirements (Think, Clock)
+    # 2. **Directory only**: Tools needing working directory (Bash, Grep, Glob)
+    # 3. **Agent context**: Tools needing agent tracking (Read, Write, Edit, MultiEdit)
+    # 4. **Scratchpad**: Tools needing scratchpad storage instance
+    #
+    # @example Adding a new tool with creation requirements
+    #   # In the tool class:
+    #   class MyTool < RubyLLM::Tool
+    #     def self.creation_requirements
+    #       [:agent_name, :directory]
+    #     end
+    #   end
+    #
+    #   # In registry:
+    #   BUILTIN_TOOLS = {
+    #     MyTool: SwarmSDK::Tools::MyTool,
+    #   }
     #
     # Note: Plugin-provided tools (e.g., memory tools) are NOT in this registry.
     # They are registered via SwarmSDK::PluginRegistry instead.
     class Registry
       # All available built-in tools
+      #
+      # Maps tool names to their classes. The class must respond to `creation_requirements`
+      # to specify what parameters are needed for instantiation.
       BUILTIN_TOOLS = {
-        Read: :special, # Requires agent context for read tracking
-        Write: :special, # Requires agent context for read-before-write enforcement
-        Edit: :special, # Requires agent context for read-before-edit enforcement
+        Read: SwarmSDK::Tools::Read,
+        Write: SwarmSDK::Tools::Write,
+        Edit: SwarmSDK::Tools::Edit,
+        MultiEdit: SwarmSDK::Tools::MultiEdit,
         Bash: SwarmSDK::Tools::Bash,
         Grep: SwarmSDK::Tools::Grep,
         Glob: SwarmSDK::Tools::Glob,
-        MultiEdit: :special, # Requires agent context for read-before-edit enforcement
-        TodoWrite: :special, # Requires agent context for todo tracking
-        ScratchpadWrite: :special, # Requires scratchpad storage instance
-        ScratchpadRead: :special, # Requires scratchpad storage instance
-        ScratchpadList: :special, # Requires scratchpad storage instance
+        TodoWrite: SwarmSDK::Tools::TodoWrite,
+        ScratchpadWrite: :scratchpad, # Requires scratchpad storage instance
+        ScratchpadRead: :scratchpad,  # Requires scratchpad storage instance
+        ScratchpadList: :scratchpad,  # Requires scratchpad storage instance
         Think: SwarmSDK::Tools::Think,
         WebFetch: SwarmSDK::Tools::WebFetch,
         Clock: SwarmSDK::Tools::Clock,
@@ -35,12 +62,49 @@ module SwarmSDK
         # They are managed by SwarmSDK::PluginRegistry instead.
         #
         # @param name [Symbol, String] Tool name
-        # @return [Class, Symbol, nil] Tool class, :special, or nil if not found
+        # @return [Class, Symbol, nil] Tool class, :scratchpad marker, or nil if not found
         def get(name)
           name_sym = name.to_sym
           BUILTIN_TOOLS[name_sym]
         end
 
+        # Create a tool instance using the Factory Pattern
+        #
+        # Uses the tool's `creation_requirements` class method to determine
+        # what parameters to pass to the constructor.
+        #
+        # @param name [Symbol, String] Tool name
+        # @param context [Hash] Available context for tool creation
+        # @option context [Symbol] :agent_name Agent identifier
+        # @option context [String] :directory Agent's working directory
+        # @option context [Object] :scratchpad_storage Scratchpad storage instance
+        # @return [RubyLLM::Tool] Instantiated tool
+        # @raise [ConfigurationError] If tool is unknown or has unmet requirements
+        def create(name, context = {})
+          name_sym = name.to_sym
+          tool_entry = BUILTIN_TOOLS[name_sym]
+
+          raise ConfigurationError, "Unknown tool: #{name}" unless tool_entry
+
+          # Handle scratchpad tools specially (they use factory methods)
+          if tool_entry == :scratchpad
+            return create_scratchpad_tool(name_sym, context[:scratchpad_storage])
+          end
+
+          # Get the tool class and its requirements
+          tool_class = tool_entry
+
+          # Check if tool defines creation requirements
+          if tool_class.respond_to?(:creation_requirements)
+            requirements = tool_class.creation_requirements
+            params = extract_params(requirements, context, name)
+            tool_class.new(**params)
+          else
+            # No requirements - simple instantiation
+            tool_class.new
+          end
+        end
+
         # Get multiple tool classes by names
         #
         # @param names [Array<Symbol, String>] Tool names
@@ -87,6 +151,54 @@ module SwarmSDK
         def validate(names)
           names.reject { |name| exists?(name) }
         end
+
+        private
+
+        # Extract required parameters from context
+        #
+        # @param requirements [Array<Symbol>] Required parameter names
+        # @param context [Hash] Available context
+        # @param tool_name [Symbol] Tool name for error messages
+        # @return [Hash] Parameters to pass to tool constructor
+        # @raise [ConfigurationError] If required parameter is missing
+        def extract_params(requirements, context, tool_name)
+          params = {}
+
+          requirements.each do |req|
+            unless context.key?(req)
+              raise ConfigurationError,
+                "Tool #{tool_name} requires #{req} but it was not provided in context"
+            end
+
+            params[req] = context[req]
+          end
+
+          params
+        end
+
+        # Create a scratchpad tool using its factory method
+        #
+        # @param name [Symbol] Scratchpad tool name
+        # @param storage [Object] Scratchpad storage instance
+        # @return [RubyLLM::Tool] Instantiated scratchpad tool
+        # @raise [ConfigurationError] If storage is not provided
+        def create_scratchpad_tool(name, storage)
+          unless storage
+            raise ConfigurationError,
+              "Scratchpad tool #{name} requires scratchpad_storage in context"
+          end
+
+          case name
+          when :ScratchpadWrite
+            Tools::Scratchpad::ScratchpadWrite.create_for_scratchpad(storage)
+          when :ScratchpadRead
+            Tools::Scratchpad::ScratchpadRead.create_for_scratchpad(storage)
+          when :ScratchpadList
+            Tools::Scratchpad::ScratchpadList.create_for_scratchpad(storage)
+          else
+            raise ConfigurationError, "Unknown scratchpad tool: #{name}"
+          end
+        end
       end
     end
   end

data/lib/swarm_sdk/tools/stores/scratchpad_storage.rb

@@ -15,10 +15,13 @@ module SwarmSDK
       # Use for temporary, cross-agent communication within a single session.
       class ScratchpadStorage < Storage
         # Initialize scratchpad storage (always volatile)
-        def initialize
+        #
+        # @param total_size_limit [Integer, nil] Maximum total size in bytes (defaults to Defaults::Storage::TOTAL_SIZE_BYTES)
+        def initialize(total_size_limit: nil)
           super() # Initialize parent Storage class
           @entries = {}
           @total_size = 0
+          @total_size_limit = total_size_limit || SwarmSDK.config.scratchpad_total_size_limit
           @mutex = Mutex.new
         end
 
@@ -38,8 +41,9 @@ module SwarmSDK
             content_size = content.bytesize
 
             # Check entry size limit
-            if content_size > MAX_ENTRY_SIZE
-              raise ArgumentError, "Content exceeds maximum size (#{format_bytes(MAX_ENTRY_SIZE)}). " \
+            entry_size_limit = SwarmSDK.config.scratchpad_entry_size_limit
+            if content_size > entry_size_limit
+              raise ArgumentError, "Content exceeds maximum size (#{format_bytes(entry_size_limit)}). " \
                 "Current: #{format_bytes(content_size)}"
             end
 
@@ -49,8 +53,8 @@ module SwarmSDK
             new_total_size = @total_size - existing_size + content_size
 
             # Check total size limit
-            if new_total_size > MAX_TOTAL_SIZE
-              raise ArgumentError, "Scratchpad full (#{format_bytes(MAX_TOTAL_SIZE)} limit). " \
+            if new_total_size > @total_size_limit
+              raise ArgumentError, "Scratchpad full (#{format_bytes(@total_size_limit)} limit). " \
                 "Current: #{format_bytes(@total_size)}, " \
                 "Would be: #{format_bytes(new_total_size)}. " \
                 "Clear old entries or use smaller content."

data/lib/swarm_sdk/tools/stores/storage.rb

@@ -14,12 +14,6 @@ module SwarmSDK
       # - Search capabilities: Glob patterns and grep-style content search
       # - Thread-safe: Mutex-protected operations
       class Storage
-        # Maximum size per entry (3MB)
-        MAX_ENTRY_SIZE = 3_000_000
-
-        # Maximum total storage size (100GB)
-        MAX_TOTAL_SIZE = 100_000_000_000
-
         # Represents a single storage entry with metadata
         Entry = Struct.new(:content, :title, :updated_at, :size, keyword_init: true)
 

data/lib/swarm_sdk/tools/todo_write.rb

@@ -7,6 +7,13 @@ module SwarmSDK
     # This tool helps agents track progress on complex multi-step tasks.
     # Each agent maintains its own independent todo list.
     class TodoWrite < RubyLLM::Tool
+      # Factory pattern: declare what parameters this tool needs for instantiation
+      class << self
+        def creation_requirements
+          [:agent_name]
+        end
+      end
+
       description <<~DESC
         Use this tool to create and manage a structured task list for your current work session. This helps you track progress, organize complex tasks, and demonstrate thoroughness to the user.
         It also helps the user understand the progress of the task and overall progress of their requests.

data/lib/swarm_sdk/tools/web_fetch.rb

@@ -11,7 +11,6 @@ module SwarmSDK
         super()
         @cache = {}
         @cache_ttl = 900 # 15 minutes in seconds
-        @llm_enabled = SwarmSDK.settings.webfetch_llm_enabled?
       end
 
       def name
@@ -51,16 +50,18 @@ module SwarmSDK
         desc: "The prompt to run on the fetched content. Required when SwarmSDK is configured with webfetch_provider and webfetch_model. Optional otherwise (ignored if LLM processing not configured).",
         required: false
 
-      MAX_CONTENT_LENGTH = 100_000 # characters
+      # NOTE: Content length and timeout now accessed via SwarmSDK.config
       USER_AGENT = "SwarmSDK WebFetch Tool (https://github.com/parruda/claude-swarm)"
-      TIMEOUT = 30 # seconds
 
       def execute(url:, prompt: nil)
         # Validate inputs
         return validation_error("url is required") if url.nil? || url.empty?
 
+        # Check if LLM processing is enabled (lazy check)
+        llm_enabled = SwarmSDK.config.webfetch_llm_enabled?
+
         # Validate prompt when LLM processing is enabled
-        if @llm_enabled && (prompt.nil? || prompt.empty?)
+        if llm_enabled && (prompt.nil? || prompt.empty?)
           return validation_error("prompt is required when LLM processing is configured")
         end
 
@@ -69,7 +70,7 @@ module SwarmSDK
         return validation_error("Invalid URL format: #{url}") unless normalized_url
 
         # Check cache first (cache key includes prompt if LLM is enabled)
-        cache_key = @llm_enabled ? "#{normalized_url}:#{prompt}" : normalized_url
+        cache_key = llm_enabled ? "#{normalized_url}:#{prompt}" : normalized_url
         cached = get_from_cache(cache_key)
         return cached if cached
 
@@ -86,13 +87,14 @@ module SwarmSDK
         markdown_content = html_to_markdown(fetch_result[:body])
 
         # Truncate if too long
-        if markdown_content.length > MAX_CONTENT_LENGTH
-          markdown_content = markdown_content[0...MAX_CONTENT_LENGTH]
+        max_content = SwarmSDK.config.web_fetch_character_limit
+        if markdown_content.length > max_content
+          markdown_content = markdown_content[0...max_content]
           markdown_content += "\n\n[Content truncated due to length]"
         end
 
         # Process with AI model if LLM is enabled, otherwise return markdown
-        result = if @llm_enabled
+        result = if llm_enabled
           process_with_llm(markdown_content, prompt, normalized_url)
         else
           markdown_content
@@ -142,12 +144,13 @@ module SwarmSDK
         require "faraday"
         require "faraday/follow_redirects"
 
+        timeout = SwarmSDK.config.web_fetch_timeout
         response = Faraday.new(url: url) do |conn|
           conn.request(:url_encoded)
           conn.response(:follow_redirects, limit: 5)
           conn.adapter(Faraday.default_adapter)
-          conn.options.timeout = TIMEOUT
-          conn.options.open_timeout = TIMEOUT
+          conn.options.timeout = timeout
+          conn.options.open_timeout = timeout
         end.get do |req|
           req.headers["User-Agent"] = USER_AGENT
           req.headers["Accept"] = "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8"
@@ -166,7 +169,7 @@ module SwarmSDK
           redirect_url: redirect_url,
         }
       rescue Faraday::TimeoutError
-        error("Request timed out after #{TIMEOUT} seconds")
+        error("Request timed out after #{SwarmSDK.config.web_fetch_timeout} seconds")
       rescue Faraday::ConnectionFailed => e
         error("Connection failed: #{e.message}")
       rescue StandardError => e
@@ -193,17 +196,17 @@ module SwarmSDK
           Please respond to the user's request based on the content above.
         PROMPT
 
-        # Get settings
-        config = SwarmSDK.settings
+        # Get config
+        sdk_config = SwarmSDK.config
 
         # Build chat with configured provider and model
         chat_params = {
-          model: config.webfetch_model,
-          provider: config.webfetch_provider.to_sym,
+          model: sdk_config.webfetch_model,
+          provider: sdk_config.webfetch_provider.to_sym,
         }
-        chat_params[:base_url] = config.webfetch_base_url if config.webfetch_base_url
+        chat_params[:base_url] = sdk_config.webfetch_base_url if sdk_config.webfetch_base_url
 
-        chat = RubyLLM.chat(**chat_params).with_params(max_tokens: config.webfetch_max_tokens)
+        chat = RubyLLM.chat(**chat_params).with_params(max_tokens: sdk_config.webfetch_max_tokens)
 
         response = chat.ask(full_prompt)
 

data/lib/swarm_sdk/tools/write.rb

@@ -10,6 +10,13 @@ module SwarmSDK
     class Write < RubyLLM::Tool
       include PathResolver
 
+      # Factory pattern: declare what parameters this tool needs for instantiation
+      class << self
+        def creation_requirements
+          [:agent_name, :directory]
+        end
+      end
+
       description <<~DESC
         Writes a file to the local filesystem.
         This tool will overwrite the existing file if there is one at the provided path.
@@ -42,8 +49,7 @@ module SwarmSDK
       # @param directory [String] Agent's working directory
       def initialize(agent_name:, directory:)
         super()
-        @agent_name = agent_name.to_sym
-        @directory = File.expand_path(directory)
+        initialize_agent_context(agent_name: agent_name, directory: directory)
       end
 
       # Override name to return simple "Write" instead of full class path
@@ -101,17 +107,6 @@ module SwarmSDK
       rescue StandardError => e
         error("Unexpected error writing file: #{e.class.name} - #{e.message}")
       end
-
-      private
-
-      # Helper methods
-      def validation_error(message)
-        "<tool_use_error>InputValidationError: #{message}</tool_use_error>"
-      end
-
-      def error(message)
-        "Error: #{message}"
-      end
     end
   end
 end

data/lib/swarm_sdk/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module SwarmSDK
-  VERSION = "2.2.0"
+  VERSION = "2.4.0"
 end

data/lib/swarm_sdk/{node → workflow}/agent_config.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module SwarmSDK
-  module Node
+  class Workflow
     # AgentConfig provides fluent API for configuring agents within a node
     #
     # This class enables the chainable syntax:

data/lib/swarm_sdk/workflow/builder.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+module SwarmSDK
+  class Workflow
+    # Builder provides DSL for building multi-node workflows
+    # This is the top-level builder accessed via SwarmSDK.workflow
+    #
+    # The DSL enables:
+    # - Node-based workflow configuration
+    # - Agent delegation per node
+    # - Input/output transformers for data flow
+    # - Context preservation across nodes
+    #
+    # @example Multi-stage workflow
+    #   workflow = SwarmSDK.workflow do
+    #     name "Build Pipeline"
+    #     start_node :planning
+    #
+    #     agent :architect do
+    #       model "gpt-5"
+    #       prompt "You design systems"
+    #     end
+    #
+    #     agent :coder do
+    #       model "gpt-4"
+    #       prompt "You implement code"
+    #     end
+    #
+    #     node :planning do
+    #       agent(:architect)
+    #     end
+    #
+    #     node :implementation do
+    #       agent(:coder)
+    #       depends_on :planning
+    #     end
+    #   end
+    #
+    #   workflow.execute("Build auth system")
+    class Builder < Builders::BaseBuilder
+      # Main entry point for DSL
+      #
+      # @example
+      #   workflow = SwarmSDK.workflow do
+      #     name "Pipeline"
+      #     start_node :planning
+      #     node(:planning) { agent(:architect) }
+      #   end
+      class << self
+        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(allow_filesystem_tools: nil)
+        super
+        @nodes = {}
+        @start_node = nil
+      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)
+      #     depends_on :planning
+      #   end
+      def node(name, &block)
+        builder = Workflow::NodeBuilder.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 Workflow instance
+      def build_swarm # Returns Workflow despite method name
+        raise ConfigurationError, "Workflow name not set. Use: name 'My Workflow'" unless @swarm_name
+        raise ConfigurationError, "No nodes defined. Use: node :name { ... }" if @nodes.empty?
+        raise ConfigurationError, "start_node not set. Use: start_node :name" unless @start_node
+
+        # Validate filesystem tools BEFORE building
+        validate_all_agents_filesystem_tools if @all_agents_config
+        validate_agent_filesystem_tools
+
+        build_workflow
+      end
+
+      private
+
+      # Build a node-based workflow
+      #
+      # @return [Workflow] Configured workflow instance
+      def build_workflow
+        # Build agent definitions
+        agent_definitions = build_agent_definitions
+
+        # Create workflow
+        workflow = Workflow.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 workflow if external swarms registered
+        workflow.swarm_registry_config = @swarm_registry_config if @swarm_registry_config.any?
+
+        workflow
+      end
+    end
+  end
+end