class RubyLLM::Browser::Session::Backend

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.

Public Instance Methods

act(_session, action:, operation:, now:) click to toggle source

Dispatches one already-authorized action. Raises {SessionUnknown} when the outcome after dispatch cannot be confirmed.

# File lib/ruby_llm/browser/backend.rb, line 82
def act(_session, action:, operation:, now:)
  raise NotImplementedError, "Backend#act must be implemented"
end

capabilities() click to toggle source

@return [Capabilities]

# File lib/ruby_llm/browser/backend.rb, line 50
def capabilities
  raise NotImplementedError, "Backend#capabilities must be implemented"
end

end_session(_session, operation:, now:) click to toggle source

Attempts to terminate session. Returns true only when closure is confirmed.

# File lib/ruby_llm/browser/backend.rb, line 87
def end_session(_session, operation:, now:)
  raise NotImplementedError, "Backend#end_session must be implemented"
end

extract(_session, schema:, instruction:, operation:, now:) click to toggle source

@return [Hash] structured data matching schema

# File lib/ruby_llm/browser/backend.rb, line 76
def extract(_session, schema:, instruction:, operation:, now:)
  raise NotImplementedError, "Backend#extract must be implemented"
end

navigate(_session, url:, operation:, now:) click to toggle source

Navigates session to url. Returns the updated {Session}.

# File lib/ruby_llm/browser/backend.rb, line 65
def navigate(_session, url:, operation:, now:)
  raise NotImplementedError, "Backend#navigate must be implemented"
end

observe(_session, instruction:, operation:, now:) click to toggle source

@return [Array<Hash>] candidate actions, each with ‘description`, `method`,

`selector` and optional `arguments`

# File lib/ruby_llm/browser/backend.rb, line 71
def observe(_session, instruction:, operation:, now:)
  raise NotImplementedError, "Backend#observe must be implemented"
end

reconcile(_operation, now:) click to toggle source

Resolves an operation whose remote outcome is unconfirmed.

@return [Symbol] one of :closed, :active, :unknown, :cleanup_pending

# File lib/ruby_llm/browser/backend.rb, line 94
def reconcile(_operation, now:)
  :unknown
end

secrets(= []) click to toggle source

Secret literal values (API keys, …) to scrub from page text and results. @return [Array<String>]

# File lib/ruby_llm/browser/backend.rb, line 56
  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

start(context:, operation:, now:) click to toggle source

Opens a session. Returns a {Session} or raises {SessionUnknown} when the outcome is unconfirmed.

# File lib/ruby_llm/browser/backend.rb, line 60
def start(context:, operation:, now:)
  raise NotImplementedError, "Backend#start must be implemented"
end