actionagent 1.8.1 → 1.9.0

data/app/services/action_agent/agent_sync.rb

@@ -32,7 +32,8 @@ module ActionAgent
     end
 
     # @param agents [Array<Class>] ActiveAgent::Base subclasses
-    # @param owner [Object] the record agents and API keys scope to
+    # @param owner [Object, nil] the record agents and API keys scope to; nil
+    #   only in an install with no owner model, where agents have no owner
     # @param provider [String, Symbol, nil] defaults to the class's own
     # @param model [String, nil] defaults to the class's own
     def self.call(agents, owner:, provider: nil, model: nil)
@@ -48,7 +49,9 @@ module ActionAgent
 
     # @return [Result]
     def call
-      return Result.new(rows: [], errors: "An owner is required: the engine scopes agents to one.") if @owner.nil?
+      if @owner.nil? && Agent.owner_association
+        return Result.new(rows: [], errors: "An owner is required: the engine scopes agents to one.")
+      end
 
       rows = Agent.transaction { @agents.map { |klass| upsert(klass) } }
       Result.new(rows: rows, errors: nil)

data/app/services/action_agent/agent_tool_roster.rb

@@ -33,6 +33,14 @@ module ActionAgent
   # capabilities and the schema tools, +mcp_servers+ for services and their
   # per-server allow-lists (an entry with no +tools+ key offers everything
   # the server serves).
+  #
+  # Every tool row, and every tool a service lists, carries +approval_names+:
+  # the names Agent#approval_required_tools takes for it, which are the names
+  # the model calls it by. A capability names each function it exposes, and
+  # a schema or MCP tool its own name. The list is empty for a row whose
+  # calls the dashboard cannot hold for approval: the input tools, which ask
+  # on their own, and a tool the agent class declares in code, which its
+  # class runs.
   class AgentToolRoster
     AGENT_DEFINED = "agent_defined"
     DASHBOARD = "dashboard"
@@ -167,7 +175,8 @@ module ActionAgent
         usage_row(by_name[name]).merge(
           name: name,
           description: by_name[name]&.dig(:description),
-          enabled: allowed.nil? || allowed.include?(name)
+          enabled: allowed.nil? || allowed.include?(name),
+          approval_names: [ name ]
         )
       end
     end
@@ -200,7 +209,8 @@ module ActionAgent
           # window may still show it being called, but that is history. A
           # tool the agent class declares in code is offered by the class.
           enabled: schema ? saved_tools.include?(name) : true,
-          editable: schema
+          editable: schema,
+          approval_names: schema ? [ name ] : []
         )
       end
     end
@@ -222,15 +232,20 @@ module ActionAgent
           source: DASHBOARD,
           description: Agent::TOOL_DESCRIPTIONS[capability],
           enabled: saved_tools.include?(capability),
-          editable: true
+          editable: true,
+          approval_names: capability_functions(capability) - AgentToolbox::INPUT_FUNCTIONS
         )
       end
     end
 
+    def capability_functions(capability)
+      AgentToolbox::DEFINITIONS[capability]&.map { |definition| definition[:name].to_s } || []
+    end
+
     # A capability is one checkbox over the several functions it exposes
     # ("memory" is save_memory + recall_memory), so its usage is their sum.
     def capability_usage(capability)
-      names = (AgentToolbox::DEFINITIONS[capability]&.map { |definition| definition[:name].to_s } || []) + [ capability ]
+      names = capability_functions(capability) + [ capability ]
       rows = detected.select { |tool| names.include?(tool[:name]) }
       return nil if rows.empty?
 

data/app/services/action_agent/agent_toolbox.rb

@@ -50,6 +50,28 @@ module ActionAgent
       # Stateful: navigate changes what snapshot/click see, so these bypass
       # the toolbox result cache.
       "playwright_mcp" => [
+        # Not a browser action: the point where the agent stops and a person
+        # continues on the page it reached. AgentExecutionService answers it
+        # against the run's session recording (see #request_handoff there),
+        # which is why it has no FUNCTIONS entry.
+        {
+          name: "request_handoff",
+          description: "Hand the browser session to a person and stop. Call this the moment the page asks for something only its owner may give: payment details, a password, a one-time code, a consent. Pass the URL of the page you stopped on and the non-secret values you already entered, so the person can check them. After calling it, take no further browser actions; report where you stopped and what the person does next.",
+          parameters: {
+            type: "object",
+            properties: {
+              reason: { type: "string", description: "What the page is asking for, e.g. \"payment details\" or \"a login code sent by email\"" },
+              url: { type: "string", description: "The URL of the page the person continues on" },
+              form_values: {
+                type: "object",
+                description: "Values already entered, field label to value. Never a card number, password or code.",
+                additionalProperties: { type: "string" }
+              },
+              instructions: { type: "string", description: "One or two sentences on what the person should do next" }
+            },
+            required: [ "reason", "url" ]
+          }
+        },
         {
           name: "browser_navigate",
           description: "Open a URL in the managed browser. Returns a text snapshot of the page with element refs.",
@@ -77,6 +99,68 @@ module ActionAgent
             },
             required: [ "ref" ]
           }
+        },
+        {
+          name: "browser_type",
+          description: "Type text into an editable element from the latest snapshot: a text box, a search field. Set submit to press Enter afterwards.",
+          parameters: {
+            type: "object",
+            properties: {
+              ref: { type: "string", description: "Element ref from the snapshot" },
+              element: { type: "string", description: "Human-readable description of the element" },
+              text: { type: "string", description: "The text to type" },
+              submit: { type: "boolean", description: "Press Enter after typing" }
+            },
+            required: [ "ref", "text" ]
+          }
+        },
+        {
+          name: "browser_fill_form",
+          description: "Fill several form fields in one step. Each field names its ref from the latest snapshot, a label, its type and the value to enter; a checkbox takes true or false, a combobox the option's text.",
+          parameters: {
+            type: "object",
+            properties: {
+              fields: {
+                type: "array",
+                description: "The fields to fill",
+                items: {
+                  type: "object",
+                  properties: {
+                    ref: { type: "string", description: "Element ref from the snapshot" },
+                    name: { type: "string", description: "The field's label, e.g. Email" },
+                    type: { type: "string", enum: %w[textbox checkbox radio combobox slider], description: "The field's type" },
+                    value: { type: "string", description: "What to enter" }
+                  },
+                  required: [ "ref", "name", "type", "value" ]
+                }
+              }
+            },
+            required: [ "fields" ]
+          }
+        },
+        {
+          name: "browser_select_option",
+          description: "Choose an option in a dropdown from the latest snapshot.",
+          parameters: {
+            type: "object",
+            properties: {
+              ref: { type: "string", description: "Element ref from the snapshot" },
+              element: { type: "string", description: "Human-readable description of the element" },
+              values: { type: "array", items: { type: "string" }, description: "The option values or texts to select" }
+            },
+            required: [ "ref", "values" ]
+          }
+        },
+        {
+          name: "browser_press_key",
+          description: "Press a key in the browser, such as Enter, Escape, Tab or ArrowDown.",
+          parameters: {
+            type: "object",
+            properties: {
+              key: { type: "string", description: "The key to press" }
+            },
+            required: [ "key" ]
+          }
         }
       ],
       # Subject-bound like memory: routed by AgentExecutionService (needs the
@@ -148,6 +232,36 @@ module ActionAgent
           }
         }
       ],
+      # Asking a person mid-run. Each call pauses the run until the answer
+      # arrives (ActionAgent::InputRequest), so AgentExecutionService routes
+      # them, and they are NOT in FUNCTIONS below.
+      "ask" => [
+        {
+          name: "ask_user",
+          description: "Ask the user a question and wait for the answer before continuing. Pass options to have them " \
+            "pick one of a fixed set of answers. Use when you need information only the user has.",
+          parameters: {
+            type: "object",
+            properties: {
+              question: { type: "string", description: "The question, as the user should read it" },
+              options: { type: "array", items: { type: "string" }, description: "Answers to choose from; omit for a free-text answer" }
+            },
+            required: [ "question" ]
+          }
+        },
+        {
+          name: "request_approval",
+          description: "Ask the user to approve an action before you take it, and wait for their decision. Call it before " \
+            "any step with side effects the user has not already agreed to. Returns approved: true, or an error when declined.",
+          parameters: {
+            type: "object",
+            properties: {
+              action: { type: "string", description: "What you want to do, in one sentence the user can approve or decline" }
+            },
+            required: [ "action" ]
+          }
+        }
+      ],
       # Memory tools mirror solid_agent's HasMemory contract. They are NOT in
       # FUNCTIONS below — execution is subject-bound, so AgentExecutionService
       # routes them to the run's AgentMemory instead of this module.
@@ -179,6 +293,28 @@ module ActionAgent
       ]
     }.freeze
 
+    # Asks the user for a secret, such as an API key, delivered to the agent's
+    # server-side handler (ActionAgent::SecretRequests) and never to the
+    # model. Offered only to an agent with a registered handler, never
+    # through an agent's tools list, so it is not in DEFINITIONS.
+    REQUEST_SECRET_DEFINITION = {
+      name: "request_secret",
+      description: "Ask the user for a secret value, such as an API key or a password. The value is handed to the " \
+        "system without you ever seeing it; you receive only confirmation that it was provided.",
+      parameters: {
+        type: "object",
+        properties: {
+          name: { type: "string", description: "The secret's name, e.g. STRIPE_API_KEY" },
+          prompt: { type: "string", description: "What to tell the user about the value you need" }
+        },
+        required: [ "name", "prompt" ]
+      }
+    }.freeze
+
+    # The tools that pause a run to ask a person, routed by
+    # AgentExecutionService.
+    INPUT_FUNCTIONS = %w[ask_user request_approval request_secret].freeze
+
     # Function name => implementation method, for routing tool calls.
     FUNCTIONS = {
       "fetch_url" => :fetch_url,
@@ -188,24 +324,51 @@ module ActionAgent
       "browser_navigate" => :browser_navigate,
       "browser_snapshot" => :browser_snapshot,
       "browser_click" => :browser_click,
+      "browser_type" => :browser_type,
+      "browser_fill_form" => :browser_fill_form,
+      "browser_select_option" => :browser_select_option,
+      "browser_press_key" => :browser_press_key,
       "render_ui" => :render_ui
     }.freeze
 
     # Stateful tools whose results must never be replayed from cache — and
     # render_ui, whose result is the call itself, so there is nothing to
-    # replay.
-    UNCACHED_FUNCTIONS = %w[browser_navigate browser_snapshot browser_click render_ui].freeze
+    # replay, and the tools whose result is a person's answer.
+    UNCACHED_FUNCTIONS = (%w[
+      browser_navigate browser_snapshot browser_click browser_type browser_fill_form
+      browser_select_option browser_press_key render_ui
+    ] + INPUT_FUNCTIONS).freeze
+
+    # The group whose tools drive the process-wide browser
+    # (PlaywrightMCPClient), and those tools. A run against a sandbox with a
+    # running browser gets that browser's tools instead, and a multi-tenant
+    # install never offers or calls these: every tenant's runs would share
+    # one browser.
+    SHARED_BROWSER_GROUP = "playwright_mcp"
+    SHARED_BROWSER_FUNCTIONS = DEFINITIONS.fetch(SHARED_BROWSER_GROUP).map { |definition| definition[:name] }.freeze
 
     # Hosts browse_page may fetch — the platform's own trusted docs.
     BROWSE_ALLOWED_HOSTS = %w[docs.activeagents.ai].freeze
 
     class << self
       # Tool definitions for the subset of an agent's enabled tools that have
-      # server-side implementations.
-      def definitions_for(tool_names)
-        Array(tool_names).flat_map do |name|
-          DEFINITIONS[name.to_s] || schema_tool_definitions(name.to_s)
-        end
+      # server-side implementations. The shared browser's are left out when
+      # +browser_attached+ (the run reaches its sandbox's browser, which
+      # serves tools of the same names) or when shared_browser? is false.
+      # Never request_secret, whatever the list names.
+      def definitions_for(tool_names, browser_attached: false)
+        names = Array(tool_names).map(&:to_s)
+        names -= [ SHARED_BROWSER_GROUP ] if browser_attached || !shared_browser?
+
+        names.flat_map do |name|
+          DEFINITIONS[name] || schema_tool_definitions(name)
+        end.reject { |definition| definition[:name].to_s == REQUEST_SECRET_DEFINITION[:name] }
+      end
+
+      # Whether runs may use the process-wide browser: never in a
+      # multi-tenant install.
+      def shared_browser?
+        !ActionAgent.multi_tenant?
       end
 
       def function?(name)
@@ -230,6 +393,9 @@ module ActionAgent
       # instead of re-running the side effect.
       def call(name, **kwargs)
         return { error: "Unknown tool: #{name}" } unless function?(name)
+        if SHARED_BROWSER_FUNCTIONS.include?(name.to_s) && !shared_browser?
+          return { error: "#{name} needs a browser: start the browser of the sandbox this agent runs against" }
+        end
 
         # Who the call is for is never one of the call's arguments: it comes
         # off here, before a tool sees them. That keeps a built-in from
@@ -354,8 +520,48 @@ module ActionAgent
         playwright_mcp("browser_snapshot", {})
       end
 
-      def browser_click(ref:, element: nil)
-        playwright_mcp("browser_click", { ref: ref, element: element || ref })
+      def browser_click(ref: nil, target: nil, element: nil, button: nil)
+        playwright_mcp("browser_click", browser_target(ref || target, element).merge({ button: button }.compact))
+      end
+
+      def browser_type(text:, ref: nil, target: nil, element: nil, submit: nil, slowly: nil)
+        arguments = browser_target(ref || target, element).merge({ text: text.to_s, submit: submit, slowly: slowly }.compact)
+        playwright_mcp("browser_type", arguments)
+      end
+
+      def browser_fill_form(fields:)
+        normalized = Array(fields).map do |field|
+          field = field.to_h.transform_keys(&:to_s)
+          {
+            target: (field["target"] || field["ref"]).to_s,
+            name: field["name"].to_s,
+            type: field["type"].presence || "textbox",
+            value: field["value"].to_s
+          }
+        end
+        raise ArgumentError, "every field needs a ref" if normalized.any? { |field| field[:target].blank? }
+
+        playwright_mcp("browser_fill_form", { fields: normalized })
+      end
+
+      def browser_select_option(values:, ref: nil, target: nil, element: nil)
+        playwright_mcp("browser_select_option", browser_target(ref || target, element).merge(values: Array(values).map(&:to_s)))
+      end
+
+      def browser_press_key(key:)
+        playwright_mcp("browser_press_key", { key: key.to_s })
+      end
+
+      # Playwright MCP addresses an element by +target+ — a ref from the
+      # latest snapshot, or a selector — and names it in +element+ for the
+      # permission prompt it may show. Earlier releases of the server called
+      # the ref +ref+, and that is still what the tool schemas ask the model
+      # for, so both spellings are accepted here and sent as the server now
+      # expects.
+      def browser_target(target, element)
+        raise ArgumentError, "an element ref from the snapshot is required" if target.blank?
+
+        { target: target.to_s, element: (element.presence || target).to_s }
       end
 
       SNAPSHOT_LINK = /\[Snapshot\]\(([^)]+)\)/

data/app/services/action_agent/browser_live_ticket.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require "base64"
+require "json"
+require "openssl"
+
+module ActionAgent
+  # Used to issue the tickets that let a dashboard viewer into a sandbox
+  # browser's live view. The viewer's page sends the ticket as the first
+  # message on the live view's WebSocket, and the browser sidecar checks it
+  # (browser-sidecar/lib/live-ticket.mjs), so a ticket never travels in a URL.
+  #
+  # A ticket is base64url JSON claims, a dot, and the base64url HMAC-SHA256
+  # of that first part. The key is the HMAC-SHA256 of CONTEXT under the
+  # browser's token, which the sidecar was given on stdin when it started:
+  # a ticket opens only the browser it was issued for, and only until that
+  # browser stops. The sidecar accepts each ticket once, within LIFETIME.
+  #
+  # Claims:
+  #   v     1
+  #   sid   the sandbox session
+  #   sub   the user it was issued to, as a String, or nil without one
+  #   name  their name, shown to other viewers ("held by Ada"), or nil
+  #   mode  "view" to watch, "control" to also take over
+  #   iat   when it was issued, in epoch seconds
+  #   exp   when it expires, in epoch seconds
+  #   jti   its unique id
+  class BrowserLiveTicket
+    CONTEXT = "activeagents/browser-live-ticket/v1"
+    MODES = %w[view control].freeze
+    # The sidecar refuses a ticket issued for longer than 60 seconds.
+    LIFETIME = 30.seconds
+    MAX_NAME_LENGTH = 80
+
+    # Returns { ticket:, mode:, expires_at: } for +sandbox+'s running browser.
+    #
+    # @param user [Object, nil] the viewer, whose id and name the ticket carries
+    # @param mode [String] one of MODES
+    # @raise [ArgumentError] for an unknown mode, or a sandbox whose browser
+    #   has no token
+    def self.issue(sandbox, user:, mode:, now: Time.current, jti: SecureRandom.urlsafe_base64(24))
+      raise ArgumentError, "mode must be one of #{MODES.join(', ')}" unless MODES.include?(mode)
+      raise ArgumentError, "The sandbox's browser has no token" if sandbox.browser_token.blank?
+
+      issued_at = now.to_i
+      claims = {
+        v: 1,
+        sid: sandbox.session_id,
+        sub: user&.id&.to_s,
+        name: display_name(user),
+        mode: mode,
+        iat: issued_at,
+        exp: issued_at + LIFETIME.to_i,
+        jti: jti
+      }
+      { ticket: sign(sandbox.browser_token, claims), mode: mode, expires_at: Time.zone.at(claims[:exp]) }
+    end
+
+    # The ticket for +claims+, signed with the key derived from +token+.
+    def self.sign(token, claims)
+      payload = Base64.urlsafe_encode64(JSON.generate(claims), padding: false)
+      signature = OpenSSL::HMAC.digest("SHA256", key(token), payload)
+      "#{payload}.#{Base64.urlsafe_encode64(signature, padding: false)}"
+    end
+
+    def self.key(token)
+      OpenSSL::HMAC.digest("SHA256", token, CONTEXT)
+    end
+
+    def self.display_name(user)
+      return nil unless user
+
+      name = user.try(:display_name).presence || user.try(:name).presence || user.try(:email_address).presence || user.try(:email).presence
+      name&.to_s&.truncate(MAX_NAME_LENGTH)
+    end
+    private_class_method :key, :display_name
+  end
+end

data/app/services/action_agent/browser_sidecar.rb

@@ -0,0 +1,213 @@
+# frozen_string_literal: true
+
+require "json"
+require "open3"
+
+module ActionAgent
+  # Used to install, find and check the browser sidecar the :local sandbox
+  # backend runs: the @activeagents/browser-sidecar npm package, versioned
+  # with this engine, and the Chromium it drives. Both live under the local
+  # sandbox root:
+  #
+  #   .browser/
+  #     node_modules/   the package and its dependencies
+  #     browsers/       Chromium (PLAYWRIGHT_BROWSERS_PATH)
+  #
+  # ActionAgent.browser_sidecar_path names a checkout of the package to run
+  # instead, for working on the sidecar; its version is not checked.
+  #
+  # Nothing here downloads anything except #install!: a start with the
+  # sidecar or Chromium missing is refused with the command that installs
+  # them (#refusal).
+  class BrowserSidecar
+    PACKAGE = "@activeagents/browser-sidecar"
+    ENTRYPOINT = "bin/browser-sidecar.mjs"
+    MINIMUM_NODE = Gem::Version.new("20")
+    INSTALL_COMMAND = "bin/rails action_agent:browser:install"
+    CHECK_TIMEOUT = 30
+    INSTALL_TIMEOUT = 900
+
+    class Error < StandardError; end
+
+    # One thing a browser start needs. +fix+ says how to get it when it is
+    # not +ok+.
+    Check = Struct.new(:name, :ok, :detail, :fix, keyword_init: true) do
+      def message
+        ok ? detail : "#{detail}. #{fix}"
+      end
+    end
+
+    class << self
+      # @return [Pathname]
+      def root
+        ActionAgent.local_sandbox_root.join(".browser")
+      end
+
+      # Where Chromium is installed and looked for.
+      # @return [Pathname]
+      def browsers_path
+        root.join("browsers")
+      end
+
+      # The configured checkout, or nil to run the installed package.
+      # @return [Pathname, nil]
+      def checkout
+        path = ActionAgent.browser_sidecar_path.presence
+        path && Pathname.new(path.to_s).expand_path
+      end
+
+      # @return [Pathname]
+      def package_dir
+        checkout || root.join("node_modules", *PACKAGE.split("/"))
+      end
+
+      # The environment the sidecar runs with, on top of a sandbox's
+      # sanitized one.
+      # @return [Hash{String => String}]
+      def environment
+        { "PLAYWRIGHT_BROWSERS_PATH" => browsers_path.to_s }
+      end
+
+      # The command line that runs the sidecar with +args+.
+      # @return [Array<String>]
+      def command(*args)
+        [ ActionAgent.node_command.to_s, package_dir.join(ENTRYPOINT).to_s, *args ]
+      end
+
+      # Whether a sidecar reporting +version+ may run: the engine's own
+      # version, or any version from a configured checkout.
+      def acceptable_version?(version)
+        checkout.present? || version == ActionAgent::VERSION
+      end
+
+      # Node, the sidecar and Chromium, each checked. The doctor task prints
+      # these; a browser start refuses with the first that is not ok.
+      #
+      # @return [Array<Check>]
+      def checks
+        node = node_check
+        return [ node ] unless node.ok
+
+        sidecar, report = sidecar_check
+        return [ node, sidecar ] unless report
+
+        [ node, sidecar, chromium_check(report) ]
+      end
+
+      # Why a browser cannot start on this machine, or nil when it can.
+      # @return [String, nil]
+      def refusal
+        checks.find { |check| !check.ok }&.message
+      end
+
+      # Installs the sidecar (npm ci in a checkout, else the package at the
+      # engine's version under #root) and its Chromium, writing their output
+      # to +io+.
+      #
+      # @raise [Error] when a step fails
+      def install!(io = $stdout)
+        if checkout
+          run!(io, [ ActionAgent.npm_command.to_s, "ci" ], chdir: checkout)
+        else
+          FileUtils.mkdir_p(root)
+          manifest = root.join("package.json")
+          manifest.write(JSON.pretty_generate({ "private" => true, "description" => "The dashboard's browser sidecar" })) unless manifest.exist?
+          run!(io, [ ActionAgent.npm_command.to_s, "install", "--no-audit", "--no-fund", "--save-exact", "#{PACKAGE}@#{ActionAgent::VERSION}" ],
+            chdir: root)
+        end
+        run!(io, command("install-browser"), chdir: checkout || root)
+      end
+
+      private
+
+      def node_check
+        output, status = capture([ ActionAgent.node_command.to_s, "--version" ])
+        version = output.to_s[/\Av?(\d+\.\d+\.\d+)/, 1]
+        if status&.success? && version && Gem::Version.new(version) >= MINIMUM_NODE
+          return Check.new(name: "node", ok: true, detail: "Node.js #{version}")
+        end
+
+        Check.new(
+          name: "node", ok: false,
+          detail: version ? "Node.js #{version} is older than #{MINIMUM_NODE}" : "Node.js was not found (#{ActionAgent.node_command})",
+          fix: "Install Node.js #{MINIMUM_NODE} or later, or set ActionAgent.node_command"
+        )
+      end
+
+      # The sidecar check, and what its `check` command reported (nil when
+      # it could not run).
+      def sidecar_check
+        unless package_dir.join(ENTRYPOINT).file?
+          return [ Check.new(name: "sidecar", ok: false, detail: "The browser sidecar is not installed (#{package_dir})",
+            fix: "Run #{INSTALL_COMMAND}"), nil ]
+        end
+
+        output, status = capture(command("check"))
+        report = status&.success? ? parse_report(output) : nil
+        unless report
+          return [ Check.new(name: "sidecar", ok: false, detail: "The browser sidecar did not run: #{output.to_s.strip.lines.last&.strip}",
+            fix: "Run #{INSTALL_COMMAND}"), nil ]
+        end
+
+        version = report["version"].to_s
+        unless acceptable_version?(version)
+          return [ Check.new(name: "sidecar", ok: false,
+            detail: "The browser sidecar is version #{version}, and this dashboard needs #{ActionAgent::VERSION}",
+            fix: "Run #{INSTALL_COMMAND}"), report ]
+        end
+
+        [ Check.new(name: "sidecar", ok: true, detail: "Browser sidecar #{version}#{" (#{checkout})" if checkout}"), report ]
+      end
+
+      def chromium_check(report)
+        chromium = report["chromium"].is_a?(Hash) ? report["chromium"] : {}
+        return Check.new(name: "chromium", ok: true, detail: "Chromium at #{chromium["executable"]}") if chromium["installed"]
+
+        Check.new(name: "chromium", ok: false, detail: "Chromium is not installed (#{browsers_path})", fix: "Run #{INSTALL_COMMAND}")
+      end
+
+      def parse_report(output)
+        report = JSON.parse(output.to_s.lines.last.to_s)
+        report.is_a?(Hash) ? report : nil
+      rescue JSON::ParserError
+        nil
+      end
+
+      def process_environment
+        LocalSandboxBackend.sanitized_environment.merge(environment)
+      end
+
+      # Runs +argv+ with output captured, for at most CHECK_TIMEOUT seconds.
+      # Returns the output and the exit status, nil when it could not run.
+      def capture(argv)
+        Open3.popen2e(process_environment, *argv, unsetenv_others: true, pgroup: true) do |stdin, output, waiter|
+          stdin.close
+          reader = Thread.new { output.read }
+          unless waiter.join(CHECK_TIMEOUT)
+            Process.kill("KILL", -waiter.pid)
+            return [ "timed out after #{CHECK_TIMEOUT}s", nil ]
+          end
+          [ reader.value, waiter.value ]
+        end
+      rescue SystemCallError => e
+        [ e.message, nil ]
+      end
+
+      def run!(io, argv, chdir:)
+        io.puts("$ #{argv.join(' ')}")
+        Open3.popen2e(process_environment, *argv, chdir: chdir.to_s, unsetenv_others: true, pgroup: true) do |stdin, output, waiter|
+          stdin.close
+          reader = Thread.new { output.each_line { |line| io.write(line) } }
+          unless waiter.join(INSTALL_TIMEOUT)
+            Process.kill("KILL", -waiter.pid)
+            raise Error, "#{argv.first} did not finish within #{INSTALL_TIMEOUT}s"
+          end
+          reader.join
+          raise Error, "#{argv.join(' ')} failed (#{waiter.value.exitstatus || waiter.value.termsig})" unless waiter.value.success?
+        end
+      rescue SystemCallError => e
+        raise Error, "Could not run #{argv.first}: #{e.message}"
+      end
+    end
+  end
+end