swarm_sdk 2.0.4 → 2.0.5

data/lib/swarm_sdk/tools/stores/{scratchpad.rb → memory_storage.rb}

@@ -3,39 +3,33 @@
 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.
+      # MemoryStorage provides persistent, per-agent storage
       #
       # Features:
-      # - Session-scoped: Cleared when swarm execution completes
-      # - Shared: Any agent can read/write any scratchpad address
+      # - Per-agent: Each agent has its own isolated storage
+      # - Persistent: ALWAYS saves to JSON file
       # - 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)
-
-        # Initialize scratchpad with optional persistence
+      # - Thread-safe: Mutex-protected operations
+      class MemoryStorage < Storage
+        # Initialize memory storage with required persistence
         #
-        # @param persist_to [String, nil] Path to JSON file for persistence (nil = no persistence)
-        def initialize(persist_to: nil)
+        # @param persist_to [String] Path to JSON file for persistence (REQUIRED)
+        # @raise [ArgumentError] If persist_to is not provided
+        def initialize(persist_to:)
+          super() # Initialize parent Storage class
+          raise ArgumentError, "persist_to is required for MemoryStorage" if persist_to.nil? || persist_to.to_s.strip.empty?
+
           @entries = {}
           @total_size = 0
           @persist_to = persist_to
           @mutex = Mutex.new
 
-          # Load existing data if persistence is enabled
-          load_from_file if @persist_to && File.exist?(@persist_to)
+          # Load existing data if file exists
+          load_from_file if File.exist?(@persist_to)
         end
 
-        # Write content to scratchpad
+        # Write content to memory storage
         #
         # @param file_path [String] Path to store content
         # @param content [String] Content to store
@@ -63,7 +57,7 @@ module SwarmSDK
 
             # Check total size limit
             if new_total_size > MAX_TOTAL_SIZE
-              raise ArgumentError, "Scratchpad full (#{format_bytes(MAX_TOTAL_SIZE)} limit). " \
+              raise ArgumentError, "Memory storage 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."
@@ -73,7 +67,7 @@ module SwarmSDK
             entry = Entry.new(
               content: content,
               title: title,
-              created_at: Time.now,
+              updated_at: Time.now,
               size: content_size,
             )
 
@@ -81,14 +75,14 @@ module SwarmSDK
             @entries[file_path] = entry
             @total_size = new_total_size
 
-            # Persist to file if enabled
-            save_to_file if @persist_to
+            # Always persist to file
+            save_to_file
 
             entry
           end
         end
 
-        # Read content from scratchpad
+        # Read content from memory storage
         #
         # @param file_path [String] Path to read from
         # @raise [ArgumentError] If path not found
@@ -97,15 +91,38 @@ module SwarmSDK
           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
+          raise ArgumentError, "memory://#{file_path} not found" unless entry
 
           entry.content
         end
 
-        # List scratchpad entries, optionally filtered by prefix
+        # Delete a specific entry
+        #
+        # @param file_path [String] Path to delete
+        # @raise [ArgumentError] If path not found
+        # @return [void]
+        def delete(file_path:)
+          @mutex.synchronize do
+            raise ArgumentError, "file_path is required" if file_path.nil? || file_path.to_s.strip.empty?
+
+            entry = @entries[file_path]
+            raise ArgumentError, "memory://#{file_path} not found" unless entry
+
+            # Update total size
+            @total_size -= entry.size
+
+            # Remove entry
+            @entries.delete(file_path)
+
+            # Always persist to file
+            save_to_file
+          end
+        end
+
+        # List memory storage 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)
+        # @return [Array<Hash>] Array of entry metadata (path, title, size, updated_at)
         def list(prefix: nil)
           entries = @entries
 
@@ -114,21 +131,21 @@ module SwarmSDK
             entries = entries.select { |path, _| path.start_with?(prefix) }
           end
 
-          # Return metadata
+          # Return metadata sorted by path
           entries.map do |path, entry|
             {
               path: path,
               title: entry.title,
               size: entry.size,
-              created_at: entry.created_at,
+              updated_at: entry.updated_at,
             }
           end.sort_by { |e| e[:path] }
         end
 
-        # Search entries by glob pattern (like filesystem glob)
+        # Search entries by glob pattern
         #
         # @param pattern [String] Glob pattern (e.g., "**/*.txt", "parallel/*/task_*")
-        # @return [Array<Hash>] Array of matching entry metadata (path, title, size, created_at)
+        # @return [Array<Hash>] Array of matching entry metadata, sorted by most recent first
         def glob(pattern:)
           raise ArgumentError, "pattern is required" if pattern.nil? || pattern.to_s.strip.empty?
 
@@ -138,18 +155,18 @@ module SwarmSDK
           # Filter entries by pattern
           matching_entries = @entries.select { |path, _| regex.match?(path) }
 
-          # Return metadata sorted by path
+          # Return metadata sorted by most recent first
           matching_entries.map do |path, entry|
             {
               path: path,
               title: entry.title,
               size: entry.size,
-              created_at: entry.created_at,
+              updated_at: entry.updated_at,
             }
-          end.sort_by { |e| e[:path] }
+          end.sort_by { |e| -e[:updated_at].to_f }
         end
 
-        # Search entry content by pattern (like grep)
+        # Search entry content by pattern
         #
         # @param pattern [String] Regular expression pattern to search for
         # @param case_insensitive [Boolean] Whether to perform case-insensitive search
@@ -170,24 +187,24 @@ module SwarmSDK
               .sort
             matching_paths
           when "content"
-            # Return paths with matching lines
+            # Return paths with matching lines, sorted by most recent first
             results = []
             @entries.each do |path, entry|
               matching_lines = []
               entry.content.each_line.with_index(1) do |line, line_num|
                 matching_lines << { line_number: line_num, content: line.chomp } if regex.match?(line)
               end
-              results << { path: path, matches: matching_lines } unless matching_lines.empty?
+              results << { path: path, matches: matching_lines, updated_at: entry.updated_at } unless matching_lines.empty?
             end
-            results.sort_by { |r| r[:path] }
+            results.sort_by { |r| -r[:updated_at].to_f }.map { |r| r.except(:updated_at) }
           when "count"
-            # Return paths with match counts
+            # Return paths with match counts, sorted by most recent first
             results = []
             @entries.each do |path, entry|
               count = entry.content.scan(regex).size
-              results << { path: path, count: count } if count > 0
+              results << { path: path, count: count, updated_at: entry.updated_at } if count > 0
             end
-            results.sort_by { |r| r[:path] }
+            results.sort_by { |r| -r[:updated_at].to_f }.map { |r| r.except(:updated_at) }
           else
             raise ArgumentError, "Invalid output_mode: #{output_mode}. Must be 'files_with_matches', 'content', or 'count'"
           end
@@ -197,8 +214,11 @@ module SwarmSDK
         #
         # @return [void]
         def clear
-          @entries.clear
-          @total_size = 0
+          @mutex.synchronize do
+            @entries.clear
+            @total_size = 0
+            save_to_file
+          end
         end
 
         # Get current total size
@@ -215,46 +235,10 @@ module SwarmSDK
 
         private
 
-        # Convert glob pattern to regex
-        #
-        # @param pattern [String] Glob pattern
-        # @return [Regexp] Regular expression
-        def glob_to_regex(pattern)
-          # Escape special regex characters except glob wildcards
-          escaped = Regexp.escape(pattern)
-
-          # Convert glob wildcards to regex
-          # ** matches any number of directories (including zero)
-          escaped = escaped.gsub('\*\*', ".*")
-          # * matches anything except directory separator
-          escaped = escaped.gsub('\*', "[^/]*")
-          # ? matches single character except directory separator
-          escaped = escaped.gsub('\?', "[^/]")
-
-          # Anchor to start and end
-          Regexp.new("\\A#{escaped}\\z")
-        end
-
-        # 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
-
-        # Save scratchpad data to JSON file
+        # Save memory storage data to JSON file
         #
         # @return [void]
         def save_to_file
-          return unless @persist_to
-
           # Convert entries to serializable format
           data = {
             version: 1,
@@ -263,7 +247,7 @@ module SwarmSDK
               {
                 content: entry.content,
                 title: entry.title,
-                created_at: entry.created_at.iso8601,
+                updated_at: entry.updated_at.iso8601,
                 size: entry.size,
               }
             end,
@@ -279,11 +263,11 @@ module SwarmSDK
           File.rename(temp_file, @persist_to)
         end
 
-        # Load scratchpad data from JSON file
+        # Load memory storage data from JSON file
         #
         # @return [void]
         def load_from_file
-          return unless @persist_to && File.exist?(@persist_to)
+          return unless File.exist?(@persist_to)
 
           data = JSON.parse(File.read(@persist_to))
 
@@ -292,7 +276,7 @@ module SwarmSDK
             Entry.new(
               content: entry_data["content"],
               title: entry_data["title"],
-              created_at: Time.parse(entry_data["created_at"]),
+              updated_at: Time.parse(entry_data["updated_at"]),
               size: entry_data["size"],
             )
           end
@@ -301,12 +285,12 @@ module SwarmSDK
           @total_size = data["total_size"]
         rescue JSON::ParserError => e
           # If file is corrupted, log warning and start fresh
-          warn("Warning: Failed to load scratchpad from #{@persist_to}: #{e.message}. Starting with empty scratchpad.")
+          warn("Warning: Failed to load memory storage from #{@persist_to}: #{e.message}. Starting with empty storage.")
           @entries = {}
           @total_size = 0
         rescue StandardError => e
           # If any other error occurs, log warning and start fresh
-          warn("Warning: Failed to load scratchpad from #{@persist_to}: #{e.message}. Starting with empty scratchpad.")
+          warn("Warning: Failed to load memory storage from #{@persist_to}: #{e.message}. Starting with empty storage.")
           @entries = {}
           @total_size = 0
         end

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

@@ -0,0 +1,224 @@
+# frozen_string_literal: true
+
+module SwarmSDK
+  module Tools
+    module Stores
+      # ScratchpadStorage provides volatile, shared storage
+      #
+      # Features:
+      # - Shared: All agents share the same scratchpad
+      # - Volatile: NEVER persists - all data lost when process ends
+      # - Path-based: Hierarchical organization using file-path-like addresses
+      # - Metadata-rich: Stores content + title + timestamp + size
+      # - Thread-safe: Mutex-protected operations
+      #
+      # Use for temporary, cross-agent communication within a single session.
+      class ScratchpadStorage < Storage
+        # Initialize scratchpad storage (always volatile)
+        def initialize
+          super() # Initialize parent Storage class
+          @entries = {}
+          @total_size = 0
+          @mutex = Mutex.new
+        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:)
+          @mutex.synchronize do
+            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,
+              updated_at: Time.now,
+              size: content_size,
+            )
+
+            # Update storage
+            @entries[file_path] = entry
+            @total_size = new_total_size
+
+            entry
+          end
+        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
+
+        # Delete a specific entry
+        #
+        # @param file_path [String] Path to delete
+        # @raise [ArgumentError] If path not found
+        # @return [void]
+        def delete(file_path:)
+          @mutex.synchronize do
+            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
+
+            # Update total size
+            @total_size -= entry.size
+
+            # Remove entry
+            @entries.delete(file_path)
+          end
+        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, updated_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 sorted by path
+          entries.map do |path, entry|
+            {
+              path: path,
+              title: entry.title,
+              size: entry.size,
+              updated_at: entry.updated_at,
+            }
+          end.sort_by { |e| e[:path] }
+        end
+
+        # Search entries by glob pattern
+        #
+        # @param pattern [String] Glob pattern (e.g., "**/*.txt", "parallel/*/task_*")
+        # @return [Array<Hash>] Array of matching entry metadata, sorted by most recent first
+        def glob(pattern:)
+          raise ArgumentError, "pattern is required" if pattern.nil? || pattern.to_s.strip.empty?
+
+          # Convert glob pattern to regex
+          regex = glob_to_regex(pattern)
+
+          # Filter entries by pattern
+          matching_entries = @entries.select { |path, _| regex.match?(path) }
+
+          # Return metadata sorted by most recent first
+          matching_entries.map do |path, entry|
+            {
+              path: path,
+              title: entry.title,
+              size: entry.size,
+              updated_at: entry.updated_at,
+            }
+          end.sort_by { |e| -e[:updated_at].to_f }
+        end
+
+        # Search entry content by pattern
+        #
+        # @param pattern [String] Regular expression pattern to search for
+        # @param case_insensitive [Boolean] Whether to perform case-insensitive search
+        # @param output_mode [String] Output mode: "files_with_matches" (default), "content", or "count"
+        # @return [Array<Hash>, String] Results based on output_mode
+        def grep(pattern:, case_insensitive: false, output_mode: "files_with_matches")
+          raise ArgumentError, "pattern is required" if pattern.nil? || pattern.to_s.strip.empty?
+
+          # Create regex from pattern
+          flags = case_insensitive ? Regexp::IGNORECASE : 0
+          regex = Regexp.new(pattern, flags)
+
+          case output_mode
+          when "files_with_matches"
+            # Return just the paths that match
+            matching_paths = @entries.select { |_path, entry| regex.match?(entry.content) }
+              .map { |path, _| path }
+              .sort
+            matching_paths
+          when "content"
+            # Return paths with matching lines, sorted by most recent first
+            results = []
+            @entries.each do |path, entry|
+              matching_lines = []
+              entry.content.each_line.with_index(1) do |line, line_num|
+                matching_lines << { line_number: line_num, content: line.chomp } if regex.match?(line)
+              end
+              results << { path: path, matches: matching_lines, updated_at: entry.updated_at } unless matching_lines.empty?
+            end
+            results.sort_by { |r| -r[:updated_at].to_f }.map { |r| r.except(:updated_at) }
+          when "count"
+            # Return paths with match counts, sorted by most recent first
+            results = []
+            @entries.each do |path, entry|
+              count = entry.content.scan(regex).size
+              results << { path: path, count: count, updated_at: entry.updated_at } if count > 0
+            end
+            results.sort_by { |r| -r[:updated_at].to_f }.map { |r| r.except(:updated_at) }
+          else
+            raise ArgumentError, "Invalid output_mode: #{output_mode}. Must be 'files_with_matches', 'content', or 'count'"
+          end
+        end
+
+        # Clear all entries
+        #
+        # @return [void]
+        def clear
+          @mutex.synchronize do
+            @entries.clear
+            @total_size = 0
+          end
+        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
+      end
+    end
+  end
+end

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

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+module SwarmSDK
+  module Tools
+    module Stores
+      # Abstract base class for hierarchical key-value storage with metadata
+      #
+      # Provides session-scoped storage for agents with path-based organization.
+      # Subclasses implement persistence behavior (volatile vs persistent).
+      #
+      # Features:
+      # - Path-based: Hierarchical organization using file-path-like addresses
+      # - Metadata-rich: Stores content + title + timestamp + size
+      # - Search capabilities: Glob patterns and grep-style content search
+      # - Thread-safe: Mutex-protected operations
+      class Storage
+        # Maximum size per entry (1MB)
+        MAX_ENTRY_SIZE = 1_000_000
+
+        # Maximum total storage size (100MB)
+        MAX_TOTAL_SIZE = 100_000_000
+
+        # Represents a single storage entry with metadata
+        Entry = Struct.new(:content, :title, :updated_at, :size, keyword_init: true)
+
+        # Initialize storage
+        #
+        # Subclasses should call super() in their initialize method.
+        # This base implementation does nothing - it exists only to satisfy RuboCop.
+        def initialize
+          # Base class initialization - subclasses implement their own logic
+        end
+
+        # Write content to storage
+        #
+        # @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 NotImplementedError, "Subclass must implement #write"
+        end
+
+        # Read content from storage
+        #
+        # @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 NotImplementedError, "Subclass must implement #read"
+        end
+
+        # Delete a specific entry
+        #
+        # @param file_path [String] Path to delete
+        # @raise [ArgumentError] If path not found
+        # @return [void]
+        def delete(file_path:)
+          raise NotImplementedError, "Subclass must implement #delete"
+        end
+
+        # List entries, optionally filtered by prefix
+        #
+        # @param prefix [String, nil] Filter by path prefix
+        # @return [Array<Hash>] Array of entry metadata (path, title, size, updated_at)
+        def list(prefix: nil)
+          raise NotImplementedError, "Subclass must implement #list"
+        end
+
+        # Search entries by glob pattern
+        #
+        # @param pattern [String] Glob pattern (e.g., "**/*.txt", "parallel/*/task_*")
+        # @return [Array<Hash>] Array of matching entry metadata, sorted by most recent first
+        def glob(pattern:)
+          raise NotImplementedError, "Subclass must implement #glob"
+        end
+
+        # Search entry content by pattern
+        #
+        # @param pattern [String] Regular expression pattern to search for
+        # @param case_insensitive [Boolean] Whether to perform case-insensitive search
+        # @param output_mode [String] Output mode: "files_with_matches" (default), "content", or "count"
+        # @return [Array<Hash>, String] Results based on output_mode
+        def grep(pattern:, case_insensitive: false, output_mode: "files_with_matches")
+          raise NotImplementedError, "Subclass must implement #grep"
+        end
+
+        # Clear all entries
+        #
+        # @return [void]
+        def clear
+          raise NotImplementedError, "Subclass must implement #clear"
+        end
+
+        # Get current total size
+        #
+        # @return [Integer] Total size in bytes
+        def total_size
+          raise NotImplementedError, "Subclass must implement #total_size"
+        end
+
+        # Get number of entries
+        #
+        # @return [Integer] Number of entries
+        def size
+          raise NotImplementedError, "Subclass must implement #size"
+        end
+
+        protected
+
+        # 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
+
+        # Convert glob pattern to regex
+        #
+        # @param pattern [String] Glob pattern
+        # @return [Regexp] Regular expression
+        def glob_to_regex(pattern)
+          # Escape special regex characters except glob wildcards
+          escaped = Regexp.escape(pattern)
+
+          # Convert glob wildcards to regex
+          # ** matches any number of directories (including zero)
+          escaped = escaped.gsub('\*\*', ".*")
+          # * matches anything except directory separator
+          escaped = escaped.gsub('\*', "[^/]*")
+          # ? matches single character except directory separator
+          escaped = escaped.gsub('\?', "[^/]")
+
+          # Anchor to start and end
+          Regexp.new("\\A#{escaped}\\z")
+        end
+      end
+    end
+  end
+end