ruby_llm-browser 0.1.0

data/docs/index.md

@@ -0,0 +1,82 @@
+---
+layout: home
+title: "RubyLLM::Browser"
+description: "An unofficial RubyLLM extension for offline bounded browser inspection and schema-checked extraction."
+permalink: /
+hero:
+  name: "RubyLLM::Browser"
+  text: "Policy-bound browser tools for RubyLLM"
+  tagline: "An unofficial RubyLLM extension for offline bounded browser inspection and schema-checked extraction."
+  actions:
+    - theme: brand
+      text: Get started
+      link: /getting-started/
+    - theme: alt
+      text: View on GitHub
+      link: https://github.com/yorzi/ruby_llm-browser
+features:
+  - title: "Read-only by default"
+    details: "Inspect and Extract do not dispatch browser actions, and page content remains untrusted evidence."
+    link: /inspect-extract/
+    link_text: Inspect and extract
+  - title: "Host-controlled access"
+    details: "The host supplies identity, URL policy, schemas, budgets, and consent. Live Stagehand use is disabled."
+    link: /source-policy/
+    link_text: Control source access
+  - title: "Bounded operation state"
+    details: "Track lifecycle and cap time, steps, concurrent operations, and retained result bytes."
+    link: /operation-lifecycle/
+    link_text: Bound operation work
+  - title: "Offline action simulation"
+    details: "Exercise single-use host approval checks without opening a browser or changing a website."
+    link: /offline-act/
+    link_text: Simulate an approved action
+---
+
+## Before You Install
+
+The first release is `0.1.0` and supports only the offline `FakeBackend`. The built-in
+Stagehand adapter is unsupported until provider egress and confirmed cleanup are
+qualified. The full live Act protocol is deferred to a later version.
+
+## Install
+
+```sh
+{% if site.docs_unreleased %}bundle add ruby_llm-browser --git https://github.com/yorzi/ruby_llm-browser --branch main{% else %}bundle add ruby_llm-browser --version "~> {{ site.version }}"{% endif %}
+```
+
+## A First Look
+
+This offline example makes no network request and needs no API key.
+
+```ruby
+require "ruby_llm/browser"
+
+class OfflineResolver
+  def getaddresses(_host) = [ "93.184.216.34" ]
+end
+
+context = RubyLLM::Browser::Context.new(
+  actor_id: "demo-actor", run_id: "demo-run",
+  backend: RubyLLM::Browser::FakeBackend.new,
+  source_policy: RubyLLM::Browser::Policy.new(
+    allowed_hosts: [ "docs.example.com" ], resolver: OfflineResolver.new
+  ),
+  operation_store: RubyLLM::Browser::InMemoryOperationStore.new
+)
+schema = {
+  "type" => "object",
+  "properties" => { "title" => { "type" => "string" } },
+  "required" => [ "title" ], "additionalProperties" => false
+}
+
+inspect_tool = RubyLLM::Browser::Inspect.new(context: context)
+extract_tool = RubyLLM::Browser::Extract.new(context: context, schema: schema)
+puts inspect_tool.execute(url: "https://docs.example.com/")[:status] # => ok
+puts extract_tool.execute(url: "https://docs.example.com/")[:data]   # => {"title"=>"Example"}
+```
+
+The fake backend proves only that the Ruby API can run offline. It says nothing about a
+real browser provider's egress, session cleanup, or billing. Read [the security model]({% link SECURITY_MODEL.md %}) before evaluating a live backend.
+
+[Get started]({% link _getting_started/getting-started.md %}) or read [how the gem works]({% link _getting_started/overview.md %}).

data/examples/plain_ruby.rb

@@ -0,0 +1,34 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Offline demo of the read-only tools over the fake backend: no network, no API key.
+#
+#   bundle exec ruby examples/plain_ruby.rb
+require "ruby_llm/browser"
+
+# A deterministic resolver keeps the demo offline; production uses real DNS.
+class DemoResolver
+  def getaddresses(_host) = [ "93.184.216.34" ]
+end
+
+policy = RubyLLM::Browser::Policy.new(
+  allowed_hosts: [ "docs.example.com" ], resolver: DemoResolver.new
+)
+context = RubyLLM::Browser::Context.new(
+  actor_id: "demo-actor",
+  run_id: "demo-run",
+  source_policy: policy,
+  backend: RubyLLM::Browser::FakeBackend.new,
+  operation_store: RubyLLM::Browser::InMemoryOperationStore.new,
+  budget: RubyLLM::Browser::Budget.new(max_seconds: 30, max_steps: 6)
+)
+
+inspect = RubyLLM::Browser::Inspect.new(context: context)
+puts "Inspect: #{inspect.execute(url: "https://docs.example.com/")}"
+
+schema = { "type" => "object", "properties" => { "title" => { "type" => "string" } } }
+extract = RubyLLM::Browser::Extract.new(context: context, schema: schema)
+puts "Extract: #{extract.execute(url: "https://docs.example.com/", instruction: "the title")}"
+
+blocked = inspect.execute(url: "http://169.254.169.254/latest/meta-data")
+puts "Blocked: #{blocked[:error][:code]}"

data/examples/rails_adapter.rb

@@ -0,0 +1,47 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Offline demo of the Rails adapter on in-memory SQLite: no network, no API key.
+#
+#   bundle exec ruby examples/rails_adapter.rb
+require "ruby_llm/browser/rails"
+require "active_record"
+
+class DemoResolver
+  def getaddresses(_host) = [ "93.184.216.34" ]
+end
+
+ActiveRecord::Base.establish_connection(adapter: "sqlite3", database: ":memory:")
+RubyLLM::Browser::Rails::Schema.create!
+
+# `:inline` runs the queued job immediately so the demo is synchronous and deterministic.
+ActiveJob::Base.queue_adapter = :inline
+ActiveJob::Base.logger = Logger.new(IO::NULL)
+
+policy = RubyLLM::Browser::Policy.new(
+  allowed_hosts: [ "docs.example.com" ], resolver: DemoResolver.new
+)
+budget = RubyLLM::Browser::Budget.new(max_seconds: 30, max_steps: 6)
+
+RubyLLM::Browser::Rails.context_factory = lambda do |actor_id:, run_id:|
+  RubyLLM::Browser::Context.new(
+    actor_id: actor_id, run_id: run_id, source_policy: policy,
+    backend: RubyLLM::Browser::FakeBackend.new,
+    operation_store: RubyLLM::Browser::Rails.operation_store,
+    budget: budget
+  )
+end
+
+operation = RubyLLM::Browser::Rails::OperationJob.enqueue(
+  actor_id: "demo-actor", run_id: "demo-run", kind: :inspect,
+  url: "https://docs.example.com/", budget: budget, idempotency_key: "demo-1"
+)
+
+puts "operation #{operation.id} is #{RubyLLM::Browser::Rails.operation_store.fetch(operation.id).state}"
+
+# A duplicate delivery attaches to the same durable operation.
+again = RubyLLM::Browser::Rails::OperationJob.enqueue(
+  actor_id: "demo-actor", run_id: "demo-run", kind: :inspect,
+  url: "https://docs.example.com/", budget: budget, idempotency_key: "demo-1"
+)
+puts "duplicate attached: #{again.id == operation.id}"

data/lib/generators/ruby_llm/browser/install_generator.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "rails/generators/active_record"
+
+module RubyLLM
+  module Browser
+    module Generators
+      # Generates the durable tables for the optional Rails adapter.
+      #
+      #   bin/rails generate ruby_llm:browser:install
+      class InstallGenerator < ::Rails::Generators::Base
+        include ::ActiveRecord::Generators::Migration
+        namespace "ruby_llm:browser:install"
+
+        source_root File.expand_path("templates", __dir__)
+
+        desc "Creates the RubyLLM::Browser operations and approvals migration"
+
+        def create_migration_file
+          migration_template(
+            "create_ruby_llm_browser_tables.rb.tt",
+            "db/migrate/create_ruby_llm_browser_tables.rb"
+          )
+        end
+      end
+    end
+  end
+end

data/lib/generators/ruby_llm/browser/templates/create_ruby_llm_browser_tables.rb.tt

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+# Durable tables for the RubyLLM::Browser Rails adapter.
+#
+# These tables hold only Gem-owned bookkeeping: operation identity/lifecycle and
+# single-use approvals. They are not business truth and must not be edited by hand.
+class CreateRubyLlmBrowserTables < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
+  def change
+    create_table :ruby_llm_browser_actors, id: :string do |t|
+      t.integer :sequence, null: false, default: 0
+    end
+
+    create_table :ruby_llm_browser_operations, id: false do |t|
+      t.string :id, null: false, primary_key: true
+      t.string :actor_id, null: false
+      t.string :run_id, null: false
+      t.string :state, null: false
+      t.string :session_id
+      t.string :idempotency_key
+      t.string :request_digest
+      t.integer :steps, null: false, default: 0
+      t.integer :bytes, null: false, default: 0
+      t.integer :fence, null: false, default: 0
+      t.string :error_code
+      t.boolean :cancel_requested, null: false, default: false
+      t.text :budget, null: false
+      t.datetime :created_at
+      t.datetime :updated_at
+    end
+
+    add_index :ruby_llm_browser_operations, [ :actor_id, :run_id, :idempotency_key ],
+              unique: true, name: "index_ruby_llm_browser_operations_on_idempotency",
+              where: "idempotency_key IS NOT NULL"
+    add_index :ruby_llm_browser_operations, [ :actor_id, :state ],
+              name: "index_ruby_llm_browser_operations_on_actor_state"
+    add_index :ruby_llm_browser_operations, :state,
+              name: "index_ruby_llm_browser_operations_on_state"
+
+    create_table :ruby_llm_browser_approvals, id: false do |t|
+      t.string :id, null: false, primary_key: true
+      t.string :actor_id, null: false
+      t.string :run_id, null: false
+      t.string :url, null: false
+      t.string :action_digest, null: false
+      t.text :action
+      t.string :page_revision
+      t.string :operation_id
+      t.string :session_id
+      t.datetime :issued_at, null: false
+      t.datetime :expires_at, null: false
+      t.datetime :consumed_at
+      t.boolean :revoked, null: false, default: false
+      t.datetime :created_at
+      t.datetime :updated_at
+    end
+
+    add_index :ruby_llm_browser_approvals, [ :actor_id, :run_id ],
+              name: "index_ruby_llm_browser_approvals_on_actor_run"
+  end
+end

data/lib/ruby_llm/browser/approval.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Browser
+    # A host-issued, single-use authorization for one exact browser action.
+    #
+    # An approval binds actor, run, optional operation/session, the exact normalized URL,
+    # an optional page revision and the exact action digest, with a short expiry. It is
+    # consumed atomically once, immediately before dispatch, inside the tool. A bare
+    # RubyLLM `Chat#approve` carries none of these bindings and therefore dispatches
+    # nothing on its own.
+    class Approval
+      attr_reader :id, :actor_id, :run_id, :url, :action_digest, :page_revision,
+                  :operation_id, :session_id, :issued_at, :expires_at, :consumed_at, :action
+
+      def initialize(id:, actor_id:, run_id:, url:, action_digest:, expires_at:, issued_at:,
+                     page_revision: nil, operation_id: nil, session_id: nil, consumed_at: nil,
+                     revoked: false, action: nil)
+        @id = presence!(id, :id)
+        @actor_id = presence!(actor_id, :actor_id)
+        @run_id = presence!(run_id, :run_id)
+        @url = presence!(url, :url)
+        @action_digest = presence!(action_digest, :action_digest)
+        @expires_at = time!(expires_at, :expires_at)
+        @issued_at = time!(issued_at, :issued_at)
+        @page_revision = Immutable.copy(page_revision)
+        @operation_id = Immutable.copy(operation_id)
+        @session_id = Immutable.copy(session_id)
+        @consumed_at = Immutable.copy(consumed_at)
+        @revoked = !!revoked
+        @action = Immutable.copy(action)
+        freeze
+      end
+
+      # Builds an approval for +action+ with a time-to-live.
+      #
+      # @param action [Hash] an action already normalized by {Policy#authorize_action!}
+      # @param ttl [Numeric] seconds until expiry
+      def self.for_action(actor_id:, run_id:, url:, action:, ttl:, now:, id: nil, page_revision: nil,
+                          operation_id: nil, session_id: nil)
+        new(
+          id: id || Operation.generate_id(prefix: "apr"),
+          actor_id: actor_id, run_id: run_id, url: url,
+          action_digest: action_digest(action), action: action,
+          page_revision: page_revision, operation_id: operation_id, session_id: session_id,
+          issued_at: now, expires_at: now + ttl
+        )
+      end
+
+      # The digest a host and the Gem both compute for an action.
+      def self.action_digest(action)
+        Redactor.digest(action)
+      end
+
+      # The digest a host and the Gem both compute for an observed candidate list.
+      def self.page_revision(observed)
+        Redactor.digest(observed)
+      end
+
+      def consumed? = !@consumed_at.nil?
+      def revoked? = !!@revoked
+      def expired?(now) = now >= expires_at
+      def active?(now) = !consumed? && !revoked? && !expired?(now)
+
+      # True when the approval authorizes exactly this actor/run/url/revision/digest.
+      def binding_matches?(actor_id:, run_id:, url:, action_digest:, page_revision: nil,
+                           operation_id: nil, session_id: nil)
+        return false unless @actor_id == actor_id && @run_id == run_id
+        return false unless @url == url
+        return false unless @action_digest == action_digest
+        return false unless @page_revision.nil? || @page_revision == page_revision
+        return false unless @operation_id.nil? || @operation_id == operation_id
+        return false unless @session_id.nil? || @session_id == session_id
+
+        true
+      end
+
+      # Returns a consumed copy.
+      def consume!(now:)
+        raise ApprovalStale, "approval #{id} was already consumed" if consumed?
+
+        copy(consumed_at: now)
+      end
+
+      # Returns a revoked copy.
+      def revoke!
+        copy(revoked: true)
+      end
+      def to_h
+        {
+          id: id, actor_id: actor_id, run_id: run_id, url: url,
+          action_digest: action_digest, action: action, page_revision: page_revision,
+          operation_id: operation_id, session_id: session_id, issued_at: issued_at, expires_at: expires_at,
+          consumed_at: consumed_at, revoked: revoked?
+        }
+      end
+
+      def digest = Redactor.digest(to_h)
+
+      def inspect
+        "#<#{self.class} id=#{id} actor=#{actor_id} expires_at=#{expires_at&.getutc&.iso8601}>"
+      end
+
+      private
+
+      def copy(consumed_at: @consumed_at, revoked: @revoked)
+        self.class.new(
+          id: id, actor_id: actor_id, run_id: run_id, url: url, action_digest: action_digest,
+          action: action, page_revision: page_revision, operation_id: operation_id,
+          session_id: session_id, issued_at: issued_at, expires_at: expires_at,
+          consumed_at: consumed_at, revoked: revoked
+        )
+      end
+
+      def presence!(value, name)
+        raise InvalidInput, "#{name} must be a non-empty String" unless value.is_a?(String) && !value.empty?
+
+        value.dup.freeze
+      end
+
+      def time!(value, name)
+        raise InvalidInput, "#{name} must be a Time" unless value.is_a?(Time)
+
+        value.dup.freeze
+      end
+    end
+  end
+end

data/lib/ruby_llm/browser/approval_store.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Browser
+    # Durable store for host-issued, single-use {Approval}s.
+    #
+    # The RubyLLM approval resolver may consult the store repeatedly, so reads must be
+    # side-effect free. Only {#consume_once} mutates, and it must be atomic so a replayed
+    # or duplicated worker cannot dispatch a second action.
+    class ApprovalStore
+      # Stores a freshly issued approval.
+      def issue(_approval)
+        raise NotImplementedError, "ApprovalStore#issue must be implemented"
+      end
+
+      # Read-only lookup. Returns an {Approval} or nil.
+      def fetch(_id)
+        raise NotImplementedError, "ApprovalStore#fetch must be implemented"
+      end
+
+      # Atomically consumes +id+ exactly once if it is active and bound to this
+      # actor/run/url/revision/digest.
+      #
+      # @return [Approval] the consumed approval
+      # @raise [ApprovalRequired] no such approval
+      # @raise [ApprovalStale] consumed, revoked, expired or bound to different details
+      def consume_once(_id, actor_id:, run_id:, url:, action_digest:, now:, page_revision: nil,
+                       operation_id: nil, session_id: nil)
+        raise NotImplementedError, "ApprovalStore#consume_once must be implemented"
+      end
+
+      # Revokes an approval so it can never be consumed.
+      def revoke(_id)
+        raise NotImplementedError, "ApprovalStore#revoke must be implemented"
+      end
+    end
+  end
+end

data/lib/ruby_llm/browser/backend.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Browser
+    # A live browser session handle.
+    #
+    # A session exposes only what policy and provenance need: an id, the current
+    # (possibly redirected) URL and a start time. It deliberately has no reader for the
+    # provider's `cdp_url`: that is a full-control DevTools endpoint and must never
+    # reach a tool result, model message or log.
+    class Session
+      attr_reader :id, :url, :started_at
+
+      def initialize(id:, url: nil, started_at: nil)
+        raise InvalidInput, "session id must be a non-empty String" unless id.is_a?(String) && !id.empty?
+
+        @id = id
+        @url = url
+        @started_at = started_at
+        freeze
+      end
+
+      # Returns a copy with a new current URL.
+      def with_url(url)
+        self.class.new(id: id, url: url, started_at: started_at)
+      end
+
+      def to_h
+        { id: id, url: url, started_at: started_at&.utc&.iso8601 }
+      end
+
+      def inspect = "#<#{self.class} id=#{id} url=#{url.inspect}>"
+    end
+
+    # The contract every browser backend implements.
+    #
+    # The Gem maps its own bounded operations onto a backend; it never reimplements a
+    # browser engine. Implementations must:
+    #
+    # - never raise an untyped error; use {ProviderError} (or {SessionUnknown} when an
+    #   effectful call's outcome cannot be confirmed)
+    # - issue effectful calls without automatic retries
+    # - never return `cdp_url`, cookies or credentials
+    # - report honest {Capabilities}
+    #
+    # {FakeBackend} is the offline reference. {StagehandBackend} wraps the official SDK
+    # but is unsupported for live use in the first release.
+    class Backend
+      # @return [Capabilities]
+      def capabilities
+        raise NotImplementedError, "Backend#capabilities must be implemented"
+      end
+
+      # Secret literal values (API keys, ...) to scrub from page text and results.
+      # @return [Array<String>]
+      def secrets = []
+
+      # Opens a session. Returns a {Session} or raises {SessionUnknown} when the
+      # outcome is unconfirmed.
+      def start(context:, operation:, now:)
+        raise NotImplementedError, "Backend#start must be implemented"
+      end
+
+      # Navigates +session+ to +url+. Returns the updated {Session}.
+      def navigate(_session, url:, operation:, now:)
+        raise NotImplementedError, "Backend#navigate must be implemented"
+      end
+
+      # @return [Array<Hash>] candidate actions, each with `description`, `method`,
+      #   `selector` and optional `arguments`
+      def observe(_session, instruction:, operation:, now:)
+        raise NotImplementedError, "Backend#observe must be implemented"
+      end
+
+      # @return [Hash] structured data matching +schema+
+      def extract(_session, schema:, instruction:, operation:, now:)
+        raise NotImplementedError, "Backend#extract must be implemented"
+      end
+
+      # Dispatches one already-authorized action. Raises {SessionUnknown} when the
+      # outcome after dispatch cannot be confirmed.
+      def act(_session, action:, operation:, now:)
+        raise NotImplementedError, "Backend#act must be implemented"
+      end
+
+      # Attempts to terminate +session+. Returns true only when closure is confirmed.
+      def end_session(_session, operation:, now:)
+        raise NotImplementedError, "Backend#end_session must be implemented"
+      end
+
+      # Resolves an operation whose remote outcome is unconfirmed.
+      #
+      # @return [Symbol] one of :closed, :active, :unknown, :cleanup_pending
+      def reconcile(_operation, now:)
+        :unknown
+      end
+    end
+  end
+end

data/lib/ruby_llm/browser/budget.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Browser
+    # Immutable limits for a single browser operation.
+    #
+    # A budget is deliberately conservative. Elapsed time, steps and bytes are separate
+    # limits, and a projected or estimated cost is never presented as a provider-enforced
+    # hard billing cap. When a limit is unknown or exhausted the Gem refuses more work
+    # rather than guessing.
+    class Budget
+      DEFAULT_MAX_SECONDS = 60
+      DEFAULT_MAX_STEPS = 12
+      DEFAULT_MAX_BYTES = 262_144 # 256 KiB of page/result bytes
+      DEFAULT_MAX_CONCURRENT = 1
+
+      attr_reader :max_seconds, :max_steps, :max_bytes, :max_concurrent, :max_cost_usd
+
+      # @param max_seconds [Numeric] wall-clock ceiling for the operation
+      # @param max_steps [Integer] maximum provider round-trips (navigate/observe/...)
+      # @param max_bytes [Integer] maximum bytes of page/result content kept per operation
+      # @param max_concurrent [Integer] concurrent sessions allowed for the actor
+      # @param max_cost_usd [Numeric, nil] advisory cost reservation; nil means unknown
+      def initialize(max_seconds: DEFAULT_MAX_SECONDS, max_steps: DEFAULT_MAX_STEPS,
+                     max_bytes: DEFAULT_MAX_BYTES, max_concurrent: DEFAULT_MAX_CONCURRENT,
+                     max_cost_usd: nil)
+        @max_seconds = positive_number!(max_seconds, :max_seconds)
+        @max_steps = positive_integer!(max_steps, :max_steps)
+        @max_bytes = positive_integer!(max_bytes, :max_bytes)
+        @max_concurrent = positive_integer!(max_concurrent, :max_concurrent)
+        @max_cost_usd = max_cost_usd.nil? ? nil : non_negative_number!(max_cost_usd, :max_cost_usd)
+
+        freeze
+      end
+
+      def to_h
+        {
+          max_seconds: max_seconds,
+          max_steps: max_steps,
+          max_bytes: max_bytes,
+          max_concurrent: max_concurrent,
+          max_cost_usd: max_cost_usd
+        }
+      end
+
+      def digest
+        Redactor.digest(to_h)
+      end
+
+      def ==(other)
+        other.is_a?(Budget) && to_h == other.to_h
+      end
+      alias eql? ==
+
+      def hash
+        to_h.hash
+      end
+
+      def inspect
+        "#<#{self.class} seconds=#{max_seconds} steps=#{max_steps} bytes=#{max_bytes} concurrent=#{max_concurrent}>"
+      end
+
+      private
+
+      def positive_number!(value, name)
+        unless value.is_a?(Numeric) && value.finite? && value.positive?
+          raise InvalidInput, "#{name} must be a positive number"
+        end
+
+        value
+      end
+
+      def non_negative_number!(value, name)
+        unless value.is_a?(Numeric) && value.finite? && value >= 0
+          raise InvalidInput, "#{name} must be a non-negative number"
+        end
+
+        value
+      end
+
+      def positive_integer!(value, name)
+        unless value.is_a?(Integer) && value.positive?
+          raise InvalidInput, "#{name} must be a positive integer"
+        end
+
+        value
+      end
+    end
+  end
+end

data/lib/ruby_llm/browser/capabilities.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Browser
+    # What a backend can actually guarantee.
+    #
+    # Capabilities are the Gem's fail-closed gate. Policy refuses to start a session
+    # unless a backend claims *enforced* egress isolation; a URL allowlist in Ruby can
+    # never substitute for it. Local mode needs a host-pinned server binary, and the
+    # Stagehand SDK always merges +STAGEHAND_CUSTOM_HEADERS+, so those headers must be
+    # host-approved before any session starts.
+    class Capabilities
+      # Supported egress-isolation postures.
+      #
+      # - `:enforced`   every initiated request stays within approved destinations and
+      #                 public address ranges at connection time
+      # - `:unverified` not proven; the Gem treats this as unusable for live sessions
+      EGRESS_ISOLATION = %i[enforced unverified].freeze
+
+      # Server/topology modes.
+      SERVER_MODES = %i[fake remote local].freeze
+
+      attr_reader :server_mode, :egress_isolation
+
+      def initialize(server_mode: :remote, egress_isolation: :unverified,
+                     local_binary_pinned: false, custom_headers_present: false,
+                     custom_headers_approved: false, act_supported: false)
+        @server_mode = symbolize!(server_mode, SERVER_MODES, :server_mode)
+        @egress_isolation = symbolize!(egress_isolation, EGRESS_ISOLATION, :egress_isolation)
+        @local_binary_pinned = !!local_binary_pinned
+        @custom_headers_present = !!custom_headers_present
+        @custom_headers_approved = !!custom_headers_approved
+        @act_supported = !!act_supported
+        freeze
+      end
+
+      def local_mode? = server_mode == :local
+      def enforced_egress? = egress_isolation == :enforced
+      def local_binary_pinned? = @local_binary_pinned
+      def custom_headers_present? = @custom_headers_present
+      def custom_headers_approved? = @custom_headers_approved
+      def act_supported? = @act_supported
+
+      def to_h
+        {
+          server_mode: server_mode,
+          egress_isolation: egress_isolation,
+          local_binary_pinned: @local_binary_pinned,
+          custom_headers_present: @custom_headers_present,
+          custom_headers_approved: @custom_headers_approved,
+          act_supported: @act_supported
+        }
+      end
+
+      def digest = Redactor.digest(to_h)
+
+      def ==(other)
+        other.is_a?(Capabilities) && to_h == other.to_h
+      end
+      alias eql? ==
+
+      def hash = to_h.hash
+
+      def inspect = "#<#{self.class} #{to_h.map { |k, v| "#{k}=#{v}" }.join(" ")}>"
+
+      private
+
+      def symbolize!(value, allowed, name)
+        symbol = value.to_sym
+        return symbol if allowed.include?(symbol)
+
+        raise InvalidInput, "#{name} must be one of #{allowed.inspect}"
+      end
+    end
+  end
+end