swarm_sdk 2.2.0 → 2.3.0

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 || Defaults::Storage::TOTAL_SIZE_BYTES
           @mutex = Mutex.new
         end
 
@@ -38,8 +41,8 @@ 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)}). " \
+            if content_size > Defaults::Storage::ENTRY_SIZE_BYTES
+              raise ArgumentError, "Content exceeds maximum size (#{format_bytes(Defaults::Storage::ENTRY_SIZE_BYTES)}). " \
                 "Current: #{format_bytes(content_size)}"
             end
 
@@ -49,8 +52,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

@@ -51,9 +51,10 @@ 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
+      # Backward compatibility aliases - use Defaults module for new code
+      MAX_CONTENT_LENGTH = Defaults::Limits::WEB_FETCH_CHARACTERS
       USER_AGENT = "SwarmSDK WebFetch Tool (https://github.com/parruda/claude-swarm)"
-      TIMEOUT = 30 # seconds
+      TIMEOUT = Defaults::Timeouts::WEB_FETCH_SECONDS
 
       def execute(url:, prompt: nil)
         # Validate inputs

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.3.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