gemlings-browser 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: cef53274076111e67c881d45ebeb7805e97bd3dafc99cee1a8b6e0a1379eb414
+  data.tar.gz: b876597b34cde7a45c0c6ace5f90efe489d125478794d6d94fd20cebe8ac58c5
+SHA512:
+  metadata.gz: 9e623e7c85927529955ac58eb5ae89a5f4f11bf162e566db501de1d82a800d0d2d0755233a1255b8241566112f713d376292fdb82e9fdbc812886c43c3a79520
+  data.tar.gz: 81037dcbcfad32530b4f6e5cb6833e8e75b14d98d2d968467fbfacdd511c9dce8ce5f72d32d0ccd7a9f133bea9448b16d5d84f6edee6cd1344a80a13c32f291f

data/LICENSE

@@ -0,0 +1,105 @@
+# Functional Source License, Version 1.1, Apache 2.0 Future License
+
+## Abbreviation
+
+FSL-1.1-Apache-2.0
+
+## Notice
+
+Copyright 2026 Abhishek Parolkar
+
+## Terms and Conditions
+
+### Licensor ("We")
+
+Abhishek Parolkar and his affiliated entities, the party offering the Software and Content under these Terms and Conditions.
+
+### The Software and Content
+
+The "Software and Content" refers to each version of the software, documentation, approaches, strategies, methodologies, and all other materials that we make available under these Terms and Conditions, as indicated by our inclusion of these Terms and Conditions with the Software and Content.
+
+### License Grant
+
+Subject to your compliance with this License Grant and the Patents,
+Redistribution and Trademark clauses below, we hereby grant you the right to
+use, copy, modify, create derivative works, publicly perform, publicly display
+and redistribute the Software and Content for any Permitted Purpose identified below.
+
+### Permitted Purpose
+
+A Permitted Purpose is any purpose other than a Competing Use. A Competing Use
+means making the Software and Content available to others in a commercial product or
+service that:
+
+1. substitutes for the Software and Content;
+
+2. substitutes for any other product or service we offer using the Software and Content
+   that exists as of the date we make the Software and Content available; or
+
+3. offers the same or substantially similar functionality as the Software and Content.
+
+Permitted Purposes specifically include using the Software and Content:
+
+1. for your internal use and access;
+
+2. for non-commercial education;
+
+3. for non-commercial research; and
+
+4. in connection with professional services that you provide to a licensee
+   using the Software and Content in accordance with these Terms and Conditions.
+
+### Patents
+
+To the extent your use for a Permitted Purpose would necessarily infringe our
+patents, the license grant above includes a license under our patents. If you
+make a claim against any party that the Software and Content infringes or contributes to
+the infringement of any patent, then your patent license to the Software and Content ends
+immediately.
+
+### Redistribution
+
+The Terms and Conditions apply to all copies, modifications and derivatives of
+the Software and Content.
+
+If you redistribute any copies, modifications or derivatives of the Software and Content,
+you must include a copy of or a link to these Terms and Conditions and not
+remove any copyright notices provided in or with the Software and Content.
+
+### Disclaimer
+
+THE SOFTWARE AND CONTENT IS PROVIDED "AS IS" AND WITHOUT WARRANTIES OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING WITHOUT LIMITATION WARRANTIES OF FITNESS FOR A PARTICULAR
+PURPOSE, MERCHANTABILITY, TITLE OR NON-INFRINGEMENT.
+
+IN NO EVENT WILL WE HAVE ANY LIABILITY TO YOU ARISING OUT OF OR RELATED TO THE
+SOFTWARE AND CONTENT, INCLUDING INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES,
+EVEN IF WE HAVE BEEN INFORMED OF THEIR POSSIBILITY IN ADVANCE.
+
+### Trademarks and Domain Names
+
+Except for displaying the License Details and identifying us as the origin of
+the Software and Content, you have no right under these Terms and Conditions to use our
+trademarks, trade names, service marks or product names.
+
+The fully qualified name "https://github.com/parolkar" and the domain names associated with it are the exclusive property of Abhishek Parolkar. No right or license is granted to use these names or domains in any manner whatsoever without the express written permission of Abhishek Parolkar. Any unauthorized use of these names or domains is strictly prohibited.
+
+## Grant of Future License
+
+We hereby irrevocably grant you an additional license to use the Software and Content under
+the Apache License, Version 2.0 that is effective on the second anniversary of
+the date we make the Software and Content available. On or after that date, you may use the
+Software and Content under the Apache License, Version 2.0, in which case the following
+will apply:
+
+Licensed under the Apache License, Version 2.0 (the "License"); you may not use
+this file except in compliance with the License.
+
+You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed
+under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
+CONDITIONS OF ANY KIND, either express or implied. See the License for the
+specific language governing permissions and limitations under the License.

data/README.md

@@ -0,0 +1,114 @@
+# gemlings-browser
+
+Browser automation for [Gemlings](https://github.com/parolkar/jrubyagents) agents, powered by Playwright.
+
+## Quick Start
+
+```bash
+# 1. Install the gem
+gem install gemlings-browser
+
+# 2. Install Playwright + Chromium
+gemlings-browser install
+
+# 3. Use with an agent
+```
+
+```ruby
+require "gemlings"
+require "gemlings/browser"
+
+agent = Gemlings::CodeAgent.new(
+  model: "anthropic/claude-sonnet-4-20250514",
+  tools: [Gemlings::Browser::BrowseTool]
+)
+
+agent.run("Go to example.com and get the page title")
+```
+
+## Tools
+
+### `browser_action`
+
+The primary tool. Executes Ruby code with browser access.
+
+```ruby
+# The agent writes code like this:
+page = browser.get_page("main")
+page.goto("https://news.ycombinator.com")
+titles = page.query_selector_all(".titleline a").map(&:text_content)
+puts titles.first(5).join("\n")
+```
+
+Available in scripts:
+- `browser.get_page("name")` — Named page (persists across calls)
+- `browser.new_page` — Anonymous page
+- `browser.list_pages` — List all tabs
+- `browser.close_page("name")` — Close a tab
+- `save_screenshot(page, "file.png")` — Save screenshot
+- `write_file("name", data)` / `read_file("name")` — Sandboxed file I/O
+
+### `browser_screenshot`
+
+Takes a screenshot of a named page.
+
+```ruby
+tools: [Gemlings::Browser::BrowseTool, Gemlings::Browser::ScreenshotTool]
+```
+
+### `browser_list_pages`
+
+Lists all open pages with names, URLs, and titles.
+
+### `browser_close_page`
+
+Closes a named page.
+
+## Configuration
+
+```ruby
+GemlingsBrowser.configure do |c|
+  c.headless = true          # default: false
+  c.timeout = 60             # default: 30 seconds
+  c.browser_type = :chromium # default: :chromium
+  c.base_dir = "~/.my-dir"  # default: ~/.gemlings-browser
+end
+```
+
+## Connecting to Existing Chrome
+
+Launch Chrome with remote debugging:
+
+```bash
+google-chrome --remote-debugging-port=9222
+```
+
+Use `BrowseTool` with auto-connect:
+
+```ruby
+tool = Gemlings::Browser::BrowseTool.new(connect: true)
+agent = Gemlings::CodeAgent.new(
+  model: "anthropic/claude-sonnet-4-20250514",
+  tools: [tool]
+)
+```
+
+The gem auto-discovers Chrome via DevToolsActivePort files and port probing (9222–9229).
+
+## Privacy
+
+gemlings-browser makes **zero outbound network requests** on its own. All browser activity is local and under your control.
+
+- Playwright telemetry is disabled (`PLAYWRIGHT_TELEMETRY_DISABLED=1`)
+- No analytics, tracking, or phone-home code
+- Temp files are sandboxed to `~/.gemlings-browser/tmp/`
+- No cloud dependencies or API keys required
+
+## Requirements
+
+- Ruby 3.2+ or JRuby 10+
+- Node.js (for Playwright driver)
+
+## License
+
+MIT — see [LICENSE](LICENSE).

data/exe/gemlings-browser

@@ -0,0 +1,22 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative "../lib/gemlings_browser/version"
+
+case ARGV[0]
+when "install"
+  require_relative "../lib/gemlings/browser"
+  GemlingsBrowser::Installer.run
+when "status"
+  require_relative "../lib/gemlings/browser"
+  GemlingsBrowser::Installer.status
+when "version", "-v", "--version"
+  puts "gemlings-browser #{GemlingsBrowser::VERSION}"
+else
+  puts "gemlings-browser v#{GemlingsBrowser::VERSION}"
+  puts ""
+  puts "Usage:"
+  puts "  gemlings-browser install   Install Playwright + Chromium"
+  puts "  gemlings-browser status    Show installation status"
+  puts "  gemlings-browser version   Show gem version"
+end

data/lib/gemlings/browser.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+# Main entry point for gemlings-browser.
+# Usage:
+#   require "gemlings/browser"
+
+# Disable Playwright telemetry — no data leaves the machine.
+ENV["PLAYWRIGHT_TELEMETRY_DISABLED"] = "1"
+
+require "gemlings"
+require_relative "../gemlings_browser/version"
+require_relative "../gemlings_browser/configuration"
+require_relative "../gemlings_browser/page_registry"
+require_relative "../gemlings_browser/chrome_discovery"
+require_relative "../gemlings_browser/temp_files"
+require_relative "../gemlings_browser/browser_manager"
+require_relative "../gemlings_browser/installer"
+require_relative "../gemlings_browser/tools/browse_tool"
+require_relative "../gemlings_browser/tools/screenshot_tool"
+require_relative "../gemlings_browser/tools/list_pages_tool"
+require_relative "../gemlings_browser/tools/close_page_tool"

data/lib/gemlings_browser/browser_manager.rb

@@ -0,0 +1,153 @@
+# frozen_string_literal: true
+
+require "playwright"
+
+module GemlingsBrowser
+  class BrowserManager
+    # Holds a Playwright connection, browser, context, and its page registry.
+    BrowserEntry = Struct.new(:playwright, :browser, :context, :registry, keyword_init: true)
+
+    def initialize
+      @browsers = {}
+      @mutex = Mutex.new
+    end
+
+    # Launch or reuse a managed Chromium instance.
+    def ensure_browser(name, headless: nil, ignore_https_errors: false)
+      @mutex.synchronize do
+        entry = @browsers[name]
+        return entry if entry && browser_alive?(entry)
+
+        cleanup_entry(entry) if entry
+        @browsers[name] = launch_browser(headless: headless, ignore_https_errors: ignore_https_errors)
+      end
+    end
+
+    # Connect to a running browser via CDP WebSocket endpoint.
+    def connect_browser(name, endpoint)
+      @mutex.synchronize do
+        entry = @browsers[name]
+        return entry if entry && browser_alive?(entry)
+
+        cleanup_entry(entry) if entry
+        @browsers[name] = connect_cdp(endpoint)
+      end
+    end
+
+    # Auto-discover a running Chrome and connect to it.
+    # Returns the BrowserEntry, or nil if nothing found.
+    def auto_connect(name)
+      endpoint = ChromeDiscovery.new.discover
+      return nil unless endpoint
+
+      connect_browser(name, endpoint)
+    end
+
+    # Get or create a named page for the given browser.
+    # The page persists across calls until explicitly closed.
+    def get_page(browser_name, page_name)
+      entry = fetch_entry!(browser_name)
+      page = entry.registry.get(page_name)
+      return page if page
+
+      page = entry.context.new_page
+      entry.registry.set(page_name, page)
+      page
+    end
+
+    # Create an anonymous page (caller is responsible for closing it).
+    def new_page(browser_name)
+      entry = fetch_entry!(browser_name)
+      entry.context.new_page
+    end
+
+    # List all tracked pages for a browser.
+    def list_pages(browser_name)
+      entry = fetch_entry!(browser_name)
+      entry.registry.all
+    end
+
+    # Close a named page.
+    def close_page(browser_name, page_name)
+      entry = fetch_entry!(browser_name)
+      entry.registry.remove(page_name)
+    end
+
+    # Stop a specific browser and clean up its resources.
+    def stop_browser(name)
+      @mutex.synchronize do
+        entry = @browsers.delete(name)
+        cleanup_entry(entry) if entry
+      end
+    end
+
+    # Shutdown all browsers and Playwright connections.
+    def stop_all
+      @mutex.synchronize do
+        @browsers.each_value { |entry| cleanup_entry(entry) }
+        @browsers.clear
+      end
+    end
+
+    private
+
+    def fetch_entry!(browser_name)
+      entry = @mutex.synchronize { @browsers[browser_name] }
+      raise "No browser named '#{browser_name}'. Call ensure_browser or auto_connect first." unless entry
+
+      entry
+    end
+
+    def launch_browser(headless:, ignore_https_errors:)
+      config = GemlingsBrowser.configuration
+      headless = config.headless if headless.nil?
+
+      playwright = Playwright.create(
+        playwright_cli_executable_path: config.playwright_cli_path
+      )
+
+      browser = playwright.playwright.chromium.launch(headless: headless)
+      context = browser.new_context(ignoreHTTPSErrors: ignore_https_errors)
+
+      BrowserEntry.new(
+        playwright: playwright,
+        browser: browser,
+        context: context,
+        registry: PageRegistry.new
+      )
+    end
+
+    def connect_cdp(endpoint)
+      config = GemlingsBrowser.configuration
+
+      playwright = Playwright.create(
+        playwright_cli_executable_path: config.playwright_cli_path
+      )
+
+      browser = playwright.playwright.chromium.connect_over_cdp(endpoint)
+      context = browser.contexts.first || browser.new_context
+
+      BrowserEntry.new(
+        playwright: playwright,
+        browser: browser,
+        context: context,
+        registry: PageRegistry.new
+      )
+    end
+
+    def browser_alive?(entry)
+      entry.browser.connected?
+    rescue StandardError
+      false
+    end
+
+    def cleanup_entry(entry)
+      return unless entry
+
+      entry.registry.clear
+      entry.context&.close rescue nil
+      entry.browser&.close rescue nil
+      entry.playwright&.stop rescue nil
+    end
+  end
+end

data/lib/gemlings_browser/chrome_discovery.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "json"
+
+module GemlingsBrowser
+  class ChromeDiscovery
+    DISCOVERY_PORTS = (9222..9229).to_a.freeze
+    PROBE_TIMEOUT = 0.75 # seconds
+
+    # Attempt to discover a running Chrome instance.
+    # Returns a CDP WebSocket URL string, or nil.
+    def discover
+      endpoint = read_devtools_active_port
+      return endpoint if endpoint
+
+      DISCOVERY_PORTS.each do |port|
+        endpoint = probe_port(port)
+        return endpoint if endpoint
+      end
+
+      nil
+    end
+
+    private
+
+    # --- DevToolsActivePort file parsing ---
+
+    def read_devtools_active_port
+      devtools_active_port_candidates.each do |path|
+        next unless File.exist?(path)
+
+        lines = File.read(path).strip.split("\n")
+        next if lines.size < 2
+
+        port = lines[0].strip.to_i
+        ws_path = lines[1].strip
+        next if port.zero? || ws_path.empty?
+
+        return "ws://127.0.0.1:#{port}#{ws_path}"
+      end
+
+      nil
+    rescue StandardError
+      nil
+    end
+
+    def devtools_active_port_candidates
+      home = Dir.home
+      case host_os
+      when /darwin/i
+        [
+          File.join(home, "Library", "Application Support", "Google", "Chrome", "DevToolsActivePort"),
+          File.join(home, "Library", "Application Support", "Google", "Chrome Canary", "DevToolsActivePort"),
+          File.join(home, "Library", "Application Support", "Chromium", "DevToolsActivePort"),
+          File.join(home, "Library", "Application Support", "BraveSoftware", "Brave-Browser", "DevToolsActivePort")
+        ]
+      when /linux/i
+        [
+          File.join(home, ".config", "google-chrome", "DevToolsActivePort"),
+          File.join(home, ".config", "google-chrome-unstable", "DevToolsActivePort"),
+          File.join(home, ".config", "chromium", "DevToolsActivePort"),
+          File.join(home, ".config", "BraveSoftware", "Brave-Browser", "DevToolsActivePort")
+        ]
+      when /mingw|mswin|cygwin/i
+        local_app_data = ENV["LOCALAPPDATA"] || File.join(home, "AppData", "Local")
+        [
+          File.join(local_app_data, "Google", "Chrome", "User Data", "DevToolsActivePort"),
+          File.join(local_app_data, "Chromium", "User Data", "DevToolsActivePort"),
+          File.join(local_app_data, "BraveSoftware", "Brave-Browser", "User Data", "DevToolsActivePort")
+        ]
+      else
+        []
+      end
+    end
+
+    # --- Port probing ---
+
+    def probe_port(port)
+      uri = URI("http://127.0.0.1:#{port}/json/version")
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.open_timeout = PROBE_TIMEOUT
+      http.read_timeout = PROBE_TIMEOUT
+
+      response = http.get(uri.path)
+      return nil unless response.is_a?(Net::HTTPSuccess)
+
+      data = JSON.parse(response.body)
+      data["webSocketDebuggerUrl"]
+    rescue StandardError
+      nil
+    end
+
+    def host_os
+      RbConfig::CONFIG["host_os"]
+    end
+  end
+end

data/lib/gemlings_browser/configuration.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module GemlingsBrowser
+  class Configuration
+    attr_accessor :headless, :timeout, :base_dir, :browser_type, :playwright_cli_path
+
+    def initialize
+      @headless = false
+      @timeout = 30
+      @base_dir = File.join(Dir.home, ".gemlings-browser")
+      @browser_type = :chromium
+      @playwright_cli_path = detect_playwright_cli
+    end
+
+    private
+
+    def detect_playwright_cli
+      candidates = %w[playwright]
+      candidates.each do |cmd|
+        return cmd if command_exists?(cmd)
+      end
+      "npx playwright"
+    end
+
+    def command_exists?(cmd)
+      exts = ENV["PATHEXT"] ? ENV["PATHEXT"].split(";") : [""]
+      ENV["PATH"].to_s.split(File::PATH_SEPARATOR).each do |dir|
+        exts.each do |ext|
+          path = File.join(dir, "#{cmd}#{ext}")
+          return true if File.executable?(path) && !File.directory?(path)
+        end
+      end
+      false
+    end
+  end
+
+  class << self
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield(configuration)
+    end
+
+    def reset_configuration!
+      @configuration = Configuration.new
+    end
+
+    def manager
+      @manager ||= BrowserManager.new
+    end
+
+    def reset_manager!
+      @manager&.stop_all
+      @manager = nil
+    end
+  end
+end

data/lib/gemlings_browser/installer.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module GemlingsBrowser
+  module Installer
+    class << self
+      # Install Playwright and Chromium browser.
+      def run
+        puts "Installing Playwright browsers..."
+        cli = GemlingsBrowser.configuration.playwright_cli_path
+
+        success = system("#{cli} install chromium")
+        if success
+          puts "Chromium installed successfully."
+        else
+          warn "Failed to install Chromium. Ensure Node.js is installed and 'npx' is available."
+          exit 1
+        end
+      end
+
+      # Print installation status.
+      def status
+        cli = GemlingsBrowser.configuration.playwright_cli_path
+        puts "gemlings-browser v#{GemlingsBrowser::VERSION}"
+        puts "Playwright CLI: #{cli}"
+        puts ""
+        puts "Checking installed browsers..."
+        system("#{cli} install --dry-run chromium 2>&1") || puts("(Could not determine browser status)")
+        puts ""
+        puts "Base directory: #{GemlingsBrowser.configuration.base_dir}"
+        puts "Headless: #{GemlingsBrowser.configuration.headless}"
+        puts "Timeout: #{GemlingsBrowser.configuration.timeout}s"
+      end
+    end
+  end
+end

data/lib/gemlings_browser/page_registry.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+module GemlingsBrowser
+  class PageRegistry
+    def initialize
+      @pages = {}
+      @mutex = Mutex.new
+    end
+
+    # Retrieve a named page, or nil if not found / closed.
+    def get(name)
+      @mutex.synchronize do
+        page = @pages[name]
+        return nil unless page
+
+        if page_closed?(page)
+          @pages.delete(name)
+          return nil
+        end
+
+        page
+      end
+    end
+
+    # Store a named page.
+    def set(name, page)
+      @mutex.synchronize do
+        @pages[name] = page
+      end
+    end
+
+    # Return metadata for all live pages.
+    def all
+      @mutex.synchronize do
+        prune_closed_internal
+        @pages.map do |name, page|
+          {
+            name: name,
+            url: safe_page_attr(page, :url),
+            title: safe_page_attr(page, :title)
+          }
+        end
+      end
+    end
+
+    # Close and remove a named page. Returns true if found.
+    def remove(name)
+      @mutex.synchronize do
+        page = @pages.delete(name)
+        return false unless page
+
+        safe_close(page)
+        true
+      end
+    end
+
+    # Remove entries whose pages have been closed externally.
+    def prune_closed
+      @mutex.synchronize { prune_closed_internal }
+    end
+
+    # Number of tracked pages.
+    def size
+      @mutex.synchronize { @pages.size }
+    end
+
+    # Close all pages and clear the registry.
+    def clear
+      @mutex.synchronize do
+        @pages.each_value { |page| safe_close(page) }
+        @pages.clear
+      end
+    end
+
+    private
+
+    def prune_closed_internal
+      @pages.delete_if { |_name, page| page_closed?(page) }
+    end
+
+    def page_closed?(page)
+      page.closed?
+    rescue StandardError
+      true
+    end
+
+    def safe_close(page)
+      page.close unless page_closed?(page)
+    rescue StandardError
+      # Page may already be gone — ignore.
+    end
+
+    def safe_page_attr(page, attr)
+      page.public_send(attr)
+    rescue StandardError
+      nil
+    end
+  end
+end

data/lib/gemlings_browser/temp_files.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module GemlingsBrowser
+  module TempFiles
+    class << self
+      # Resolve a safe path within the sandboxed temp directory.
+      # Uses File.basename to prevent directory traversal attacks.
+      def path_for(name)
+        safe_name = File.basename(name.to_s)
+        raise ArgumentError, "Invalid filename" if safe_name.empty? || safe_name == "."
+
+        FileUtils.mkdir_p(temp_dir)
+        File.join(temp_dir, safe_name)
+      end
+
+      # Write data to a sandboxed file. Returns the full path.
+      def write(name, data)
+        path = path_for(name)
+        File.binwrite(path, data)
+        path
+      end
+
+      # Read a sandboxed file's contents.
+      def read(name)
+        path = path_for(name)
+        raise Errno::ENOENT, "File not found: #{name}" unless File.exist?(path)
+
+        File.binread(path)
+      end
+
+      # Convenience: return a path suitable for a screenshot.
+      def screenshot_path(name = nil)
+        name ||= "screenshot_#{Time.now.to_i}.png"
+        name = "#{name}.png" unless name.end_with?(".png", ".jpg", ".jpeg", ".webp")
+        path_for(name)
+      end
+
+      # Remove all temp files.
+      def cleanup!
+        FileUtils.rm_rf(temp_dir)
+      end
+
+      private
+
+      def temp_dir
+        File.join(GemlingsBrowser.configuration.base_dir, "tmp")
+      end
+    end
+  end
+end

data/lib/gemlings_browser/tools/browse_tool.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+require "stringio"
+require "timeout"
+
+module Gemlings
+  module Browser
+    class BrowseTool < Gemlings::Tool
+      tool_name "browser_action"
+      description <<~DESC
+        Controls a browser using Playwright. Execute Ruby code with access to:
+          browser.get_page("name")   - Get/create a named page (persists across calls)
+          browser.new_page           - Create an anonymous page
+          browser.list_pages         - List all tabs: [{name:, url:, title:}]
+          browser.close_page("name") - Close a named page
+          save_screenshot(page, "name.png") - Save screenshot, returns path
+          write_file("name", data)   - Write to sandboxed temp dir, returns path
+          read_file("name")          - Read from sandboxed temp dir
+
+        Pages are Playwright Page objects with full API:
+          page.goto(url), page.click(selector), page.fill(selector, value),
+          page.title, page.url, page.text_content(selector),
+          page.screenshot(path: "..."), page.evaluate(js),
+          page.query_selector_all(selector), page.wait_for_selector(selector), etc.
+
+        Named pages persist across calls — no need to re-navigate.
+      DESC
+      input :script, type: :string, description: "Ruby code to execute with browser access"
+      output_type :string
+
+      def initialize(browser_name: "default", headless: nil, connect: nil)
+        @browser_name = browser_name
+        @headless = headless
+        @connect = connect
+      end
+
+      def call(script:)
+        manager = GemlingsBrowser.manager
+
+        if @connect
+          unless manager.auto_connect(@browser_name)
+            manager.ensure_browser(@browser_name, headless: @headless)
+          end
+        else
+          manager.ensure_browser(@browser_name, headless: @headless)
+        end
+
+        context = build_context(manager)
+        execute_script(context, script)
+      end
+
+      private
+
+      def execute_script(context, script)
+        output = StringIO.new
+        old_stdout = $stdout
+
+        begin
+          $stdout = output
+          result = Timeout.timeout(GemlingsBrowser.configuration.timeout) do
+            context.instance_eval(script, "(browser-script)", 1)
+          end
+          $stdout = old_stdout
+
+          parts = []
+          parts << output.string unless output.string.empty?
+          parts << result.inspect unless result.nil?
+          parts.empty? ? "" : parts.join("\n")
+        rescue Timeout::Error
+          $stdout = old_stdout
+          "Error: Script timed out after #{GemlingsBrowser.configuration.timeout}s"
+        rescue => e
+          $stdout = old_stdout
+          "Error: #{e.class}: #{e.message}"
+        end
+      end
+
+      def build_context(manager)
+        ctx = Object.new
+        browser_name = @browser_name
+
+        # Build the browser API object
+        browser_api = Object.new
+        browser_api.define_singleton_method(:get_page) do |name|
+          manager.get_page(browser_name, name)
+        end
+        browser_api.define_singleton_method(:new_page) do
+          manager.new_page(browser_name)
+        end
+        browser_api.define_singleton_method(:list_pages) do
+          manager.list_pages(browser_name)
+        end
+        browser_api.define_singleton_method(:close_page) do |name|
+          manager.close_page(browser_name, name)
+        end
+
+        ctx.define_singleton_method(:browser) { browser_api }
+
+        # File I/O helpers
+        ctx.define_singleton_method(:save_screenshot) do |page, name|
+          path = GemlingsBrowser::TempFiles.screenshot_path(name)
+          page.screenshot(path: path)
+          path
+        end
+
+        ctx.define_singleton_method(:write_file) do |name, data|
+          GemlingsBrowser::TempFiles.write(name, data)
+        end
+
+        ctx.define_singleton_method(:read_file) do |name|
+          GemlingsBrowser::TempFiles.read(name)
+        end
+
+        ctx
+      end
+    end
+  end
+end

data/lib/gemlings_browser/tools/close_page_tool.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Gemlings
+  module Browser
+    class ClosePageTool < Gemlings::Tool
+      tool_name "browser_close_page"
+      description "Closes a named browser page."
+      input :page_name, type: :string, description: "Name of the page to close"
+      output_type :string
+
+      def call(page_name:)
+        manager = GemlingsBrowser.manager
+        if manager.close_page("default", page_name)
+          "Page '#{page_name}' closed."
+        else
+          "No page named '#{page_name}' found."
+        end
+      rescue => e
+        "Error: #{e.class}: #{e.message}"
+      end
+    end
+  end
+end

data/lib/gemlings_browser/tools/list_pages_tool.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Gemlings
+  module Browser
+    class ListPagesTool < Gemlings::Tool
+      tool_name "browser_list_pages"
+      description "Lists all open browser pages/tabs with their names, URLs, and titles."
+      output_type :string
+
+      def call(**_kwargs)
+        manager = GemlingsBrowser.manager
+        pages = manager.list_pages("default")
+
+        if pages.empty?
+          "No open pages."
+        else
+          lines = pages.map do |info|
+            "#{info[:name]}: #{info[:url] || '(blank)'} - #{info[:title] || '(untitled)'}"
+          end
+          lines.join("\n")
+        end
+      rescue => e
+        "Error: #{e.class}: #{e.message}"
+      end
+    end
+  end
+end

data/lib/gemlings_browser/tools/screenshot_tool.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Gemlings
+  module Browser
+    class ScreenshotTool < Gemlings::Tool
+      tool_name "browser_screenshot"
+      description "Takes a screenshot of a named browser page. Returns the file path."
+      input :page_name, type: :string, description: "Name of the page to screenshot"
+      input :filename, type: :string, description: "Output filename (e.g. 'debug.png')", required: false
+      output_type :string
+
+      def call(page_name:, filename: nil)
+        manager = GemlingsBrowser.manager
+        page = manager.get_page("default", page_name)
+
+        path = GemlingsBrowser::TempFiles.screenshot_path(filename || "#{page_name}.png")
+        page.screenshot(path: path)
+        path
+      rescue => e
+        "Error: #{e.class}: #{e.message}"
+      end
+    end
+  end
+end

data/lib/gemlings_browser/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module GemlingsBrowser
+  VERSION = "0.1.0"
+end

metadata

@@ -0,0 +1,116 @@
+--- !ruby/object:Gem::Specification
+name: gemlings-browser
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Abhishek Parolkar
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: gemlings
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.3.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.3.0
+- !ruby/object:Gem::Dependency
+  name: playwright-ruby-client
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.50'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.50'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+description: Gives Gemlings agents browser control via Playwright. Named persistent
+  pages, auto-connect to Chrome, screenshots, and sandboxed file I/O. Zero telemetry.
+email:
+- abhishek@parolkar.com
+executables:
+- gemlings-browser
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- exe/gemlings-browser
+- lib/gemlings/browser.rb
+- lib/gemlings_browser/browser_manager.rb
+- lib/gemlings_browser/chrome_discovery.rb
+- lib/gemlings_browser/configuration.rb
+- lib/gemlings_browser/installer.rb
+- lib/gemlings_browser/page_registry.rb
+- lib/gemlings_browser/temp_files.rb
+- lib/gemlings_browser/tools/browse_tool.rb
+- lib/gemlings_browser/tools/close_page_tool.rb
+- lib/gemlings_browser/tools/list_pages_tool.rb
+- lib/gemlings_browser/tools/screenshot_tool.rb
+- lib/gemlings_browser/version.rb
+homepage: https://github.com/parolkar/gemlings-browser
+licenses:
+- nonstandard
+metadata:
+  homepage_uri: https://github.com/parolkar/gemlings-browser
+  source_code_uri: https://github.com/parolkar/gemlings-browser
+  changelog_uri: https://github.com/parolkar/gemlings-browser/blob/main/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.7.2
+specification_version: 4
+summary: Browser automation tool for Gemlings agents
+test_files: []