actionagent 1.7.2 → 1.8.1

data/app/controllers/action_agent/api/github_connections_controller.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+module ActionAgent
+  module Api
+    # The owner's GitHub connection (Settings -> Integrations): the OAuth
+    # web flow that creates it, the repositories it makes available, and
+    # disconnecting it. The access token is write-only; responses carry the
+    # GitHub login and the chosen repositories, never the token.
+    #
+    # #connect and #callback are browser navigations rather than fetches, so
+    # they answer with redirects back into the dashboard's Settings view.
+    class GithubConnectionsController < BaseController
+      STATE_SESSION_KEY = :action_agent_github_oauth_state
+
+      before_action :require_owner!
+      before_action :require_github_oauth!, only: [ :connect, :callback ]
+      before_action :set_connection, only: [ :repositories, :update, :destroy ]
+
+      # Later handlers win, so the subclass is registered last.
+      rescue_from GithubClient::Error, with: :github_unavailable
+      rescue_from GithubClient::Unauthorized, with: :github_unauthorized
+
+      # GET /api/github_connection
+      def show
+        connection = owned(GithubConnection).first
+
+        render json: {
+          configured: ActionAgent.github_oauth_configured?,
+          connected: connection.present?,
+          connection: connection&.as_summary
+        }
+      end
+
+      # GET /api/github_connection/repositories — what the token reaches,
+      # each marked with whether the workspace has it selected.
+      def repositories
+        selected = @connection.repository_names.map(&:downcase).to_set
+
+        render json: {
+          repositories: @connection.client.repositories.map do |repo|
+            repo.merge("selected" => selected.include?(repo["full_name"].downcase))
+          end
+        }
+      end
+
+      # PATCH /api/github_connection { repositories: ["owner/name", ...] }
+      #
+      # Only names GitHub lists for this token are kept: the selection is
+      # what a checkout sandbox trusts, so it is never taken from the client.
+      def update
+        # Not params.require: an empty list (clear the selection) is valid.
+        requested = params[:repositories]
+        unless requested.is_a?(Array) && requested.all? { |name| name.is_a?(String) }
+          return render json: { error: "repositories must be a list of owner/name strings" }, status: :bad_request
+        end
+
+        available = @connection.client.repositories.index_by { |repo| repo["full_name"].downcase }
+        unknown = requested.reject { |name| available.key?(name.downcase) }
+        if unknown.any?
+          return render json: { error: "Not reachable with this GitHub connection: #{unknown.join(', ')}" },
+            status: :unprocessable_entity
+        end
+
+        @connection.update!(repositories: requested.map { |name| available.fetch(name.downcase) }.uniq { |repo| repo["id"] })
+        render json: { connected: true, connection: @connection.as_summary }
+      end
+
+      # DELETE /api/github_connection
+      def destroy
+        @connection.destroy!
+        head :no_content
+      end
+
+      # GET /api/github_connection/connect — starts the OAuth web flow.
+      def connect
+        state = SecureRandom.urlsafe_base64(32)
+        session[STATE_SESSION_KEY] = state
+
+        redirect_to GithubClient.authorize_url(redirect_uri: callback_url, state: state), allow_other_host: true
+      end
+
+      # GET /api/github_connection/callback?code=...&state=...
+      def callback
+        # Single use: read and cleared before anything else can fail.
+        expected = session.delete(STATE_SESSION_KEY)
+        return redirect_to_settings(github: "denied") if params[:error].present?
+
+        unless expected.present? && params[:state].is_a?(String) &&
+            ActiveSupport::SecurityUtils.secure_compare(expected, params[:state])
+          return redirect_to_settings(github: "invalid_state")
+        end
+        return redirect_to_settings(github: "missing_code") unless params[:code].is_a?(String) && params[:code].present?
+
+        grant = GithubClient.exchange_code(code: params[:code], redirect_uri: callback_url)
+        user = GithubClient.new(grant[:access_token]).user
+
+        # Built through the owner scope, like a provider key, so the new
+        # record carries whichever owner column this install uses.
+        connection = owned(GithubConnection).first || owned(GithubConnection).new
+        # A different GitHub account starts with nothing selected: the old
+        # selection was checked against the other account's access.
+        connection.repositories = [] if connection.persisted? && connection.github_user_id != user["id"]
+        connection.update!(
+          access_token: grant[:access_token],
+          scopes: grant[:scope],
+          github_user_id: user["id"],
+          login: user["login"],
+          avatar_url: user["avatar_url"]
+        )
+
+        redirect_to_settings(github: "connected")
+      rescue GithubClient::Error => e
+        Rails.logger.warn("[ActionAgent] GitHub OAuth callback failed: #{e.message}")
+        redirect_to_settings(github: "error")
+      end
+
+      private
+
+      def set_connection
+        @connection = owned(GithubConnection).first!
+      end
+
+      def require_github_oauth!
+        return if ActionAgent.github_oauth_configured?
+
+        redirect_to_settings(github: "not_configured")
+      end
+
+      def callback_url
+        "#{request.base_url}#{request.script_name}/api/github_connection/callback"
+      end
+
+      def redirect_to_settings(**query)
+        redirect_to "#{request.script_name}/settings?#{{ tab: 'integrations' }.merge(query).to_query}"
+      end
+
+      def github_unauthorized
+        render json: { error: "GitHub rejected the stored token. Reconnect GitHub.", reconnect_required: true },
+          status: :unprocessable_entity
+      end
+
+      def github_unavailable(exception)
+        render json: { error: exception.message }, status: :bad_gateway
+      end
+    end
+  end
+end

data/app/controllers/action_agent/api/mcp_controller.rb

@@ -11,7 +11,9 @@ module ActionAgent
     #   schema tools (ActiveAgent::SchemaTools, the classes the dashboard
     #   discovers) is callable directly — find_<records>, count_<records>,
     #   get_<record> — as this key's caller, so a client reads the host's
-    #   records under the same scope an agent run would (#439).
+    #   records under the same scope an agent run would (#439). The
+    #   dashboard's own evaluation and telemetry tools (MCPDashboardTools)
+    #   are offered beside them.
     # - resources/list & resources/read: each agent is an agent://<slug>
     #   resource whose content is its live scorecard (config + stats + memory
     #   summary from the solid_agent datasets).
@@ -30,6 +32,8 @@ module ActionAgent
       skip_forgery_protection
       before_action :authenticate_api_key!, except: [ :unsupported ]
 
+      include MCPDashboardTools
+
       PROTOCOL_VERSION = "2025-03-26"
       JSONRPC_METHOD_NOT_FOUND = -32601
       JSONRPC_INVALID_PARAMS = -32602
@@ -105,6 +109,21 @@ module ActionAgent
         @owner = api_key.owner
       end
 
+      # The key's owner stands in for the signed-in owner, so the dashboard's
+      # own scopes (owned, owner_agents, owned_traces, RunSandbox) read what
+      # the JSON API would read for that owner.
+      def current_owner
+        @owner
+      end
+
+      # The key's user when it records one. Otherwise the owner, unless the
+      # owner is an account: a tenant is never a user.
+      def current_user
+        return @api_key.user if @api_key.respond_to?(:user) && @api_key.user
+
+        ActionAgent.multi_tenant? ? nil : @owner
+      end
+
       # The agents this key can reach. A key belongs to whoever owns it, and
       # a single-user install has no owner, so the key reaches every agent
       # the dashboard holds.
@@ -149,12 +168,23 @@ module ActionAgent
           protocolVersion: PROTOCOL_VERSION,
           capabilities: { tools: {}, resources: {} },
           serverInfo: { name: "activeagents", version: "1.0" },
-          instructions: "Each run_<slug> tool runs one of this account's agents; every other tool reads the host " \
-                        "application's records directly, as the caller this key authenticates. Each agent://<slug> " \
-                        "resource returns the agent's live scorecard."
+          instructions: initialize_instructions
         }
       end
 
+      def initialize_instructions
+        text = "Each run_<slug> tool runs one of this account's agents; each find_, count_ and get_ tool reads the " \
+               "host application's records directly, as the caller this key authenticates. Each agent://<slug> " \
+               "resource returns the agent's live scorecard."
+        return text unless ActionAgent.mcp_dashboard_tools?
+
+        "#{text} The evaluations_, evaluation_runs_ and traces_ tools work on this account's evaluations and " \
+          "telemetry: edit the agent in your own checkout, start a run with evaluations_run (pass sandbox_id to run " \
+          "against a checkout sandbox), poll evaluation_runs_get for its status, results and fix items, compare runs " \
+          "with evaluation_runs_compare, and read a failing result's trace with traces_get (traces_search finds " \
+          "recent failures)."
+      end
+
       MESSAGE_INPUT_SCHEMA = {
         type: "object",
         properties: {
@@ -182,7 +212,7 @@ module ActionAgent
           agent_tools
         end
 
-        { tools: tools + schema_tools_list }
+        { tools: dashboard_tools_list + tools + schema_tools_list }
       end
 
       # The host's schema tools, offered as the same tool definitions an
@@ -206,6 +236,9 @@ module ActionAgent
 
       def tools_call
         name = params.dig(:params, :name).to_s
+        # The three families' names are disjoint (see MCPDashboardTools), so
+        # this order never decides between two tools.
+        return dashboard_tool_call(name) if dashboard_tool?(name)
         return schema_tool_call(name) if ActionAgent.mcp_schema_tools? && ActionAgent.schema_tool_class_for(name)
 
         slug, action = name.delete_prefix("run_").split("__", 2)

data/app/controllers/action_agent/api/mcp_servers_controller.rb

@@ -9,6 +9,8 @@ module ActionAgent
     # and solid_agent records (ToolDiscovery), servers an agent declares in
     # its configuration, and the default catalog (MCPCatalog). An install
     # therefore sees both what it is already using and what it could turn on.
+    # The caller's live checkout sandbox runtimes are listed with the catalog,
+    # so the one started from Settings -> Integrations shows up here too.
     class MCPServersController < BaseController
       before_action :require_owner!
       # Launching provisions a sandbox and runs a server in it, so it answers
@@ -108,8 +110,15 @@ module ActionAgent
 
       private
 
+      # Runtimes are the caller's own: a listing carries no token, but which
+      # repositories another owner has running is still theirs to know.
       def discovery
-        ToolDiscovery.new(traces: owned_traces, agents: owner_agents, hours: window_hours)
+        ToolDiscovery.new(
+          traces: owned_traces,
+          agents: owner_agents,
+          hours: window_hours,
+          runtimes: SandboxSession.runtime_server_listings(owned(SandboxSession))
+        )
       end
 
       # The catalog names this dashboard's own MCP endpoint as "<mount>/mcp",

data/app/controllers/action_agent/api/provider_keys_controller.rb

@@ -4,7 +4,9 @@ module ActionAgent
   module Api
     # Per-account LLM provider credentials (Settings -> Provider API Keys).
     # API keys are write-only: responses carry a masked hint, never the key.
-    # Ollama's credential is a host URL and is echoed back in full.
+    # Ollama's credential is a host URL and is echoed back in full; its
+    # optional API key (remote servers) is masked like the others. Claude
+    # Code's connection API key is stored here too, write-only like a key.
     class ProviderKeysController < BaseController
       before_action :require_owner!
 
@@ -20,16 +22,42 @@ module ActionAgent
       end
 
       # POST /api/provider_keys — upserts the credential for a provider.
+      # Host-based providers may also carry an optional api_key; omitting it
+      # keeps the stored one, sending an empty string clears it.
       def create
         provider = params.require(:provider)
         credential = params.require(:credential)
 
         record = owned(ProviderKey).find_or_initialize_by(provider: provider)
-        record.update!(credential: credential)
+        attributes = { credential: credential }
+        attributes[:api_key] = params[:api_key].presence if params.key?(:api_key) && record.host_based?
+        record.update!(**attributes)
 
         render json: { provider_key: serialize(provider, record) }, status: :created
       end
 
+      # POST /api/provider_keys/test — checks that a host-based provider is
+      # reachable and lists the models it serves. Tests the submitted host
+      # (and api_key) when given, so a URL can be checked before saving;
+      # otherwise the stored credential, else the host app's default. Never
+      # persists anything.
+      def test
+        provider = params.require(:provider)
+        unless ProviderKey::HOST_PROVIDERS.include?(provider)
+          return render json: { error: "#{provider} is not a host-based provider" }, status: :unprocessable_entity
+        end
+
+        stored = owned(ProviderKey).find_by(provider: provider)
+        host = params[:credential].presence || stored&.credential || platform_host(provider)
+        api_key = params.key?(:api_key) ? params[:api_key].presence : stored&.api_key
+
+        if host.blank?
+          return render json: { ok: false, host: nil, models: [], latency_ms: nil, error: "No host configured" }
+        end
+
+        render json: OllamaHostProbe.call(host: host, api_key: api_key).to_h
+      end
+
       # DELETE /api/provider_keys/:provider
       def destroy
         owned(ProviderKey).find_by!(provider: params[:provider]).destroy!
@@ -38,12 +66,35 @@ module ActionAgent
 
       private
 
+      # The host app's default (config/active_agent.yml, e.g. OLLAMA_HOST)
+      # that applies when the owner has not configured their own.
+      def platform_host(provider)
+        return nil unless ProviderKey::HOST_PROVIDERS.include?(provider)
+
+        config = ActiveAgent.configuration[provider.to_sym]
+        config.respond_to?(:[]) ? config[:host].presence : nil
+      rescue StandardError
+        nil
+      end
+
       def serialize(provider, record)
+        host_based = ProviderKey::HOST_PROVIDERS.include?(provider)
+
         {
           provider: provider,
-          host_based: ProviderKey::HOST_PROVIDERS.include?(provider),
+          host_based: host_based,
+          # "key", "host", or "connection" (Settings -> Integrations rather
+          # than Provider API Keys).
+          kind: ProviderKey.kind_of_provider(provider),
           configured: record.present?,
           hint: record&.display_hint,
+          api_key_configured: record&.api_key? || false,
+          api_key_hint: record&.api_key_hint,
+          platform_default: host_based && record.nil? ? platform_host(provider) : nil,
+          # A Claude Code connection still holding a Claude subscription token
+          # from an earlier version: never used, and the UI asks for an API
+          # key in its place.
+          needs_replacing: record.present? && record.needs_replacing?,
           updated_at: record&.updated_at&.iso8601
         }
       end

data/app/controllers/action_agent/api/provider_models_controller.rb

@@ -67,16 +67,20 @@ module ActionAgent
         owned(ProviderKey).find_by(provider: provider)
       end
 
+      # Same probe as Settings -> "Test connection", so the builder's dropdown
+      # and the settings page agree on what the host serves (including the
+      # optional Bearer key for remote servers).
       def live_ollama_models
         host = ollama_host
         return nil unless host
 
-        data = fetch_json(URI.join("#{host.chomp('/')}/", "models"))
-        ids = Array(data&.dig("data")).filter_map { |model| model["id"] }
-        [ ids.sort, "live" ] if ids.any?
-      rescue StandardError => e
-        Rails.logger.warn("[ProviderModels] ollama lookup failed: #{e.message}")
-        nil
+        result = OllamaHostProbe.call(host: host, api_key: owner_provider_key("ollama")&.api_key)
+        unless result.ok
+          Rails.logger.warn("[ProviderModels] ollama lookup failed: #{result.error}")
+          return nil
+        end
+
+        [ result.models, "live" ] if result.models.any?
       end
 
       # Queries the Anthropic Models API with the account's key (newest first,

data/app/controllers/action_agent/api/sandboxes_controller.rb

@@ -12,6 +12,9 @@ module ActionAgent
       # development, so it bypassed that safeguard too.
 
       before_action :require_execution_enabled!, only: [ :run, :compare ]
+      # A checkout runs the owner's code (setup, server): the same gates as
+      # running an agent, like MCPServersController#launch.
+      before_action :gate_checkout!, only: [ :create ]
       before_action :enforce_execution_quota!, only: [ :compare ]
       before_action :set_sandbox, only: [ :show, :run, :destroy ]
 
@@ -83,16 +86,34 @@ module ActionAgent
       end
 
       # GET /api/sandboxes
-      # List available sandbox types and sample tasks
+      # List available sandbox types and sample tasks, and the caller's own
+      # sandboxes (?sandbox_type= narrows them), with what the Settings ->
+      # Integrations view needs to offer Claude Code sessions in a checkout.
       def index
         render json: {
           sandbox_types: SandboxSession::SANDBOX_TYPES,
           free_tier_limits: SandboxSession::FREE_TIER_LIMITS,
           templates: free_tier_templates,
-          sample_tasks: sample_tasks
+          sample_tasks: sample_tasks,
+          sandboxes: listed_sandboxes.map(&:summary),
+          code_sessions_supported: code_sessions_supported?,
+          codex_sessions_supported: codex_sessions_supported?,
+          codex_connected: owned(ProviderKey).where(provider: "codex").any? { |key| key.runtime_environment.present? },
+          **claude_code_status
         }
       end
 
+      # Refuses a checkout the owner may not start. Usage is recorded by
+      # #create once the sandbox saved: a request refused for its own
+      # content (a repository that is not selected, say) runs nothing, so it
+      # must not spend a plan run.
+      def gate_checkout!
+        return unless checkout_requested?
+
+        require_execution_enabled!
+        enforce_execution_quota! unless performed?
+      end
+
       # POST /api/sandboxes
       # Create a new sandbox session, owned by whoever opened it.
       def create
@@ -100,11 +121,17 @@ module ActionAgent
         # Guarded: the association only exists when the host app configured a
         # user model, and a single-user install configures none.
         @sandbox.user = current_user if @sandbox.respond_to?(:user=)
+        # A checkout is validated against the owner's GitHub connection, which
+        # an account-owned install finds through the account.
+        @sandbox.account_id = current_account.id if current_account && @sandbox.has_attribute?(:account_id)
         @sandbox.agent_template = AgentTemplate.find_by(slug: params[:template_slug]) if params[:template_slug]
 
         if @sandbox.save
           @sandbox.provision!
           @sandbox.reload # Reload to get updated status after provisioning
+          # Counted once the checkout exists, as MCPServersController#launch
+          # counts a launched server.
+          record_execution_usage if checkout_requested?
           render json: { sandbox: @sandbox.summary }, status: :created
         else
           render json: { errors: @sandbox.errors.full_messages }, status: :unprocessable_entity
@@ -162,20 +189,92 @@ module ActionAgent
       end
 
       # DELETE /api/sandboxes/:session_id
-      # End sandbox session
+      # End sandbox session. Expiring it enqueues SandboxCleanupJob, which
+      # terminates whatever the backend runs for it (a checkout's processes
+      # included); one still provisioning is released by
+      # SandboxProvisionJob when its backend returns.
       def destroy
         @sandbox.expire!
-        render json: { deleted: true }
+        render json: { deleted: true, sandbox: @sandbox.summary }
       end
 
       private
 
       def set_sandbox
-        @sandbox = owned(SandboxSession).find_by!(session_id: params[:id])
+        @sandbox = account_scoped(owned(SandboxSession)).find_by!(session_id: params[:id])
+      end
+
+      def checkout_requested?
+        params[:sandbox_type].to_s == "app_runtime"
+      end
+
+      # A checkout runs on its account's GitHub token and Claude Code
+      # credential, so in a multi-tenant install it is listed, shown and
+      # stopped only within the caller's current account, as
+      # CodeSessionsController finds it: listing another account's checkout
+      # as Ready offered a Claude Code panel that then answered 404. Other
+      # sandbox types are the caller's own wherever they were opened.
+      def account_scoped(scope)
+        return scope unless current_account
+
+        scope.where.not(sandbox_type: "app_runtime").or(scope.where(account_id: current_account.id))
+      end
+
+      # Whether the configured backend can run Claude Code sessions. A
+      # backend that cannot even be loaded (a misspelled class in
+      # ActionAgent.sandbox_backends, or a class file requiring an SDK the
+      # host doesn't bundle, which raises LoadError) cannot, and must not
+      # take the rest of this listing down with it.
+      #
+      # Nor can one whose Claude Code authentication does not work there
+      # (ActionAgent.claude_code_auth = :local_login needs :local).
+      def code_sessions_supported?
+        orchestrator = SandboxOrchestrator.new
+        orchestrator.supports?(:code_session) && ClaudeCodeAuth.backend_refusal(orchestrator).nil?
+      rescue StandardError, LoadError => e
+        Rails.logger.warn("[ActionAgent] sandbox backend unavailable: #{e.message}")
+        false
+      end
+
+      def codex_sessions_supported?
+        SandboxOrchestrator.new.supports_code_runner?("codex")
+      rescue StandardError, LoadError
+        false
+      end
+
+      # Whether the caller's Claude Code can run sessions, by
+      # ClaudeCodeAuth's rule: an API key they connected, or this machine's
+      # own login. Never a credential.
+      #
+      #   claude_code_auth       "api_key" | "local_login"
+      #   claude_code_connected  Boolean
+      #   claude_code_login      { logged_in:, auth_method: } (local_login only)
+      #
+      # The key is found through its own owner column, as
+      # SandboxSession#runtime_environment finds the credential it hands a
+      # checkout: a provider key is account-owned before user-owned.
+      def claude_code_status
+        status = ClaudeCodeAuth.status(owned(ProviderKey))
+        {
+          claude_code_auth: status[:mode],
+          claude_code_connected: status[:connected],
+          claude_code_login: status[:login]
+        }.compact
+      end
+
+      # The caller's sandboxes that have not expired, newest first. A failed
+      # one stays listed so its error can be read; one past its expiry but
+      # not reaped yet stays listed so it can still be stopped.
+      def listed_sandboxes
+        scope = account_scoped(owned(SandboxSession)).where.not(status: :expired).recent.limit(20)
+        type = params[:sandbox_type]
+        type.is_a?(String) && type.present? ? scope.by_type(type) : scope
       end
 
+      # An app_runtime sandbox also names the checkout: one of the owner's
+      # selected GitHub repositories and, optionally, a ref.
       def sandbox_params
-        params.permit(:sandbox_type)
+        params.permit(:sandbox_type, :repository, :repository_ref)
       end
 
       def free_tier_templates

data/app/controllers/concerns/action_agent/api/evaluation_run_starting.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module ActionAgent
+  module Api
+    # Starting an evaluation run on the caller's behalf, shared by the
+    # evaluations API (POST /api/evaluations/:id/run) and the MCP facade's
+    # `evaluations_run` tool so both check a run the same way.
+    #
+    # A scenario suite accepts a selection that narrows the run:
+    #   - scenario_ids:  the scenarios to replay, by id
+    #   - keys:          the scenarios to replay, by key
+    #   - group:         one scenario group
+    #   - models:        the candidate models, as an array or a comma-separated string
+    #   - sandbox_id:    a checkout sandbox of the caller's that every replay reaches (see RunSandbox)
+    module EvaluationRunStarting
+      extend ActiveSupport::Concern
+
+      include RunSandbox
+
+      private
+
+      # Starts a run of +evaluation+ and returns it. A scenario suite replays
+      # through the provider once per scenario and model, so it runs in the
+      # background and the run comes back pending. A generation-sampling
+      # evaluation scores recorded data and finishes inline.
+      #
+      # A failure is recorded on the run rather than raised, so the caller
+      # always gets a run to report.
+      #
+      # @return [EvaluationRun]
+      def start_evaluation_run(evaluation, selection)
+        return evaluation.run_later!(**selection) if evaluation.scenario_suite?
+
+        evaluation.run!
+      rescue StandardError => e
+        Rails.logger.warn(
+          "[ActionAgent] evaluation #{evaluation.id} run failed: #{e.class}: #{e.message}"
+        )
+        # EvaluationRunnerService records the failure on the run before
+        # re-raising. A failure before the run record existed is recorded here.
+        evaluation.evaluation_runs.recent.first ||
+          evaluation.evaluation_runs.create!(status: :failed, error_message: e.message, completed_at: Time.current)
+      end
+
+      # Returns the selection +source+ (params or tool arguments) asks for,
+      # without the sandbox, which evaluation_run_sandbox checks separately.
+      def evaluation_run_selection(source)
+        models = source[:models]
+        models = models.to_s.split(",") unless models.is_a?(Array)
+
+        {
+          scenario_ids: Array(source[:scenario_ids]).map(&:to_s).reject(&:blank?),
+          keys: Array(source[:keys]).map(&:to_s).reject(&:blank?),
+          group: source[:group].to_s.presence,
+          models: models.map(&:to_s).map(&:strip).reject(&:blank?)
+        }.compact_blank
+      end
+
+      # Returns the checked sandbox +sandbox_id+ names for a run of
+      # +evaluation+, or nil when none was asked for. Raises RunSandbox::Refused.
+      #
+      # Only a scenario suite's own replay executes the agent: a sampling run
+      # scores recorded generations, and a host adapter replays in the host's
+      # runtime, where no dashboard dispatcher runs.
+      #
+      # @return [SandboxSession, nil]
+      def evaluation_run_sandbox(evaluation, sandbox_id)
+        return nil if sandbox_id.blank?
+
+        unless evaluation.scenario_suite?
+          raise RunSandbox::Refused, "Only a scenario evaluation runs the agent; this one scores recorded generations, " \
+            "so it cannot run against a sandbox"
+        end
+        if scenario_evaluation_adapter?(evaluation)
+          raise RunSandbox::Refused, "This install replays scenarios through its own adapter, which cannot reach a " \
+            "dashboard sandbox"
+        end
+
+        run_sandbox_for(evaluation.agent, sandbox_id)
+      end
+
+      # Whether a run of +evaluation+ cannot replay its scenarios: its agent
+      # is observed (read-only), and no host adapter replays it instead.
+      def unexecutable_scenario_run?(evaluation)
+        evaluation.agent.observed? && !scenario_evaluation_adapter?(evaluation)
+      end
+
+      def scenario_evaluation_adapter?(evaluation)
+        ActionAgent.scenario_evaluation_adapter_resolver&.call(evaluation).respond_to?(:call)
+      end
+    end
+  end
+end