actionagent 1.8.1 → 1.9.0

data/app/services/action_agent/sandbox_browser.rb

@@ -0,0 +1,299 @@
+# frozen_string_literal: true
+
+module ActionAgent
+  # Used to start and stop a checkout sandbox's browser, and to account for
+  # it: the browser columns of its SandboxSession, the SessionRecording of
+  # what it showed, and the minutes it ran.
+  #
+  # A sandbox runs at most one browser, which the sandbox backend starts
+  # (SandboxOrchestrator#start_browser) pointed at the sandbox's app. While
+  # it runs, every agent run against the sandbox reaches it as the MCP server
+  # "browser:<session_id>" (SandboxSession#browser_server_entry).
+  #
+  # Browser statuses:
+  #   starting  the backend is starting it
+  #   running   its MCP endpoint answers
+  #   stopped   it was stopped, or its sandbox expired
+  #   failed    it did not start
+  class SandboxBrowser
+    class Error < StandardError; end
+
+    STARTED = %w[starting running].freeze
+    # A start that has been "starting" this long died before it finished.
+    STALE_START = 10.minutes
+
+    # Starts +sandbox+'s browser and returns the sandbox, with the browser
+    # running.
+    #
+    # @param mode [String, Symbol] one of SandboxSession::BROWSER_MODES
+    # @param capabilities [Array<String>] optional tool groups, from
+    #   SandboxSession::BROWSER_CAPABILITIES
+    # @param recording_url [#call, nil] given the browser's new
+    #   SessionRecording, returns the absolute URL its events are posted to
+    #   (the recording's events endpoint); nil records nothing
+    # @param live_origins [Array<String>] the dashboard origins whose pages
+    #   may open the browser's live view; none gives it no live view.
+    #   Anything that is not an http(s) origin is left out.
+    # @raise [Error] when the sandbox cannot run a browser now, a browser
+    #   already runs, or the backend failed to start one
+    # @param storage_state [Hash, nil] a Playwright storage state the browser
+    #   starts with, such as a project's saved sign-in
+    def self.start(sandbox, mode:, capabilities: [], recording_url: nil, live_origins: [], storage_state: nil)
+      new(sandbox).start(mode.to_s, Array(capabilities).map(&:to_s).uniq, recording_url, origins(live_origins), storage_state)
+    end
+
+    # +values+ as the origins a browser compares an Origin header with:
+    # "scheme://host" with the port unless it is the scheme's default.
+    #
+    # @example
+    #   origins(["http://LOCALHOST:3000/activeagents", "https://dash.example:443", "file:///etc"])
+    #   # => ["http://localhost:3000", "https://dash.example"]
+    def self.origins(values)
+      Array(values).filter_map do |value|
+        uri = URI.parse(value.to_s)
+        next unless %w[http https].include?(uri.scheme) && uri.host.present?
+
+        port = uri.port == uri.default_port ? "" : ":#{uri.port}"
+        "#{uri.scheme}://#{uri.host.downcase}#{port}"
+      rescue URI::InvalidURIError
+        nil
+      end.uniq
+    end
+
+    # The sandbox, with a browser running: the one already running, or one
+    # started headless (see .start) with +capabilities+ and +storage_state+.
+    # Returns [sandbox, whether it started one].
+    #
+    # @raise [Error] as .start does
+    def self.ensure_running!(sandbox, capabilities: [], recording_url: nil, storage_state: nil)
+      sandbox.reload
+      return [ sandbox, false ] if sandbox.browser_running?
+
+      [ start(sandbox, mode: "headless", capabilities: capabilities, recording_url: recording_url, storage_state: storage_state), true ]
+    end
+
+    # A recording_url for .start that posts to the events endpoint of the
+    # dashboard mounted at +mount_url+ (its absolute URL, the request's base
+    # URL and script name), for a start outside a request. Nil without one.
+    #
+    # @return [Proc, nil]
+    def self.recording_url_for(mount_url)
+      return nil if mount_url.blank?
+
+      ->(recording) { "#{mount_url.to_s.chomp('/')}/api/session_recordings/#{recording.id}/events" }
+    end
+
+    # The running browser's cookies and localStorage for the sandbox's app,
+    # as a Playwright storage state, read from the sidecar's
+    # GET /storage-state next to its MCP endpoint.
+    #
+    # @raise [Error] when no browser runs or it does not answer
+    # @return [Hash]
+    def self.storage_state(sandbox)
+      entry = sandbox.browser_server_entry or raise Error, "The sandbox's browser is not running"
+
+      uri = URI.join(entry[:url], "storage-state")
+      response = Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https", open_timeout: 5, read_timeout: 30) do |http|
+        http.request(Net::HTTP::Get.new(uri, entry[:headers]))
+      end
+      raise Error, "The browser did not hand over its sign-in (HTTP #{response.code})" unless response.is_a?(Net::HTTPSuccess)
+
+      state = JSON.parse(response.body)["storage_state"]
+      raise Error, "The browser answered without a storage state" unless state.is_a?(Hash)
+
+      state
+    rescue JSON::ParserError, SystemCallError, IOError, Timeout::Error, Net::HTTPBadResponse, URI::Error => e
+      raise Error, "The browser did not hand over its sign-in: #{e.class}"
+    end
+
+    # Stops +sandbox+'s browser through its backend, then finishes it
+    # (finish!). Returns the sandbox.
+    #
+    # @raise [Error] when the backend could not stop it
+    def self.stop(sandbox)
+      if STARTED.include?(sandbox.browser_status)
+        orchestrator = orchestrator!
+        if orchestrator.supports?(:stop_browser) && orchestrator.stop_browser(sandbox) == false
+          raise Error, "The browser could not be stopped; try again"
+        end
+      end
+      finish!(sandbox)
+      sandbox
+    rescue Error
+      raise
+    rescue StandardError => e
+      raise Error, "The browser could not be stopped: #{e.message}"
+    end
+
+    # Stops +sandbox+'s browser through its backend (stop) when one is
+    # starting or running and the sandbox is not yet past its expiry. Called
+    # before a sandbox is expired, so the browser's last recorded events are
+    # posted while its recording still accepts them. Past the expiry the
+    # recording would refuse them, and the browser has already stopped itself
+    # (SandboxSession#browser_stops_at), so this does nothing. Never raises:
+    # a browser it cannot stop is left to finish! and SandboxCleanupJob.
+    def self.stop_before_expiry(sandbox)
+      sandbox.reload
+      return unless STARTED.include?(sandbox.browser_status) && sandbox.expires_at&.future?
+
+      stop(sandbox)
+    rescue StandardError => e
+      Rails.logger.warn("[ActionAgent] could not stop the browser of sandbox #{sandbox.session_id} before expiring it: #{e.message}")
+    end
+
+    # The configured sandbox backend, or Error when it cannot be loaded.
+    def self.orchestrator!
+      SandboxOrchestrator.new
+    rescue StandardError, LoadError => e
+      raise Error, "The sandbox backend is unavailable: #{e.message}"
+    end
+
+    # Marks +sandbox+'s browser stopped and clears its endpoint and token, so
+    # no run reaches it any more, then records the minutes it ran
+    # (ActionAgent.record_usage with :browser_minutes, against
+    # SandboxSession#metering_owner) and completes the sandbox's live
+    # recordings. Asks nothing of the backend. Does nothing unless the
+    # browser was starting or running.
+    #
+    # @return [Integer, nil] the minutes recorded, nil when none were
+    def self.finish!(sandbox)
+      minutes = nil
+      finished = false
+      sandbox.with_lock do
+        next unless STARTED.include?(sandbox.browser_status)
+
+        minutes = sandbox.browser_minutes if sandbox.browser_started_at
+        sandbox.update!(browser_status: "stopped", browser_mcp_url: nil, browser_live_url: nil, browser_token: nil)
+        finished = true
+      end
+      return nil unless finished
+
+      ActionAgent.record_usage(sandbox.metering_owner, :browser_minutes, minutes) if minutes
+      SessionRecording.recording.where(sandbox_session_id: sandbox.id).find_each(&:complete!)
+      minutes
+    end
+
+    def initialize(sandbox)
+      @sandbox = sandbox
+    end
+
+    def start(mode, capabilities, recording_url, live_origins, storage_state = nil)
+      validate!(mode, capabilities)
+      orchestrator = self.class.orchestrator!
+      unless orchestrator.supports?(:start_browser)
+        raise Error, "The #{orchestrator.backend_name} sandbox backend cannot run a browser"
+      end
+      unless orchestrator.browser_modes.include?(mode.to_sym)
+        raise Error, "The #{orchestrator.backend_name} sandbox backend cannot show a browser window; start the browser headless"
+      end
+
+      token = "aabrw_#{SecureRandom.base58(40)}"
+      claim!(mode, token)
+      recording = nil
+      launch = nil
+      begin
+        recording, launch_recording = start_recording(recording_url)
+        launch = { token: token, app_url: @sandbox.cloud_run_url, capabilities: capabilities, stop_at: @sandbox.browser_stops_at,
+                   recording: launch_recording, live: live_origins.any? ? { session_id: @sandbox.session_id, origins: live_origins } : nil,
+                   storage_state: storage_state }.compact
+        @sandbox.browser_launch = launch
+        result = orchestrator.start_browser(@sandbox, mode: mode.to_sym)
+        unless mark_running!(result, token)
+          release(orchestrator)
+          raise Error, "The sandbox stopped while its browser was starting"
+        end
+      rescue StandardError, LoadError => e
+        failed!(recording, e)
+        message = e.is_a?(Error) ? e.message : "The browser did not start: #{e.message}"
+        raise Error, SecretScrubber.scrub(message, [ token, launch&.dig(:recording, :token) ])
+      ensure
+        @sandbox.browser_launch = nil
+      end
+      @sandbox
+    end
+
+    private
+
+    def validate!(mode, capabilities)
+      raise Error, "Only a checkout sandbox runs a browser" unless @sandbox.app_runtime?
+      unless @sandbox.active? && (@sandbox.ready? || @sandbox.running?)
+        raise Error, "The sandbox is #{@sandbox.status}; start its browser once it is ready"
+      end
+      raise Error, "The sandbox expires too soon to start a browser" unless @sandbox.browser_stops_at&.future?
+      raise Error, "The sandbox has no app to open" if @sandbox.cloud_run_url.blank?
+      unless SandboxSession::BROWSER_MODES.include?(mode)
+        raise Error, "mode must be one of #{SandboxSession::BROWSER_MODES.join(', ')}"
+      end
+
+      unknown = capabilities - SandboxSession::BROWSER_CAPABILITIES
+      raise Error, "Unknown browser capabilities: #{unknown.join(', ')}" if unknown.any?
+    end
+
+    # Takes the browser for this start, under the row lock: refused while
+    # another start or browser holds it.
+    def claim!(mode, token)
+      @sandbox.with_lock do
+        if STARTED.include?(@sandbox.browser_status) && !stale_start?
+          raise Error, "The sandbox's browser is already #{@sandbox.browser_status}"
+        end
+
+        @sandbox.update!(browser_status: "starting", browser_mode: mode, browser_token: token, browser_mcp_url: nil,
+          browser_live_url: nil, browser_started_at: nil)
+      end
+    end
+
+    def stale_start?
+      @sandbox.browser_status == "starting" && @sandbox.updated_at < STALE_START.ago
+    end
+
+    # A new recording for the browser, and what the backend needs to post to
+    # it: nil for both without +recording_url+.
+    def start_recording(recording_url)
+      return [ nil, nil ] if recording_url.nil?
+
+      recording = SessionRecording.start!(sandbox_session: @sandbox, source: "agent",
+        name: "browser_#{Time.current.strftime('%Y%m%d_%H%M%S')}")
+      limits = RecordingEvent.limits
+      [ recording, {
+        url: recording_url.call(recording),
+        token: recording.issue_ingest_token!,
+        batch_events: limits[:batch_events],
+        batch_bytes: limits[:batch_bytes]
+      } ]
+    end
+
+    # Records the running browser, unless the sandbox was stopped or expired
+    # while it started. Returns whether it did.
+    def mark_running!(result, token)
+      @sandbox.with_lock do
+        next false unless @sandbox.browser_status == "starting" && @sandbox.active?
+
+        @sandbox.update!(
+          browser_status: "running",
+          browser_mcp_url: result[:mcp_url],
+          browser_token: result[:mcp_token].presence || token,
+          browser_live_url: result[:live_url],
+          browser_started_at: Time.current
+        )
+        true
+      end
+    end
+
+    def release(orchestrator)
+      orchestrator.stop_browser(@sandbox)
+    rescue StandardError => e
+      Rails.logger.warn("[ActionAgent] could not stop the browser of sandbox #{@sandbox.session_id}: #{e.message}")
+    end
+
+    def failed!(recording, error)
+      @sandbox.with_lock do
+        next unless @sandbox.browser_status == "starting"
+
+        @sandbox.update!(browser_status: "failed", browser_token: nil, browser_mcp_url: nil, browser_live_url: nil)
+      end
+      recording&.fail!("The browser did not start")
+    rescue StandardError => e
+      Rails.logger.warn("[ActionAgent] could not record a failed browser start (#{error.class}): #{e.message}")
+    end
+  end
+end

data/app/services/action_agent/sandbox_browser_driver.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module ActionAgent
+  # Used to drive a sandbox's running browser from the engine itself, for the
+  # steps no model takes: opening the app at a project's start URL, and
+  # signing in with credentials the model never sees (BrowserSignIn).
+  #
+  # It talks to the browser's MCP endpoint in an MCP session of its own,
+  # which drives the same tab as an agent's session. Its calls are not agent
+  # tool calls, so they are neither traced nor recorded as actions; the
+  # browser's own recording masks what is typed.
+  class SandboxBrowserDriver
+    class Error < StandardError; end
+
+    # The line Playwright MCP reports a page's address on.
+    PAGE_URL = /^- Page URL: (\S+)/
+
+    # @raise [Error] when the sandbox's browser is not running
+    def initialize(sandbox)
+      @sandbox = sandbox
+      entry = sandbox.browser_server_entry or raise Error, "The sandbox's browser is not running"
+      @client = MCPClient.new(url: entry[:url], label: entry[:name], headers: entry[:headers] || {})
+    end
+
+    # Calls +tool+ and returns its text. With +log_arguments+ false the
+    # arguments' values are left out of the log.
+    #
+    # @raise [Error] when the tool fails or the browser does not answer
+    # @return [String]
+    def call(tool, arguments = {}, log_arguments: true)
+      result = @client.call_tool(tool.to_s, arguments, log_arguments: log_arguments)
+      raise Error, "#{tool} failed in the sandbox's browser" if result[:is_error]
+
+      result[:text].to_s
+    rescue MCPClient::Error => e
+      raise Error, "The sandbox's browser did not answer #{tool}: #{e.class}"
+    end
+
+    # Opens +path+ (a path on the sandbox's app) and returns the page URL
+    # the browser reports, or nil.
+    def open(path)
+      page_url(call("browser_navigate", { url: path.to_s.presence || "/" }))
+    end
+
+    # Runs +function+, the source of a JavaScript function taking no
+    # arguments, in the page and returns what it returned, parsed from JSON
+    # (nil when it returned nothing readable).
+    def evaluate(function)
+      text = call("browser_evaluate", { function: function })
+      json = text[/^### Result\n(.*?)(?=\n### |\z)/m, 1]
+      json && JSON.parse(json.strip)
+    rescue JSON::ParserError
+      nil
+    end
+
+    # Types +text+ into the element +selector+ names, a CSS selector. The
+    # text is a credential, so it is never logged.
+    def type(selector, text, submit: false)
+      call("browser_type", { target: selector, text: text, submit: submit }, log_arguments: false)
+      nil
+    end
+
+    def click(selector)
+      call("browser_click", { target: selector })
+      nil
+    end
+
+    # The path of the page the browser shows, or nil.
+    def current_path
+      path = evaluate("() => location.pathname")
+      path.is_a?(String) ? path : nil
+    end
+
+    def wait(seconds)
+      call("browser_wait_for", { time: seconds })
+      nil
+    end
+
+    private
+
+    def page_url(text)
+      text[PAGE_URL, 1]
+    end
+  end
+end

data/app/services/action_agent/sandbox_credential_paths.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module ActionAgent
+  # Defense in depth for custom adapters and accidental copies into app/.
+  # The actual credentials live outside the checkout and are never read.
+  #
+  # Only what a copy of them would look like is excluded: a Claude Code
+  # credentials file anywhere, and the sandbox's own config directories at
+  # the checkout's root. A repository's .claude/ settings, or an app's
+  # lib/claude/ code, stay in diffs, file reads and pull requests.
+  module SandboxCredentialPaths
+    DIRECTORIES = %w[claude claude-api claude-home claude-login].freeze
+    FILE = ".credentials.json"
+    module_function
+
+    def protected?(path)
+      parts = path.to_s.delete_prefix("./").split("/")
+      DIRECTORIES.any? { |name| parts.first.to_s.casecmp?(name) } || parts.any? { |part| part.casecmp?(FILE) }
+    end
+
+    def pathspecs
+      DIRECTORIES.map { |name| ":(exclude,glob,icase)#{name}/**" } +
+        [ ":(exclude,glob,icase)**/#{FILE}", ":(exclude,glob,icase)#{FILE}" ]
+    end
+  end
+end

data/app/services/action_agent/sandbox_mail.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+module ActionAgent
+  # Used to read the mail a sandbox's app sent, such as a sign-up's
+  # verification link.
+  #
+  # A sandbox backend sets DIRECTORY_ENV in the app's environment, and the
+  # engine, which every sandbox app bundles, then switches Action Mailer to
+  # Mail's file delivery into that directory (see ActionAgent::Engine). File
+  # delivery appends each message to one file per recipient address, so the
+  # newest message for an address is the last one in its file. The setting
+  # lives only in the sandbox's environment, never in the checkout.
+  module SandboxMail
+    # Raised when the sandbox's backend cannot read its files.
+    class Unsupported < StandardError; end
+
+    DIRECTORY_ENV = "ACTION_AGENT_SANDBOX_MAIL_DIR"
+    # Where mail is written, relative to the checkout.
+    DIRECTORY = "tmp/activeagents/mail"
+    ADDRESS = /\A[^\s@\/\\]+@[^\s@\/\\]+\z/
+    MAX_TEXT = 4_000
+    MAX_LINKS = 20
+    LINK = %r{https?://[^\s"'<>()]+}
+
+    module_function
+
+    # The newest message the app sent to +to+ as { subject:, from:, to:,
+    # date:, text:, links: [{ url:, path: }] }, scrubbed of +secrets+, or {}
+    # when none was sent. Each link's path is its path and query, which the
+    # sandbox browser opens on the app whatever host the mail named.
+    #
+    # @raise [ArgumentError] when +to+ is not an email address
+    # @raise [Unsupported] when the backend cannot read the sandbox's files
+    # @return [Hash]
+    def last_message(sandbox, to:, secrets: [], orchestrator: SandboxOrchestrator.new)
+      address = to.to_s.strip
+      raise ArgumentError, "to must be an email address" unless address.match?(ADDRESS)
+      unless orchestrator.supports?(:read_file)
+        raise Unsupported, "The #{orchestrator.backend_name} sandbox backend cannot read the sandbox's mail"
+      end
+
+      mailbox = orchestrator.read_file(sandbox, "#{DIRECTORY}/#{address}")
+      return {} if mailbox.blank?
+
+      message = parse(last_raw_message(mailbox.to_s.dup.force_encoding(Encoding::BINARY)))
+      message ? SecretScrubber.scrub(message, secrets) : {}
+    end
+
+    # The last message in +mailbox+, a file Mail's file delivery appended
+    # messages to, each followed by a blank line. A message starts with a
+    # header line after that blank line (Date, or Return-Path when the app
+    # sets one), and its header block carries a Message-ID.
+    def last_raw_message(mailbox)
+      starts = [ 0 ]
+      mailbox.scan(/\r?\n\r?\n(?=[A-Za-z][A-Za-z0-9-]*: )/) { starts << Regexp.last_match.end(0) }
+      start = starts.reverse.find do |offset|
+        header_end = mailbox.index(/\r?\n\r?\n/, offset) || mailbox.length
+        mailbox[offset...header_end].match?(/^Message-ID:/i)
+      end
+      mailbox[(start || 0)..]
+    end
+
+    def parse(raw)
+      require "mail"
+      mail = Mail.new(raw)
+      text = message_text(mail)
+      {
+        subject: mail.subject.to_s,
+        from: Array(mail.from).join(", "),
+        to: Array(mail.to).join(", "),
+        date: mail.date&.iso8601,
+        text: text.truncate(MAX_TEXT),
+        links: links(text, mail)
+      }
+    rescue LoadError
+      raise Unsupported, "Reading the sandbox's mail needs the mail gem in the dashboard app"
+    rescue StandardError => e
+      Rails.logger.warn("[ActionAgent] could not parse a sandbox's mail: #{e.class}")
+      nil
+    end
+
+    def message_text(mail)
+      part = mail.multipart? ? (mail.text_part || mail.html_part) : mail
+      body = part&.decoded.to_s.dup.force_encoding(Encoding::UTF_8).scrub
+      part&.mime_type.to_s.include?("html") ? html_text(body) : body.strip
+    end
+
+    def html_text(html)
+      ActionController::Base.helpers.strip_tags(html.gsub(/<(br|\/p|\/div|\/li|\/h\d)[^>]*>/i, "\n")).gsub(/\n{3,}/, "\n\n").strip
+    end
+
+    def links(text, mail)
+      html = mail.multipart? ? mail.html_part&.decoded.to_s : (mail.mime_type.to_s.include?("html") ? mail.decoded.to_s : "")
+      urls = (text.scan(LINK) + html.scan(/href=["'](https?:[^"']+)["']/i).flatten).map { |url| CGI.unescapeHTML(url) }
+      urls.uniq.first(MAX_LINKS).map do |url|
+        uri = URI.parse(url)
+        { url: url, path: [ uri.path.presence || "/", uri.query ].compact.join("?") }
+      rescue URI::InvalidURIError
+        { url: url, path: nil }
+      end
+    end
+  end
+end