shared_tools 0.3.0 → 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

@@ -146,10 +146,19 @@ module SharedTools
 
 
       # @param logger [Logger] optional logger
-      # @param driver [SharedTools::Tools::Browser::BaseDriver] optional, will attempt to create WatirDriver if not provided
+      # @param driver [SharedTools::Tools::Browser::BaseDriver] optional, will attempt to create WatirDriver when execute is called
       def initialize(logger: nil, driver: nil)
         @logger = logger || RubyLLM.logger
-        @driver = driver || default_driver
+        @driver = driver  # Defer default_driver to execute time to support RubyLLM tool discovery
+      end
+
+      # 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!
@@ -166,6 +175,9 @@ module SharedTools
       #
       # @return [String]
       def execute(action:, url: nil, selector: nil, value: nil, context_size: 2, full_html: false, text_content: nil)
+        # Lazily resolve driver at execute time
+        @driver ||= default_driver
+
         case action.to_s.downcase
         when Action::VISIT
           require_param!(:url, url)

data/lib/shared_tools/tools/clipboard_tool.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+require_relative '../../shared_tools'
+
+module SharedTools
+  module Tools
+    # 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', text: 'Hello!')
+    #   tool.execute(action: 'read')
+    #   tool.execute(action: 'clear')
+    class ClipboardTool < ::RubyLLM::Tool
+      def self.name = 'clipboard_tool'
+
+      description <<~DESC
+        Read from, write to, and clear the system clipboard.
+        Supports macOS, Linux (requires xclip or xsel), and Windows.
+
+        Actions:
+        - 'read'  — Return the current clipboard contents
+        - 'write' — Replace clipboard contents with the given text
+        - 'clear' — Empty the clipboard
+      DESC
+
+      params do
+        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
+      def initialize(logger: nil)
+        @logger = logger || RubyLLM.logger
+      end
+
+      # @param action [String] 'read', 'write', or 'clear'
+      # @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'  then read_clipboard
+        when 'write' then write_clipboard(text)
+        when 'clear' then clear_clipboard
+        else
+          { success: false, error: "Unknown action '#{action}'. Use: read, write, clear" }
+        end
+      rescue => e
+        @logger.error("ClipboardTool error: #{e.message}")
+        { success: false, error: e.message }
+      end
+
+      private
+
+      def read_clipboard
+        content = clipboard_read
+        { success: true, content: content, length: content.length }
+      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
+
+      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 "Clipboard not supported on this platform. Install xclip or xsel on Linux."
+        end
+      end
+
+      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 "Clipboard not supported on this platform. Install xclip or xsel on Linux."
+        end
+      end
+
+      def macos?
+        RUBY_PLATFORM.include?('darwin')
+      end
+
+      def windows?
+        RUBY_PLATFORM.match?(/mswin|mingw|cygwin/)
+      end
+
+      def linux_xclip?
+        @linux_xclip ||= system('which xclip > /dev/null 2>&1')
+      end
+
+      def linux_xsel?
+        @linux_xsel ||= system('which xsel > /dev/null 2>&1')
+      end
+    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}")

data/lib/shared_tools/tools/computer/mac_driver.rb

@@ -21,7 +21,15 @@ module SharedTools
         # @param text [String]
         # @param duration [Integer]
         def hold_key(text:, duration:)
-          raise NotImplementedError, "#{self.class.name}##{__method__} undefined"
+          options = text.to_s.split('+')
+          key     = options.pop
+          mask    = options.reduce(0) { |m, opt| m | Library::CoreGraphics::EventFlags.find(opt) }
+
+          @keyboard.key_down(key, mask: mask)
+          Kernel.sleep(duration.to_f)
+          @keyboard.key_up(key, mask: mask)
+
+          { success: true, key: text, duration: duration }
         end
 
         # @return [Hash<{ x: Integer, y: Integer }>]
@@ -86,10 +94,35 @@ module SharedTools
           @keyboard.type(text)
         end
 
-        # @param amount [Integer]
-        # @param direction [String] e.g. "up", "down", "left", "right"
+        # @param amount [Integer]    number of scroll units
+        # @param direction [String] "up", "down", "left", or "right"
         def scroll(amount:, direction:)
-          raise NotImplementedError, "#{self.class.name}##{__method__} undefined"
+          # Attach CGEventCreateScrollWheelEvent2 if not already done
+          unless Library::CoreGraphics.respond_to?(:CGEventCreateScrollWheelEvent2)
+            Library::CoreGraphics.module_eval do
+              attach_function :CGEventCreateScrollWheelEvent2,
+                              [:pointer, :uint32, :uint32, :int32, :int32, :int32],
+                              :pointer
+            end
+          end
+
+          amt = amount.to_i
+          # kCGScrollEventUnitLine = 1; wheel_count = 2 (vertical + horizontal)
+          delta_y, delta_x = case direction.to_s.downcase
+                             when 'up'    then [ amt,  0]
+                             when 'down'  then [-amt,  0]
+                             when 'left'  then [0, -amt]
+                             when 'right' then [0,  amt]
+                             else              [0,    0]
+                             end
+
+          event = Library::CoreGraphics.CGEventCreateScrollWheelEvent2(nil, 1, 2, delta_y, delta_x, 0)
+          Library::CoreGraphics.CGEventPost(
+            Library::CoreGraphics::EventTapLocation::HID_EVENT_TAP, event
+          )
+          Library::CoreGraphics.CFRelease(event)
+
+          { success: true, direction: direction, amount: amt }
         end
 
         # @yield [file]

data/lib/shared_tools/tools/computer_tool.rb

@@ -139,13 +139,16 @@ module SharedTools
       end
 
 
-      # @param driver [Computer::BaseDriver] optional, will attempt to create platform-specific driver if not provided
+      # @param driver [Computer::BaseDriver] optional, will attempt to create platform-specific driver when execute is called
       # @param logger [Logger] optional logger
       def initialize(driver: nil, logger: nil)
         @logger = logger || RubyLLM.logger
-        @driver = driver || default_driver
+        @driver = driver  # Defer default_driver to execute time to support RubyLLM tool discovery
       end
 
+      # Set driver after instantiation (useful when tool is discovered by RubyLLM)
+      attr_writer :driver
+
       # @param action [String]
       # @param coordinate [Hash<{ width: Integer, height: Integer }>] the (x,y) coordinate
       # @param text [String]
@@ -162,6 +165,9 @@ module SharedTools
         scroll_direction: nil,
         scroll_amount: nil
       )
+        # Lazily resolve driver at execute time
+        @driver ||= default_driver
+
         @logger.info({
           action:,
           coordinate:,