shared_tools 0.3.1 → 0.4.1

data/lib/shared_tools/tools/browser/ferrum_driver.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+require 'tempfile'
+
+module SharedTools
+  module Tools
+    module Browser
+      # A browser driver backed by Ferrum (Chrome DevTools Protocol).
+      # No chromedriver binary required — Ferrum talks directly to Chrome.
+      #
+      # @example
+      #   driver = SharedTools::Tools::Browser::FerrumDriver.new
+      #   driver.goto(url: "https://example.com")
+      #   driver.click(selector: "a.some-link")
+      #   driver.close
+      class FerrumDriver < BaseDriver
+        # @param logger [Logger]
+        # @param network_idle_timeout [Numeric] seconds to wait for network idle after navigation
+        # @param ferrum_options [Hash] additional options passed directly to Ferrum::Browser
+        def initialize(logger: Logger.new(IO::NULL), network_idle_timeout: 5, **ferrum_options)
+          super(logger:)
+          @network_idle_timeout = network_idle_timeout
+          options = {
+            headless: true,
+            timeout: TIMEOUT,
+            browser_options: { 'disable-blink-features' => 'AutomationControlled' }
+          }.merge(ferrum_options)
+          @browser = Ferrum::Browser.new(**options)
+        end
+
+        def close
+          @browser.quit
+        end
+
+        # @return [String]
+        def url
+          @browser.current_url
+        end
+
+        # @return [String]
+        def title
+          @browser.title
+        end
+
+        # @return [String]
+        def html
+          @browser.evaluate('document.documentElement.outerHTML')
+        end
+
+        # @param url [String]
+        # @return [Hash]
+        def goto(url:)
+          @browser.go_to(url)
+          wait_for_network_idle
+          { status: :ok }
+        end
+
+        # @yield [file]
+        # @yieldparam file [File]
+        def screenshot
+          tempfile = Tempfile.new(['screenshot', '.png'])
+          @browser.screenshot(path: tempfile.path)
+          yield File.open(tempfile.path, 'rb')
+        ensure
+          tempfile&.close
+          tempfile&.unlink
+        end
+
+        # @param selector [String] CSS selector for an input or textarea
+        # @param text [String]
+        # @return [Hash]
+        def fill_in(selector:, text:)
+          element = wait_for_element { @browser.at_css(selector) }
+          return { status: :error, message: "unknown selector=#{selector.inspect}" } if element.nil?
+
+          element.evaluate("this.value = #{text.to_json}")
+          element.evaluate("this.dispatchEvent(new Event('input', {bubbles: true}))")
+          element.evaluate("this.dispatchEvent(new Event('change', {bubbles: true}))")
+          { status: :ok }
+        rescue => e
+          { status: :error, message: e.message }
+        end
+
+        # @param selector [String] CSS selector
+        # @return [Hash]
+        def click(selector:)
+          element = wait_for_element { @browser.at_css(selector) }
+          return { status: :error, message: "unknown selector=#{selector.inspect}" } if element.nil?
+
+          element.click
+          { status: :ok }
+        rescue => e
+          { status: :error, message: e.message }
+        end
+
+      private
+
+        # Wait until there are no pending network requests (JS-rendered pages).
+        # Falls back silently if Ferrum raises a timeout.
+        def wait_for_network_idle
+          @browser.network.wait_for_idle(duration: 0.3, timeout: @network_idle_timeout)
+        rescue Ferrum::TimeoutError
+          # Some requests never settle; accept whatever state the page is in.
+        end
+
+        def wait_for_element
+          deadline = Time.now + TIMEOUT
+          loop do
+            result = yield
+            return result if result
+            break if Time.now >= deadline
+            sleep 0.2
+          end
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/shared_tools/tools/browser/inspect_tool.rb

@@ -44,10 +44,12 @@ module SharedTools
       private
 
         def default_driver
-          if defined?(Watir)
+          if defined?(Ferrum)
+            FerrumDriver.new(logger: @logger)
+          elsif defined?(Watir)
             WatirDriver.new(logger: @logger)
           else
-            raise LoadError, "Browser tools require a driver. Either install the 'watir' gem or pass a driver: parameter"
+            raise LoadError, "Browser tools require a driver. Install the 'ferrum' gem or pass a driver: parameter"
           end
         end
 

data/lib/shared_tools/tools/browser/page_inspect_tool.rb

@@ -43,10 +43,12 @@ module SharedTools
       private
 
         def default_driver
-          if defined?(Watir)
+          if defined?(Ferrum)
+            FerrumDriver.new(logger: @logger)
+          elsif defined?(Watir)
             WatirDriver.new(logger: @logger)
           else
-            raise LoadError, "Browser tools require a driver. Either install the 'watir' gem or pass a driver: parameter"
+            raise LoadError, "Browser tools require a driver. Install the 'ferrum' gem or pass a driver: parameter"
           end
         end
       end

data/lib/shared_tools/tools/browser/page_screenshot_tool.rb

@@ -1,36 +1,48 @@
 # frozen_string_literal: true
 
-require "base64"
-
 module SharedTools
   module Tools
     module Browser
       # A browser automation tool for taking screenshots of the current page.
+      # Saves the screenshot to a file and returns the path — avoids injecting
+      # large base64 blobs into the conversation context.
       class PageScreenshotTool < ::RubyLLM::Tool
         def self.name = 'browser_page_screenshot'
 
-        description "A browser automation tool for taking screenshots of the current page."
+        description "Take a screenshot of the current browser page and save it to a file."
+
+        params do
+          string :path, required: false,
+                        description: "File path to save the screenshot (e.g. 'screenshot.png'). " \
+                                     "Defaults to a timestamped name in the current directory."
+        end
 
         def initialize(driver: nil, logger: nil)
           @driver = driver || default_driver
           @logger = logger || RubyLLM.logger
         end
 
-        def execute
+        def execute(path: nil)
           @logger.info("#{self.class.name}##{__method__}")
 
+          save_path = path || "screenshot_#{Time.now.strftime('%Y%m%d_%H%M%S')}.png"
+
           @driver.screenshot do |file|
-            "data:image/png;base64,#{Base64.strict_encode64(file.read)}"
+            File.binwrite(save_path, file.read)
           end
+
+          { status: :ok, saved_to: File.expand_path(save_path) }
         end
 
       private
 
         def default_driver
-          if defined?(Watir)
+          if defined?(Ferrum)
+            FerrumDriver.new(logger: @logger)
+          elsif defined?(Watir)
             WatirDriver.new(logger: @logger)
           else
-            raise LoadError, "Browser tools require a driver. Either install the 'watir' gem or pass a driver: parameter"
+            raise LoadError, "Browser tools require a driver. Install the 'ferrum' gem or pass a driver: parameter"
           end
         end
       end

data/lib/shared_tools/tools/browser/selector_inspect_tool.rb

@@ -43,10 +43,12 @@ module SharedTools
       private
 
         def default_driver
-          if defined?(Watir)
+          if defined?(Ferrum)
+            FerrumDriver.new(logger: @logger)
+          elsif defined?(Watir)
             WatirDriver.new(logger: @logger)
           else
-            raise LoadError, "Browser tools require a driver. Either install the 'watir' gem or pass a driver: parameter"
+            raise LoadError, "Browser tools require a driver. Install the 'ferrum' gem or pass a driver: parameter"
           end
         end
 

data/lib/shared_tools/tools/browser/text_field_area_set_tool.rb

@@ -33,10 +33,12 @@ module SharedTools
       private
 
         def default_driver
-          if defined?(Watir)
+          if defined?(Ferrum)
+            FerrumDriver.new(logger: @logger)
+          elsif defined?(Watir)
             WatirDriver.new(logger: @logger)
           else
-            raise LoadError, "Browser tools require a driver. Either install the 'watir' gem or pass a driver: parameter"
+            raise LoadError, "Browser tools require a driver. Install the 'ferrum' gem or pass a driver: parameter"
           end
         end
       end

data/lib/shared_tools/tools/browser/visit_tool.rb

@@ -31,10 +31,12 @@ module SharedTools
       private
 
         def default_driver
-          if defined?(Watir)
+          if defined?(Ferrum)
+            FerrumDriver.new(logger: @logger)
+          elsif defined?(Watir)
             WatirDriver.new(logger: @logger)
           else
-            raise LoadError, "Browser tools require a driver. Either install the 'watir' gem or pass a driver: parameter"
+            raise LoadError, "Browser tools require a driver. Install the 'ferrum' gem or pass a driver: parameter"
           end
         end
       end

data/lib/shared_tools/tools/browser.rb

@@ -9,12 +9,41 @@ require 'shared_tools'
 require_relative 'browser/base_driver'
 require_relative 'browser/inspect_utils'
 
-# Try to load watir for browser automation
+# Load formatters (used by inspect_tool and related components)
+require_relative 'browser/formatters/action_formatter'
+require_relative 'browser/formatters/data_entry_formatter'
+require_relative 'browser/formatters/element_formatter'
+require_relative 'browser/formatters/input_formatter'
+
+# Load elements helpers (used by inspect_tool)
+require_relative 'browser/elements/element_grouper'
+require_relative 'browser/elements/nearby_element_detector'
+
+# Load page_inspect helpers (used by page_inspect_tool)
+require_relative 'browser/page_inspect/button_summarizer'
+require_relative 'browser/page_inspect/form_summarizer'
+require_relative 'browser/page_inspect/html_summarizer'
+require_relative 'browser/page_inspect/link_summarizer'
+
+# Load selector_generator and its sub-modules (used by click_tool and related)
+require_relative 'browser/selector_generator/base_selectors'
+require_relative 'browser/selector_generator/contextual_selectors'
+require_relative 'browser/selector_generator'
+
+# Try to load Ferrum (preferred) for browser automation via Chrome DevTools Protocol
+begin
+  require 'ferrum'
+  require_relative 'browser/ferrum_driver'
+rescue LoadError
+  # Ferrum gem not installed
+end
+
+# Fall back to Watir if available
 begin
   require 'watir'
   require_relative 'browser/watir_driver'
 rescue LoadError
-  # Watir gem not installed, BrowserTools will require manual driver
+  # Watir gem not installed
 end
 
 # Load tools (order matters - utils loaded first)

data/lib/shared_tools/tools/browser_tool.rb

@@ -155,6 +155,12 @@ module SharedTools
       # Set driver after instantiation (useful when tool is discovered by RubyLLM)
       attr_writer :driver
 
+      # Reports whether this tool can function.
+      # Returns true when a driver was injected or the watir gem is loaded.
+      def available?
+        !!@driver || defined?(Watir)
+      end
+
       def cleanup!
         @driver.close
       end

data/lib/shared_tools/tools/clipboard_tool.rb

@@ -1,59 +1,33 @@
 # frozen_string_literal: true
 
-require 'ruby_llm/tool'
+require_relative '../../shared_tools'
 
 module SharedTools
   module Tools
-    # A tool for reading from and writing to the system clipboard.
-    # Supports macOS (pbcopy/pbpaste), Linux (xclip/xsel), and Windows (clip).
+    # Read, write, and clear the system clipboard.
+    # Supports macOS (pbcopy/pbpaste), Linux (xclip or xsel), and Windows (clip/PowerShell).
     #
     # @example
     #   tool = SharedTools::Tools::ClipboardTool.new
-    #   tool.execute(action: 'write', content: 'Hello, World!')
-    #   result = tool.execute(action: 'read')
-    #   puts result[:content]  # "Hello, World!"
-    class ClipboardTool < RubyLLM::Tool
-      def self.name = 'clipboard'
+    #   tool.execute(action: 'write', text: 'Hello!')
+    #   tool.execute(action: 'read')
+    #   tool.execute(action: 'clear')
+    class ClipboardTool < ::RubyLLM::Tool
+      def self.name = 'clipboard_tool'
 
-      description <<~'DESCRIPTION'
-        Read from or write to the system clipboard.
-
-        This tool provides cross-platform clipboard access:
-        - macOS: Uses pbcopy/pbpaste
-        - Linux: Uses xclip or xsel (must be installed)
-        - Windows: Uses clip/powershell
+      description <<~DESC
+        Read from, write to, and clear the system clipboard.
+        Supports macOS, Linux (requires xclip or xsel), and Windows.
 
         Actions:
-        - 'read': Get the current clipboard contents
-        - 'write': Set the clipboard contents
-        - 'clear': Clear the clipboard
-
-        Example usage:
-          tool = SharedTools::Tools::ClipboardTool.new
-
-          # Write to clipboard
-          tool.execute(action: 'write', content: 'Hello, World!')
-
-          # Read from clipboard
-          result = tool.execute(action: 'read')
-          puts result[:content]
-
-          # Clear clipboard
-          tool.execute(action: 'clear')
-      DESCRIPTION
+        - 'read'  — Return the current clipboard contents
+        - 'write' — Replace clipboard contents with the given text
+        - 'clear' — Empty the clipboard
+      DESC
 
       params do
-        string :action, description: <<~DESC.strip
-          The clipboard action to perform:
-          - 'read': Get current clipboard contents
-          - 'write': Set clipboard contents (requires 'content' parameter)
-          - 'clear': Clear the clipboard
-        DESC
-
-        string :content, description: <<~DESC.strip, required: false
-          The text content to write to the clipboard.
-          Required when action is 'write'.
-        DESC
+        string :action, description: "Action to perform: 'read', 'write', or 'clear'"
+        string :text, required: false, description: "Text to write. Required only for the 'write' action."
       end
 
       # @param logger [Logger] optional logger
@@ -61,133 +35,84 @@ module SharedTools
         @logger = logger || RubyLLM.logger
       end
 
-      # Execute clipboard action
-      #
       # @param action [String] 'read', 'write', or 'clear'
-      # @param content [String, nil] content to write (required for 'write' action)
-      # @return [Hash] result with success status and content/error
-      def execute(action:, content: nil)
-        @logger.info("ClipboardTool#execute action=#{action.inspect}")
+      # @param text   [String, nil] text for write action
+      # @return [Hash] result
+      def execute(action:, text: nil)
+        @logger.info("ClipboardTool#execute action=#{action}")
 
         case action.to_s.downcase
-        when 'read'
-          read_clipboard
-        when 'write'
-          write_clipboard(content)
-        when 'clear'
-          clear_clipboard
+        when 'read'  then read_clipboard
+        when 'write' then write_clipboard(text)
+        when 'clear' then clear_clipboard
         else
-          {
-            success: false,
-            error: "Unknown action: #{action}. Valid actions are: read, write, clear"
-          }
+          { success: false, error: "Unknown action '#{action}'. Use: read, write, clear" }
         end
       rescue => e
         @logger.error("ClipboardTool error: #{e.message}")
-        {
-          success: false,
-          error: e.message
-        }
+        { success: false, error: e.message }
       end
 
       private
 
       def read_clipboard
-        content = case platform
-                  when :macos
-                    `pbpaste 2>/dev/null`
-                  when :linux
-                    if command_exists?('xclip')
-                      `xclip -selection clipboard -o 2>/dev/null`
-                    elsif command_exists?('xsel')
-                      `xsel --clipboard --output 2>/dev/null`
-                    else
-                      raise "No clipboard tool found. Install xclip or xsel."
-                    end
-                  when :windows
-                    `powershell -command "Get-Clipboard" 2>nul`.chomp
-                  else
-                    raise "Unsupported platform: #{RUBY_PLATFORM}"
-                  end
-
-        {
-          success: true,
-          content: content,
-          length: content.length
-        }
+        content = clipboard_read
+        { success: true, content: content, length: content.length }
       end
 
-      def write_clipboard(content)
-        if content.nil? || content.empty?
-          return {
-            success: false,
-            error: "Content is required for write action"
-          }
-        end
+      def write_clipboard(text)
+        raise ArgumentError, "text is required for the write action" if text.nil?
+        clipboard_write(text)
+        { success: true, message: "Text written to clipboard", length: text.length }
+      end
 
-        case platform
-        when :macos
-          IO.popen('pbcopy', 'w') { |io| io.print content }
-        when :linux
-          if command_exists?('xclip')
-            IO.popen('xclip -selection clipboard', 'w') { |io| io.print content }
-          elsif command_exists?('xsel')
-            IO.popen('xsel --clipboard --input', 'w') { |io| io.print content }
-          else
-            raise "No clipboard tool found. Install xclip or xsel."
-          end
-        when :windows
-          IO.popen('clip', 'w') { |io| io.print content }
+      def clear_clipboard
+        clipboard_write('')
+        { success: true, message: "Clipboard cleared" }
+      end
+
+      def clipboard_read
+        if macos?
+          `pbpaste`
+        elsif linux_xclip?
+          `xclip -selection clipboard -o 2>/dev/null`
+        elsif linux_xsel?
+          `xsel --clipboard --output 2>/dev/null`
+        elsif windows?
+          `powershell -command "Get-Clipboard" 2>/dev/null`.strip
         else
-          raise "Unsupported platform: #{RUBY_PLATFORM}"
+          raise "Clipboard not supported on this platform. Install xclip or xsel on Linux."
         end
-
-        {
-          success: true,
-          message: "Content written to clipboard",
-          length: content.length
-        }
       end
 
-      def clear_clipboard
-        case platform
-        when :macos
-          IO.popen('pbcopy', 'w') { |io| io.print '' }
-        when :linux
-          if command_exists?('xclip')
-            IO.popen('xclip -selection clipboard', 'w') { |io| io.print '' }
-          elsif command_exists?('xsel')
-            IO.popen('xsel --clipboard --input', 'w') { |io| io.print '' }
-          else
-            raise "No clipboard tool found. Install xclip or xsel."
-          end
-        when :windows
-          IO.popen('clip', 'w') { |io| io.print '' }
+      def clipboard_write(text)
+        if macos?
+          IO.popen('pbcopy', 'w') { |io| io.write(text) }
+        elsif linux_xclip?
+          IO.popen('xclip -selection clipboard', 'w') { |io| io.write(text) }
+        elsif linux_xsel?
+          IO.popen('xsel --clipboard --input', 'w') { |io| io.write(text) }
+        elsif windows?
+          IO.popen('clip', 'w') { |io| io.write(text) }
         else
-          raise "Unsupported platform: #{RUBY_PLATFORM}"
+          raise "Clipboard not supported on this platform. Install xclip or xsel on Linux."
         end
+      end
 
-        {
-          success: true,
-          message: "Clipboard cleared"
-        }
+      def macos?
+        RUBY_PLATFORM.include?('darwin')
       end
 
-      def platform
-        case RUBY_PLATFORM
-        when /darwin/
-          :macos
-        when /linux/
-          :linux
-        when /mswin|mingw|cygwin/
-          :windows
-        else
-          :unknown
-        end
+      def windows?
+        RUBY_PLATFORM.match?(/mswin|mingw|cygwin/)
+      end
+
+      def linux_xclip?
+        @linux_xclip ||= system('which xclip > /dev/null 2>&1')
       end
 
-      def command_exists?(cmd)
-        system("which #{cmd} > /dev/null 2>&1")
+      def linux_xsel?
+        @linux_xsel ||= system('which xsel > /dev/null 2>&1')
       end
     end
   end

data/lib/shared_tools/tools/composite_analysis_tool.rb

@@ -18,12 +18,22 @@ module SharedTools
       DESCRIPTION
 
       params do
-        string :data_source, description: <<~DESC.strip, required: true
+        string :data_source, description: <<~DESC.strip, required: false
           Primary data source to analyze. Can be either a local file path or a web URL.
           For files: Use relative or absolute paths to CSV, JSON, XML, or text files.
           For URLs: Use complete HTTP/HTTPS URLs to accessible data endpoints or web pages.
           The tool automatically detects the source type and uses appropriate fetching methods.
           Examples: './data/sales.csv', '/home/user/data.json', 'https://api.example.com/data'
+          Either data_source or data must be provided.
+        DESC
+
+        string :data, description: <<~DESC.strip, required: false
+          Inline data to analyze, provided directly as a string. Accepts:
+          - Pipe-delimited markdown tables (header row with | separators)
+          - CSV text (comma-separated rows, first row treated as headers)
+          - JSON text (object or array)
+          - Plain text (one item per line)
+          Either data or data_source must be provided.
         DESC
 
         string :analysis_type, description: <<~DESC.strip, required: false
@@ -48,16 +58,23 @@ module SharedTools
         @logger = logger || RubyLLM.logger
       end
 
-      def execute(data_source:, analysis_type: "standard", **options)
+      def execute(data_source: nil, data: nil, analysis_type: "standard", **options)
+        if data_source.nil? && data.nil?
+          return { success: false, error: "Either data_source or data must be provided." }
+        end
+
         results = {}
         analysis_start = Time.now
 
         begin
-          @logger.info("CompositeAnalysisTool#execute data_source=#{data_source} analysis_type=#{analysis_type}")
+          @logger.info("CompositeAnalysisTool#execute data_source=#{data_source.inspect} analysis_type=#{analysis_type}")
 
           # Step 1: Fetch data using appropriate method
           @logger.debug("Fetching data from source...")
-          if data_source.start_with?('http://', 'https://')
+          if data
+            results[:data] = parse_inline_data(data)
+            results[:source_type] = 'inline'
+          elsif data_source.start_with?('http://', 'https://')
             results[:data] = fetch_web_data(data_source)
             results[:source_type] = 'web'
           else
@@ -116,6 +133,45 @@ module SharedTools
 
       private
 
+      # Parse inline data string into a Ruby structure.
+      # Handles pipe-delimited markdown tables, CSV, JSON, and plain text.
+      def parse_inline_data(raw)
+        raw = raw.strip
+
+        # JSON
+        if raw.start_with?('{', '[')
+          begin
+            return JSON.parse(raw)
+          rescue JSON::ParserError
+            # fall through
+          end
+        end
+
+        lines = raw.lines.map(&:strip).reject(&:empty?)
+
+        # Pipe-delimited markdown table: "Col A | Col B | Col C"
+        if lines.first&.include?('|')
+          headers = lines.first.split('|').map(&:strip).reject(&:empty?)
+          data_lines = lines.drop(1).reject { |l| l.match?(/^\|?[-:\s|]+$/) }
+          return data_lines.map do |line|
+            values = line.split('|').map(&:strip).reject(&:empty?)
+            headers.zip(values).to_h
+          end
+        end
+
+        # CSV (comma-separated)
+        if lines.first&.include?(',')
+          headers = lines.first.split(',').map(&:strip)
+          return lines.drop(1).map do |line|
+            values = line.split(',').map(&:strip)
+            headers.zip(values).to_h
+          end
+        end
+
+        # Plain text — return as array of lines
+        lines
+      end
+
       # Fetch data from web URL
       def fetch_web_data(url)
         @logger.debug("Fetching web data from: #{url}")