swarm_sdk 2.0.3 → 2.0.5

data/lib/swarm_sdk/swarm.rb

@@ -62,6 +62,13 @@ module SwarmSDK
     DEFAULT_TOOLS = ToolConfigurator::DEFAULT_TOOLS
 
     attr_reader :name, :agents, :lead_agent, :mcp_clients
+
+    # Check if scratchpad tools are enabled
+    #
+    # @return [Boolean]
+    def scratchpad_enabled?
+      @scratchpad_enabled
+    end
     attr_writer :config_for_hooks
 
     # Class-level MCP log level configuration
@@ -129,16 +136,24 @@ module SwarmSDK
     # @param name [String] Human-readable swarm name
     # @param global_concurrency [Integer] Max concurrent LLM calls across entire swarm
     # @param default_local_concurrency [Integer] Default max concurrent tool calls per agent
-    def initialize(name:, global_concurrency: DEFAULT_GLOBAL_CONCURRENCY, default_local_concurrency: DEFAULT_LOCAL_CONCURRENCY)
+    # @param scratchpad [Tools::Stores::Scratchpad, nil] Optional scratchpad instance (for testing)
+    # @param scratchpad_enabled [Boolean] Whether to enable scratchpad tools (default: true)
+    def initialize(name:, global_concurrency: DEFAULT_GLOBAL_CONCURRENCY, default_local_concurrency: DEFAULT_LOCAL_CONCURRENCY, scratchpad: nil, scratchpad_enabled: true)
       @name = name
       @global_concurrency = global_concurrency
       @default_local_concurrency = default_local_concurrency
+      @scratchpad_enabled = scratchpad_enabled
 
       # Shared semaphore for all agents
       @global_semaphore = Async::Semaphore.new(@global_concurrency)
 
-      # Shared scratchpad for all agents
-      @scratchpad = Tools::Stores::Scratchpad.new
+      # Shared scratchpad storage for all agents (volatile)
+      # Use provided scratchpad storage (for testing) or create volatile one
+      @scratchpad_storage = scratchpad || Tools::Stores::ScratchpadStorage.new
+
+      # Per-agent memory storage (persistent)
+      # Will be populated when agents are initialized
+      @memory_storages = {}
 
       # Hook registry for named hooks and swarm defaults
       @hook_registry = Hooks::Registry.new
@@ -535,13 +550,42 @@ module SwarmSDK
         @agent_definitions,
         @global_semaphore,
         @hook_registry,
-        @scratchpad,
+        @scratchpad_storage,
+        @memory_storages,
         config_for_hooks: @config_for_hooks,
       )
 
       @agents = initializer.initialize_all
       @agent_contexts = initializer.agent_contexts
       @agents_initialized = true
+
+      # Emit agent_start events for all agents
+      emit_agent_start_events
+    end
+
+    # Emit agent_start events for all initialized agents
+    def emit_agent_start_events
+      # Only emit if LogStream is enabled
+      return unless LogStream.emitter
+
+      @agents.each do |agent_name, chat|
+        agent_def = @agent_definitions[agent_name]
+
+        LogStream.emit(
+          type: "agent_start",
+          agent: agent_name,
+          swarm_name: @name,
+          model: agent_def.model,
+          provider: agent_def.provider || "openai",
+          directory: agent_def.directory,
+          system_prompt: agent_def.system_prompt,
+          tools: chat.tools.keys,
+          delegates_to: agent_def.delegates_to,
+          memory_enabled: agent_def.memory_enabled?,
+          memory_directory: agent_def.memory_enabled? ? agent_def.memory.directory : nil,
+          timestamp: Time.now.utc.strftime("%Y-%m-%dT%H:%M:%SZ"),
+        )
+      end
     end
 
     # Normalize tools to internal format (kept for add_agent)
@@ -576,12 +620,12 @@ module SwarmSDK
 
     # Create a tool instance (delegates to ToolConfigurator)
     def create_tool_instance(tool_name, agent_name, directory)
-      ToolConfigurator.new(self, @scratchpad).create_tool_instance(tool_name, agent_name, directory)
+      ToolConfigurator.new(self, @scratchpad_storage, @memory_storages).create_tool_instance(tool_name, agent_name, directory)
     end
 
     # Wrap tool with permissions (delegates to ToolConfigurator)
     def wrap_tool_with_permissions(tool_instance, permissions_config, agent_definition)
-      ToolConfigurator.new(self, @scratchpad).wrap_tool_with_permissions(tool_instance, permissions_config, agent_definition)
+      ToolConfigurator.new(self, @scratchpad_storage, @memory_storages).wrap_tool_with_permissions(tool_instance, permissions_config, agent_definition)
     end
 
     # Build MCP transport config (delegates to McpConfigurator)
@@ -591,7 +635,7 @@ module SwarmSDK
 
     # Create delegation tool (delegates to AgentInitializer)
     def create_delegation_tool(name:, description:, delegate_chat:, agent_name:)
-      AgentInitializer.new(self, @agent_definitions, @global_semaphore, @hook_registry, @scratchpad)
+      AgentInitializer.new(self, @agent_definitions, @global_semaphore, @hook_registry, @scratchpad_storage, @memory_storages)
         .create_delegation_tool(name: name, description: description, delegate_chat: delegate_chat, agent_name: agent_name)
     end
 

data/lib/swarm_sdk/tools/document_converters/html_converter.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+module SwarmSDK
+  module Tools
+    module DocumentConverters
+      # Converter for HTML to Markdown
+      # Uses reverse_markdown gem if available, otherwise falls back to simple regex-based conversion
+      class HtmlConverter < BaseConverter
+        class << self
+          def gem_name
+            "reverse_markdown"
+          end
+
+          def format_name
+            "HTML"
+          end
+
+          def extensions
+            [".html", ".htm"]
+          end
+        end
+
+        # Convert HTML string to Markdown
+        # @param html [String] HTML content to convert
+        # @return [String] Markdown content
+        def convert_string(html)
+          if self.class.available?
+            convert_with_gem(html)
+          else
+            convert_simple(html)
+          end
+        end
+
+        # Convert HTML file to Markdown
+        # @param file_path [String] Path to HTML file
+        # @return [String] Markdown content
+        def convert(file_path)
+          html = File.read(file_path)
+          convert_string(html)
+        rescue StandardError => e
+          error("Failed to read HTML file: #{e.message}")
+        end
+
+        private
+
+        # Convert HTML to Markdown using reverse_markdown gem
+        # @param html [String] HTML content
+        # @return [String] Markdown content
+        def convert_with_gem(html)
+          require "reverse_markdown"
+
+          ReverseMarkdown.convert(html, unknown_tags: :bypass, github_flavored: true)
+        rescue StandardError
+          # Fallback to simple conversion if gem conversion fails
+          convert_simple(html)
+        end
+
+        # Simple regex-based HTML to Markdown conversion (fallback)
+        # @param html [String] HTML content
+        # @return [String] Markdown content
+        def convert_simple(html)
+          # Remove script and style tags
+          content = html.gsub(%r{<script[^>]*>.*?</script>}im, "")
+          content = content.gsub(%r{<style[^>]*>.*?</style>}im, "")
+
+          # Convert common HTML elements
+          content = content.gsub(%r{<h1[^>]*>(.*?)</h1>}im, "\n# \\1\n")
+          content = content.gsub(%r{<h2[^>]*>(.*?)</h2>}im, "\n## \\1\n")
+          content = content.gsub(%r{<h3[^>]*>(.*?)</h3>}im, "\n### \\1\n")
+          content = content.gsub(%r{<h4[^>]*>(.*?)</h4>}im, "\n#### \\1\n")
+          content = content.gsub(%r{<h5[^>]*>(.*?)</h5>}im, "\n##### \\1\n")
+          content = content.gsub(%r{<h6[^>]*>(.*?)</h6>}im, "\n###### \\1\n")
+          content = content.gsub(%r{<p[^>]*>(.*?)</p>}im, "\n\\1\n")
+          content = content.gsub(%r{<br\s*/?>}i, "\n")
+          content = content.gsub(%r{<strong[^>]*>(.*?)</strong>}im, "**\\1**")
+          content = content.gsub(%r{<b[^>]*>(.*?)</b>}im, "**\\1**")
+          content = content.gsub(%r{<em[^>]*>(.*?)</em>}im, "_\\1_")
+          content = content.gsub(%r{<i[^>]*>(.*?)</i>}im, "_\\1_")
+          content = content.gsub(%r{<code[^>]*>(.*?)</code>}im, "`\\1`")
+          content = content.gsub(%r{<a[^>]*href=["']([^"']*)["'][^>]*>(.*?)</a>}im, "[\\2](\\1)")
+          content = content.gsub(%r{<li[^>]*>(.*?)</li>}im, "- \\1\n")
+
+          # Remove remaining HTML tags
+          content = content.gsub(/<[^>]+>/, "")
+
+          # Decode HTML entities
+          content = content.gsub("&lt;", "<")
+          content = content.gsub("&gt;", ">")
+          content = content.gsub("&amp;", "&")
+          content = content.gsub("&quot;", "\"")
+          content = content.gsub("&#39;", "'")
+          content = content.gsub("&nbsp;", " ")
+
+          # Clean up whitespace
+          content = content.gsub(/\n\n\n+/, "\n\n")
+          content.strip
+        end
+      end
+    end
+  end
+end

data/lib/swarm_sdk/tools/memory/memory_delete.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module SwarmSDK
+  module Tools
+    module Memory
+      # Tool for deleting content from memory storage
+      #
+      # Removes entries that are no longer relevant.
+      # Each agent has its own isolated memory storage.
+      class MemoryDelete < RubyLLM::Tool
+        define_method(:name) { "MemoryDelete" }
+
+        description <<~DESC
+          Delete content from your memory when it's no longer relevant.
+          Use this to remove outdated information, completed tasks, or data that's no longer needed.
+          This helps keep your memory organized and prevents it from filling up.
+
+          IMPORTANT: Only delete entries that are truly no longer needed. Once deleted, the content cannot be recovered.
+        DESC
+
+        param :file_path,
+          desc: "Path to delete from memory (e.g., 'analysis/old_report', 'parallel/batch1/task_0')",
+          required: true
+
+        class << self
+          # Create a MemoryDelete tool for a specific memory storage instance
+          #
+          # @param memory_storage [Stores::MemoryStorage] Per-agent memory storage instance
+          # @return [MemoryDelete] Tool instance
+          def create_for_memory(memory_storage)
+            new(memory_storage)
+          end
+        end
+
+        # Initialize with memory storage instance
+        #
+        # @param memory_storage [Stores::MemoryStorage] Per-agent memory storage instance
+        def initialize(memory_storage)
+          super() # Call RubyLLM::Tool's initialize
+          @memory_storage = memory_storage
+        end
+
+        # Execute the tool
+        #
+        # @param file_path [String] Path to delete from
+        # @return [String] Success message
+        def execute(file_path:)
+          memory_storage.delete(file_path: file_path)
+          "Deleted memory://#{file_path}"
+        rescue ArgumentError => e
+          validation_error(e.message)
+        end
+
+        private
+
+        attr_reader :memory_storage
+
+        def validation_error(message)
+          "<tool_use_error>InputValidationError: #{message}</tool_use_error>"
+        end
+      end
+    end
+  end
+end

data/lib/swarm_sdk/tools/memory/memory_edit.rb

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+module SwarmSDK
+  module Tools
+    module Memory
+      # Tool for editing memory entries with exact string replacement
+      #
+      # Performs exact string replacements in memory content.
+      # Each agent has its own isolated memory storage.
+      class MemoryEdit < RubyLLM::Tool
+        define_method(:name) { "MemoryEdit" }
+
+        description <<~DESC
+          Performs exact string replacements in memory entries.
+          Works like the Edit tool but operates on memory content instead of files.
+          You must use MemoryRead on the entry before editing it.
+          When editing text from MemoryRead output, ensure you preserve the exact indentation as it appears AFTER the line number prefix.
+          The line number prefix format is: spaces + line number + tab. Everything after that tab is the actual content to match.
+          Never include any part of the line number prefix in the old_string or new_string.
+          The edit will FAIL if old_string is not unique in the entry. Either provide a larger string with more surrounding context to make it unique or use replace_all to change every instance of old_string.
+          Use replace_all for replacing and renaming strings across the entry.
+        DESC
+
+        param :file_path,
+          desc: "Path to the memory entry (e.g., 'analysis/report', 'parallel/batch1/task_0')",
+          required: true
+
+        param :old_string,
+          desc: "The exact text to replace (must match exactly including whitespace)",
+          required: true
+
+        param :new_string,
+          desc: "The text to replace it with (must be different from old_string)",
+          required: true
+
+        param :replace_all,
+          desc: "Replace all occurrences of old_string (default false)",
+          required: false
+
+        class << self
+          # Create a MemoryEdit tool for a specific memory storage instance
+          #
+          # @param memory_storage [Stores::MemoryStorage] Per-agent memory storage instance
+          # @param agent_name [Symbol, String] Agent identifier for tracking reads
+          # @return [MemoryEdit] Tool instance
+          def create_for_memory(memory_storage, agent_name)
+            new(memory_storage, agent_name)
+          end
+        end
+
+        # Initialize with memory storage instance and agent name
+        #
+        # @param memory_storage [Stores::MemoryStorage] Per-agent memory storage instance
+        # @param agent_name [Symbol, String] Agent identifier
+        def initialize(memory_storage, agent_name)
+          super() # Call RubyLLM::Tool's initialize
+          @memory_storage = memory_storage
+          @agent_name = agent_name.to_sym
+        end
+
+        # Execute the tool
+        #
+        # @param file_path [String] Path to memory entry
+        # @param old_string [String] Text to replace
+        # @param new_string [String] Replacement text
+        # @param replace_all [Boolean] Replace all occurrences
+        # @return [String] Success message or error
+        def execute(file_path:, old_string:, new_string:, replace_all: false)
+          # Validate inputs
+          return validation_error("file_path is required") if file_path.nil? || file_path.to_s.strip.empty?
+          return validation_error("old_string is required") if old_string.nil? || old_string.empty?
+          return validation_error("new_string is required") if new_string.nil?
+
+          # old_string and new_string must be different
+          if old_string == new_string
+            return validation_error("old_string and new_string must be different. They are currently identical.")
+          end
+
+          # Read current content (this will raise ArgumentError if entry doesn't exist)
+          content = memory_storage.read(file_path: file_path)
+
+          # Enforce read-before-edit
+          unless Stores::StorageReadTracker.entry_read?(@agent_name, file_path)
+            return validation_error(
+              "Cannot edit memory entry without reading it first. " \
+                "You must use MemoryRead on 'memory://#{file_path}' before editing it. " \
+                "This ensures you have the current content to match against.",
+            )
+          end
+
+          # Check if old_string exists in content
+          unless content.include?(old_string)
+            return validation_error(<<~ERROR.chomp)
+              old_string not found in memory entry. Make sure it matches exactly, including all whitespace and indentation.
+              Do not include line number prefixes from MemoryRead tool output.
+            ERROR
+          end
+
+          # Count occurrences
+          occurrences = content.scan(old_string).count
+
+          # If not replace_all and multiple occurrences, error
+          if !replace_all && occurrences > 1
+            return validation_error(<<~ERROR.chomp)
+              Found #{occurrences} occurrences of old_string.
+              Either provide more surrounding context to make the match unique, or use replace_all: true to replace all occurrences.
+            ERROR
+          end
+
+          # Perform replacement
+          new_content = if replace_all
+            content.gsub(old_string, new_string)
+          else
+            content.sub(old_string, new_string)
+          end
+
+          # Get existing entry metadata
+          entries = memory_storage.list
+          existing_entry = entries.find { |e| e[:path] == file_path }
+
+          # Write updated content back (preserving the title)
+          memory_storage.write(
+            file_path: file_path,
+            content: new_content,
+            title: existing_entry[:title],
+          )
+
+          # Build success message
+          replaced_count = replace_all ? occurrences : 1
+          "Successfully replaced #{replaced_count} occurrence(s) in memory://#{file_path}"
+        rescue ArgumentError => e
+          validation_error(e.message)
+        end
+
+        private
+
+        attr_reader :memory_storage
+
+        def validation_error(message)
+          "<tool_use_error>InputValidationError: #{message}</tool_use_error>"
+        end
+      end
+    end
+  end
+end

data/lib/swarm_sdk/tools/memory/memory_glob.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module SwarmSDK
+  module Tools
+    module Memory
+      # Tool for searching memory entries by glob pattern
+      #
+      # Finds memory entries matching a glob pattern (like filesystem glob).
+      # Each agent has its own isolated memory storage.
+      class MemoryGlob < RubyLLM::Tool
+        define_method(:name) { "MemoryGlob" }
+
+        description <<~DESC
+          Search your memory entries by glob pattern.
+          Works like filesystem glob - use * for wildcards, ** for recursive matching.
+          Use this to discover entries matching specific patterns.
+
+          Examples:
+          - "parallel/*" - all entries directly under parallel/
+          - "parallel/**" - all entries under parallel/ (recursive)
+          - "*/report" - all entries named "report" in any top-level directory
+          - "analysis/*/result_*" - entries like "analysis/foo/result_1"
+        DESC
+
+        param :pattern,
+          desc: "Glob pattern to match (e.g., '**/*.txt', 'parallel/*/task_*')",
+          required: true
+
+        class << self
+          # Create a MemoryGlob tool for a specific memory storage instance
+          #
+          # @param memory_storage [Stores::MemoryStorage] Per-agent memory storage instance
+          # @return [MemoryGlob] Tool instance
+          def create_for_memory(memory_storage)
+            new(memory_storage)
+          end
+        end
+
+        # Initialize with memory storage instance
+        #
+        # @param memory_storage [Stores::MemoryStorage] Per-agent memory storage instance
+        def initialize(memory_storage)
+          super() # Call RubyLLM::Tool's initialize
+          @memory_storage = memory_storage
+        end
+
+        # Execute the tool
+        #
+        # @param pattern [String] Glob pattern to match
+        # @return [String] Formatted list of matching entries
+        def execute(pattern:)
+          entries = memory_storage.glob(pattern: pattern)
+
+          if entries.empty?
+            return "No entries found matching pattern '#{pattern}'"
+          end
+
+          result = []
+          result << "Memory entries matching '#{pattern}' (#{entries.size} #{entries.size == 1 ? "entry" : "entries"}):"
+
+          entries.each do |entry|
+            result << "  memory://#{entry[:path]} - \"#{entry[:title]}\" (#{format_bytes(entry[:size])})"
+          end
+
+          result.join("\n")
+        rescue ArgumentError => e
+          validation_error(e.message)
+        end
+
+        private
+
+        attr_reader :memory_storage
+
+        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
+end

data/lib/swarm_sdk/tools/memory/memory_grep.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+module SwarmSDK
+  module Tools
+    module Memory
+      # Tool for searching memory content by pattern
+      #
+      # Searches content stored in memory entries using regex patterns.
+      # Each agent has its own isolated memory storage.
+      class MemoryGrep < RubyLLM::Tool
+        define_method(:name) { "MemoryGrep" }
+
+        description <<~DESC
+          Search your memory content by pattern (like grep).
+          Use regex patterns to search content within memory entries.
+          Returns matching entries and optionally line numbers and content.
+
+          Output modes:
+          - files_with_matches: Only list paths containing matches (default)
+          - content: Show matching lines with line numbers
+          - count: Show number of matches per file
+        DESC
+
+        param :pattern,
+          desc: "Regular expression pattern to search for",
+          required: true
+
+        param :case_insensitive,
+          desc: "Perform case-insensitive search (default: false)",
+          required: false
+
+        param :output_mode,
+          desc: "Output mode: 'files_with_matches' (default), 'content', or 'count'",
+          required: false
+
+        class << self
+          # Create a MemoryGrep tool for a specific memory storage instance
+          #
+          # @param memory_storage [Stores::MemoryStorage] Per-agent memory storage instance
+          # @return [MemoryGrep] Tool instance
+          def create_for_memory(memory_storage)
+            new(memory_storage)
+          end
+        end
+
+        # Initialize with memory storage instance
+        #
+        # @param memory_storage [Stores::MemoryStorage] Per-agent memory storage instance
+        def initialize(memory_storage)
+          super() # Call RubyLLM::Tool's initialize
+          @memory_storage = memory_storage
+        end
+
+        # Execute the tool
+        #
+        # @param pattern [String] Regex pattern to search for
+        # @param case_insensitive [Boolean] Whether to perform case-insensitive search
+        # @param output_mode [String] Output mode
+        # @return [String] Formatted search results
+        def execute(pattern:, case_insensitive: false, output_mode: "files_with_matches")
+          results = memory_storage.grep(
+            pattern: pattern,
+            case_insensitive: case_insensitive,
+            output_mode: output_mode,
+          )
+
+          format_results(results, pattern, output_mode)
+        rescue ArgumentError => e
+          validation_error(e.message)
+        rescue RegexpError => e
+          validation_error("Invalid regex pattern: #{e.message}")
+        end
+
+        private
+
+        attr_reader :memory_storage
+
+        def validation_error(message)
+          "<tool_use_error>InputValidationError: #{message}</tool_use_error>"
+        end
+
+        def format_results(results, pattern, output_mode)
+          case output_mode
+          when "files_with_matches"
+            format_files_with_matches(results, pattern)
+          when "content"
+            format_content(results, pattern)
+          when "count"
+            format_count(results, pattern)
+          else
+            validation_error("Invalid output_mode: #{output_mode}")
+          end
+        end
+
+        def format_files_with_matches(paths, pattern)
+          if paths.empty?
+            return "No matches found for pattern '#{pattern}'"
+          end
+
+          result = []
+          result << "Memory entries matching '#{pattern}' (#{paths.size} #{paths.size == 1 ? "entry" : "entries"}):"
+          paths.each do |path|
+            result << "  memory://#{path}"
+          end
+          result.join("\n")
+        end
+
+        def format_content(results, pattern)
+          if results.empty?
+            return "No matches found for pattern '#{pattern}'"
+          end
+
+          total_matches = results.sum { |r| r[:matches].size }
+          output = []
+          output << "Memory entries matching '#{pattern}' (#{results.size} #{results.size == 1 ? "entry" : "entries"}, #{total_matches} #{total_matches == 1 ? "match" : "matches"}):"
+          output << ""
+
+          results.each do |result|
+            output << "memory://#{result[:path]}:"
+            result[:matches].each do |match|
+              output << "  #{match[:line_number]}: #{match[:content]}"
+            end
+            output << ""
+          end
+
+          output.join("\n").rstrip
+        end
+
+        def format_count(results, pattern)
+          if results.empty?
+            return "No matches found for pattern '#{pattern}'"
+          end
+
+          total_matches = results.sum { |r| r[:count] }
+          output = []
+          output << "Memory entries matching '#{pattern}' (#{results.size} #{results.size == 1 ? "entry" : "entries"}, #{total_matches} total #{total_matches == 1 ? "match" : "matches"}):"
+
+          results.each do |result|
+            output << "  memory://#{result[:path]}: #{result[:count]} #{result[:count] == 1 ? "match" : "matches"}"
+          end
+
+          output.join("\n")
+        end
+      end
+    end
+  end
+end