swarm_sdk 2.0.0.pre.2

data/lib/swarm_sdk/tools/scratchpad_read.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module SwarmSDK
+  module Tools
+    # Tool for reading content from scratchpad memory
+    #
+    # Retrieves content stored by any agent using scratchpad_write.
+    # All agents in the swarm share the same scratchpad.
+    class ScratchpadRead < RubyLLM::Tool
+      define_method(:name) { "ScratchpadRead" }
+
+      description <<~DESC
+        Read content from scratchpad.
+        Use this to retrieve detailed outputs, analysis, or results that were
+        stored using scratchpad_write. Any agent can read any scratchpad content.
+      DESC
+
+      param :file_path,
+        desc: "Path to read from scratchpad (e.g., 'analysis/report', 'parallel/batch1/task_0')",
+        required: true
+
+      class << self
+        # Create a ScratchpadRead tool for a specific scratchpad instance
+        #
+        # @param scratchpad [Stores::Scratchpad] Shared scratchpad instance
+        # @return [ScratchpadRead] Tool instance
+        def create_for_scratchpad(scratchpad)
+          new(scratchpad)
+        end
+      end
+
+      # Initialize with scratchpad instance
+      #
+      # @param scratchpad [Stores::Scratchpad] Shared scratchpad instance
+      def initialize(scratchpad)
+        super() # Call RubyLLM::Tool's initialize
+        @scratchpad = scratchpad
+      end
+
+      # Execute the tool
+      #
+      # @param file_path [String] Path to read from
+      # @return [String] Content at the path or error message
+      def execute(file_path:)
+        scratchpad.read(file_path: file_path)
+      rescue ArgumentError => e
+        validation_error(e.message)
+      end
+
+      private
+
+      attr_reader :scratchpad
+
+      def validation_error(message)
+        "<tool_use_error>InputValidationError: #{message}</tool_use_error>"
+      end
+    end
+  end
+end

data/lib/swarm_sdk/tools/scratchpad_write.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module SwarmSDK
+  module Tools
+    # Tool for writing content to scratchpad memory
+    #
+    # Stores content in session-scoped, in-memory storage with metadata.
+    # All agents in the swarm share the same scratchpad.
+    class ScratchpadWrite < RubyLLM::Tool
+      define_method(:name) { "ScratchpadWrite" }
+
+      description <<~DESC
+        Store content in scratchpad for later retrieval.
+        Use this to save detailed outputs, analysis, or results that would
+        otherwise bloat tool responses. Any agent can read this content using scratchpad_read.
+
+        IMPORTANT: You must determine the appropriate file_path based on the task you're performing.
+        Choose a logical, descriptive path that reflects the content type and purpose.
+        Examples: 'analysis/code_review', 'research/findings', 'parallel/batch_1/results', 'logs/debug_trace'
+      DESC
+
+      param :file_path,
+        desc: "File-path-like address you determine based on the task (e.g., 'analysis/report', 'parallel/batch1/task_0')",
+        required: true
+
+      param :content,
+        desc: "Content to store in scratchpad (max 1MB per entry)",
+        required: true
+
+      param :title,
+        desc: "Brief title describing the content (shown in listings)",
+        required: true
+
+      class << self
+        # Create a ScratchpadWrite tool for a specific scratchpad instance
+        #
+        # @param scratchpad [Stores::Scratchpad] Shared scratchpad instance
+        # @return [ScratchpadWrite] Tool instance
+        def create_for_scratchpad(scratchpad)
+          new(scratchpad)
+        end
+      end
+
+      # Initialize with scratchpad instance
+      #
+      # @param scratchpad [Stores::Scratchpad] Shared scratchpad instance
+      def initialize(scratchpad)
+        super() # Call RubyLLM::Tool's initialize
+        @scratchpad = scratchpad
+      end
+
+      # Execute the tool
+      #
+      # @param file_path [String] Path to store content
+      # @param content [String] Content to store
+      # @param title [String] Brief title
+      # @return [String] Success message with path and size
+      def execute(file_path:, content:, title:)
+        entry = scratchpad.write(file_path: file_path, content: content, title: title)
+        "Stored at scratchpad://#{file_path} (#{format_bytes(entry.size)})"
+      rescue ArgumentError => e
+        validation_error(e.message)
+      end
+
+      private
+
+      attr_reader :scratchpad
+
+      def validation_error(message)
+        "<tool_use_error>InputValidationError: #{message}</tool_use_error>"
+      end
+
+      # Format bytes to human-readable size
+      #
+      # @param bytes [Integer] Number of bytes
+      # @return [String] Formatted size
+      def format_bytes(bytes)
+        if bytes >= 1_000_000
+          "#{(bytes.to_f / 1_000_000).round(1)}MB"
+        elsif bytes >= 1_000
+          "#{(bytes.to_f / 1_000).round(1)}KB"
+        else
+          "#{bytes}B"
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module SwarmSDK
+  module Tools
+    module Stores
+      # ReadTracker manages read-file tracking for all agents
+      #
+      # This module maintains a global registry of which files each agent has read
+      # during their conversation. This enables enforcement of the "read-before-write"
+      # and "read-before-edit" rules that ensure agents have context before modifying files.
+      #
+      # Each agent maintains an independent set of read files, keyed by agent identifier.
+      module ReadTracker
+        @read_files = {}
+        @mutex = Mutex.new
+
+        class << self
+          # Register that an agent has read a file
+          #
+          # @param agent_id [Symbol] The agent identifier
+          # @param file_path [String] The absolute path to the file
+          def register_read(agent_id, file_path)
+            @mutex.synchronize do
+              @read_files[agent_id] ||= Set.new
+              @read_files[agent_id] << File.expand_path(file_path)
+            end
+          end
+
+          # Check if an agent has read a file
+          #
+          # @param agent_id [Symbol] The agent identifier
+          # @param file_path [String] The absolute path to the file
+          # @return [Boolean] true if the agent has read this file
+          def file_read?(agent_id, file_path)
+            @mutex.synchronize do
+              return false unless @read_files[agent_id]
+
+              @read_files[agent_id].include?(File.expand_path(file_path))
+            end
+          end
+
+          # Clear read history for an agent (useful for testing)
+          #
+          # @param agent_id [Symbol] The agent identifier
+          def clear(agent_id)
+            @mutex.synchronize do
+              @read_files.delete(agent_id)
+            end
+          end
+
+          # Clear all read history (useful for testing)
+          def clear_all
+            @mutex.synchronize do
+              @read_files.clear
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,153 @@
+# frozen_string_literal: true
+
+module SwarmSDK
+  module Tools
+    module Stores
+      # Scratchpad provides session-scoped, in-memory storage for agents
+      # to store detailed outputs that would otherwise bloat tool responses.
+      #
+      # Features:
+      # - Session-scoped: Cleared when swarm execution completes
+      # - Shared: Any agent can read/write any scratchpad address
+      # - Path-based: Hierarchical organization using file-path-like addresses
+      # - In-memory: No filesystem I/O, pure memory storage
+      # - Metadata-rich: Stores content + title + timestamp + size
+      class Scratchpad
+        # Maximum size per scratchpad entry (1MB)
+        MAX_ENTRY_SIZE = 1_000_000
+
+        # Maximum total scratchpad size (100MB)
+        MAX_TOTAL_SIZE = 100_000_000
+
+        # Represents a single scratchpad entry with metadata
+        Entry = Struct.new(:content, :title, :created_at, :size, keyword_init: true)
+
+        def initialize
+          @entries = {}
+          @total_size = 0
+        end
+
+        # Write content to scratchpad
+        #
+        # @param file_path [String] Path to store content
+        # @param content [String] Content to store
+        # @param title [String] Brief title describing the content
+        # @raise [ArgumentError] If size limits are exceeded
+        # @return [Entry] The created entry
+        def write(file_path:, content:, title:)
+          raise ArgumentError, "file_path is required" if file_path.nil? || file_path.to_s.strip.empty?
+          raise ArgumentError, "content is required" if content.nil?
+          raise ArgumentError, "title is required" if title.nil? || title.to_s.strip.empty?
+
+          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)}). " \
+              "Current: #{format_bytes(content_size)}"
+          end
+
+          # Calculate new total size
+          existing_entry = @entries[file_path]
+          existing_size = existing_entry ? existing_entry.size : 0
+          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). " \
+              "Current: #{format_bytes(@total_size)}, " \
+              "Would be: #{format_bytes(new_total_size)}. " \
+              "Clear old entries or use smaller content."
+          end
+
+          # Create entry
+          entry = Entry.new(
+            content: content,
+            title: title,
+            created_at: Time.now,
+            size: content_size,
+          )
+
+          # Update storage
+          @entries[file_path] = entry
+          @total_size = new_total_size
+
+          entry
+        end
+
+        # Read content from scratchpad
+        #
+        # @param file_path [String] Path to read from
+        # @raise [ArgumentError] If path not found
+        # @return [String] Content at the path
+        def read(file_path:)
+          raise ArgumentError, "file_path is required" if file_path.nil? || file_path.to_s.strip.empty?
+
+          entry = @entries[file_path]
+          raise ArgumentError, "scratchpad://#{file_path} not found" unless entry
+
+          entry.content
+        end
+
+        # List scratchpad entries, optionally filtered by prefix
+        #
+        # @param prefix [String, nil] Filter by path prefix
+        # @return [Array<Hash>] Array of entry metadata (path, title, size, created_at)
+        def list(prefix: nil)
+          entries = @entries
+
+          # Filter by prefix if provided
+          if prefix && !prefix.empty?
+            entries = entries.select { |path, _| path.start_with?(prefix) }
+          end
+
+          # Return metadata
+          entries.map do |path, entry|
+            {
+              path: path,
+              title: entry.title,
+              size: entry.size,
+              created_at: entry.created_at,
+            }
+          end.sort_by { |e| e[:path] }
+        end
+
+        # Clear all entries
+        #
+        # @return [void]
+        def clear
+          @entries.clear
+          @total_size = 0
+        end
+
+        # Get current total size
+        #
+        # @return [Integer] Total size in bytes
+        attr_reader :total_size
+
+        # Get number of entries
+        #
+        # @return [Integer] Number of entries
+        def size
+          @entries.size
+        end
+
+        private
+
+        # Format bytes to human-readable size
+        #
+        # @param bytes [Integer] Number of bytes
+        # @return [String] Formatted size (e.g., "1.5MB", "500.0KB")
+        def format_bytes(bytes)
+          if bytes >= 1_000_000
+            "#{(bytes.to_f / 1_000_000).round(1)}MB"
+          elsif bytes >= 1_000
+            "#{(bytes.to_f / 1_000).round(1)}KB"
+          else
+            "#{bytes}B"
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module SwarmSDK
+  module Tools
+    module Stores
+      # TodoManager provides per-agent todo list storage
+      #
+      # Each agent maintains its own independent todo list that persists
+      # throughout the agent's execution session. This allows agents to
+      # track progress on complex multi-step tasks.
+      class TodoManager
+        @storage = {}
+        @mutex = Mutex.new
+
+        class << self
+          # Get the current todo list for an agent
+          #
+          # @param agent_id [Symbol, String] Unique agent identifier
+          # @return [Array<Hash>] Array of todo items
+          def get_todos(agent_id)
+            @mutex.synchronize do
+              @storage[agent_id.to_sym] ||= []
+            end
+          end
+
+          # Set the todo list for an agent
+          #
+          # @param agent_id [Symbol, String] Unique agent identifier
+          # @param todos [Array<Hash>] Array of todo items
+          # @return [Array<Hash>] The stored todos
+          def set_todos(agent_id, todos)
+            @mutex.synchronize do
+              @storage[agent_id.to_sym] = todos
+            end
+          end
+
+          # Clear all todos for an agent
+          #
+          # @param agent_id [Symbol, String] Unique agent identifier
+          def clear_todos(agent_id)
+            @mutex.synchronize do
+              @storage.delete(agent_id.to_sym)
+            end
+          end
+
+          # Clear all todos for all agents
+          def clear_all
+            @mutex.synchronize do
+              @storage.clear
+            end
+          end
+
+          # Get summary of all agent todo lists
+          #
+          # @return [Hash] Map of agent_id => todo count
+          def summary
+            @mutex.synchronize do
+              @storage.transform_values(&:size)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/swarm_sdk/tools/todo_write.rb

@@ -0,0 +1,216 @@
+# frozen_string_literal: true
+
+module SwarmSDK
+  module Tools
+    # TodoWrite tool for creating and managing structured task lists
+    #
+    # This tool helps agents track progress on complex multi-step tasks.
+    # Each agent maintains its own independent todo list.
+    class TodoWrite < RubyLLM::Tool
+      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.
+        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
+        3. THIRD: Execute tasks, marking in_progress → completed as you work
+        4. ONLY add new todos if unexpected work is discovered during implementation
+
+        Use the todo list when:
+        1. Complex multi-step tasks - When a task requires 3 or more distinct steps or actions
+        2. Non-trivial and complex tasks - Tasks that require careful planning or multiple operations
+        3. User explicitly requests todo list - When the user directly asks you to use the todo list
+        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
+
+        ## When NOT to Use This Tool
+
+        Skip using this tool when:
+        1. There is only a single, straightforward task
+        2. The task is trivial and tracking it provides no organizational benefit
+        3. The task can be completed in less than 3 trivial steps
+        4. The task is purely conversational or informational
+
+        NOTE that you should not use this tool if there is only one trivial task to do. In this case you are better off just doing the task directly.
+
+        ## Task States and Management
+
+        1. **Task States**: Use these states to track progress:
+          - pending: Task not yet started
+          - in_progress: Currently working on (limit to ONE task at a time)
+          - completed: Task finished successfully
+
+          **IMPORTANT**: Task descriptions must have two forms:
+          - content: The imperative form describing what needs to be done (e.g., "Run tests", "Build the project")
+          - activeForm: The present continuous form shown during execution (e.g., "Running tests", "Building the project")
+
+        2. **Task Management**:
+          - Update task status in real-time as you work
+          - Mark tasks complete IMMEDIATELY after finishing (don't batch completions)
+          - Exactly ONE task must be in_progress at any time (not less, not more)
+          - Complete current tasks before starting new ones
+          - Remove tasks that are no longer relevant from the list entirely
+          - **CRITICAL**: You MUST complete ALL pending todos before giving your final answer to the user
+          - NEVER leave in_progress or pending tasks when you finish responding
+
+        3. **Task Completion Requirements**:
+          - ONLY mark a task as completed when you have FULLY accomplished it
+          - If you encounter errors, blockers, or cannot finish, keep the task as in_progress
+          - When blocked, create a new task describing what needs to be resolved
+          - Never mark a task as completed if:
+            - Tests are failing
+            - Implementation is partial
+            - You encountered unresolved errors
+            - You couldn't find necessary files or dependencies
+
+        4. **Task Breakdown**:
+          - 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"
+
+        When in doubt, use this tool. Being proactive with task management demonstrates attentiveness and ensures you complete all requirements successfully.
+      DESC
+
+      param :todos_json,
+        type: "string",
+        desc: <<~DESC.chomp,
+          JSON array of todo objects. Each todo must have:
+          content (string, task in imperative form like 'Run tests'),
+          status (string, one of: 'pending', 'in_progress', 'completed'),
+          activeForm (string, task in present continuous form like 'Running tests').
+          Example: [{"content":"Read file","status":"pending","activeForm":"Reading file"}]
+        DESC
+        required: true
+
+      # Initialize the TodoWrite tool for a specific agent
+      #
+      # @param agent_name [Symbol, String] The agent identifier
+      def initialize(agent_name:)
+        super()
+        @agent_name = agent_name.to_sym
+      end
+
+      # Override name to return simple "TodoWrite" instead of full class path
+      def name
+        "TodoWrite"
+      end
+
+      def execute(todos_json:)
+        # Parse JSON
+        todos = begin
+          JSON.parse(todos_json)
+        rescue JSON::ParserError
+          nil
+        end
+
+        return validation_error("Invalid JSON format. Please provide a valid JSON array of todo objects.") if todos.nil?
+
+        # Validate todos structure
+        unless todos.is_a?(Array)
+          return validation_error("todos must be an array of todo objects")
+        end
+
+        if todos.empty?
+          return validation_error("todos array cannot be empty")
+        end
+
+        validated_todos = []
+        errors = []
+
+        todos.each_with_index do |todo, index|
+          unless todo.is_a?(Hash)
+            errors << "Todo at index #{index} must be a hash/object"
+            next
+          end
+
+          # Convert string keys to symbols for consistency
+          todo = todo.transform_keys(&:to_sym) if todo.is_a?(Hash)
+
+          # Validate required fields
+          unless todo[:content]
+            errors << "Todo at index #{index} missing required field 'content'"
+            next
+          end
+
+          unless todo[:status]
+            errors << "Todo at index #{index} missing required field 'status'"
+            next
+          end
+
+          unless todo[:activeForm]
+            errors << "Todo at index #{index} missing required field 'activeForm'"
+            next
+          end
+
+          # Validate status values
+          valid_statuses = ["pending", "in_progress", "completed"]
+          unless valid_statuses.include?(todo[:status].to_s)
+            errors << "Todo at index #{index} has invalid status '#{todo[:status]}'. Must be one of: #{valid_statuses.join(", ")}"
+            next
+          end
+
+          # Validate content and activeForm are non-empty
+          if todo[:content].to_s.strip.empty?
+            errors << "Todo at index #{index} has empty content"
+            next
+          end
+
+          if todo[:activeForm].to_s.strip.empty?
+            errors << "Todo at index #{index} has empty activeForm"
+            next
+          end
+
+          validated_todos << {
+            content: todo[:content].to_s,
+            status: todo[:status].to_s,
+            activeForm: todo[:activeForm].to_s,
+          }
+        end
+
+        return validation_error("TodoWrite failed due to the following issues:\n#{errors.join("\n")}") unless errors.empty?
+
+        # Check that exactly one task is in_progress (with helpful message)
+        in_progress_count = validated_todos.count { |t| t[:status] == "in_progress" }
+        warning_message = if in_progress_count == 0
+          "Warning: No tasks marked as in_progress. You should have exactly ONE task in_progress at a time.\n" \
+            "Please mark the task you're currently working on as in_progress.\n\n"
+        elsif in_progress_count > 1
+          "Warning: Multiple tasks marked as in_progress (#{in_progress_count} tasks).\n" \
+            "You should have exactly ONE task in_progress at a time.\n" \
+            "Please ensure only the current task is in_progress, others should be pending or completed.\n\n"
+        else
+          ""
+        end
+
+        # Store the validated todos
+        Stores::TodoManager.set_todos(@agent_name, validated_todos)
+
+        <<~RESPONSE
+          <system-reminder>
+          #{warning_message}Your todo list has changed. DO NOT mention this explicitly to the user. Here are the latest contents of your todo list:
+          #{validated_todos.map { |t| "- #{t[:content]} (#{t[:status]})" }.join("\n")}
+          Continue on with the tasks at hand if applicable.
+          </system-reminder>
+        RESPONSE
+      rescue StandardError => e
+        "Error managing todos: #{e.class.name} - #{e.message}"
+      end
+
+      private
+
+      # Helper method for validation errors
+      def validation_error(message)
+        "<tool_use_error>InputValidationError: #{message}</tool_use_error>"
+      end
+    end
+  end
+end