swarm_memory 2.1.1 → 2.1.3

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

@@ -3,39 +3,74 @@
 module SwarmSDK
   module Tools
     module Stores
-      # ReadTracker manages read-file tracking for all agents
+      # ReadTracker manages read-file tracking for all agents with content digest verification
       #
       # 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.
+      # during their conversation along with SHA256 digests of the content. This enables
+      # enforcement of the "read-before-write" and "read-before-edit" rules that ensure
+      # agents have context before modifying files, AND prevents editing files that have
+      # changed externally since being read.
       #
-      # Each agent maintains an independent set of read files, keyed by agent identifier.
+      # Each agent maintains an independent map of read files to content digests.
       module ReadTracker
-        @read_files = {}
+        @read_files = {} # { agent_id => { file_path => sha256_digest } }
         @mutex = Mutex.new
 
         class << self
-          # Register that an agent has read a file
+          # Register that an agent has read a file with content digest
           #
           # @param agent_id [Symbol] The agent identifier
           # @param file_path [String] The absolute path to the file
-          def register_read(agent_id, file_path)
+          # @param content [String] File content (for digest calculation)
+          # @return [String] The calculated SHA256 digest
+          def register_read(agent_id, file_path, content)
             @mutex.synchronize do
-              @read_files[agent_id] ||= Set.new
-              @read_files[agent_id] << File.expand_path(file_path)
+              @read_files[agent_id] ||= {}
+              digest = Digest::SHA256.hexdigest(content)
+              @read_files[agent_id][File.expand_path(file_path)] = digest
+              digest
             end
           end
 
-          # Check if an agent has read a file
+          # Check if an agent has read a file AND content hasn't changed
           #
           # @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
+          # @return [Boolean] true if agent read file and content matches
           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))
+              expanded_path = File.expand_path(file_path)
+              stored_digest = @read_files[agent_id][expanded_path]
+              return false unless stored_digest
+
+              # Check if file still exists and matches stored digest
+              return false unless File.exist?(expanded_path)
+
+              current_digest = Digest::SHA256.hexdigest(File.read(expanded_path))
+              current_digest == stored_digest
+            end
+          end
+
+          # Get all read files with digests for snapshot
+          #
+          # @param agent_id [Symbol] The agent identifier
+          # @return [Hash] { file_path => digest }
+          def get_read_files(agent_id)
+            @mutex.synchronize do
+              @read_files[agent_id]&.dup || {}
+            end
+          end
+
+          # Restore read files with digests from snapshot
+          #
+          # @param agent_id [Symbol] The agent identifier
+          # @param files_with_digests [Hash] { file_path => digest }
+          # @return [void]
+          def restore_read_files(agent_id, files_with_digests)
+            @mutex.synchronize do
+              @read_files[agent_id] = files_with_digests.dup
             end
           end
 

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

@@ -218,6 +218,51 @@ module SwarmSDK
         def size
           @entries.size
         end
+
+        # Get all entries with content for snapshot
+        #
+        # Thread-safe method that returns a copy of all entries.
+        # Used by snapshot/restore functionality.
+        #
+        # @return [Hash] { path => Entry }
+        def all_entries
+          @mutex.synchronize do
+            @entries.dup
+          end
+        end
+
+        # Restore entries from snapshot
+        #
+        # Restores entries directly without using write() to preserve timestamps.
+        # This ensures entry ordering and metadata accuracy after restore.
+        #
+        # @param entries_data [Hash] { path => { content:, title:, updated_at:, size: } }
+        # @return [void]
+        def restore_entries(entries_data)
+          @mutex.synchronize do
+            entries_data.each do |path, data|
+              # Handle both symbol and string keys from JSON
+              content = data[:content] || data["content"]
+              title = data[:title] || data["title"]
+              updated_at_str = data[:updated_at] || data["updated_at"]
+
+              # Parse timestamp from ISO8601 string
+              updated_at = Time.parse(updated_at_str)
+
+              # Create entry with preserved timestamp
+              entry = Entry.new(
+                content: content,
+                title: title,
+                updated_at: updated_at,
+                size: content.bytesize,
+              )
+
+              # Update storage
+              @entries[path] = entry
+              @total_size += entry.size
+            end
+          end
+        end
       end
     end
   end

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

@@ -14,11 +14,11 @@ module SwarmSDK
       # - 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 size per entry (3MB)
+        MAX_ENTRY_SIZE = 3_000_000
 
-        # Maximum total storage size (100MB)
-        MAX_TOTAL_SIZE = 100_000_000
+        # Maximum total storage size (100GB)
+        MAX_TOTAL_SIZE = 100_000_000_000
 
         # Represents a single storage entry with metadata
         Entry = Struct.new(:content, :title, :updated_at, :size, keyword_init: true)

data/lib/swarm_sdk/tools/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

@@ -8,17 +8,17 @@ module SwarmSDK
     # 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.
+        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 +27,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 +73,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/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.1"
+  VERSION = "2.2.0"
 end