swarm_sdk 2.0.0.pre.2

data/lib/swarm_sdk/tools/bash.rb

@@ -0,0 +1,274 @@
+# frozen_string_literal: true
+
+module SwarmSDK
+  module Tools
+    # Bash tool for executing shell commands
+    #
+    # Executes commands in a persistent shell session with timeout support.
+    # Provides comprehensive guidance on proper usage patterns.
+    class Bash < RubyLLM::Tool
+      def initialize(directory:)
+        super()
+        @directory = File.expand_path(directory)
+      end
+
+      def name
+        "Bash"
+      end
+
+      description <<~DESC
+        Executes a given bash command in a persistent shell session with optional timeout, ensuring proper handling and security measures.
+
+        IMPORTANT: This tool is for terminal operations like git, npm, docker, etc. DO NOT use it for file operations (reading, writing, editing, searching, finding files) - use the specialized tools for this instead.
+
+        Before executing the command, please follow these steps:
+
+        1. Directory Verification:
+           - If the command will create new directories or files, first use `ls` to verify the parent directory exists and is the correct location
+           - For example, before running "mkdir foo/bar", first use `ls foo` to check that "foo" exists and is the intended parent directory
+
+        2. Command Execution:
+           - Always quote file paths that contain spaces with double quotes (e.g., cd "path with spaces/file.txt")
+           - Examples of proper quoting:
+             - cd "/Users/name/My Documents" (correct)
+             - cd /Users/name/My Documents (incorrect - will fail)
+             - python "/path/with spaces/script.py" (correct)
+             - python /path/with spaces/script.py (incorrect - will fail)
+           - After ensuring proper quoting, execute the command.
+           - Capture the output of the command.
+
+        Usage notes:
+          - The command argument is required.
+          - You can specify an optional timeout in milliseconds (up to 600000ms / 10 minutes). If not specified, commands will timeout after 120000ms (2 minutes).
+          - It is very helpful if you write a clear, concise description of what this command does in 5-10 words.
+          - If the output exceeds 30000 characters, output will be truncated before being returned to you.
+          - Avoid using Bash with the `find`, `grep`, `cat`, `head`, `tail`, `sed`, `awk`, or `echo` commands, unless explicitly instructed or when these commands are truly necessary for the task. Instead, always prefer using the dedicated tools for these commands:
+            - File search: Use Glob (NOT find or ls)
+            - Content search: Use Grep (NOT grep or rg)
+            - Read files: Use Read (NOT cat/head/tail)
+            - Edit files: Use Edit (NOT sed/awk)
+            - Write files: Use Write (NOT echo >/cat <<EOF)
+            - Communication: Output text directly (NOT echo/printf)
+          - When issuing multiple commands:
+            - If the commands are independent and can run in parallel, make multiple Bash tool calls in a single message. For example, if you need to run "git status" and "git diff", send a single message with two Bash tool calls in parallel.
+            - If the commands depend on each other and must run sequentially, use a single Bash call with '&&' to chain them together (e.g., `git add . && git commit -m "message" && git push`). For instance, if one operation must complete before another starts (like mkdir before cp, Write before Bash for git operations, or git add before git commit), run these operations sequentially instead.
+            - Use ';' only when you need to run commands sequentially but don't care if earlier commands fail
+            - DO NOT use newlines to separate commands (newlines are ok in quoted strings)
+          - Try to maintain your current working directory throughout the session by using absolute paths and avoiding usage of `cd`. You may use `cd` if the User explicitly requests it.
+            <good-example>
+            pytest /foo/bar/tests
+            </good-example>
+            <bad-example>
+            cd /foo/bar && pytest tests
+            </bad-example>
+      DESC
+
+      param :command,
+        type: "string",
+        desc: "The command to execute",
+        required: true
+
+      param :description,
+        type: "string",
+        desc: "Clear, concise description of what this command does in 5-10 words, in active voice. Examples:\nInput: ls\nOutput: List files in current directory\n\nInput: git status\nOutput: Show working tree status\n\nInput: npm install\nOutput: Install package dependencies\n\nInput: mkdir foo\nOutput: Create directory 'foo'",
+        required: false
+
+      param :timeout,
+        type: "number",
+        desc: "Optional timeout in milliseconds (max 600000)",
+        required: false
+
+      DEFAULT_TIMEOUT_MS = 120_000 # 2 minutes
+      MAX_TIMEOUT_MS = 600_000 # 10 minutes
+      MAX_OUTPUT_LENGTH = 30_000 # characters
+
+      # Commands that are ALWAYS blocked for safety reasons
+      # These cannot be overridden by permissions configuration
+      ALWAYS_BLOCKED_COMMANDS = [
+        %r{^rm\s+-rf\s+/$}, # rm -rf / - delete root filesystem
+      ].freeze
+
+      def execute(command:, description: nil, timeout: nil)
+        # Validate inputs
+        return validation_error("command is required") if command.nil? || command.empty?
+
+        # Check against always-blocked commands
+        blocked_pattern = ALWAYS_BLOCKED_COMMANDS.find { |pattern| pattern.match?(command) }
+        if blocked_pattern
+          return blocked_command_error(command, blocked_pattern)
+        end
+
+        # Validate and set timeout
+        timeout_ms = timeout || DEFAULT_TIMEOUT_MS
+        timeout_ms = [timeout_ms, MAX_TIMEOUT_MS].min
+        timeout_seconds = timeout_ms / 1000.0
+
+        # Execute command with timeout
+        stdout = +""
+        stderr = +""
+        exit_status = nil
+
+        begin
+          require "open3"
+          require "timeout"
+
+          Timeout.timeout(timeout_seconds) do
+            # CRITICAL: Change to agent's directory for subprocess
+            # This is SAFE because Open3.popen3 creates a subprocess
+            # The subprocess inherits the directory, but the parent fiber is unaffected
+            Dir.chdir(@directory) do
+              Open3.popen3(command) do |stdin, out, err, wait_thr|
+                stdin.close # Close stdin since we don't send input
+
+                # Read stdout and stderr
+                stdout = out.read || ""
+                stderr = err.read || ""
+                exit_status = wait_thr.value.exitstatus
+              end
+            end
+          end
+        rescue Timeout::Error
+          return format_timeout_error(command, timeout_seconds)
+        rescue Errno::ENOENT => e
+          return error("Command not found or executable not in PATH: #{e.message}")
+        rescue Errno::EACCES
+          return error("Permission denied: Cannot execute command '#{command}'")
+        rescue StandardError => e
+          return error("Failed to execute command: #{e.class.name} - #{e.message}")
+        end
+
+        # Build output
+        output = format_command_output(command, description, stdout, stderr, exit_status)
+
+        # Truncate if too long
+        if output.length > MAX_OUTPUT_LENGTH
+          truncated = output[0...MAX_OUTPUT_LENGTH]
+          truncated += "\n\n<system-reminder>Output truncated at #{MAX_OUTPUT_LENGTH} characters. The full output was #{output.length} characters.</system-reminder>"
+          output = truncated
+        end
+
+        # Add usage reminders for certain patterns
+        output = add_usage_reminders(output, command)
+
+        output
+      rescue StandardError => e
+        error("Unexpected error executing command: #{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 blocked_command_error(command, pattern)
+        <<~ERROR
+          Error: Command blocked for safety reasons.
+          Command: #{command}
+          Pattern: #{pattern.source}
+
+          <system-reminder>
+          SECURITY BLOCK: This command is permanently blocked for safety reasons and cannot be executed.
+
+          This is a built-in safety feature of the Bash tool that cannot be overridden by any configuration.
+          The command matches a pattern that could cause catastrophic system damage.
+
+          DO NOT attempt to:
+          - Modify the command slightly to bypass this check
+          - Ask the user to allow this command
+          - Work around this restriction in any way
+
+          If you need to perform a similar operation safely, consider:
+          - Using a more specific path instead of system-wide operations
+          - Using dedicated tools for file operations
+          - Asking the user for guidance on a safer approach
+
+          This is an UNRECOVERABLE error. You must inform the user that this command cannot be executed for safety reasons.
+          </system-reminder>
+        ERROR
+      end
+
+      def format_timeout_error(command, timeout_seconds)
+        <<~ERROR
+          Error: Command timed out after #{timeout_seconds} seconds.
+          Command: #{command}
+
+          <system-reminder>The command exceeded the timeout limit. Consider:
+          1. Breaking the command into smaller steps
+          2. Increasing the timeout parameter
+          3. Running long-running commands in the background if supported
+          </system-reminder>
+        ERROR
+      end
+
+      def format_command_output(command, description, stdout, stderr, exit_status)
+        parts = []
+
+        # Add description if provided
+        parts << "Running: #{description}" if description
+
+        # Add command
+        parts << "$ #{command}"
+        parts << ""
+
+        # Add exit status
+        parts << "Exit code: #{exit_status}"
+
+        # Add stdout if present
+        if stdout && !stdout.empty?
+          parts << ""
+          parts << "STDOUT:"
+          parts << stdout.chomp
+        end
+
+        # Add stderr if present
+        if stderr && !stderr.empty?
+          parts << ""
+          parts << "STDERR:"
+          parts << stderr.chomp
+        end
+
+        # Add warning for non-zero exit
+        if exit_status != 0
+          parts << ""
+          parts << "<system-reminder>Command exited with non-zero status (#{exit_status}). Check STDERR for error details.</system-reminder>"
+        end
+
+        parts.join("\n")
+      end
+
+      def add_usage_reminders(output, command)
+        reminders = []
+
+        # Detect file operation commands that should use dedicated tools
+        if command.match?(/\b(cat|head|tail|less|more)\s+/)
+          reminders << "You used a command to read a file. Consider using the Read tool instead for better formatting and error handling."
+        end
+
+        if command.match?(/\b(grep|rg|ag)\s+/)
+          reminders << "You used grep/ripgrep to search files. Consider using the Grep tool instead for structured results."
+        end
+
+        if command.match?(/\b(find|locate)\s+/)
+          reminders << "You used find to locate files. Consider using the Glob tool instead for pattern-based file matching."
+        end
+
+        if command.match?(/\b(sed|awk)\s+/) && !command.include?("|")
+          reminders << "You used sed/awk for file editing. Consider using the Edit tool instead for safer, tracked file modifications."
+        end
+
+        if command.match?(/\becho\s+.*>\s*/) || command.match?(/\bcat\s*<</)
+          reminders << "You used echo/cat with redirection to write a file. Consider using the Write tool instead for proper file creation."
+        end
+
+        return output if reminders.empty?
+
+        output + "\n\n<system-reminder>\n#{reminders.join("\n\n")}\n</system-reminder>"
+      end
+    end
+  end
+end

data/lib/swarm_sdk/tools/delegate.rb

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+
+module SwarmSDK
+  module Tools
+    # Delegate tool for delegating tasks to other agents in the swarm
+    #
+    # Creates agent-specific delegation tools (e.g., DelegateTaskToBackend)
+    # that allow one agent to delegate work to another agent.
+    # Supports pre/post delegation hooks for customization.
+    class Delegate < RubyLLM::Tool
+      attr_reader :delegate_name, :delegate_target, :tool_name
+
+      # Initialize a delegation tool
+      #
+      # @param delegate_name [String] Name of the delegate agent (e.g., "backend")
+      # @param delegate_description [String] Description of the delegate agent
+      # @param delegate_chat [AgentChat] The chat instance for the delegate agent
+      # @param agent_name [Symbol, String] Name of the agent using this tool
+      # @param swarm [Swarm] The swarm instance
+      # @param hook_registry [Hooks::Registry] Registry for callbacks
+      def initialize(
+        delegate_name:,
+        delegate_description:,
+        delegate_chat:,
+        agent_name:,
+        swarm:,
+        hook_registry:
+      )
+        super()
+
+        @delegate_name = delegate_name
+        @delegate_description = delegate_description
+        @delegate_chat = delegate_chat
+        @agent_name = agent_name
+        @swarm = swarm
+        @hook_registry = hook_registry
+
+        # Generate tool name in the expected format: DelegateTaskTo[AgentName]
+        @tool_name = "DelegateTaskTo#{delegate_name.to_s.capitalize}"
+        @delegate_target = delegate_name.to_s
+      end
+
+      # Build description dynamically based on delegate
+      description do
+        "Delegate tasks to #{@delegate_name}. #{@delegate_description}"
+      end
+
+      param :task,
+        type: "string",
+        desc: "Task description for the agent",
+        required: true
+
+      # Override name to return custom delegation tool name
+      def name
+        @tool_name
+      end
+
+      # Execute delegation with pre/post hooks
+      #
+      # @param task [String] Task to delegate
+      # @return [String] Result from delegate agent or error message
+      def execute(task:)
+        # Trigger pre_delegation callback
+        context = Hooks::Context.new(
+          event: :pre_delegation,
+          agent_name: @agent_name,
+          swarm: @swarm,
+          delegation_target: @delegate_target,
+          metadata: {
+            tool_name: @tool_name,
+            task: task,
+            timestamp: Time.now.utc.iso8601,
+          },
+        )
+
+        executor = Hooks::Executor.new(@hook_registry, logger: RubyLLM.logger)
+        result = executor.execute_safe(event: :pre_delegation, context: context, callbacks: [])
+
+        # Check if callback halted or replaced the delegation
+        if result.halt?
+          return result.value || "Delegation halted by callback"
+        elsif result.replace?
+          return result.value
+        end
+
+        # Proceed with delegation
+        response = @delegate_chat.ask(task)
+        delegation_result = response.content
+
+        # Trigger post_delegation callback
+        post_context = Hooks::Context.new(
+          event: :post_delegation,
+          agent_name: @agent_name,
+          swarm: @swarm,
+          delegation_target: @delegate_target,
+          delegation_result: delegation_result,
+          metadata: {
+            tool_name: @tool_name,
+            task: task,
+            result: delegation_result,
+            timestamp: Time.now.utc.iso8601,
+          },
+        )
+
+        post_result = executor.execute_safe(event: :post_delegation, context: post_context, callbacks: [])
+
+        # Return modified result if callback replaces it
+        if post_result.replace?
+          post_result.value
+        else
+          delegation_result
+        end
+      rescue Faraday::TimeoutError, Net::ReadTimeout => e
+        # Log timeout error as JSON event
+        LogStream.emit(
+          type: "delegation_error",
+          agent: @agent_name,
+          delegate_to: @tool_name,
+          error_class: e.class.name,
+          error_message: "Request timed out",
+          backtrace: e.backtrace&.first(5) || [],
+        )
+        "Error: Request to #{@tool_name} timed out. The agent may be overloaded or the LLM service is not responding. Please try again or simplify the task."
+      rescue Faraday::Error => e
+        # Log network error as JSON event
+        LogStream.emit(
+          type: "delegation_error",
+          agent: @agent_name,
+          delegate_to: @tool_name,
+          error_class: e.class.name,
+          error_message: e.message,
+          backtrace: e.backtrace&.first(5) || [],
+        )
+        "Error: Network error communicating with #{@tool_name}: #{e.class.name}. Please check connectivity and try again."
+      rescue StandardError => e
+        # Log unexpected error as JSON event
+        backtrace_array = e.backtrace&.first(5) || []
+        LogStream.emit(
+          type: "delegation_error",
+          agent: @agent_name,
+          delegate_to: @tool_name,
+          error_class: e.class.name,
+          error_message: e.message,
+          backtrace: backtrace_array,
+        )
+        # Return error string for LLM
+        backtrace_str = backtrace_array.join("\n  ")
+        "Error: #{@tool_name} encountered an error: #{e.class.name}: #{e.message}\nBacktrace:\n  #{backtrace_str}"
+      end
+    end
+  end
+end

data/lib/swarm_sdk/tools/document_converters/base_converter.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module SwarmSDK
+  module Tools
+    module DocumentConverters
+      # Base class for document converters
+      # Provides common interface and utility methods for converting various document formats
+      class BaseConverter
+        class << self
+          # The gem name required for this converter
+          # @return [String]
+          def gem_name
+            raise NotImplementedError, "#{name} must implement .gem_name"
+          end
+
+          # Human-readable format name
+          # @return [String]
+          def format_name
+            raise NotImplementedError, "#{name} must implement .format_name"
+          end
+
+          # File extensions this converter handles
+          # @return [Array<String>]
+          def extensions
+            raise NotImplementedError, "#{name} must implement .extensions"
+          end
+
+          # Check if the required gem is available
+          # @return [Boolean]
+          def available?
+            gem_available?(gem_name)
+          end
+
+          # Check if a gem is installed
+          # @param gem_name [String] Name of the gem to check
+          # @return [Boolean]
+          def gem_available?(gem_name)
+            Gem::Specification.find_by_name(gem_name)
+            true
+          rescue Gem::LoadError
+            false
+          end
+        end
+
+        # Convert a document file to text/content
+        # @param file_path [String] Path to the file
+        # @return [String, RubyLLM::Content] Converted content or error message
+        def convert(file_path)
+          raise NotImplementedError, "#{self.class.name} must implement #convert"
+        end
+
+        protected
+
+        # Return a system reminder about missing gem
+        # @param format [String] Format name (e.g., "PDF")
+        # @param gem_name [String] Required gem name
+        # @return [String]
+        def unsupported_format_reminder(format, gem_name)
+          <<~REMINDER
+            <system-reminder>
+            This file is a #{format} document, but the required gem is not installed.
+
+            To enable #{format} file reading, please install the gem:
+              gem install #{gem_name}
+
+            Or add to your Gemfile:
+              gem "#{gem_name}"
+
+            Don't install the gem yourself. Ask the user if they would like you to install this gem.
+            </system-reminder>
+          REMINDER
+        end
+
+        # Return an error message
+        # @param message [String] Error message
+        # @return [String]
+        def error(message)
+          "Error: #{message}"
+        end
+      end
+    end
+  end
+end

data/lib/swarm_sdk/tools/document_converters/docx_converter.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+module SwarmSDK
+  module Tools
+    module DocumentConverters
+      # Converts DOCX documents to text with image extraction
+      class DocxConverter < BaseConverter
+        class << self
+          def gem_name
+            "docx"
+          end
+
+          def format_name
+            "DOCX"
+          end
+
+          def extensions
+            [".docx", ".doc"]
+          end
+        end
+
+        # Convert a DOCX document to text/content
+        # @param file_path [String] Path to the DOCX file
+        # @return [String, RubyLLM::Content] Converted content or error message
+        def convert(file_path)
+          unless self.class.available?
+            return unsupported_format_reminder(self.class.format_name, self.class.gem_name)
+          end
+
+          # Check for legacy DOC format
+          if File.extname(file_path).downcase == ".doc"
+            return error("DOC format is not supported. Please convert to DOCX first.")
+          end
+
+          begin
+            require "docx"
+            require "tmpdir"
+
+            doc = Docx::Document.open(file_path)
+
+            # Extract images from the DOCX
+            image_paths = ImageExtractors::DocxImageExtractor.extract_images(doc, file_path)
+
+            output = []
+            output << "Document: #{File.basename(file_path)}"
+            output << "=" * 60
+            output << ""
+
+            # Extract paragraphs
+            paragraphs = doc.paragraphs.map(&:text).reject(&:empty?)
+
+            # Check for empty document
+            if paragraphs.empty? && doc.tables.empty?
+              output << "(Document is empty - no paragraphs or tables)"
+            else
+              output += paragraphs
+
+              # Extract tables with enhanced formatting
+              if doc.tables.any?
+                output << ""
+                output << "Tables:"
+                output << "-" * 60
+
+                doc.tables.each_with_index do |table, idx|
+                  output << ""
+                  output << "Table #{idx + 1} (#{table.row_count} rows × #{table.column_count} columns):"
+
+                  table.rows.each do |row|
+                    output << row.cells.map(&:text).join(" | ")
+                  end
+                end
+              end
+            end
+
+            text_content = output.join("\n")
+
+            # If there are images, return Content with attachments
+            if image_paths.any?
+              content = RubyLLM::Content.new(text_content)
+              image_paths.each do |image_path|
+                content.add_attachment(image_path)
+              end
+              content
+            else
+              # No images, return just text
+              text_content
+            end
+          rescue Zip::Error => e
+            error("Invalid or corrupted DOCX file: #{e.message}")
+          rescue Errno::ENOENT => e
+            error("File not found or missing document.xml: #{e.message}")
+          rescue StandardError => e
+            error("Failed to parse DOCX file: #{e.message}")
+          end
+        end
+      end
+    end
+  end
+end

data/lib/swarm_sdk/tools/document_converters/pdf_converter.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module SwarmSDK
+  module Tools
+    module DocumentConverters
+      # Converts PDF documents to text with image extraction
+      class PdfConverter < BaseConverter
+        class << self
+          def gem_name
+            "pdf-reader"
+          end
+
+          def format_name
+            "PDF"
+          end
+
+          def extensions
+            [".pdf"]
+          end
+        end
+
+        # Convert a PDF document to text/content
+        # @param file_path [String] Path to the PDF file
+        # @return [String, RubyLLM::Content] Converted content or error message
+        def convert(file_path)
+          unless self.class.available?
+            return unsupported_format_reminder(self.class.format_name, self.class.gem_name)
+          end
+
+          begin
+            require "pdf-reader"
+            require "tmpdir"
+            require "fileutils"
+
+            reader = PDF::Reader.new(file_path)
+            output = []
+            output << "PDF Document: #{File.basename(file_path)}"
+            output << "=" * 60
+            output << "Pages: #{reader.page_count}"
+            output << ""
+
+            # Extract images from the PDF
+            image_paths = ImageExtractors::PdfImageExtractor.extract_images(reader, file_path)
+
+            # Extract text from each page
+            reader.pages.each_with_index do |page, index|
+              output << "Page #{index + 1}:"
+              output << "-" * 60
+              text = page.text.strip
+              output << (text.empty? ? "(No text content on this page)" : text)
+              output << ""
+            end
+
+            text_content = output.join("\n")
+
+            # If there are images, return Content with attachments
+            if image_paths.any?
+              content = RubyLLM::Content.new(text_content)
+              image_paths.each do |image_path|
+                content.add_attachment(image_path)
+              end
+              content
+            else
+              # No images, return just text
+              text_content
+            end
+          rescue PDF::Reader::MalformedPDFError => e
+            error("PDF file is malformed: #{e.message}")
+          rescue PDF::Reader::UnsupportedFeatureError => e
+            error("PDF contains unsupported features: #{e.message}")
+          rescue StandardError => e
+            error("Failed to parse PDF file: #{e.message}")
+          end
+        end
+      end
+    end
+  end
+end