actionagent 1.9.2 → 1.9.3

data/app/services/action_agent/agent_toolbox.rb

@@ -11,9 +11,11 @@ module ActionAgent
   # tool-call roundtrips that show up as :tool spans in Traces, tool messages
   # in Interactions, and tool counts in Metrics.
   #
-  # Only tools with a safe server-side implementation are mapped; anything
-  # else an agent enables (terminal, playwright, ...) is ignored for platform
-  # execution.
+  # Every capability in Agent::AVAILABLE_TOOLS has definitions here. The ones
+  # that act for the run — on its checkout (CheckoutTools), its Slack
+  # connection (SlackTools), its provider (translate_text), its memory, its
+  # workspace's agents, or a person — are routed by AgentExecutionService and
+  # have no FUNCTIONS entry.
   class AgentToolbox
     FETCH_LIMIT_BYTES = 50_000
     FETCH_TIMEOUT_SECONDS = 5
@@ -262,6 +264,138 @@ module ActionAgent
           }
         }
       ],
+      # The checkout capabilities: they act on the checkout sandbox the run
+      # was given (CheckoutTools), so AgentExecutionService routes them, and
+      # they are NOT in FUNCTIONS below.
+      "terminal" => [
+        {
+          name: "run_command",
+          description: "Run a shell command (bash) in the root of the repository checkout this run was given, with the " \
+            "app's environment and database, and return its exit status and combined output. Use it to run tests, " \
+            "rake tasks, scripts or git. Each call starts a fresh shell.",
+          parameters: {
+            type: "object",
+            properties: {
+              command: { type: "string", description: "The command line, e.g. bin/rails test test/models" },
+              timeout_seconds: { type: "integer", description: "Stop the command after this many seconds (at most 120)" }
+            },
+            required: [ "command" ]
+          }
+        }
+      ],
+      "filesystem" => [
+        {
+          name: "list_files",
+          description: "List the files in the repository checkout this run was given, tracked and untracked, without " \
+            "the ones .gitignore excludes. Pass a directory to list only what is under it.",
+          parameters: {
+            type: "object",
+            properties: { path: { type: "string", description: "A directory relative to the checkout root, e.g. app/models" } },
+            required: []
+          }
+        },
+        {
+          name: "read_file",
+          description: "Read a text file from the repository checkout this run was given.",
+          parameters: {
+            type: "object",
+            properties: { path: { type: "string", description: "The file's path relative to the checkout root" } },
+            required: [ "path" ]
+          }
+        },
+        {
+          name: "write_file",
+          description: "Write a text file in the repository checkout this run was given, replacing it if it exists and " \
+            "creating the directories it needs.",
+          parameters: {
+            type: "object",
+            properties: {
+              path: { type: "string", description: "The file's path relative to the checkout root" },
+              content: { type: "string", description: "The file's complete new content" }
+            },
+            required: [ "path", "content" ]
+          }
+        }
+      ],
+      "edit" => [
+        {
+          name: "edit_file",
+          description: "Edit a file in the repository checkout this run was given by replacing one exact passage. " \
+            "old_text must appear exactly once in the file; include enough surrounding lines to make it unique.",
+          parameters: {
+            type: "object",
+            properties: {
+              path: { type: "string", description: "The file's path relative to the checkout root" },
+              old_text: { type: "string", description: "The exact text to replace" },
+              new_text: { type: "string", description: "What to put in its place" }
+            },
+            required: [ "path", "old_text", "new_text" ]
+          }
+        }
+      ],
+      "database" => [
+        {
+          name: "query_database",
+          description: "Run a read-only SQL query against the app's database in the repository checkout this run was " \
+            "given, and return the columns and up to 200 rows. Writes are refused.",
+          parameters: {
+            type: "object",
+            properties: { sql: { type: "string", description: "One SQL statement, e.g. SELECT id, email FROM users LIMIT 10" } },
+            required: [ "sql" ]
+          }
+        }
+      ],
+      # Through the owner's Slack bot token (SlackTools), routed by
+      # AgentExecutionService.
+      "slack" => [
+        {
+          name: "slack_list_channels",
+          description: "List the Slack channels the workspace's bot can see, with their ids.",
+          parameters: { type: "object", properties: {}, required: [] }
+        },
+        {
+          name: "slack_read_channel",
+          description: "Read a Slack channel's most recent messages, newest first.",
+          parameters: {
+            type: "object",
+            properties: {
+              channel: { type: "string", description: "The channel id, e.g. C0123456789" },
+              limit: { type: "integer", description: "How many messages (default 20, at most 50)" }
+            },
+            required: [ "channel" ]
+          }
+        },
+        {
+          name: "slack_post_message",
+          description: "Post a message to a Slack channel as the workspace's bot, or reply in a thread.",
+          parameters: {
+            type: "object",
+            properties: {
+              channel: { type: "string", description: "The channel id, e.g. C0123456789" },
+              text: { type: "string", description: "The message, in Slack mrkdwn" },
+              thread_ts: { type: "string", description: "Reply in the thread of this message ts" }
+            },
+            required: [ "channel", "text" ]
+          }
+        }
+      ],
+      # A generation on the run's own provider, model and credentials,
+      # routed by AgentExecutionService.
+      "translate" => [
+        {
+          name: "translate_text",
+          description: "Translate text into another language, keeping its formatting, code and placeholders.",
+          parameters: {
+            type: "object",
+            properties: {
+              text: { type: "string", description: "The text to translate" },
+              target_language: { type: "string", description: "The language to translate into, e.g. Spanish or ja" },
+              source_language: { type: "string", description: "The text's language, when known" }
+            },
+            required: [ "text", "target_language" ]
+          }
+        }
+      ],
       # 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.
@@ -315,6 +449,19 @@ module ActionAgent
     # AgentExecutionService.
     INPUT_FUNCTIONS = %w[ask_user request_approval request_secret].freeze
 
+    # The functions with side effects outside the conversation, by the
+    # capability that exposes them. They wait for a person's approval unless
+    # the agent's approval list says otherwise: Agent puts them on the list
+    # when a capability is gained without one (a template, the agents API),
+    # and the builder and the Tools tab add them when a capability is
+    # switched on (frontend/utils/builderRoster.mjs keeps the same table).
+    APPROVAL_BY_DEFAULT = {
+      "terminal" => %w[run_command],
+      "filesystem" => %w[write_file],
+      "edit" => %w[edit_file],
+      "slack" => %w[slack_post_message]
+    }.freeze
+
     # Function name => implementation method, for routing tool calls.
     FUNCTIONS = {
       "fetch_url" => :fetch_url,
@@ -365,6 +512,12 @@ module ActionAgent
         end.reject { |definition| definition[:name].to_s == REQUEST_SECRET_DEFINITION[:name] }
       end
 
+      # The approval list +tool_names+ get by default: the side-effecting
+      # functions of the capabilities among them (APPROVAL_BY_DEFAULT).
+      def default_approvals(tool_names)
+        Array(tool_names).flat_map { |name| APPROVAL_BY_DEFAULT[name.to_s] || [] }.uniq
+      end
+
       # Whether runs may use the process-wide browser: never in a
       # multi-tenant install.
       def shared_browser?

data/app/services/action_agent/browser_client_token.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "uri"
+
+module ActionAgent
+  # Used to give a client that runs other people's code, such as a Claude
+  # Code turn, the sandbox's browser without its master token: the sidecar
+  # mints a client token for /mcp only (POST /tokens), labelled with who it
+  # is for, and the token is revoked once the turn ends (DELETE /tokens/:id).
+  # Its shell commands inherit what Claude Code was given, so a token they
+  # could read must be worthless once the turn is over.
+  class BrowserClientToken
+    TIMEOUT = 5
+
+    class Error < StandardError; end
+
+    attr_reader :id, :token, :mcp_url
+
+    # Mints a token for +sandbox+'s running browser.
+    #
+    # @param sandbox [SandboxSession]
+    # @param label [String] what the live view calls the client
+    # @return [BrowserClientToken]
+    # @raise [Error] when the browser is not running or refuses
+    def self.mint(sandbox, label:)
+      raise Error, "The sandbox's browser is not running" unless sandbox.browser_running? && sandbox.browser_token.present?
+
+      mcp_url = URI(sandbox.browser_mcp_url)
+      body = request(Net::HTTP::Post, tokens_uri(mcp_url), sandbox.browser_token, JSON.generate(label: label))
+      new(id: body.fetch("id"), token: body.fetch("token"), mcp_url: mcp_url.to_s, sandbox: sandbox)
+    rescue KeyError, JSON::ParserError
+      raise Error, "The browser answered a token request without one"
+    end
+
+    def initialize(id:, token:, mcp_url:, sandbox:)
+      @id = id
+      @token = token
+      @mcp_url = mcp_url
+      @sandbox = sandbox
+    end
+
+    # Revokes the token. A browser that stopped meanwhile took its tokens
+    # with it, so a failure here is only logged.
+    def revoke!
+      self.class.request(Net::HTTP::Delete, self.class.tokens_uri(URI(@mcp_url), @id), @sandbox.browser_token)
+      true
+    rescue Error, SystemCallError, IOError, Timeout::Error, URI::Error => e
+      Rails.logger.info("[ActionAgent] browser client token #{@id} not revoked: #{e.message}")
+      false
+    end
+
+    # The Claude Code --mcp-config document reaching the browser as the
+    # "browser" server with this token.
+    def mcp_config
+      { mcpServers: { browser: { type: "http", url: mcp_url, headers: { "Authorization" => "Bearer #{token}" } } } }
+    end
+
+    class << self
+      def tokens_uri(mcp_url, id = nil)
+        uri = mcp_url.dup
+        uri.path = id ? "/tokens/#{id}" : "/tokens"
+        uri.query = nil
+        uri
+      end
+
+      # @return [Hash] the parsed body
+      def request(klass, uri, master_token, body = nil)
+        raise Error, "Only a loopback browser is reached this way" unless %w[127.0.0.1 localhost ::1 [::1]].include?(uri.host)
+
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.open_timeout = TIMEOUT
+        http.read_timeout = TIMEOUT
+        request = klass.new(uri)
+        request["Authorization"] = "Bearer #{master_token}"
+        request["Content-Type"] = "application/json"
+        request.body = body if body
+        response = http.request(request)
+        raise Error, "The browser answered HTTP #{response.code}" unless response.is_a?(Net::HTTPSuccess)
+
+        response.body.to_s.empty? ? {} : JSON.parse(response.body)
+      end
+    end
+  end
+end

data/app/services/action_agent/checkout_tools.rb

@@ -0,0 +1,154 @@
+# frozen_string_literal: true
+
+module ActionAgent
+  # The toolbox capabilities that work in a checkout: terminal (run_command),
+  # filesystem (list_files, read_file, write_file), edit (edit_file) and
+  # database (query_database). Each acts on the checkout sandbox the run was
+  # given (AgentRun#sandbox_id — the runner's and an evaluation's
+  # `sandbox_id`), through SandboxOrchestrator, so they reach exactly what a
+  # Claude Code session in that checkout reaches.
+  #
+  # A run given no checkout gets an error saying how to give it one, rather
+  # than a tool that silently does nothing. Results and errors are returned
+  # as hashes for the model to read.
+  class CheckoutTools
+    FUNCTIONS = %w[run_command list_files read_file write_file edit_file query_database].freeze
+
+    # Rows query_database returns at most, and how long it may take, Rails
+    # boot included.
+    MAX_QUERY_ROWS = 200
+    QUERY_TIMEOUT = 90
+    # The line the query script's JSON follows, so whatever the app prints
+    # while booting is not mistaken for the result.
+    QUERY_MARKER = "__ACTION_AGENT_QUERY__"
+
+    NO_CHECKOUT = "This run has no checkout sandbox. Choose one under Checkout on the agent's Run page " \
+      "(or run an evaluation against one), then run again."
+
+    def self.function?(name)
+      FUNCTIONS.include?(name.to_s)
+    end
+
+    # @param sandbox [SandboxSession, nil] the run's checkout, or nil
+    def initialize(sandbox, orchestrator: nil)
+      @sandbox = sandbox
+      @orchestrator = orchestrator
+    end
+
+    # @return [Hash]
+    def call(name, kwargs)
+      return { error: "Unknown tool: #{name}" } unless self.class.function?(name)
+      return { error: NO_CHECKOUT } unless @sandbox
+      unless @sandbox.ready? || @sandbox.running?
+        return { error: "The checkout sandbox #{@sandbox.session_id} is #{@sandbox.status}; start it again and rerun" }
+      end
+
+      args = kwargs.to_h.symbolize_keys
+      case name.to_s
+      when "run_command" then run_command(**args.slice(:command, :timeout_seconds))
+      when "list_files" then list_files(**args.slice(:path))
+      when "read_file" then read_file(**args.slice(:path))
+      when "write_file" then write_file(**args.slice(:path, :content))
+      when "edit_file" then edit_file(**args.slice(:path, :old_text, :new_text))
+      when "query_database" then query_database(**args.slice(:sql))
+      end
+    rescue ArgumentError, SandboxOrchestrator::UnsupportedBackendError, LocalSandboxBackend::Error => e
+      { error: e.message }
+    end
+
+    def run_command(command:, timeout_seconds: nil)
+      orchestrator.run_command(@sandbox, command.to_s, timeout: timeout_seconds&.to_i)
+    end
+
+    def list_files(path: nil)
+      orchestrator.list_files(@sandbox, path.presence)
+    end
+
+    def read_file(path:)
+      content = orchestrator.read_file(@sandbox, path.to_s)
+      return { error: "#{path} does not exist in the checkout" } if content.nil?
+
+      text = content.dup.force_encoding(Encoding::UTF_8)
+      return { error: "#{path} is not a text file" } unless text.valid_encoding?
+
+      { path: path, content: text }
+    end
+
+    def write_file(path:, content:)
+      orchestrator.write_file(@sandbox, path.to_s, content.to_s)
+    end
+
+    # One exact replacement, the edit a model can say precisely: +old_text+
+    # must appear exactly once, so the edit lands where it was meant to.
+    def edit_file(path:, old_text:, new_text:)
+      current = read_file(path: path)
+      return current if current[:error]
+
+      occurrences = current[:content].scan(old_text.to_s).size
+      return { error: "old_text is empty" } if old_text.to_s.empty?
+      return { error: "old_text was not found in #{path}" } if occurrences.zero?
+      return { error: "old_text appears #{occurrences} times in #{path}; include more context so it appears once" } if occurrences > 1
+
+      written = orchestrator.write_file(@sandbox, path.to_s, current[:content].sub(old_text.to_s) { new_text.to_s })
+      written.merge(replaced: 1)
+    end
+
+    # Runs +sql+ in the checkout's own Rails environment, against the
+    # database its boot provisioned, inside a read-only transaction that is
+    # rolled back (PostgreSQL, MySQL), or on a query_only connection (SQLite). The SQL travels base64-encoded inside the script, so
+    # nothing in it reaches the shell.
+    def query_database(sql:)
+      return { error: "No SQL to run" } if sql.to_s.strip.empty?
+
+      result = orchestrator.run_command(@sandbox, query_command(sql.to_s), timeout: QUERY_TIMEOUT)
+      line = result[:output].to_s.lines.reverse.find { |candidate| candidate.start_with?(QUERY_MARKER) }
+      unless line
+        return { error: "The query did not run", exit_status: result[:exit_status], output: result[:output].to_s.last(4_000) }
+      end
+
+      JSON.parse(line.delete_prefix(QUERY_MARKER))
+    rescue JSON::ParserError
+      { error: "The query's result could not be read", output: result[:output].to_s.last(4_000) }
+    end
+
+    private
+
+    def orchestrator
+      @orchestrator ||= SandboxOrchestrator.new
+    end
+
+    def query_command(sql)
+      encoded = [ sql ].pack("m0")
+      script = <<~RUBY
+        sql = "#{encoded}".unpack1("m0").force_encoding("UTF-8")
+        connection = ActiveRecord::Base.connection
+        adapter = connection.adapter_name.downcase
+        out = nil
+        read = lambda do
+          result = connection.select_all(sql)
+          out = { columns: result.columns, rows: result.rows.first(#{MAX_QUERY_ROWS}), row_count: result.rows.size, truncated: result.rows.size > #{MAX_QUERY_ROWS} }
+        end
+        begin
+          if adapter.include?("sqlite")
+            # Rails opens SQLite transactions with BEGIN IMMEDIATE, which
+            # query_only refuses; query_only alone keeps the connection from writing.
+            connection.execute("PRAGMA query_only = ON")
+            read.call
+          else
+            connection.execute("SET SESSION TRANSACTION READ ONLY") if adapter.match?(/mysql|trilogy/)
+            connection.transaction do
+              connection.execute("SET TRANSACTION READ ONLY") if adapter.include?("postg")
+              read.call
+              raise ActiveRecord::Rollback
+            end
+          end
+        rescue => e
+          out = { error: e.message.to_s[0, 2000] }
+        end
+        puts "#{QUERY_MARKER}" + out.to_json
+      RUBY
+
+      "bin/rails runner #{Shellwords.escape(script)}"
+    end
+  end
+end

data/app/services/action_agent/code_conversation.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+module ActionAgent
+  # Used to carry on a Claude Code or Codex conversation: a chain of
+  # CodeSessions, one per turn, the first being the root (see CodeSession).
+  #
+  # A turn runs only after the one before it settled, one at a time per
+  # checkout. A message sent while a turn runs is queued in the conversation
+  # (.post!) and started once that turn settles (.advance!, called by
+  # CodeSessionJob). A turn resumes the CLI session the first turn started, so
+  # it sees everything said before. That session lives in the CLI's own
+  # configuration for the credential the conversation started with, so a
+  # conversation keeps that credential: a turn on another is refused.
+  module CodeConversation
+    # A conversation's length, and how many messages may wait behind its
+    # running turn.
+    MAX_TURNS = 50
+    MAX_QUEUED_TURNS = 3
+    MAX_NOTE_CHARACTERS = 2_000
+
+    class Refused < StandardError; end
+
+    module_function
+
+    # Adds a turn to +root+'s conversation: queued, and started at once when
+    # nothing else runs in its checkout. The caller has checked the checkout
+    # can take a session (CodeSessionsController#refusal_for) and charged the
+    # execution.
+    #
+    # @param root [CodeSession] the conversation's first turn
+    # @param prompt [String] the person's message, exactly as typed
+    # @param user_id [Integer, nil] who sent it, billed for it
+    # @param credential_mode [String, nil] what the turn would run on now
+    # @param handoff [Hash, nil] { "taken_at", "released_at", "page_url", "by" }:
+    #   the sender's own account of driving the browser since the last turn
+    # @param model [String, nil]
+    # @return [CodeSession] the new turn
+    # @raise [Refused]
+    def post!(root, prompt:, user_id:, credential_mode: nil, handoff: nil, model: nil)
+      raise Refused, "Continue the conversation from its first turn" unless root.root?
+
+      root.sandbox_session.with_lock do
+        turns = root.turns
+        raise Refused, "This conversation has reached its #{MAX_TURNS} turns: start a new one" if turns.size >= MAX_TURNS
+        raise Refused, "#{MAX_QUEUED_TURNS} messages are already waiting in this conversation" if turns.count(&:queued?) >= MAX_QUEUED_TURNS
+        if credential_mode && root.credential_mode && credential_mode != root.credential_mode
+          raise Refused, "This conversation ran on another Claude Code credential (#{root.credential_mode}): start a new conversation"
+        end
+        if (other = busy_elsewhere(root))
+          raise Refused, "Another #{other.runner == 'codex' ? 'Codex' : 'Claude Code'} session is #{other.status} in this sandbox"
+        end
+        raise Refused, "The first turn never started a session to continue: start a new conversation" if resume_id(root).nil?
+
+        turn = CodeSession.create!(
+          sandbox_session: root.sandbox_session,
+          conversation_root: root,
+          turn_index: turns.last.turn_index + 1,
+          prompt: CodeSession.strip_note_tags(prompt),
+          context_note: note_for(handoff),
+          model: model.presence || root.model,
+          runner: root.runner,
+          origin: root.origin,
+          credential_mode: root.credential_mode,
+          resume_session_id: resume_id(root),
+          user_id: user_id,
+          account_id: root.account_id
+        )
+      end.tap { advance!(root) }
+    end
+
+    # Starts the oldest queued turn of +root+'s conversation, when no turn of
+    # it runs. Called by CodeSessionJob once a turn settled, and by .post!.
+    #
+    # @return [CodeSession, nil] the turn started
+    def advance!(root)
+      root = root.root
+      turn = root.sandbox_session.with_lock do
+        turns = root.turns
+        next nil if turns.any?(&:running?)
+
+        # The root starts by itself (CodeSessionsController#create); a
+        # follow-up waits for it. The oldest queued follow-up goes next.
+        # Enqueuing one twice does no harm: CodeSessionJob claims a turn
+        # atomically, and a second job finds it no longer queued.
+        next nil if root.queued?
+
+        turns.find { |candidate| candidate.queued? && !candidate.root? }
+      end
+      CodeSessionJob.perform_later(turn.id) if turn
+      turn
+    end
+
+    # The CLI session +root+'s conversation resumes: the id the first turn
+    # started with, or, for a Codex conversation, the thread its first turn
+    # reported.
+    def resume_id(root)
+      root.runner == "codex" ? root.runner_session_id.presence : root.resume_session_id.presence
+    end
+
+    # A queued or running session in +root+'s checkout that is not a turn of
+    # its conversation.
+    def busy_elsewhere(root)
+      root.sandbox_session.code_sessions.where(status: [ :queued, :running ])
+        .where.not(id: root.id).where("conversation_root_id IS NULL OR conversation_root_id <> ?", root.id).first
+    end
+
+    # What the dashboard tells Claude ahead of the message, from the sender's
+    # account of driving the browser, or nil.
+    def note_for(handoff)
+      return nil unless handoff.respond_to?(:to_h)
+
+      handoff = handoff.to_h.transform_keys(&:to_s)
+      by = handoff["by"].to_s.gsub(/[[:cntrl:]]/, " ").strip.presence || "The person"
+      taken = timestamp(handoff["taken_at"])
+      released = timestamp(handoff["released_at"])
+      return nil unless taken || released
+
+      page = handoff["page_url"].to_s[%r{\Ahttps?://[^\s<>"]{1,500}\z}]
+      parts = []
+      parts << "#{by} took control of the browser at #{taken}" if taken
+      parts << "handed it back at #{released}" if released
+      text = "#{parts.join(' and ')}."
+      text += " The page on screen was #{page}." if page
+      "#{text} The page may have changed: take a snapshot before acting.".truncate(MAX_NOTE_CHARACTERS)
+    end
+
+    def timestamp(value)
+      Time.iso8601(value.to_s).utc.strftime("%H:%M:%S UTC")
+    rescue ArgumentError
+      nil
+    end
+  end
+end

data/app/services/action_agent/codex_auth.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module ActionAgent
+  # How Codex sessions authenticate (ActionAgent.codex_auth), and the one rule
+  # for whether an owner's Codex is "connected", shared by the sandbox
+  # listing, the assistant's configuration and the session API so they never
+  # disagree. The Codex counterpart of ClaudeCodeAuth.
+  #
+  # :api_key     the owner's OpenAI API key, stored as a ProviderKey and
+  #              handed to the session as CODEX_API_KEY.
+  # :local_login the login of the machine the dashboard runs on, as
+  #              `codex login status` reports it (see
+  #              LocalSandboxBackend.codex_login_status). The dashboard never
+  #              sees that credential.
+  module CodexAuth
+    module_function
+
+    # @return [String] "api_key" or "local_login"
+    def mode
+      ActionAgent.codex_auth.to_s
+    end
+
+    def local_login?
+      mode == "local_login"
+    end
+
+    # Why +orchestrator+'s backend cannot run Codex sessions with the
+    # configured authentication, or nil. A machine's own login is the
+    # dashboard user's, so only a backend running sessions as that user, on
+    # that machine, may use it: a container or a remote host would either
+    # find no login or need it copied there, which is what this mode exists
+    # to never do.
+    def backend_refusal(orchestrator)
+      return unless local_login?
+      return if orchestrator.local?
+
+      "ActionAgent.codex_auth = :local_login uses this machine's own Codex login, so it works only " \
+        "with the :local sandbox backend, not #{orchestrator.backend_name}"
+    end
+
+    # Whether the owner of +provider_keys+ (a ProviderKey scope already
+    # narrowed to them) has an API key Codex can run on.
+    def api_key_connected?(provider_keys)
+      provider_keys.where(provider: "codex").any? { |key| key.runtime_environment.present? }
+    end
+
+    # What the dashboard reports about Codex for the owner of
+    # +provider_keys+: booleans and the login's method, never a credential.
+    #
+    # @return [Hash] { mode:, connected:, login: } (login for :local_login only)
+    def status(provider_keys)
+      if local_login?
+        # Only the :local backend uses the login, and no other one needs
+        # this machine's CLI asked about it.
+        login = local_backend? ? LocalSandboxBackend.codex_login_status : LocalSandboxBackend::LOGGED_OUT
+        { mode: mode, connected: login[:logged_in], login: login.slice(:logged_in, :auth_method) }
+      else
+        { mode: mode, connected: api_key_connected?(provider_keys) }
+      end
+    end
+
+    # A backend that cannot even be loaded is not the :local one.
+    def local_backend?
+      SandboxOrchestrator.new.local?
+    rescue StandardError, LoadError
+      false
+    end
+
+    # Why a Codex session cannot start in +sandbox+ for want of credentials,
+    # or nil.
+    def credential_refusal(sandbox)
+      if local_login?
+        return if LocalSandboxBackend.codex_login_status[:logged_in]
+
+        "Codex is not logged in on this machine: run `codex login` as the user the dashboard runs as"
+      elsif sandbox.runtime_environment(runner: "codex").blank?
+        "Codex is not connected: connect an OpenAI API key in Settings -> Integrations first"
+      end
+    end
+  end
+end