swarm_memory 2.1.2 → 2.1.3

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.2"
+  VERSION = "2.2.0"
 end

data/lib/swarm_sdk.rb

@@ -26,6 +26,8 @@ loader.push_dir("#{__dir__}/swarm_sdk", namespace: SwarmSDK)
 loader.inflector = Zeitwerk::GemInflector.new(__FILE__)
 loader.inflector.inflect(
   "cli" => "CLI",
+  "llm_instrumentation_middleware" => "LLMInstrumentationMiddleware",
+  "mcp" => "MCP",
   "openai_with_responses" => "OpenAIWithResponses",
 )
 loader.setup
@@ -44,8 +46,176 @@ module SwarmSDK
     attr_accessor :settings
 
     # Main entry point for DSL
-    def build(&block)
-      Swarm::Builder.build(&block)
+    def build(allow_filesystem_tools: nil, &block)
+      Swarm::Builder.build(allow_filesystem_tools: allow_filesystem_tools, &block)
+    end
+
+    # Validate YAML configuration without creating a swarm
+    #
+    # Performs comprehensive validation of YAML configuration including:
+    # - YAML syntax
+    # - Required fields (version, swarm name, lead, agents)
+    # - Agent configurations (description, directory existence)
+    # - Circular dependencies
+    # - File references (agent_file paths)
+    # - Hook configurations
+    #
+    # @param yaml_content [String] YAML configuration content
+    # @param base_dir [String, Pathname] Base directory for resolving agent file paths (default: Dir.pwd)
+    # @return [Array<Hash>] Array of error hashes (empty if valid)
+    #
+    # @example Validate YAML string
+    #   errors = SwarmSDK.validate(yaml_content)
+    #   if errors.empty?
+    #     puts "Configuration is valid!"
+    #   else
+    #     errors.each do |error|
+    #       puts "#{error[:field]}: #{error[:message]}"
+    #     end
+    #   end
+    #
+    # @example Error hash structure
+    #   {
+    #     type: :missing_field,           # Error type
+    #     field: "swarm.agents.backend.description",  # JSON-style path to field
+    #     message: "Agent 'backend' missing required 'description' field",
+    #     agent: "backend"                # Optional, present if error is agent-specific
+    #   }
+    def validate(yaml_content, base_dir: Dir.pwd)
+      errors = []
+
+      begin
+        config = Configuration.new(yaml_content, base_dir: base_dir)
+        config.load_and_validate
+
+        # Build swarm to trigger DSL validation
+        # This catches errors from Agent::Definition, Builder, etc.
+        config.to_swarm
+      rescue ConfigurationError, CircularDependencyError => e
+        errors << parse_configuration_error(e)
+      rescue StandardError => e
+        errors << {
+          type: :unknown_error,
+          field: nil,
+          message: e.message,
+        }
+      end
+
+      errors
+    end
+
+    # Validate YAML configuration file
+    #
+    # Convenience method that reads the file and validates the content.
+    #
+    # @param path [String, Pathname] Path to YAML configuration file
+    # @return [Array<Hash>] Array of error hashes (empty if valid)
+    #
+    # @example
+    #   errors = SwarmSDK.validate_file("config.yml")
+    #   if errors.empty?
+    #     puts "Valid configuration!"
+    #     swarm = SwarmSDK.load_file("config.yml")
+    #   else
+    #     errors.each { |e| puts "Error: #{e[:message]}" }
+    #   end
+    def validate_file(path)
+      path = Pathname.new(path).expand_path
+
+      unless path.exist?
+        return [{
+          type: :file_not_found,
+          field: nil,
+          message: "Configuration file not found: #{path}",
+        }]
+      end
+
+      yaml_content = File.read(path)
+      base_dir = path.dirname
+
+      validate(yaml_content, base_dir: base_dir)
+    rescue StandardError => e
+      [{
+        type: :file_read_error,
+        field: nil,
+        message: "Error reading file: #{e.message}",
+      }]
+    end
+
+    # Load swarm from YAML string
+    #
+    # This is the primary programmatic API for loading YAML configurations.
+    # For file-based loading, use SwarmSDK.load_file for convenience.
+    #
+    # @param yaml_content [String] YAML configuration content
+    # @param base_dir [String, Pathname] Base directory for resolving agent file paths (default: Dir.pwd)
+    # @return [Swarm, NodeOrchestrator] Configured swarm or orchestrator instance
+    # @raise [ConfigurationError] If YAML is invalid or configuration is incorrect
+    #
+    # @example Load from YAML string
+    #   yaml = <<~YAML
+    #     version: 2
+    #     swarm:
+    #       name: "Dev Team"
+    #       lead: backend
+    #       agents:
+    #         backend:
+    #           description: "Backend developer"
+    #           model: "gpt-4"
+    #           agent_file: "agents/backend.md"  # Resolved relative to base_dir
+    #   YAML
+    #
+    #   swarm = SwarmSDK.load(yaml, base_dir: "/path/to/project")
+    #   result = swarm.execute("Build authentication")
+    #
+    # @example Load with default base_dir (Dir.pwd)
+    #   yaml = File.read("config.yml")
+    #   swarm = SwarmSDK.load(yaml)  # base_dir defaults to Dir.pwd
+    def load(yaml_content, base_dir: Dir.pwd, allow_filesystem_tools: nil)
+      config = Configuration.new(yaml_content, base_dir: base_dir)
+      config.load_and_validate
+      swarm = config.to_swarm(allow_filesystem_tools: allow_filesystem_tools)
+
+      # Apply hooks if any are configured (YAML-only feature)
+      if hooks_configured?(config)
+        Hooks::Adapter.apply_hooks(swarm, config)
+      end
+
+      # Store config reference for agent hooks (applied during initialize_agents)
+      swarm.config_for_hooks = config
+
+      swarm
+    end
+
+    # Load swarm from YAML file (convenience method)
+    #
+    # Reads the YAML file and uses the file's directory as the base directory
+    # for resolving agent file paths. This is the recommended method for
+    # loading swarms from configuration files.
+    #
+    # @param path [String, Pathname] Path to YAML configuration file
+    # @return [Swarm, NodeOrchestrator] Configured swarm or orchestrator instance
+    # @raise [ConfigurationError] If file not found or configuration invalid
+    #
+    # @example
+    #   swarm = SwarmSDK.load_file("config.yml")
+    #   result = swarm.execute("Build authentication")
+    #
+    # @example With absolute path
+    #   swarm = SwarmSDK.load_file("/absolute/path/config.yml")
+    def load_file(path, allow_filesystem_tools: nil)
+      config = Configuration.load_file(path)
+      swarm = config.to_swarm(allow_filesystem_tools: allow_filesystem_tools)
+
+      # Apply hooks if any are configured (YAML-only feature)
+      if hooks_configured?(config)
+        Hooks::Adapter.apply_hooks(swarm, config)
+      end
+
+      # Store config reference for agent hooks (applied during initialize_agents)
+      swarm.config_for_hooks = config
+
+      swarm
     end
 
     # Configure SwarmSDK global settings
@@ -62,6 +232,180 @@ module SwarmSDK
     # Alias for backward compatibility
     alias_method :configuration, :settings
     alias_method :reset_configuration!, :reset_settings!
+
+    private
+
+    # Check if hooks are configured in the configuration
+    #
+    # @param config [Configuration] Configuration instance
+    # @return [Boolean] true if any hooks are configured
+    def hooks_configured?(config)
+      config.swarm_hooks.any? ||
+        config.all_agents_hooks.any? ||
+        config.agents.any? { |_, agent_config| agent_config[:hooks]&.any? }
+    end
+
+    # Parse configuration error and extract structured information
+    #
+    # Attempts to extract field path and agent name from error messages.
+    # Returns a structured error hash with type, field, message, and optional agent.
+    #
+    # @param error [StandardError] The caught error
+    # @return [Hash] Structured error hash
+    def parse_configuration_error(error)
+      message = error.message
+      error_hash = { message: message }
+
+      # Detect error type and extract field information
+      case message
+      # YAML syntax errors
+      when /Invalid YAML syntax/i
+        error_hash.merge!(
+          type: :syntax_error,
+          field: nil,
+        )
+
+      # Missing version field
+      when /Missing 'version' field/i
+        error_hash.merge!(
+          type: :missing_field,
+          field: "version",
+        )
+
+      # Invalid version
+      when /SwarmSDK requires version: (\d+)/i
+        error_hash.merge!(
+          type: :invalid_value,
+          field: "version",
+        )
+
+      # Missing swarm fields
+      when /Missing '(\w+)' field in swarm configuration/i
+        field_name = Regexp.last_match(1)
+        error_hash.merge!(
+          type: :missing_field,
+          field: "swarm.#{field_name}",
+        )
+
+      # Agent missing required field
+      when /Agent '([^']+)' missing required '([^']+)' field/i
+        agent_name = Regexp.last_match(1)
+        field_name = Regexp.last_match(2)
+        error_hash.merge!(
+          type: :missing_field,
+          field: "swarm.agents.#{agent_name}.#{field_name}",
+          agent: agent_name,
+        )
+
+      # Directory does not exist
+      when /Directory '([^']+)' for agent '([^']+)' does not exist/i
+        agent_name = Regexp.last_match(2)
+        error_hash.merge!(
+          type: :directory_not_found,
+          field: "swarm.agents.#{agent_name}.directory",
+          agent: agent_name,
+        )
+
+      # Error loading agent from file (must come before "Agent file not found")
+      when /Error loading agent '([^']+)' from file/i
+        agent_name = Regexp.last_match(1)
+        error_hash.merge!(
+          type: :file_load_error,
+          field: "swarm.agents.#{agent_name}.agent_file",
+          agent: agent_name,
+        )
+
+      # Agent file not found
+      when /Agent file not found: (.+)/i
+        # Try to extract agent name from the error context if available
+        error_hash.merge!(
+          type: :file_not_found,
+          field: nil, # We don't know which agent without more context
+        )
+
+      # Lead agent not found
+      when /Lead agent '([^']+)' not found in agents/i
+        error_hash.merge!(
+          type: :invalid_reference,
+          field: "swarm.lead",
+        )
+
+      # Unknown agent in connections (old format)
+      when /Agent '([^']+)' has connection to unknown agent '([^']+)'/i
+        agent_name = Regexp.last_match(1)
+        error_hash.merge!(
+          type: :invalid_reference,
+          field: "swarm.agents.#{agent_name}.delegates_to",
+          agent: agent_name,
+        )
+
+      # Unknown agent in connections (new format with composable swarms)
+      when /Agent '([^']+)' delegates to unknown target '([^']+)'/i
+        agent_name = Regexp.last_match(1)
+        error_hash.merge!(
+          type: :invalid_reference,
+          field: "swarm.agents.#{agent_name}.delegates_to",
+          agent: agent_name,
+        )
+
+      # Circular dependency
+      when /Circular dependency detected/i
+        error_hash.merge!(
+          type: :circular_dependency,
+          field: nil,
+        )
+
+      # Configuration file not found
+      when /Configuration file not found/i
+        error_hash.merge!(
+          type: :file_not_found,
+          field: nil,
+        )
+
+      # Invalid hook event
+      when /Invalid hook event '([^']+)' for agent '([^']+)'/i
+        agent_name = Regexp.last_match(2)
+        error_hash.merge!(
+          type: :invalid_value,
+          field: "swarm.agents.#{agent_name}.hooks",
+          agent: agent_name,
+        )
+
+      # api_version validation error
+      when /Agent '([^']+)' has api_version set, but provider is/i
+        agent_name = Regexp.last_match(1)
+        error_hash.merge!(
+          type: :invalid_value,
+          field: "swarm.agents.#{agent_name}.api_version",
+          agent: agent_name,
+        )
+
+      # api_version invalid value
+      when /Agent '([^']+)' has invalid api_version/i
+        agent_name = Regexp.last_match(1)
+        error_hash.merge!(
+          type: :invalid_value,
+          field: "swarm.agents.#{agent_name}.api_version",
+          agent: agent_name,
+        )
+
+      # No agents defined
+      when /No agents defined/i
+        error_hash.merge!(
+          type: :missing_field,
+          field: "swarm.agents",
+        )
+
+      # Default: unknown error
+      else
+        error_hash.merge!(
+          type: :validation_error,
+          field: nil,
+        )
+      end
+
+      error_hash.compact
+    end
   end
 
   # Settings class for SwarmSDK global settings (not to be confused with Configuration for YAML loading)
@@ -69,17 +413,33 @@ module SwarmSDK
     # WebFetch tool LLM processing configuration
     attr_accessor :webfetch_provider, :webfetch_model, :webfetch_base_url, :webfetch_max_tokens
 
+    # Filesystem tools control
+    attr_accessor :allow_filesystem_tools
+
     def initialize
       @webfetch_provider = nil
       @webfetch_model = nil
       @webfetch_base_url = nil
       @webfetch_max_tokens = 4096
+      @allow_filesystem_tools = parse_env_bool("SWARM_SDK_ALLOW_FILESYSTEM_TOOLS", default: true)
     end
 
     # Check if WebFetch LLM processing is enabled
     def webfetch_llm_enabled?
       !@webfetch_provider.nil? && !@webfetch_model.nil?
     end
+
+    private
+
+    def parse_env_bool(key, default:)
+      return default unless ENV.key?(key)
+
+      value = ENV[key].to_s.downcase
+      return true if ["true", "yes", "1", "on", "enabled"].include?(value)
+      return false if ["false", "no", "0", "off", "disabled"].include?(value)
+
+      default
+    end
   end
 
   # Initialize default settings
@@ -132,22 +492,3 @@ RubyLLM.configure do |config|
   config.gpustack_api_base ||= ENV["GPUSTACK_API_BASE"]
   config.gpustack_api_key ||= ENV["GPUSTACK_API_KEY"]
 end
-
-# monkey patches
-# ruby_llm/mcp
-# - add `id` when sending "notifications/initialized" message: https://github.com/patvice/ruby_llm-mcp/issues/65
-# - remove `to_sym` on MCP parameter type: https://github.com/patvice/ruby_llm-mcp/issues/62#issuecomment-3421488406
-require "ruby_llm/mcp/notifications/initialize"
-require "ruby_llm/mcp/parameter"
-
-module RubyLLM
-  module MCP
-    module Notifications
-      class Initialize
-        def call
-          @coordinator.request(notification_body, add_id: true, wait_for_response: false)
-        end
-      end
-    end
-  end
-end