swarm_memory 2.1.5 → 2.1.6

data/lib/swarm_sdk/tools/todo_write.rb

@@ -1,235 +0,0 @@
-# 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
-      # Factory pattern: declare what parameters this tool needs for instantiation
-      class << self
-        def creation_requirements
-          [:agent_name]
-        end
-      end
-
-      description <<~DESC
-        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 (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 execution
-
-        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 execution
-
-        ## 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 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
-
-      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")}
-          Keep going 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

data/lib/swarm_sdk/tools/web_fetch.rb

@@ -1,262 +0,0 @@
-# frozen_string_literal: true
-
-module SwarmSDK
-  module Tools
-    # WebFetch tool for fetching and processing web content
-    #
-    # Fetches content from URLs, converts HTML to markdown, and processes it
-    # using an AI model to extract information based on a provided prompt.
-    class WebFetch < RubyLLM::Tool
-      def initialize
-        super()
-        @cache = {}
-        @cache_ttl = 900 # 15 minutes in seconds
-        @llm_enabled = SwarmSDK.settings.webfetch_llm_enabled?
-      end
-
-      def name
-        "WebFetch"
-      end
-
-      description <<~DESC
-        - Fetches content from a specified URL and converts it to markdown
-        - Optionally processes the content with an LLM if configured
-        - Fetches the URL content, converts HTML to markdown
-        - Returns markdown content or LLM analysis (based on configuration)
-        - Use this tool when you need to retrieve and analyze web content
-
-        Usage notes:
-          - IMPORTANT: If an MCP-provided web fetch tool is available, prefer using that tool instead of this one, as it may have fewer restrictions. All MCP-provided tools start with "mcp__".
-          - The URL must be a fully-formed valid URL
-          - HTTP URLs will be automatically upgraded to HTTPS
-          - This tool is read-only and does not modify any files
-          - Content will be truncated if very large
-          - Includes a self-cleaning 15-minute cache for faster responses
-          - When a URL redirects to a different host, the tool will inform you and provide the redirect URL in a special format. You should then make a new WebFetch request with the redirect URL to fetch the content.
-
-        LLM Processing:
-          - When SwarmSDK is configured with webfetch_provider and webfetch_model, the 'prompt' parameter is required
-          - The tool will process the markdown content with the configured LLM using your prompt
-          - Without this configuration, the tool returns raw markdown and the 'prompt' parameter is optional (ignored if provided)
-          - Configure with: SwarmSDK.configure { |c| c.webfetch_provider = "anthropic"; c.webfetch_model = "claude-3-5-haiku-20241022" }
-      DESC
-
-      param :url,
-        type: "string",
-        desc: "The URL to fetch content from",
-        required: true
-
-      param :prompt,
-        type: "string",
-        desc: "The prompt to run on the fetched content. Required when SwarmSDK is configured with webfetch_provider and webfetch_model. Optional otherwise (ignored if LLM processing not configured).",
-        required: false
-
-      # Backward compatibility aliases - use Defaults module for new code
-      MAX_CONTENT_LENGTH = Defaults::Limits::WEB_FETCH_CHARACTERS
-      USER_AGENT = "SwarmSDK WebFetch Tool (https://github.com/parruda/claude-swarm)"
-      TIMEOUT = Defaults::Timeouts::WEB_FETCH_SECONDS
-
-      def execute(url:, prompt: nil)
-        # Validate inputs
-        return validation_error("url is required") if url.nil? || url.empty?
-
-        # Validate prompt when LLM processing is enabled
-        if @llm_enabled && (prompt.nil? || prompt.empty?)
-          return validation_error("prompt is required when LLM processing is configured")
-        end
-
-        # Validate and normalize URL
-        normalized_url = normalize_url(url)
-        return validation_error("Invalid URL format: #{url}") unless normalized_url
-
-        # Check cache first (cache key includes prompt if LLM is enabled)
-        cache_key = @llm_enabled ? "#{normalized_url}:#{prompt}" : normalized_url
-        cached = get_from_cache(cache_key)
-        return cached if cached
-
-        # Fetch the URL
-        fetch_result = fetch_url(normalized_url)
-        return fetch_result if fetch_result.is_a?(String) && fetch_result.start_with?("Error")
-
-        # Check for redirects to different hosts
-        if fetch_result[:redirect_url] && different_host?(normalized_url, fetch_result[:redirect_url])
-          return format_redirect_message(fetch_result[:redirect_url])
-        end
-
-        # Convert HTML to markdown
-        markdown_content = html_to_markdown(fetch_result[:body])
-
-        # Truncate if too long
-        if markdown_content.length > MAX_CONTENT_LENGTH
-          markdown_content = markdown_content[0...MAX_CONTENT_LENGTH]
-          markdown_content += "\n\n[Content truncated due to length]"
-        end
-
-        # Process with AI model if LLM is enabled, otherwise return markdown
-        result = if @llm_enabled
-          process_with_llm(markdown_content, prompt, normalized_url)
-        else
-          markdown_content
-        end
-
-        # Cache the result
-        store_in_cache(cache_key, result)
-
-        result
-      rescue StandardError => e
-        error("Unexpected error fetching URL: #{e.class.name} - #{e.message}")
-      end
-
-      private
-
-      def validation_error(message)
-        "<tool_use_error>InputValidationError: #{message}</tool_use_error>"
-      end
-
-      def error(message)
-        "Error: #{message}"
-      end
-
-      def normalize_url(url)
-        # Upgrade HTTP to HTTPS
-        url = url.sub(%r{^http://}, "https://")
-
-        # Validate URL format
-        uri = URI.parse(url)
-        return unless uri.is_a?(URI::HTTP) || uri.is_a?(URI::HTTPS)
-        return unless uri.host
-
-        uri.to_s
-      rescue URI::InvalidURIError
-        nil
-      end
-
-      def different_host?(url1, url2)
-        uri1 = URI.parse(url1)
-        uri2 = URI.parse(url2)
-        uri1.host != uri2.host
-      rescue URI::InvalidURIError
-        false
-      end
-
-      def fetch_url(url)
-        require "faraday"
-        require "faraday/follow_redirects"
-
-        response = Faraday.new(url: url) do |conn|
-          conn.request(:url_encoded)
-          conn.response(:follow_redirects, limit: 5)
-          conn.adapter(Faraday.default_adapter)
-          conn.options.timeout = TIMEOUT
-          conn.options.open_timeout = TIMEOUT
-        end.get do |req|
-          req.headers["User-Agent"] = USER_AGENT
-          req.headers["Accept"] = "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8"
-        end
-
-        unless response.success?
-          return error("HTTP #{response.status}: Failed to fetch URL")
-        end
-
-        # Check final URL for redirects
-        final_url = response.env.url.to_s
-        redirect_url = final_url if final_url != url
-
-        {
-          body: response.body,
-          redirect_url: redirect_url,
-        }
-      rescue Faraday::TimeoutError
-        error("Request timed out after #{TIMEOUT} seconds")
-      rescue Faraday::ConnectionFailed => e
-        error("Connection failed: #{e.message}")
-      rescue StandardError => e
-        error("Failed to fetch URL: #{e.class.name} - #{e.message}")
-      end
-
-      def html_to_markdown(html)
-        # Use HtmlConverter to handle conversion with optional reverse_markdown gem
-        converter = DocumentConverters::HtmlConverter.new
-        converter.convert_string(html)
-      end
-
-      def process_with_llm(content, prompt, url)
-        # Use configured model for processing
-        # Format the prompt to include the content
-        full_prompt = <<~PROMPT
-          You are analyzing content from the URL: #{url}
-
-          User request: #{prompt}
-
-          Content:
-          #{content}
-
-          Please respond to the user's request based on the content above.
-        PROMPT
-
-        # Get settings
-        config = SwarmSDK.settings
-
-        # Build chat with configured provider and model
-        chat_params = {
-          model: config.webfetch_model,
-          provider: config.webfetch_provider.to_sym,
-        }
-        chat_params[:base_url] = config.webfetch_base_url if config.webfetch_base_url
-
-        chat = RubyLLM.chat(**chat_params).with_params(max_tokens: config.webfetch_max_tokens)
-
-        response = chat.ask(full_prompt)
-
-        # Extract the text response
-        response_text = response.content
-        return error("Failed to process content with LLM: No response text") unless response_text
-
-        response_text
-      rescue StandardError => e
-        error("Failed to process content with LLM: #{e.class.name} - #{e.message}")
-      end
-
-      def format_redirect_message(redirect_url)
-        <<~MESSAGE
-          This URL redirected to a different host.
-
-          Redirect URL: #{redirect_url}
-
-          <system-reminder>
-          The requested URL redirected to a different host. To fetch the content from the redirect URL,
-          make a new WebFetch request with the redirect URL provided above.
-          </system-reminder>
-        MESSAGE
-      end
-
-      def get_from_cache(key)
-        entry = @cache[key]
-        return unless entry
-
-        # Check if cache entry is still valid
-        if Time.now.to_i - entry[:timestamp] > @cache_ttl
-          @cache.delete(key)
-          return
-        end
-
-        entry[:value]
-      end
-
-      def store_in_cache(key, value)
-        # Clean old cache entries
-        clean_cache
-
-        @cache[key] = {
-          value: value,
-          timestamp: Time.now.to_i,
-        }
-      end
-
-      def clean_cache
-        now = Time.now.to_i
-        @cache.delete_if { |_key, entry| now - entry[:timestamp] > @cache_ttl }
-      end
-    end
-  end
-end

data/lib/swarm_sdk/tools/write.rb

@@ -1,112 +0,0 @@
-# frozen_string_literal: true
-
-module SwarmSDK
-  module Tools
-    # Write tool for writing content to files
-    #
-    # Creates new files or overwrites existing files.
-    # Enforces read-before-write rule for existing files.
-    # Includes validation and usage guidelines via system reminders.
-    class Write < RubyLLM::Tool
-      include PathResolver
-
-      # Factory pattern: declare what parameters this tool needs for instantiation
-      class << self
-        def creation_requirements
-          [:agent_name, :directory]
-        end
-      end
-
-      description <<~DESC
-        Writes a file to the local filesystem.
-        This tool will overwrite the existing file if there is one at the provided path.
-        If this is an existing file, you MUST use the Read tool first to read the file's contents.
-        This tool will fail if you did not read the file first.
-        ALWAYS prefer editing existing files in the codebase. NEVER write new files unless explicitly required.
-        NEVER proactively create documentation files (*.md) or README files. Only create documentation files if explicitly requested by the User.
-        Only use emojis if the user explicitly requests it. Avoid writing emojis to files unless asked.
-
-        IMPORTANT - Path Handling:
-        - Relative paths (e.g., "tmp/file.txt", "src/main.rb") are resolved relative to your agent's working directory
-        - Absolute paths (e.g., "/tmp/file.txt", "/etc/passwd") are treated as system absolute paths
-        - When the user says "tmp/file.txt" they mean the tmp directory in your working directory, NOT /tmp
-        - Only use absolute paths (starting with /) when explicitly referring to system-level paths
-      DESC
-
-      param :file_path,
-        type: "string",
-        desc: "Path to the file. Use relative paths (e.g., 'tmp/file.txt') for files in your working directory, or absolute paths (e.g., '/etc/passwd') for system files.",
-        required: true
-
-      param :content,
-        type: "string",
-        desc: "The content to write to the file",
-        required: true
-
-      # Initialize the Write tool for a specific agent
-      #
-      # @param agent_name [Symbol, String] The agent identifier
-      # @param directory [String] Agent's working directory
-      def initialize(agent_name:, directory:)
-        super()
-        initialize_agent_context(agent_name: agent_name, directory: directory)
-      end
-
-      # Override name to return simple "Write" instead of full class path
-      def name
-        "Write"
-      end
-
-      def execute(file_path:, content:)
-        # Validate inputs
-        return validation_error("file_path is required") if file_path.nil? || file_path.to_s.strip.empty?
-        return validation_error("content is required") if content.nil?
-
-        # CRITICAL: Resolve path against agent directory
-        resolved_path = resolve_path(file_path)
-
-        # Check if file already exists (use resolved path)
-        file_exists = File.exist?(resolved_path)
-
-        # Enforce read-before-write for existing files (use resolved path)
-        if file_exists && !Stores::ReadTracker.file_read?(@agent_name, resolved_path)
-          return validation_error(
-            "Cannot write to existing file without reading it first. " \
-              "You must use the Read tool on '#{file_path}' before overwriting it. " \
-              "This ensures you have context about the file's current contents.",
-          )
-        end
-
-        # Create parent directory if it doesn't exist (use resolved path)
-        parent_dir = File.dirname(resolved_path)
-        FileUtils.mkdir_p(parent_dir) unless File.directory?(parent_dir)
-
-        # Write the file (use resolved path)
-        File.write(resolved_path, content, encoding: "UTF-8")
-
-        # Build success message
-        byte_size = content.bytesize
-        line_count = content.lines.count
-        action = file_exists ? "overwrote" : "created"
-
-        message = "Successfully #{action} file: #{file_path} (#{line_count} lines, #{byte_size} bytes)"
-
-        # Add system reminder for overwritten files
-        if file_exists
-          reminder = "<system-reminder>You overwrote an existing file. Make sure this was intentional and that you read the file first if you needed to preserve any content.</system-reminder>"
-          "#{message}\n\n#{reminder}"
-        else
-          message
-        end
-      rescue Errno::EACCES
-        error("Permission denied: Cannot write to file '#{file_path}'")
-      rescue Errno::EISDIR
-        error("Path is a directory, not a file.")
-      rescue Errno::ENOENT => e
-        error("Failed to create parent directory: #{e.message}")
-      rescue StandardError => e
-        error("Unexpected error writing file: #{e.class.name} - #{e.message}")
-      end
-    end
-  end
-end

data/lib/swarm_sdk/utils.rb

@@ -1,68 +0,0 @@
-# frozen_string_literal: true
-
-module SwarmSDK
-  # Shared utility methods for SwarmSDK
-  module Utils
-    class << self
-      # Recursively convert all hash keys to symbols
-      #
-      # Handles nested hashes and arrays containing hashes.
-      #
-      # @param obj [Object] Object to symbolize (Hash, Array, or other)
-      # @return [Object] Object with symbolized keys (if applicable)
-      #
-      # @example
-      #   Utils.symbolize_keys({ "name" => "test", "config" => { "key" => "value" } })
-      #   # => { name: "test", config: { key: "value" } }
-      def symbolize_keys(obj)
-        case obj
-        when Hash
-          obj.transform_keys(&:to_sym).transform_values { |v| symbolize_keys(v) }
-        when Array
-          obj.map { |item| symbolize_keys(item) }
-        else
-          obj
-        end
-      end
-
-      # Recursively convert all hash keys to strings
-      #
-      # Handles nested hashes and arrays containing hashes.
-      #
-      # @param obj [Object] Object to stringify (Hash, Array, or other)
-      # @return [Object] Object with stringified keys (if applicable)
-      #
-      # @example
-      #   Utils.stringify_keys({ name: "test", config: { key: "value" } })
-      #   # => { "name" => "test", "config" => { "key" => "value" } }
-      def stringify_keys(obj)
-        case obj
-        when Hash
-          obj.transform_keys(&:to_s).transform_values { |v| stringify_keys(v) }
-        when Array
-          obj.map { |item| stringify_keys(item) }
-        else
-          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