swarm_sdk 2.7.14 → 3.0.0.alpha1

data/lib/swarm_sdk/tools/think.rb

@@ -1,100 +0,0 @@
-# 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 < Base
-      removable false # Think is always available
-
-      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)
-        <<~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
-
-      def validation_error(message)
-        "<tool_use_error>InputValidationError: #{message}</tool_use_error>"
-      end
-    end
-  end
-end

data/lib/swarm_sdk/tools/todo_write.rb

@@ -1,237 +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 < Base
-      removable false # TodoWrite is always available
-
-      # 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,264 +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 < Base
-      def initialize
-        super()
-        @cache = {}
-        @cache_ttl = 900 # 15 minutes in seconds
-      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
-
-      # NOTE: Content length and timeout now accessed via SwarmSDK.config
-      USER_AGENT = "SwarmSDK WebFetch Tool (https://github.com/parruda/claude-swarm)"
-
-      def execute(url:, prompt: nil)
-        # Validate inputs
-        return validation_error("url is required") if url.nil? || url.empty?
-
-        # Check if LLM processing is enabled (lazy check)
-        llm_enabled = SwarmSDK.config.webfetch_llm_enabled?
-
-        # 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
-        max_content = SwarmSDK.config.web_fetch_character_limit
-        if markdown_content.length > max_content
-          markdown_content = markdown_content[0...max_content]
-          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"
-
-        timeout = SwarmSDK.config.web_fetch_timeout
-        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 #{SwarmSDK.config.web_fetch_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 config
-        sdk_config = SwarmSDK.config
-
-        # Build chat with configured provider and model
-        chat_params = {
-          model: sdk_config.webfetch_model,
-          provider: sdk_config.webfetch_provider.to_sym,
-        }
-        chat_params[:base_url] = sdk_config.webfetch_base_url if sdk_config.webfetch_base_url
-
-        chat = RubyLLM.chat(**chat_params).with_params(max_tokens: sdk_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