flunky 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 396af494516ace4e790c451a749a47b96db080bfd9d386825902f249353b2196
+  data.tar.gz: 4f01dff6543ab4365691de268616669331fd3ec2d59812d6c35afe1dc362fe78
+SHA512:
+  metadata.gz: 22f541f37531252d1ac60a1183f53c975f471d9ac45cc8a13e9e80f8bbfc2882c5203360089a766fb91d4edea513a9da5410d573c1e708f5b893df518918f3a8
+  data.tar.gz: 7d50a1ba1ae192c0b9a468558499e5c1caf25a3b110b3e9a690d2592c5c89c85e8f3ce5dd94c60dd164f16b261bdb5701d4faf277e6e429f16fcd8eb22014e1d

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,38 @@
+AllCops:
+  TargetRubyVersion: 3.0
+  NewCops: enable
+  SuggestExtensions: false
+  Exclude:
+    - "examples/**/*"
+    # CI installs gems here via bundler-cache; never lint third-party code.
+    - "vendor/**/*"
+
+Metrics:
+  Enabled: false
+
+Style/Documentation:
+  Enabled: false
+
+# Short, conventional names (dx, dy, el) are intentional here.
+Naming/MethodParameterName:
+  MinNameLength: 2
+
+# Command methods on the driver return true to signal success; they are not
+# predicates and should not be forced to end with "?".
+Naming/PredicateMethod:
+  Enabled: false
+
+# The abstract driver declares keyword arguments it does not itself use.
+Lint/UnusedMethodArgument:
+  AllowUnusedKeywordArguments: true
+
+Style/StringLiterals:
+  Enabled: true
+  EnforcedStyle: double_quotes
+
+Style/StringLiteralsInInterpolation:
+  Enabled: true
+  EnforcedStyle: double_quotes
+
+Layout/LineLength:
+  Max: 120

data/.ruby-version

@@ -0,0 +1 @@
+3.3.6

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2026-06-18
+
+- Initial release

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,84 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, religion, or sexual identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes, and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or
+  advances of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email
+  address, without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening, offensive, or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, and will communicate reasons for moderation decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public spaces. Examples of representing our community include using an official e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders responsible for enforcement at alexrupom@hotmail.com. All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing clarity around the nature of the violation and an explanation of why the behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of actions.
+
+**Consequence**: A warning with consequences for continued behavior. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period of time. This includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public communication with the community for a specified period of time. No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community standards, including sustained inappropriate behavior,  harassment of an individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 2.0,
+available at https://www.contributor-covenant.org/version/2/0/code_of_conduct.html.
+
+Community Impact Guidelines were inspired by [Mozilla's code of conduct enforcement ladder](https://github.com/mozilla/diversity).
+
+[homepage]: https://www.contributor-covenant.org
+
+For answers to common questions about this code of conduct, see the FAQ at
+https://www.contributor-covenant.org/faq. Translations are available at https://www.contributor-covenant.org/translations.

data/Gemfile

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+# Runtime dependencies live in flunky.gemspec (ferrum).
+gemspec
+
+# Development and test tooling: not needed by anyone who installs the gem.
+group :development, :test do
+  gem "rake", "~> 13.0"
+  gem "rspec", "~> 3.0"
+  gem "rubocop", "~> 1.21"
+end

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 alexrupom
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,100 @@
+# Flunky
+
+Flunky lets any AI agent drive a real browser. It borrows the layering of a
+browser automation library (a thin driver, a stateful session, a readable action
+DSL) and adds the two things an agent needs that a test framework does not: a way
+to show the page to a model, and a way to expose actions as tools the model can
+call.
+
+The gem never calls an AI vendor itself. It emits tool schemas and a dispatcher;
+you inject the model client.
+
+## How it fits together
+
+- **Driver** (`Drivers::Base`, `Drivers::FerrumDriver`) talks to the browser.
+  Ferrum drives Chrome over the DevTools Protocol with no Selenium server. The
+  backend is swappable.
+- **Snapshot** reduces the live page to the elements an agent can act on, each
+  stamped with an integer `ref`, and renders a compact prompt block.
+- **Actions** is the human-readable DSL over the driver (`click`, `type`,
+  `fill_in`, ...).
+- **Session** owns one driver, caches the latest snapshot, and exposes the
+  actions.
+- **Tools** turns a session into vendor-neutral tool schemas plus a dispatcher.
+- **Agent** is an optional observe/decide/act loop around an injected model.
+
+## Installation
+
+Flunky needs Ruby >= 3.0 and a local Chrome (Ferrum launches it).
+
+```
+bundle add flunky
+```
+
+or
+
+```
+gem install flunky
+```
+
+## Usage
+
+```ruby
+require "flunky"
+
+Flunky.session do |s|
+  s.visit("https://example.com")
+  puts s.snapshot.to_prompt   # the page as the model sees it
+  s.actions.click(1)          # act on a stamped ref
+end
+```
+
+`refs` only exist after a snapshot stamps them, so observe (or read
+`snapshot`) before acting. After client-side navigation a ref can go stale; the
+tool dispatcher re-observes after every action so the model always sees the
+current page.
+
+### Tool calling
+
+```ruby
+session = Flunky::Session.new
+tools = Flunky::Tools.new(session)
+
+tools.definitions          # hand straight to an Anthropic style client
+tools.dispatch("click", { ref: 1 })  # run a returned tool call
+```
+
+The tool schema shape (`name` / `description` / `input_schema`) matches
+Anthropic's tool format. For OpenAI, wrap each definition as
+`{ type: "function", function: { **defn, parameters: defn[:input_schema] } }`.
+
+### Agent loop
+
+`Flunky::Agent.new(session, model:)` drives an observe/decide/act loop. `model`
+must respond to `call(messages:, tools:)` and return
+`{ text:, tool_calls: [{ id:, name:, arguments: }] }`. See
+[examples/anthropic_agent.rb](examples/anthropic_agent.rb) for a roughly 50 line
+adapter to Anthropic's `/v1/messages` endpoint.
+
+### Configuration
+
+```ruby
+Flunky.configure do |c|
+  c.headless = true
+  c.default_timeout = 10
+  c.max_elements = 200
+  c.window_size = [1280, 800]
+end
+```
+
+Per-session options passed to `Session.new` override the global configuration.
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies, then
+`bundle exec rspec`. Specs tagged `:browser` are skipped automatically when
+Chrome is not installed, so the suite passes on a bare machine.
+
+## License
+
+Available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/examples/anthropic_agent.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+# Example model adapter for Flunky::Agent. This lives outside the gem core on
+# purpose: Flunky never talks to a model vendor itself, so the caller supplies
+# an object that responds to #call(messages:, tools:) and returns
+# { text:, tool_calls: [{ id:, name:, arguments: }] }.
+#
+# It uses net/http rather than a vendor SDK so the example adds no dependency.
+# The OpenAI variant would wrap each tool definition as
+#   { type: "function", function: { **defn, parameters: defn[:input_schema] } }
+# and otherwise map messages to that API's shape.
+
+require "net/http"
+require "json"
+require "flunky"
+
+class AnthropicAgent
+  ENDPOINT = URI("https://api.anthropic.com/v1/messages")
+
+  def initialize(api_key: ENV.fetch("ANTHROPIC_API_KEY"), model: "claude-opus-4-8", max_tokens: 4096)
+    @api_key = api_key
+    @model = model
+    @max_tokens = max_tokens
+  end
+
+  # Flunky's tool schemas already match Anthropic's input_schema, so tools pass
+  # through unchanged. We translate Flunky's normalized messages into the
+  # assistant/tool_result turn structure Anthropic requires, then map the reply
+  # back to the normalized { text:, tool_calls: } shape the Agent loop expects.
+  def call(messages:, tools:)
+    body = {
+      model: @model,
+      max_tokens: @max_tokens,
+      tools: tools,
+      messages: messages.map { |m| to_anthropic(m) }
+    }
+    parse(post(body))
+  end
+
+  private
+
+  def to_anthropic(message)
+    case message[:role]
+    when "assistant"
+      blocks = []
+      blocks << { type: "text", text: message[:text] } if message[:text].to_s != ""
+      (message[:tool_calls] || []).each do |tc|
+        blocks << { type: "tool_use", id: tc[:id], name: tc[:name], input: tc[:arguments] || {} }
+      end
+      { role: "assistant", content: blocks }
+    when "tool"
+      results = message[:content].map do |r|
+        { type: "tool_result", tool_use_id: r[:tool_call_id], content: r[:output].to_json }
+      end
+      { role: "user", content: results }
+    else
+      { role: "user", content: message[:content] }
+    end
+  end
+
+  def parse(response)
+    text = response["content"].select { |b| b["type"] == "text" }.map { |b| b["text"] }.join
+    tool_calls = response["content"].select { |b| b["type"] == "tool_use" }.map do |b|
+      { id: b["id"], name: b["name"], arguments: b["input"] }
+    end
+    { text: text, tool_calls: tool_calls }
+  end
+
+  def post(body)
+    request = Net::HTTP::Post.new(ENDPOINT)
+    request["x-api-key"] = @api_key
+    request["anthropic-version"] = "2023-06-01"
+    request["content-type"] = "application/json"
+    request.body = body.to_json
+
+    http = Net::HTTP.new(ENDPOINT.host, ENDPOINT.port)
+    http.use_ssl = true
+    JSON.parse(http.request(request).body)
+  end
+end
+
+# Run a quick goal against a live page when invoked directly.
+if __FILE__ == $PROGRAM_NAME
+  Flunky.session do |session|
+    agent = Flunky::Agent.new(session, model: AnthropicAgent.new)
+    session.visit("https://example.com")
+    agent.run("Find and click the more information link.", max_steps: 5)
+  end
+end

data/flunky.gemspec

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require_relative "lib/flunky/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "flunky"
+  spec.version = Flunky::VERSION
+  spec.authors = ["alexrupom"]
+  spec.email = ["alexrupom@hotmail.com"]
+
+  spec.summary = "Let any AI agent drive a real browser."
+  spec.description = "Flunky gives AI agents a real browser: a swappable driver, a page-to-prompt " \
+                     "snapshot, a Capybara-style action DSL, and vendor-neutral tool schemas plus a " \
+                     "dispatcher. The gem never calls an AI vendor itself; model clients are injected."
+  spec.homepage = "https://github.com/alexrupom/flunky"
+  spec.license = "MIT"
+  spec.required_ruby_version = ">= 3.0.0"
+
+  spec.metadata["rubygems_mfa_required"] = "true"
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = spec.homepage
+  spec.metadata["changelog_uri"] = "#{spec.homepage}/blob/main/CHANGELOG.md"
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  spec.files = Dir.chdir(__dir__) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      (f == __FILE__) || f.match(%r{\A(?:(?:bin|test|spec|features)/|\.(?:git|travis|circleci)|appveyor)})
+    end
+  end
+  spec.bindir = "exe"
+  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  # Default driver. Kept swappable behind Drivers::Base, but Ferrum ships out of the box
+  # because it speaks Chrome DevTools directly with no Selenium server to manage.
+  spec.add_dependency "ferrum", ">= 0.14"
+
+  # For more information and examples about making a new gem, check out our
+  # guide at: https://bundler.io/guides/creating_gem.html
+end

data/lib/flunky/actions.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+module Flunky
+  # The human-readable action DSL over a driver. Each mutating action returns a
+  # small result hash so the tool layer can report outcomes uniformly.
+  #
+  # Actions also holds a reference to its session because field resolution
+  # (fill_in by label) reads the session's current snapshot, the same way a
+  # person finds a field by the label printed next to it.
+  class Actions
+    SCROLL_STEP = 600
+
+    def initialize(driver, session)
+      @driver = driver
+      @session = session
+    end
+
+    def navigate(url)
+      @driver.go_to(url)
+      ok("navigated to #{url}")
+    end
+
+    def click(ref)
+      @driver.click(ref)
+      ok("clicked [#{ref}]")
+    end
+
+    def type(ref, text)
+      @driver.type_text(ref, text, clear: true)
+      ok(%(typed "#{text}" into [#{ref}]))
+    end
+
+    # Resolve a field by its label or placeholder, then type into it.
+    def fill_in(label, with:)
+      ref = field_ref(label)
+      @driver.type_text(ref, with, clear: true)
+      ok(%(filled "#{label}" with "#{with}"))
+    end
+
+    def select(value, ref:)
+      @driver.select_option(ref, value)
+      ok(%(selected "#{value}" in [#{ref}]))
+    end
+
+    def check(ref)
+      @driver.click(ref)
+      ok("checked [#{ref}]")
+    end
+
+    def press(key)
+      @driver.press_key(key)
+      ok("pressed #{key}")
+    end
+
+    def scroll(direction)
+      dx, dy = scroll_delta(direction)
+      @driver.scroll_by(dx, dy)
+      ok("scrolled #{direction}")
+    end
+
+    def current_url
+      @driver.current_url
+    end
+
+    def screenshot
+      @driver.screenshot_base64
+    end
+
+    private
+
+    def ok(message)
+      { ok: true, message: message }
+    end
+
+    # Match against accessible name first, then placeholder, case-insensitively.
+    def field_ref(label)
+      needle = label.to_s.strip.downcase
+      element = @session.snapshot.elements.find do |el|
+        matches?(el[:name], needle) || matches?(el[:placeholder], needle)
+      end
+      raise ElementNotFound, "no field matching #{label.inspect}" if element.nil?
+
+      element[:ref]
+    end
+
+    def matches?(value, needle)
+      !value.nil? && value.to_s.strip.downcase == needle
+    end
+
+    def scroll_delta(direction)
+      case direction.to_s
+      when "up" then [0, -SCROLL_STEP]
+      when "down" then [0, SCROLL_STEP]
+      when "left" then [-SCROLL_STEP, 0]
+      when "right" then [SCROLL_STEP, 0]
+      else raise NotSupported, "unknown scroll direction #{direction.inspect}"
+      end
+    end
+  end
+end

data/lib/flunky/agent.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Flunky
+  # Optional observe/decide/act loop. The model is injected and must respond to
+  # #call(messages:, tools:) returning { text:, tool_calls: [{ id:, name:,
+  # arguments: }] }. Keeping the contract vendor-neutral is the whole point: the
+  # gem never talks to a model vendor, the caller's adapter does.
+  class Agent
+    def initialize(session, model:)
+      @session = session
+      @model = model
+      @tools = Tools.new(session)
+    end
+
+    # Drive toward +goal+, stopping when the model stops asking for tools or the
+    # step budget runs out. Returns the transcript of messages exchanged.
+    def run(goal, max_steps: 10)
+      messages = [{ role: "user", content: seed_prompt(goal) }]
+
+      max_steps.times do
+        response = @model.call(messages: messages, tools: @tools.definitions)
+        messages << { role: "assistant", content: response[:text], tool_calls: response[:tool_calls] }
+
+        calls = response[:tool_calls] || []
+        break if calls.empty?
+
+        results = calls.map { |call| run_tool(call) }
+        messages << { role: "tool", content: results }
+      end
+
+      messages
+    end
+
+    private
+
+    def run_tool(call)
+      output = @tools.dispatch(call[:name], call[:arguments] || {})
+      { tool_call_id: call[:id], name: call[:name], output: output }
+    end
+
+    def seed_prompt(goal)
+      <<~PROMPT
+        Goal: #{goal}
+
+        You control a web browser through the provided tools. Use the element
+        refs from the page snapshot below. Call tools until the goal is met,
+        then stop.
+
+        #{@session.snapshot.to_prompt}
+      PROMPT
+    end
+  end
+end

data/lib/flunky/configuration.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Flunky
+  # Process-wide defaults. A Session merges these with its own keyword options,
+  # so per-session settings always win over the global configuration.
+  class Configuration
+    attr_accessor :headless, :default_timeout, :max_elements, :window_size, :user_agent,
+                  :browser_options, :process_timeout
+
+    def initialize
+      @headless = true
+      @default_timeout = 10
+      @max_elements = 200
+      @window_size = [1280, 800]
+      @user_agent = nil
+      @browser_options = {}
+      @process_timeout = nil
+    end
+
+    def to_h
+      {
+        headless: headless,
+        default_timeout: default_timeout,
+        max_elements: max_elements,
+        window_size: window_size,
+        user_agent: user_agent,
+        browser_options: browser_options,
+        process_timeout: process_timeout
+      }
+    end
+  end
+
+  class << self
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield configuration if block_given?
+      configuration
+    end
+
+    # Mainly here so specs can start from a clean slate.
+    def reset_configuration!
+      @configuration = Configuration.new
+    end
+  end
+end

data/lib/flunky/drivers/base.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module Flunky
+  module Drivers
+    # The backend contract. A driver is the only place that knows how to talk to
+    # a real browser, so swapping backends (Ferrum, a remote CDP service, a stub
+    # in tests) means implementing this interface and nothing else.
+    #
+    # Every interactive method takes a +ref+: the integer the snapshot stamped on
+    # an element as a data-ai-ref attribute. Turning that ref back into a live
+    # node is the driver's job.
+    class Base
+      def start
+        not_supported(:start)
+      end
+
+      def quit
+        not_supported(:quit)
+      end
+
+      def go_to(_url)
+        not_supported(:go_to)
+      end
+
+      def current_url
+        not_supported(:current_url)
+      end
+
+      def title
+        not_supported(:title)
+      end
+
+      def html
+        not_supported(:html)
+      end
+
+      # Run JS in the page and return its value.
+      def evaluate(_js)
+        not_supported(:evaluate)
+      end
+
+      def screenshot_base64
+        not_supported(:screenshot_base64)
+      end
+
+      def click(_ref)
+        not_supported(:click)
+      end
+
+      def type_text(_ref, _text, clear: false)
+        not_supported(:type_text)
+      end
+
+      def select_option(_ref, _value)
+        not_supported(:select_option)
+      end
+
+      def press_key(_key)
+        not_supported(:press_key)
+      end
+
+      def scroll_by(_dx, _dy)
+        not_supported(:scroll_by)
+      end
+
+      private
+
+      def not_supported(method_name)
+        raise NotSupported, "#{self.class} does not implement ##{method_name}"
+      end
+    end
+  end
+end

data/lib/flunky/drivers/ferrum_driver.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+require "ferrum"
+
+module Flunky
+  module Drivers
+    # Default backend. Ferrum drives Chrome over the DevTools Protocol with no
+    # Selenium server in the loop, which keeps setup to "have Chrome installed".
+    class FerrumDriver < Base
+      # Named keys Ferrum expects as symbols; anything else is typed literally.
+      KEY_MAP = {
+        "Enter" => :Enter,
+        "Tab" => :Tab,
+        "Escape" => :Escape,
+        "Backspace" => :Backspace,
+        "Delete" => :Delete,
+        "ArrowUp" => :Up,
+        "ArrowDown" => :Down,
+        "ArrowLeft" => :Left,
+        "ArrowRight" => :Right
+      }.freeze
+
+      attr_reader :browser
+
+      # browser_options passes raw Chrome flags through to Ferrum (for example
+      # { "no-sandbox" => nil } when running as root in CI). process_timeout is
+      # how long to wait for Chrome to come up; it is separate from the per
+      # command timeout.
+      def initialize(headless: true, window_size: [1280, 800], default_timeout: 10,
+                     user_agent: nil, browser_options: {}, process_timeout: nil)
+        super()
+        @headless = headless
+        @window_size = window_size
+        @default_timeout = default_timeout
+        @user_agent = user_agent
+        @browser_options = browser_options || {}
+        @process_timeout = process_timeout
+        @browser = nil
+      end
+
+      def start
+        return @browser if @browser
+
+        options = {
+          headless: @headless,
+          window_size: @window_size,
+          timeout: @default_timeout,
+          browser_options: @browser_options
+        }
+        options[:process_timeout] = @process_timeout if @process_timeout
+        @browser = Ferrum::Browser.new(**options)
+        @browser.headers.set("User-Agent" => @user_agent) if @user_agent
+        @browser
+      end
+
+      def quit
+        @browser&.quit
+        @browser = nil
+      end
+
+      def go_to(url)
+        page.go_to(url)
+      end
+
+      def current_url
+        page.current_url
+      end
+
+      def title
+        page.title
+      end
+
+      def html
+        page.body
+      end
+
+      def evaluate(js)
+        page.evaluate(js)
+      end
+
+      # Side-effecting JS where we do not care about the return value.
+      def execute(js)
+        page.execute(js)
+      end
+
+      def screenshot_base64
+        page.screenshot(encoding: :base64)
+      end
+
+      def click(ref)
+        resolve(ref).click
+        true
+      end
+
+      def type_text(ref, text, clear: false)
+        node = resolve(ref)
+        node.focus
+        # Clear by emptying the field's value rather than sending backspaces,
+        # which is both faster and robust to long existing contents.
+        node.evaluate("this.value = ''") if clear
+        node.type(text)
+        true
+      end
+
+      def select_option(ref, value)
+        node = resolve(ref)
+        if tag_name(node) == "select"
+          node.select(value)
+        else
+          # Custom (non-native) selects are just clickable elements.
+          node.click
+        end
+        true
+      end
+
+      def press_key(key)
+        page.keyboard.type(KEY_MAP.fetch(key, key))
+        true
+      end
+
+      def scroll_by(dx, dy)
+        page.execute("window.scrollBy(#{Integer(dx)}, #{Integer(dy)})")
+        true
+      end
+
+      private
+
+      def page
+        start
+        @browser.page
+      end
+
+      # Integer(ref) both validates the ref and stops anything from smuggling a
+      # CSS fragment into the selector.
+      def resolve(ref)
+        node = page.at_css(%([data-ai-ref="#{Integer(ref)}"]))
+        raise ElementNotFound, "no element with ref #{ref} on the current page" if node.nil?
+
+        node
+      end
+
+      def tag_name(node)
+        node.evaluate("this.tagName")&.downcase
+      end
+    end
+  end
+end

data/lib/flunky/errors.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Flunky
+  # Base class so callers can rescue every Flunky failure with one rescue.
+  class Error < StandardError; end
+
+  # A ref (or label) did not resolve to a live node on the current page.
+  class ElementNotFound < Error; end
+
+  # The dispatcher was handed a tool name it does not know about.
+  class UnknownTool < Error; end
+
+  # A driver was asked to do something its backend cannot do.
+  class NotSupported < Error; end
+end

data/lib/flunky/js/snapshot.js

@@ -0,0 +1,98 @@
+(function () {
+  // Runs in the page and returns { url, title, elements: [...] }.
+  //
+  // Why this exists: an agent cannot reason about raw HTML, so we reduce the
+  // page to the handful of things it can act on, each stamped with a stable
+  // integer ref (data-ai-ref) that the Ruby side later uses to address it.
+  //
+  // This file must begin with the IIFE expression: the driver evaluates it as
+  // `return <file>`, so a leading comment would trigger JS semicolon insertion
+  // and run `return;` before the function ever executes.
+
+  // Drop refs from a previous snapshot so numbering restarts from 1 every time
+  // and never collides with stale attributes.
+  document.querySelectorAll("[data-ai-ref]").forEach(function (el) {
+    el.removeAttribute("data-ai-ref");
+  });
+
+  var SELECTOR = [
+    "a", "button", "input", "select", "textarea",
+    "[role=button]", "[role=link]", "[role=checkbox]", "[role=tab]", "[role=menuitem]",
+    "[contenteditable=true]", "[onclick]"
+  ].join(",");
+
+  var max = window.__AI_MAX__ || 200;
+
+  function isVisible(el) {
+    var style = window.getComputedStyle(el);
+    if (style.display === "none" || style.visibility === "hidden") return false;
+    if (parseFloat(style.opacity) === 0) return false;
+    var rect = el.getBoundingClientRect();
+    return rect.width > 0 && rect.height > 0;
+  }
+
+  function trimmed(text) {
+    return (text || "").replace(/\s+/g, " ").trim();
+  }
+
+  // Best-effort accessible name, cheapest reliable source first.
+  function accessibleName(el) {
+    var label = el.getAttribute("aria-label");
+    if (trimmed(label)) return trimmed(label);
+
+    var labelledby = el.getAttribute("aria-labelledby");
+    if (labelledby) {
+      var parts = labelledby.split(/\s+/).map(function (id) {
+        var ref = document.getElementById(id);
+        return ref ? trimmed(ref.textContent) : "";
+      });
+      var joined = trimmed(parts.join(" "));
+      if (joined) return joined;
+    }
+
+    if (el.id) {
+      var forLabel = document.querySelector('label[for="' + el.id + '"]');
+      if (forLabel && trimmed(forLabel.textContent)) return trimmed(forLabel.textContent);
+    }
+
+    var placeholder = el.getAttribute("placeholder");
+    if (trimmed(placeholder)) return trimmed(placeholder);
+
+    var alt = el.getAttribute("alt");
+    if (trimmed(alt)) return trimmed(alt);
+
+    var title = el.getAttribute("title");
+    if (trimmed(title)) return trimmed(title);
+
+    return trimmed(el.textContent);
+  }
+
+  var elements = [];
+  var ref = 0;
+  var candidates = document.querySelectorAll(SELECTOR);
+
+  for (var i = 0; i < candidates.length && elements.length < max; i++) {
+    var el = candidates[i];
+    if (!isVisible(el)) continue;
+
+    ref += 1;
+    el.setAttribute("data-ai-ref", String(ref));
+
+    var rect = el.getBoundingClientRect();
+    elements.push({
+      ref: ref,
+      tag: el.tagName.toLowerCase(),
+      type: el.getAttribute("type") || null,
+      role: el.getAttribute("role") || null,
+      name: accessibleName(el),
+      value: el.value != null ? el.value : null,
+      placeholder: el.getAttribute("placeholder") || null,
+      checked: typeof el.checked === "boolean" ? el.checked : null,
+      disabled: typeof el.disabled === "boolean" ? el.disabled : null,
+      x: Math.round(rect.left),
+      y: Math.round(rect.top)
+    });
+  }
+
+  return { url: document.location.href, title: document.title, elements: elements };
+})();

data/lib/flunky/session.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Flunky
+  # Owns one driver for the life of a browsing session, caches the latest
+  # snapshot, and hands out the action DSL. This is the object callers hold.
+  class Session
+    attr_reader :driver
+
+    # Per-session options override the global configuration. A custom backend can
+    # be injected with +driver:+; otherwise we build a Ferrum driver.
+    def initialize(driver: nil, **opts)
+      @options = Flunky.configuration.to_h.merge(opts)
+      @driver = driver || build_default_driver
+      @driver.start
+      @snapshot = nil
+    end
+
+    def visit(url)
+      @driver.go_to(url)
+      @snapshot = nil
+      self
+    end
+
+    # Re-read the page and cache the fresh snapshot.
+    def observe
+      @snapshot = Snapshot.capture(@driver, max_elements: @options[:max_elements])
+    end
+
+    # Memoized view; captures once on first use so refs exist before any action.
+    def snapshot
+      @snapshot ||= observe
+    end
+
+    def actions
+      @actions ||= Actions.new(@driver, self)
+    end
+
+    def close
+      @driver.quit
+    end
+
+    private
+
+    def build_default_driver
+      Drivers::FerrumDriver.new(
+        headless: @options[:headless],
+        window_size: @options[:window_size],
+        default_timeout: @options[:default_timeout],
+        user_agent: @options[:user_agent],
+        browser_options: @options[:browser_options] || {},
+        process_timeout: @options[:process_timeout]
+      )
+    end
+  end
+end

data/lib/flunky/snapshot.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module Flunky
+  # A reduced, model-readable view of the current page: the page's url and title
+  # plus the list of elements the agent can act on, each carrying its ref.
+  class Snapshot
+    JS_PATH = File.expand_path("js/snapshot.js", __dir__)
+
+    attr_reader :url, :title, :elements
+
+    # Run the snapshot script against a live driver and wrap the result.
+    def self.capture(driver, max_elements: Flunky.configuration.max_elements)
+      driver.evaluate("window.__AI_MAX__ = #{Integer(max_elements)}")
+      data = driver.evaluate(script)
+      from_h(data)
+    end
+
+    # Build a Snapshot from a plain hash (string or symbol keys). Handy for the
+    # capture path and for testing without a browser.
+    def self.from_h(data)
+      h = symbolize(data)
+      new(url: h[:url], title: h[:title], elements: (h[:elements] || []).map { |e| symbolize(e) })
+    end
+
+    def self.script
+      @script ||= File.read(JS_PATH)
+    end
+
+    def self.symbolize(hash)
+      hash.each_with_object({}) { |(k, v), acc| acc[k.to_sym] = v }
+    end
+    private_class_method :symbolize
+
+    def initialize(url:, title:, elements:)
+      @url = url
+      @title = title
+      @elements = elements
+    end
+
+    # Compact block the model reads. Numbered refs map straight to the integers
+    # tools expect, so the model can copy a number into a click/type call.
+    def to_prompt
+      lines = ["PAGE: #{title} (#{url})", "ELEMENTS:"]
+      lines.concat(elements.map { |el| element_line(el) })
+      lines.join("\n")
+    end
+
+    def to_h
+      { url: url, title: title, elements: elements }
+    end
+
+    private
+
+    def element_line(el)
+      header = "[#{el[:ref]}] <#{el[:tag]}#{type_suffix(el)}>"
+      [header, name_part(el), *detail_parts(el)].compact.join(" ")
+    end
+
+    def type_suffix(el)
+      el[:type] ? " type=#{el[:type]}" : ""
+    end
+
+    def name_part(el)
+      name = el[:name].to_s.strip
+      name.empty? ? nil : %("#{name}")
+    end
+
+    def detail_parts(el)
+      parts = []
+      parts << %(placeholder="#{el[:placeholder]}") if present?(el[:placeholder])
+      parts << %(value="#{el[:value]}") if present?(el[:value])
+      parts << "checked" if el[:checked] == true
+      parts << "disabled" if el[:disabled] == true
+      parts
+    end
+
+    def present?(value)
+      !value.nil? && value.to_s.strip != ""
+    end
+  end
+end

data/lib/flunky/tools.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module Flunky
+  # Turns a session into the two things a model client needs: a list of tool
+  # schemas to advertise, and a dispatcher that runs a named tool call.
+  #
+  # The schema shape (name/description/input_schema) is what Anthropic expects
+  # directly; the example adapter shows the one-line wrap for OpenAI.
+  class Tools
+    def initialize(session)
+      @session = session
+    end
+
+    def definitions
+      [
+        tool("navigate", "Load a URL in the browser.",
+             url: { type: "string", description: "Absolute URL to open" }),
+        tool("click", "Click the element with the given ref.",
+             ref: { type: "integer", description: "Element ref from the page snapshot" }),
+        tool("type", "Type text into the element with the given ref (clears it first).",
+             ref: { type: "integer" }, text: { type: "string" }),
+        tool("fill_in", "Fill a field found by its label or placeholder text.",
+             label: { type: "string" }, text: { type: "string" }),
+        tool("select", "Select an option in a dropdown element.",
+             ref: { type: "integer" }, value: { type: "string" }),
+        tool("press", "Press a key, for example Enter or Tab.",
+             key: { type: "string" }),
+        tool("scroll", "Scroll the page in a direction.",
+             direction: { type: "string", enum: %w[up down left right] }),
+        tool("read_page", "Re-read the page and return a fresh snapshot.")
+      ]
+    end
+
+    # Run a tool by name, normalize the result, and fold a fresh page view in so
+    # the model always sees the outcome of what it just did.
+    def dispatch(name, args = {})
+      args = symbolize(args)
+      result =
+        case name.to_s
+        when "navigate" then @session.actions.navigate(args[:url])
+        when "click" then @session.actions.click(args[:ref])
+        when "type" then @session.actions.type(args[:ref], args[:text])
+        when "fill_in" then @session.actions.fill_in(args[:label], with: args[:text])
+        when "select" then @session.actions.select(args[:value], ref: args[:ref])
+        when "press" then @session.actions.press(args[:key])
+        when "scroll" then @session.actions.scroll(args[:direction])
+        when "read_page" then { ok: true, message: "read page" }
+        else raise UnknownTool, "unknown tool #{name.inspect}"
+        end
+
+      result.merge(page: @session.observe.to_prompt)
+    rescue Flunky::Error => e
+      raise if e.is_a?(UnknownTool)
+
+      { ok: false, error: e.message }
+    end
+
+    private
+
+    def tool(name, description, **properties)
+      {
+        name: name,
+        description: description,
+        input_schema: {
+          type: "object",
+          properties: properties,
+          required: properties.keys.map(&:to_s)
+        }
+      }
+    end
+
+    def symbolize(args)
+      (args || {}).each_with_object({}) { |(k, v), acc| acc[k.to_sym] = v }
+    end
+  end
+end

data/lib/flunky/version.rb

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

data/lib/flunky.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require_relative "flunky/version"
+require_relative "flunky/errors"
+require_relative "flunky/configuration"
+require_relative "flunky/drivers/base"
+require_relative "flunky/drivers/ferrum_driver"
+require_relative "flunky/snapshot"
+require_relative "flunky/actions"
+require_relative "flunky/session"
+require_relative "flunky/tools"
+require_relative "flunky/agent"
+
+module Flunky
+  # Convenience entry point: open a session, hand it to the block, and always
+  # close the browser even if the block raises.
+  def self.session(**opts)
+    session = Session.new(**opts)
+    yield session if block_given?
+    session
+  ensure
+    session&.close
+  end
+end

data/sig/flunky.rbs

@@ -0,0 +1,4 @@
+module Flunky
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,87 @@
+--- !ruby/object:Gem::Specification
+name: flunky
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- alexrupom
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2026-06-18 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: ferrum
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.14'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.14'
+description: 'Flunky gives AI agents a real browser: a swappable driver, a page-to-prompt
+  snapshot, a Capybara-style action DSL, and vendor-neutral tool schemas plus a dispatcher.
+  The gem never calls an AI vendor itself; model clients are injected.'
+email:
+- alexrupom@hotmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rspec"
+- ".rubocop.yml"
+- ".ruby-version"
+- CHANGELOG.md
+- CODE_OF_CONDUCT.md
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- examples/anthropic_agent.rb
+- flunky.gemspec
+- lib/flunky.rb
+- lib/flunky/actions.rb
+- lib/flunky/agent.rb
+- lib/flunky/configuration.rb
+- lib/flunky/drivers/base.rb
+- lib/flunky/drivers/ferrum_driver.rb
+- lib/flunky/errors.rb
+- lib/flunky/js/snapshot.js
+- lib/flunky/session.rb
+- lib/flunky/snapshot.rb
+- lib/flunky/tools.rb
+- lib/flunky/version.rb
+- sig/flunky.rbs
+homepage: https://github.com/alexrupom/flunky
+licenses:
+- MIT
+metadata:
+  rubygems_mfa_required: 'true'
+  homepage_uri: https://github.com/alexrupom/flunky
+  source_code_uri: https://github.com/alexrupom/flunky
+  changelog_uri: https://github.com/alexrupom/flunky/blob/main/CHANGELOG.md
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Let any AI agent drive a real browser.
+test_files: []