actionagent 1.9.4 → 1.9.6

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

@@ -591,23 +591,7 @@ module ActionAgent
       end
 
       def version_json(version, include_diff: false)
-        json = {
-          id: version.id,
-          version_number: version.version_number,
-          change_summary: version.change_summary,
-          created_by: version.created_by,
-          created_at: version.created_at,
-          is_latest: version.latest?,
-          release: version.release?,
-          release_digest: version.release_digest,
-          revision: version.revision
-        }
-
-        if include_diff && version.previous
-          json[:diff] = version.diff(version.previous)
-        end
-
-        json
+        AgentVersionSerializer.call(version, include_diff: include_diff)
       end
 
       def default_appearance_for(preset)

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

@@ -10,11 +10,14 @@ module ActionAgent
     # stored by EvaluationReportImport. Responds:
     #
     #   201 — stored; the receipt the publisher checks
-    #   200 — an identical retry; the receipt names the stored run. Never
-    #         refused by the quota or the rate limit.
+    #   200 — a delivery under a run_id already stored: an identical retry,
+    #         or progress on a running run (EvaluationReportImport); the
+    #         receipt names the stored run and its status. Never refused by
+    #         the quota or the rate limit.
     #   409 — this run_id already holds a different report
     #   422 — not a valid version-1 report, or an evaluation name the agent
-    #         already holds for another suite or scope
+    #         already holds for another suite or scope. The body's
+    #         `capabilities` lists EvaluationReportImport::CAPABILITIES.
     #   403 — storing it needs an operator first: a cap on observed agents,
     #         evaluations or scenarios, or no owner for the tenant
     #   429 — a new report over the host's quota (kind :evaluation_report) or
@@ -58,14 +61,15 @@ module ActionAgent
         body = request.body.read(EvaluationReportImport::MAX_BYTES + 1).to_s
         return report_too_large if body.bytesize > EvaluationReportImport::MAX_BYTES
 
-        run, duplicate = EvaluationReportImport.call(account: @account, payload: JSON.parse(body), admit: -> { admission_denial })
-        ActionAgent.record_usage(@account, :evaluation_report) unless duplicate
+        run, duplicate, progressed = EvaluationReportImport.call(account: @account, payload: JSON.parse(body), admit: -> { admission_denial })
+        stored = !duplicate && !progressed
+        ActionAgent.record_usage(@account, :evaluation_report) if stored
 
-        render json: receipt(run, duplicate), status: duplicate ? :ok : :created
+        render json: receipt(run, duplicate), status: stored ? :created : :ok
       rescue JSON::ParserError
         render json: { error: "Invalid JSON" }, status: :bad_request
       rescue EvaluationReportImport::Invalid, ActiveRecord::RecordInvalid => e
-        render json: { error: e.message }, status: :unprocessable_entity
+        render json: { error: e.message, capabilities: EvaluationReportImport::CAPABILITIES }, status: :unprocessable_entity
       rescue EvaluationReportImport::Conflict => e
         render json: { error: e.message }, status: :conflict
       rescue EvaluationReportImport::Refused => e

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

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+require "openssl"
+
+module ActionAgent
+  module Api
+    # POST <mount>/api/github_app/webhooks: the GitHub App's webhook
+    # deliveries (installation, installation_repositories,
+    # github_app_authorization), applied by GithubWebhookJob.
+    #
+    # GitHub's signature authenticates a delivery on its own, so this is not a
+    # dashboard controller and sees no session, no forgery protection and none
+    # of the host's controller concerns. A delivery is accepted only when its
+    # X-Hub-Signature-256 is the HMAC-SHA256 of the raw body under
+    # ActionAgent.github_app_webhook_secret; with no secret configured there
+    # is no endpoint (404).
+    #
+    # The answer is 202 as soon as a delivery is recorded and enqueued, or
+    # recognized as one already recorded (GithubWebhookDelivery), or found to
+    # be an event the dashboard does not handle. Only a failure to enqueue
+    # answers otherwise, and leaves the delivery unrecorded so a redelivery
+    # of it is processed.
+    #
+    # The body may be JSON, or a form whose +payload+ field holds the JSON,
+    # as GitHub sends it when the App's content type is
+    # application/x-www-form-urlencoded. The signature covers the raw body
+    # either way.
+    class GithubAppWebhooksController < ActionController::API
+      wrap_parameters false
+
+      SIGNATURE_HEADER = "X-Hub-Signature-256"
+      EVENT_HEADER = "X-GitHub-Event"
+      DELIVERY_HEADER = "X-GitHub-Delivery"
+
+      def create
+        secret = ActionAgent.github_app_webhook_secret
+        return head(:not_found) if secret.blank?
+
+        body = request.raw_post.to_s
+        unless signed?(body, secret)
+          return render(json: { error: "Invalid or missing #{SIGNATURE_HEADER}" }, status: :unauthorized)
+        end
+
+        event = request.headers[EVENT_HEADER].to_s
+        return accepted("ignored") unless event.in?(GithubWebhookJob::EVENTS)
+
+        delivery_id = request.headers[DELIVERY_HEADER].to_s
+        unless delivery_id.match?(/\A[A-Za-z0-9-]{1,64}\z/)
+          return render(json: { error: "#{DELIVERY_HEADER} is required" }, status: :bad_request)
+        end
+
+        payload = parse(body)
+        return render(json: { error: "The delivery's body is not a JSON object" }, status: :bad_request) unless payload
+
+        job_payload = GithubWebhookJob.payload_for(event, payload)
+        recorded = GithubWebhookDelivery.record!(
+          delivery_id: delivery_id, event: event,
+          event_action: job_payload["action"].presence&.first(64),
+          installation_id: job_payload.dig("installation", "id").presence&.to_i
+        )
+        return accepted("duplicate") unless recorded
+
+        begin
+          GithubWebhookJob.perform_later(event, job_payload)
+        rescue StandardError
+          # Not left recorded, so a redelivery of it is processed.
+          GithubWebhookDelivery.forget!(delivery_id)
+          raise
+        end
+
+        accepted("queued")
+      end
+
+      private
+
+      # Constant time, whatever the header holds.
+      def signed?(body, secret)
+        given = request.headers[SIGNATURE_HEADER]
+        return false unless given.is_a?(String) && given.start_with?("sha256=")
+
+        expected = "sha256=#{OpenSSL::HMAC.hexdigest('SHA256', secret, body)}"
+        ActiveSupport::SecurityUtils.secure_compare(expected, given)
+      end
+
+      def parse(body)
+        body = Rack::Utils.parse_query(body)["payload"].to_s if request.media_type == "application/x-www-form-urlencoded"
+        data = JSON.parse(body)
+        data if data.is_a?(Hash)
+      rescue JSON::ParserError
+        nil
+      end
+
+      def accepted(status)
+        render json: { status: status }, status: :accepted
+      end
+    end
+  end
+end

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

@@ -151,6 +151,12 @@ module ActionAgent
         record.assign_from_github(installation)
         record.save!
         "linked"
+      # GitHub would not say whether the user administers the organization,
+      # which is not the same as saying they do not.
+      rescue GithubClient::MembershipForbidden => e
+        Rails.logger.warn("[ActionAgent] GitHub App installation #{installation_id} was not linked: #{e.message}. " \
+          "Grant the GitHub App the organization permission Members (read).")
+        "members_permission"
       # Another owner linked the same installation between the lookup and
       # the save.
       rescue ActiveRecord::RecordNotUnique
@@ -163,7 +169,9 @@ module ActionAgent
       end
 
       # Whether +github_user+ administers +account+: is that user account, or
-      # an active admin of that organization.
+      # an active admin of that organization. The organization check needs
+      # the App's organization permission Members (read): without it GitHub
+      # answers 403, and GithubClient::MembershipForbidden is raised.
       def administers?(github, github_user, account)
         account = {} unless account.is_a?(Hash)
 

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

@@ -195,8 +195,11 @@ module ActionAgent
           "failures). A run_<slug> call that pauses to ask for input returns its input request ids: " \
           "input_requests_list shows what paused runs are waiting on, and input_requests_answer answers a text or " \
           "choice request. Scenarios kept as a YAML catalog of products and sets (an .activeagents/evals file) are " \
-          "imported with catalogs_import, listed with catalogs_list, and one set is run as an evaluation named " \
-          "catalog/product/set with catalog_set_run (pass project_id to run against a project's running sandbox)."
+          "imported with catalogs_import (catalogs_preview shows what an import would change first), listed with " \
+          "catalogs_list, written back out with catalogs_export, and one set is run as an evaluation named " \
+          "catalog/product/set with catalog_set_run (pass project_id to run against a project's running sandbox). " \
+          "agents_versions lists an agent's versions with what each changed, and traces_export reads one trace " \
+          "whole, as the payload the trace ingest endpoint takes."
       end
 
       MESSAGE_INPUT_SCHEMA = {

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

@@ -17,16 +17,19 @@ module ActionAgent
       LOG_TAIL_BYTES = 8 * 1024
       LOG_PAGE_BYTES = 64 * 1024
       LOG_MAX_PAGE_BYTES = 1024 * 1024
+      # The most of a backend's error the boot status carries (see #boot_report).
+      BACKEND_ERROR_BYTES = 1_000
       UPDATABLE = %i[name default_ref start_url].freeze
 
       before_action :require_owner!
-      before_action :set_project, except: [ :index, :create, :capabilities, :preflight, :discover_secrets ]
+      before_action :set_project, except: [ :index, :create, :capabilities, :repositories, :preflight, :discover_secrets ]
       before_action :require_execution_enabled!, only: [ :boot, :run_evaluation ]
 
       # Later handlers win, so subclasses are registered after GithubClient::Error.
       rescue_from GithubClient::Error, with: :github_unavailable
       rescue_from GithubClient::NotFound, with: :github_not_found
       rescue_from GithubClient::Unauthorized, with: :github_unauthorized
+      rescue_from GithubClient::InstallationUnavailable, with: :installation_unavailable
       rescue_from Project::ConfirmationRequired, with: :confirmation_required
       rescue_from Project::BootRefused, with: :boot_refused
       rescue_from SandboxOrchestrator::UnsupportedBackendError, with: :boot_refused
@@ -48,33 +51,68 @@ module ActionAgent
         render json: capabilities_check.call
       end
 
+      # GET /api/projects/repositories
+      # The New Project picker's list: the repositories the owner's GitHub
+      # sources reach (see #github_sources), each marked with whether it is
+      # selected and with the source ("app" or "oauth") a project from it
+      # would be read and checked out through. An installation lists every
+      # repository it reaches only to a caller who may manage it, and its
+      # selection to everyone else; the OAuth connection lists what its
+      # token reaches, as GET /api/github_connection/repositories does.
+      def repositories
+        sources = github_sources! or return
+
+        listed = {}
+        sources.each do |source|
+          source.repositories.each do |repo|
+            listed[repo["full_name"].downcase] ||= repo.merge("selected" => true, "source" => source.checkout_source)
+          end
+        end
+        unavailable = nil
+        sources.each do |source|
+          listing = source.is_a?(GithubConnection) || manages_github?(source) ? source.reachable_repositories : []
+          listing.each do |repo|
+            listed[repo["full_name"].downcase] ||= repo.merge("selected" => false, "source" => source.checkout_source)
+          end
+        rescue GithubClient::InstallationUnavailable => e
+          # Marked on the installation; the other sources still list.
+          unavailable = e
+        end
+        raise unavailable if unavailable && listed.empty?
+
+        render json: { repositories: listed.values }
+      end
+
       # GET /api/projects/preflight?repository=owner/name&ref=
       # Whether the repository can become a project, read through GitHub's
       # contents API before any sandbox exists (see ProjectPreflight). A
-      # repository the connection has not selected is looked up by name,
+      # repository no GitHub source has selected is looked up by name,
       # which also reaches repositories past the listing's cap, and needs
       # :manage_github.
       def preflight
-        connection = github_connection! or return
-        repository = reachable_repository!(connection) or return
+        sources = github_sources! or return
+        source, repository = reachable_repository!(sources)
+        return unless source
 
         ref = ref_param || repository["default_branch"]
         render json: {
-          repository: repository.merge("selected" => connection.repository(repository["full_name"]).present?),
-          preflight: ProjectPreflight.call(connection.client, repository: repository["full_name"], ref: ref)
+          repository: repository.merge("selected" => source.repository(repository["full_name"]).present?,
+            "source" => source.checkout_source),
+          preflight: ProjectPreflight.call(source.contents_client(repository), repository: repository["full_name"], ref: ref)
         }
       end
 
       # GET /api/projects/discover_secrets?repository=owner/name&ref=
       # The environment variables the repository expects (see
       # ProjectSecretDiscovery), each marked with whether the project named by
-      # `project_id`, if any, has it set. A repository the connection has not
+      # `project_id`, if any, has it set. A repository no GitHub source has
       # selected needs :manage_github, as for preflight.
       def discover_secrets
-        connection = github_connection! or return
-        repository = reachable_repository!(connection) or return
+        sources = github_sources! or return
+        source, repository = reachable_repository!(sources)
+        return unless source
 
-        discovery = ProjectSecretDiscovery.call(connection.client, repository: repository["full_name"],
+        discovery = ProjectSecretDiscovery.call(source.contents_client(repository), repository: repository["full_name"],
           ref: ref_param || repository["default_branch"])
         set = params[:project_id].present? ? owned(Project).find(params[:project_id]).secrets.pluck(:name).to_set : Set.new
         discovery[:variables].each { |variable| variable[:set] = set.include?(variable[:name]) }
@@ -87,8 +125,9 @@ module ActionAgent
       #
       # Refused while a blocking capability fails, when the host's quota
       # denies a :project, and for a repository the preflight does not
-      # support. Picking a repository the GitHub connection has not selected
-      # selects it, which needs :manage_github.
+      # support. Picking a repository no GitHub source has selected selects
+      # it on the source it was found through (a GitHub App installation
+      # ahead of the OAuth connection), which needs :manage_github.
       def create
         failures = capabilities_check.blocking_failures
         if failures.any?
@@ -97,11 +136,13 @@ module ActionAgent
         end
         return if quota_denied?
 
-        connection = github_connection! or return
-        repository = reachable_repository!(connection) or return
+        sources = github_sources! or return
+        source, repository = reachable_repository!(sources)
+        return unless source
         full_name = repository["full_name"]
         ref = ref_param
-        report = ProjectPreflight.call(connection.client, repository: full_name, ref: ref || repository["default_branch"])
+        report = ProjectPreflight.call(source.contents_client(repository), repository: full_name,
+          ref: ref || repository["default_branch"])
         if report["status"] == "unsupported"
           return render json: { error: report["summary"], code: "unsupported_repository", preflight: report },
             status: :unprocessable_entity
@@ -114,10 +155,10 @@ module ActionAgent
         return unless secret_sources_allowed!(secrets)
         return unless authorize_secrets!(project, secrets)
 
-        selecting = connection.repository(full_name).nil?
+        selecting = source.repository(full_name).nil?
         Project.transaction do
           # The selection is what a project's sandbox is booted from.
-          connection.update!(repositories: connection.repositories + [ repository ]) if selecting
+          source.update!(repositories: source.repositories + [ repository ]) if selecting
           project.save!
           secrets.each { |attributes| assign_secret_params(project, attributes).save! }
           project.ensure_app_assistant! unless project.engine_installed?
@@ -175,18 +216,20 @@ module ActionAgent
       # The current sandbox's boot, step by step (see
       # SandboxOrchestrator#boot_status), with the scrubbed tail of the step
       # that failed or is running, and the modes its browser can start in
-      # (none when the backend runs no browsers).
+      # (none when the backend runs no browsers). When the backend cannot
+      # report the boot, `boot` is null and `backend_error` names the backend
+      # and the reason (see #boot_report).
       def boot_status
         sandbox = @project.current_sandbox_session
         orchestrator = SandboxOrchestrator.new
-        status = sandbox && orchestrator.supports?(:boot_status) ? orchestrator.boot_status(sandbox) : nil
-        status = SecretScrubber.scrub(status.deep_symbolize_keys, @project.scrub_values) if status.is_a?(Hash)
+        status, log_tail, backend_error = boot_report(orchestrator, sandbox)
 
         render json: {
           project: @project.summary,
           boot: status,
-          log_tail: status && log_tail(orchestrator, sandbox, status),
+          log_tail: log_tail,
           error: sandbox&.failed? ? SecretScrubber.scrub(sandbox.error_summary, @project.scrub_values) : nil,
+          backend_error: backend_error,
           logs: sandbox.present? && orchestrator.supports?(:boot_log),
           confirmation: @project.local_boot_confirmation(orchestrator),
           browser_modes: browser_modes(orchestrator)
@@ -273,7 +316,7 @@ module ActionAgent
       def capabilities_check
         @capabilities_check ||= ProjectCapabilities.new(
           owner: current_owner,
-          github_connected: owned(GithubConnection).exists?,
+          github_connected: github_sources.any?,
           base_url: "#{request.base_url}#{request.script_name}"
         )
       end
@@ -296,45 +339,78 @@ module ActionAgent
         performed?
       end
 
-      def github_connection!
-        connection = owned(GithubConnection).first
-        return connection if connection
+      # Where the owner's repositories are reached through, in the order a
+      # repository is looked for in them: the usable GitHub App
+      # installations in the order they were linked, then the OAuth
+      # connection. It is the order SandboxSession#repository_available
+      # checks a project's repository out in, so a project is read through
+      # the source its sandbox will clone from. Installations count only
+      # while a GitHub App is configured, since nothing else can mint their
+      # tokens. Each source answers #repository, #repositories,
+      # #reachable_repositories, #find_repository and #contents_client.
+      def github_sources
+        @github_sources ||= begin
+          installations = ActionAgent.github_app_configured? ? owned(GithubInstallation).order(:id).select(&:usable?) : []
+          [ *installations, owned(GithubConnection).first ].compact
+        end
+      end
+
+      def github_sources!
+        sources = github_sources
+        return sources if sources.any?
 
-        render json: { error: "Connect GitHub in Settings → Integrations first", code: "github_not_connected" },
+        render json: { error: "Install the GitHub App or connect GitHub in Settings → Integrations first", code: "github_not_connected" },
           status: :unprocessable_entity
         nil
       end
 
-      # The repository +name+ names, as the connection reaches it: from its
-      # selection, else asked of GitHub by name. Renders a 403 for a
-      # repository outside the selection when the caller may not manage the
-      # GitHub connection, and a 404 when GitHub finds none it can reach.
+      def manages_github?(source)
+        ActionAgent.permitted?(current_user, :manage_github, source)
+      end
+
+      # [source, repository] for the repository +name+ names: from the first
+      # source that selected it, else asked of GitHub by name through each
+      # source the caller may manage, in #github_sources' order. Renders a
+      # 403 for a repository outside every selection when the caller may
+      # manage none of the sources, and a 404 when GitHub finds none they
+      # reach.
       #
       # The connection's token can be one member's, reaching that member's
-      # own repositories, so only the selection is shared with every member.
-      # The 403 is decided before GitHub is asked, so it says nothing about
-      # whether the repository exists.
-      def reachable_repository!(connection, name = params[:repository])
+      # own repositories, and an installation can reach repositories a
+      # member cannot see on GitHub, so only the selections are shared with
+      # every member. The 403 is decided before GitHub is asked, so it says
+      # nothing about whether the repository exists.
+      def reachable_repository!(sources, name = params[:repository])
         unless name.is_a?(String) && Project::REPOSITORY.match?(name)
           render json: { error: "repository must be owner/name" }, status: :bad_request
           return nil
         end
 
-        selected = connection.repository(name)
-        return selected if selected
+        sources.each do |source|
+          selected = source.repository(name)
+          return [ source, selected ] if selected
+        end
 
-        unless ActionAgent.permitted?(current_user, :manage_github, connection)
+        managed = sources.select { |source| manages_github?(source) }
+        if managed.empty?
           render json: { error: "#{name} is not one of the repositories selected in Settings → Integrations, and only " \
                                 "someone who may manage the GitHub connection can pick another",
                          code: "forbidden", permission: :manage_github }, status: :forbidden
           return nil
         end
 
-        repository = connection.client.repository(name)
-        return repository if repository
+        unavailable = []
+        managed.each do |source|
+          repository = source.find_repository(name)
+          return [ source, repository ] if repository
+        rescue GithubClient::InstallationUnavailable => e
+          unavailable << e
+        end
+        # Every source asked turned out removed or suspended.
+        raise unavailable.last if unavailable.size == managed.size
 
-        render json: { error: "GitHub found no repository #{name} that this connection can reach", code: "repository_not_found" },
-          status: :not_found
+        render json: { error: "GitHub found no repository #{name} that this dashboard's GitHub access can reach",
+                       code: "repository_not_found" }, status: :not_found
         nil
       end
 
@@ -350,9 +426,10 @@ module ActionAgent
         return nil if requested == @project.default_ref.to_s
         return nil unless authorize_secret_handover!(@project)
 
-        connection = github_connection! or return
-        repository = reachable_repository!(connection, @project.repository) or return
-        report = ProjectPreflight.call(connection.client, repository: @project.repository,
+        sources = github_sources! or return
+        source, repository = reachable_repository!(sources, @project.repository)
+        return unless source
+        report = ProjectPreflight.call(source.contents_client(repository), repository: @project.repository,
           ref: requested.presence || repository["default_branch"])
         if report["status"] == "unsupported"
           render json: { error: report["summary"], code: "unsupported_repository", preflight: report },
@@ -462,6 +539,27 @@ module ActionAgent
         []
       end
 
+      # The backend's account of the sandbox's boot, scrubbed, with the tail
+      # of the step's log that goes with it: [status, log_tail, nil]. When the
+      # backend cannot give one (no host configured, the host unreachable, a
+      # container that has not written its state yet), [nil, nil, error],
+      # where error names the backend and the scrubbed reason. The page then
+      # shows the boot as unknown for that reason and keeps following it,
+      # instead of failing to load the project (#650). The sandbox's own
+      # failure, if it failed, is reported beside it as `error`.
+      def boot_report(orchestrator, sandbox)
+        return [ nil, nil, nil ] unless sandbox && orchestrator.supports?(:boot_status)
+
+        status = orchestrator.boot_status(sandbox)
+        status = SecretScrubber.scrub(status.deep_symbolize_keys, @project.scrub_values) if status.is_a?(Hash)
+        [ status, status && log_tail(orchestrator, sandbox, status), nil ]
+      rescue StandardError => e
+        Rails.logger.warn("[ActionAgent] the #{orchestrator.backend_name} sandbox backend could not report the boot of " \
+          "sandbox #{sandbox.session_id}: #{e.class}: #{e.message}")
+        [ nil, nil, { backend: orchestrator.backend_name,
+                      message: SecretScrubber.scrub(e.message.to_s, @project.scrub_values).truncate(BACKEND_ERROR_BYTES) } ]
+      end
+
       # The last LOG_TAIL_BYTES of the step that failed, else of the one
       # running, else of the last that ran: { step:, text:, truncated: }.
       def log_tail(orchestrator, sandbox, status)
@@ -500,6 +598,12 @@ module ActionAgent
           status: :unprocessable_entity
       end
 
+      def installation_unavailable(exception)
+        state = exception.reason == :suspended ? "is suspended" : "was removed"
+        render json: { error: "The GitHub App installation #{state} on GitHub. Reinstall the GitHub App in Settings → Integrations.",
+                       code: "installation_unavailable", reinstall_required: true }, status: :unprocessable_entity
+      end
+
       def github_not_found(exception)
         render json: { error: exception.message, code: "not_found" }, status: :not_found
       end

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

@@ -211,18 +211,19 @@ module ActionAgent
       # GET /api/sandboxes/:session_id/boot
       # How a checkout's boot went, step by step (see
       # SandboxOrchestrator#boot_status). `boot` is null when the backend
-      # reports no steps, or holds nothing for the sandbox.
+      # reports no steps, or holds nothing for the sandbox; when the backend
+      # cannot report it at all, `backend_error` names the backend and the
+      # reason (see #boot_report).
       def boot
         orchestrator = SandboxOrchestrator.new
-        status = @sandbox.app_runtime? && orchestrator.supports?(:boot_status) ? orchestrator.boot_status(@sandbox) : nil
-        # A project's checkout booted with its secrets, which the backend may
-        # not know to mask.
-        status = SecretScrubber.scrub(status, @sandbox.project_scrub_values) if status
-        render json: {
+        status, backend_error = boot_report(orchestrator)
+        payload = {
           boot: status,
           resumable: !!(status&.dig(:kept) && @sandbox.failed? && !@sandbox.past_expiry? && orchestrator.supports?(:resume_boot)),
           logs: @sandbox.app_runtime? && orchestrator.supports?(:boot_log)
         }
+        payload[:backend_error] = backend_error if backend_error
+        render json: payload
       end
 
       # GET /api/sandboxes/:session_id/boot_log?step=NAME&offset=N&limit=N
@@ -298,6 +299,30 @@ module ActionAgent
 
       private
 
+      # The most of a backend's error the boot status carries (see #boot_report).
+      BACKEND_ERROR_BYTES = 1_000
+
+      # The backend's account of the sandbox's boot, scrubbed of its
+      # project's secrets (a project's checkout booted with them, which the
+      # backend may not know to mask): [status, nil]. When the backend cannot
+      # give one (no host configured, the host unreachable, a container that
+      # has not written its state yet), [nil, error], where error names the
+      # backend and the scrubbed reason, so the page reports it instead of
+      # failing on a 500 (#650; Api::ProjectsController#boot_report is the
+      # same for a project).
+      def boot_report(orchestrator)
+        return [ nil, nil ] unless @sandbox.app_runtime? && orchestrator.supports?(:boot_status)
+
+        status = orchestrator.boot_status(@sandbox)
+        status = SecretScrubber.scrub(status, @sandbox.project_scrub_values) if status
+        [ status, nil ]
+      rescue StandardError => e
+        Rails.logger.warn("[ActionAgent] the #{orchestrator.backend_name} sandbox backend could not report the boot of " \
+          "sandbox #{@sandbox.session_id}: #{e.class}: #{e.message}")
+        [ nil, { backend: orchestrator.backend_name,
+                 message: SecretScrubber.scrub(e.message.to_s, @sandbox.project_scrub_values).truncate(BACKEND_ERROR_BYTES) } ]
+      end
+
       def set_sandbox
         @sandbox = account_scoped(owned(SandboxSession)).find_by!(session_id: params[:id])
       end

data/app/controllers/action_agent/dashboard_controller.rb

@@ -24,8 +24,34 @@ module ActionAgent
       render "action_agent/dashboard/index", locals: { props: props }
     end
 
+    # A shareable link to an evaluation, one of its runs, or one scenario
+    # result of that run (/evaluations/:id/runs/:run_id/results/:result_id).
+    # The page is the dashboard either way; what the link names is checked
+    # against the caller's agents, the scope the evaluations API reads, so a
+    # member of the owning account opens it and anyone else gets a 404 —
+    # the same answer a link to nothing gets, so it says nothing about what
+    # another account has. The dashboard still renders, and its own request
+    # for the evaluation reports it unavailable. A telemetry-only install,
+    # with no evaluations table, has nothing to link to either.
+    def evaluation
+      linked_evaluation_records
+      index
+    rescue ActiveRecord::RecordNotFound, ActiveRecord::StatementInvalid
+      render "action_agent/dashboard/index", locals: { props: props }, status: :not_found
+    end
+
     private
 
+    # Raises RecordNotFound unless the evaluation is the caller's, the run
+    # is one of its runs and the result one of that run's results.
+    def linked_evaluation_records
+      evaluation = Evaluation.joins(:agent).where(agent: owner_agents).find(params[:evaluation_id])
+      return unless params[:run_id]
+
+      run = evaluation.evaluation_runs.find(params[:run_id])
+      run.scenario_results.find(params[:result_id]) if params[:result_id]
+    end
+
     def props
       {
         user: current_user_props,