swarm_memory 2.1.2 → 2.1.4

data/lib/swarm_sdk/tools/think.rb

@@ -82,7 +82,10 @@ module SwarmSDK
         required: true
 
       def execute(**kwargs)
-        "Thought noted."
+        <<~RESP
+          Thought noted.
+        RESP
+        # <system-reminder>The user cannot see your thoughts. You MUST NOT stop without giving the user a response.</system-reminder>
       end
 
       private

data/lib/swarm_sdk/tools/todo_write.rb

@@ -7,18 +7,25 @@ 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 coding session. This helps you track progress, organize complex tasks, and demonstrate thoroughness to the user.
+        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.
 
         ## When to Use This Tool
         Use this tool proactively in these scenarios:
 
         **CRITICAL**: Follow this workflow for multi-step tasks:
-        1. FIRST: Analyze the task scope (search files, read code, understand requirements)
-        2. SECOND: Create a COMPLETE todo list with ALL known tasks BEFORE starting implementation
+        1. FIRST: Analyze the task scope (gather information, understand requirements)
+        2. SECOND: Create a COMPLETE todo list with ALL known tasks BEFORE starting work
         3. THIRD: Execute tasks, marking in_progress → completed as you work
-        4. ONLY add new todos if unexpected work is discovered during implementation
+        4. ONLY add new todos if unexpected work is discovered during execution
 
         Use the todo list when:
         1. Complex multi-step tasks - When a task requires 3 or more distinct steps or actions
@@ -27,7 +34,7 @@ module SwarmSDK
         4. User provides multiple tasks - When users provide a list of things to be done (numbered or comma-separated)
         5. After receiving new instructions - After analyzing scope, create complete todo list before starting work
         6. When you start working on a task - Mark it as in_progress BEFORE beginning work. Ideally you should only have one todo as in_progress at a time
-        7. After completing a task - Mark it as completed and add any new follow-up tasks discovered during implementation
+        7. After completing a task - Mark it as completed and add any new follow-up tasks discovered during execution
 
         ## When NOT to Use This Tool
 
@@ -73,9 +80,21 @@ module SwarmSDK
           - Create specific, actionable items
           - Break complex tasks into smaller, manageable steps
           - Use clear, descriptive task names
-          - Always provide both forms:
-            - content: "Fix authentication bug"
-            - activeForm: "Fixing authentication bug"
+          - Always provide both forms (content and activeForm)
+
+        ## Examples
+
+        **Coding Tasks**:
+        - content: "Fix authentication bug in login handler"
+        - activeForm: "Fixing authentication bug in login handler"
+
+        **Non-Coding Tasks**:
+        - content: "Analyze customer feedback from Q4 survey"
+        - activeForm: "Analyzing customer feedback from Q4 survey"
+
+        **Research Tasks**:
+        - content: "Research best practices for API rate limiting"
+        - activeForm: "Researching best practices for API rate limiting"
 
         When in doubt, use this tool. Being proactive with task management demonstrates attentiveness and ensures you complete all requirements successfully.
       DESC

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/utils.rb

@@ -45,6 +45,24 @@ module SwarmSDK
           obj
         end
       end
+
+      # Convert hash to YAML string
+      #
+      # Converts a Ruby hash to a YAML string. Useful for creating inline
+      # swarm definitions from hash configurations.
+      #
+      # @param hash [Hash] Hash to convert
+      # @return [String] YAML string representation
+      #
+      # @example
+      #   config = { version: 2, swarm: { name: "Test" } }
+      #   Utils.hash_to_yaml(config)
+      #   # => "---\nversion: 2\nswarm:\n  name: Test\n"
+      def hash_to_yaml(hash)
+        # Convert symbols to strings for valid YAML
+        stringified = stringify_keys(hash)
+        stringified.to_yaml
+      end
     end
   end
 end

data/lib/swarm_sdk/validation_result.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module SwarmSDK
+  # Internal result object for validation phase during snapshot restore
+  #
+  # Used during restore to track which agents can be restored and which
+  # need to be skipped due to configuration mismatches.
+  #
+  # @api private
+  class ValidationResult
+    attr_reader :warnings,
+      :skipped_agents,
+      :restorable_agents,
+      :skipped_delegations,
+      :restorable_delegations
+
+    # Initialize validation result
+    #
+    # @param warnings [Array<Hash>] Warning messages with details
+    # @param skipped_agents [Array<Symbol>] Names of agents that can't be restored
+    # @param restorable_agents [Array<Symbol>] Names of agents that can be restored
+    # @param skipped_delegations [Array<String>] Names of delegations that can't be restored
+    # @param restorable_delegations [Array<String>] Names of delegations that can be restored
+    def initialize(warnings:, skipped_agents:, restorable_agents:,
+      skipped_delegations:, restorable_delegations:)
+      @warnings = warnings
+      @skipped_agents = skipped_agents
+      @restorable_agents = restorable_agents
+      @skipped_delegations = skipped_delegations
+      @restorable_delegations = restorable_delegations
+    end
+  end
+end

data/lib/swarm_sdk/version.rb

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

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

@@ -1,12 +1,13 @@
 # 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:
     #   agent(:backend).delegates_to(:tester, :database)
     #   agent(:backend, reset_context: false)  # Preserve context across nodes
+    #   agent(:backend).tools(:Read, :Edit)    # Override tools for this node
     #
     # @example Basic delegation
     #   agent(:backend).delegates_to(:tester)
@@ -16,6 +17,12 @@ module SwarmSDK
     #
     # @example Preserve agent context
     #   agent(:architect, reset_context: false)
+    #
+    # @example Override tools for this node
+    #   agent(:backend).tools(:Read, :Think)
+    #
+    # @example Combine delegation and tool override
+    #   agent(:backend).delegates_to(:tester).tools(:Read, :Edit, :Write)
     class AgentConfig
       attr_reader :agent_name
 
@@ -24,6 +31,7 @@ module SwarmSDK
         @node_builder = node_builder
         @delegates_to = []
         @reset_context = reset_context
+        @tools = nil # nil means use global agent definition tools
         @finalized = false
       end
 
@@ -33,21 +41,38 @@ module SwarmSDK
       # @return [self] For method chaining
       def delegates_to(*agent_names)
         @delegates_to = agent_names.map(&:to_sym)
-        finalize
+        update_registration
         self
       end
 
-      # Finalize agent configuration (called automatically)
+      # Override tools for this agent in this node
+      #
+      # @param tool_names [Array<Symbol>] Tool names to use (overrides global agent definition)
+      # @return [self] For method chaining
       #
-      # Registers this agent configuration with the parent node builder.
-      # If delegates_to was never called, registers with empty delegation.
+      # @example
+      #   agent(:backend).tools(:Read, :Edit)
+      def tools(*tool_names)
+        @tools = tool_names.map(&:to_sym)
+        update_registration
+        self
+      end
+
+      # Update agent registration (called after each fluent method)
+      #
+      # Always updates the registration with current state.
+      # This allows chaining: .delegates_to(...).tools(...)
       #
       # @return [void]
-      def finalize
-        return if @finalized
+      def update_registration
+        @node_builder.register_agent(@agent_name, @delegates_to, @reset_context, @tools)
+      end
 
-        @node_builder.register_agent(@agent_name, @delegates_to, @reset_context)
-        @finalized = true
+      # Finalize agent configuration (backward compatibility)
+      #
+      # @return [void]
+      def finalize
+        update_registration
       end
     end
   end

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