claude_swarm 1.0.1 → 1.0.2

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

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module SwarmSDK
+  module Tools
+    module Stores
+      # TodoManager provides per-agent todo list storage
+      #
+      # Each agent maintains its own independent todo list that persists
+      # throughout the agent's execution session. This allows agents to
+      # track progress on complex multi-step tasks.
+      class TodoManager
+        @storage = {}
+        @mutex = Mutex.new
+
+        class << self
+          # Get the current todo list for an agent
+          #
+          # @param agent_id [Symbol, String] Unique agent identifier
+          # @return [Array<Hash>] Array of todo items
+          def get_todos(agent_id)
+            @mutex.synchronize do
+              @storage[agent_id.to_sym] ||= []
+            end
+          end
+
+          # Set the todo list for an agent
+          #
+          # @param agent_id [Symbol, String] Unique agent identifier
+          # @param todos [Array<Hash>] Array of todo items
+          # @return [Array<Hash>] The stored todos
+          def set_todos(agent_id, todos)
+            @mutex.synchronize do
+              @storage[agent_id.to_sym] = todos
+            end
+          end
+
+          # Clear all todos for an agent
+          #
+          # @param agent_id [Symbol, String] Unique agent identifier
+          def clear_todos(agent_id)
+            @mutex.synchronize do
+              @storage.delete(agent_id.to_sym)
+            end
+          end
+
+          # Clear all todos for all agents
+          def clear_all
+            @mutex.synchronize do
+              @storage.clear
+            end
+          end
+
+          # Get summary of all agent todo lists
+          #
+          # @return [Hash] Map of agent_id => todo count
+          def summary
+            @mutex.synchronize do
+              @storage.transform_values(&:size)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/swarm_sdk/tools/think.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module SwarmSDK
+  module Tools
+    # Think tool for explicit reasoning and planning
+    #
+    # Allows the agent to write down thoughts, plans, strategies, and intermediate
+    # calculations. These thoughts become part of the conversation context, enabling
+    # better attention and reasoning through complex problems.
+    #
+    # This is inspired by research showing that explicitly articulating reasoning steps
+    # (chain-of-thought prompting) leads to significantly better outcomes, especially
+    # for complex tasks requiring multi-step reasoning or arithmetic.
+    class Think < RubyLLM::Tool
+      def name
+        "Think"
+      end
+
+      description <<~DESC
+        **IMPORTANT: You SHOULD use this tool frequently throughout your work. Using this tool leads to significantly
+        better outcomes and more accurate solutions. Make it a habit to think before acting.**
+
+        This tool allows you to write down your thoughts, plans, strategies, and intermediate calculations.
+        Think of it as your working memory - just as humans think before speaking or acting, you should think before
+        using other tools or providing responses.
+
+        **STRONGLY RECOMMENDED to use this tool:**
+        - **ALWAYS** before starting any task (even simple ones)
+        - **ALWAYS** when you need to do any arithmetic or counting
+        - **ALWAYS** after reading files or getting search results to process what you learned
+        - **FREQUENTLY** between steps to track progress and plan next actions
+
+        This is your private thinking space - use it liberally to enhance your problem-solving capabilities. Recording
+        your thoughts helps you maintain context across multiple steps and remember important information throughout your task.
+
+        When and how to use this tool:
+
+        1. **Before starting any complex task**: Write down your understanding of the problem, break it into smaller
+           sub-tasks, and create a step-by-step plan. Example:
+           - "The user wants me to refactor this codebase. Let me first understand the structure..."
+           - "I need to: 1) Analyze current architecture, 2) Identify pain points, 3) Propose changes..."
+
+        2. **For arithmetic and calculations**: Work through math problems step by step. Example:
+           - "If we have 150 requests/second and each takes 20ms, that's 150 * 0.02 = 3 seconds of CPU time..."
+           - "Converting 2GB to bytes: 2 * 1024 * 1024 * 1024 = 2,147,483,648 bytes"
+
+        3. **After completing sub-tasks**: Summarize what you've accomplished and what remains. Example:
+           - "I've successfully implemented the authentication module. Next, I need to integrate it with the API..."
+           - "Fixed 3 out of 5 bugs. Remaining: memory leak in parser, race condition in worker thread"
+
+        4. **When encountering complexity**: Break down complex logic or decisions. Example:
+           - "This function has multiple edge cases. Let me list them: null input, empty array, negative numbers..."
+           - "The user's request is ambiguous. Possible interpretations: A) modify existing code, B) create new module..."
+
+        5. **For remembering context**: Store important information you'll need later. Example:
+           - "Important: The user mentioned they're using Ruby 3.2, so I can use pattern matching"
+           - "File structure: main.rb requires from lib/, config is in config.yml"
+
+        6. **When debugging or analyzing**: Track your investigation process. Example:
+           - "The error occurs in line 42. Let me trace backwards: function called from main(), receives data from..."
+           - "Hypothesis: the bug might be due to timezone differences. Let me check..."
+
+        7. **For creative problem-solving**: Brainstorm multiple approaches before choosing one. Example:
+           - "Approaches to optimize this: 1) Add caching, 2) Use parallel processing, 3) Optimize algorithm..."
+           - "Design patterns that could work here: Factory, Observer, or maybe Strategy pattern..."
+
+        **Remember: The most successful agents use this tool 5-10 times per task on average. If you haven't used this
+        tool in the last 2-3 actions, you probably should. Using this tool is a sign of thoughtful, methodical problem
+        solving and leads to fewer mistakes and better solutions.**
+
+        Your thoughts persist throughout your session as part of the conversation history, so you can refer
+        back to earlier thinking. Use clear formatting and organization to make it easy to reference
+        later. Don't hesitate to think out loud - this tool is designed to augment your cognitive capabilities and help
+        you deliver better solutions.
+
+        **CRITICAL:** The Think tool takes only one parameter: thoughts. Do not include any other parameters.
+      DESC
+
+      param :thoughts,
+        type: "string",
+        desc: "Your thoughts, plans, calculations, or any notes you want to record",
+        required: true
+
+      def execute(**kwargs)
+        "Thought noted."
+      end
+
+      private
+
+      def validation_error(message)
+        "<tool_use_error>InputValidationError: #{message}</tool_use_error>"
+      end
+    end
+  end
+end

data/lib/swarm_sdk/tools/todo_write.rb

@@ -0,0 +1,216 @@
+# 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
+      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.
+        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
+        3. THIRD: Execute tasks, marking in_progress → completed as you work
+        4. ONLY add new todos if unexpected work is discovered during implementation
+
+        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 implementation
+
+        ## 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: "Fix authentication bug"
+            - activeForm: "Fixing authentication bug"
+
+        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

@@ -0,0 +1,261 @@
+# 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
+
+      MAX_CONTENT_LENGTH = 100_000 # characters
+      USER_AGENT = "SwarmSDK WebFetch Tool (https://github.com/parruda/claude-swarm)"
+      TIMEOUT = 30 # 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