actionagent 1.9.3 → 1.9.5

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

@@ -37,8 +37,8 @@ module ActionAgent
 
       NAMES = %w[
         evaluations_list evaluations_get evaluations_create scenarios_merge explorations_submit evaluations_run
-        evaluation_runs_get evaluation_runs_compare traces_search traces_get input_requests_list input_requests_answer
-        catalogs_list catalogs_import catalog_set_run
+        evaluation_runs_get evaluation_runs_compare traces_search traces_get traces_export input_requests_list
+        input_requests_answer catalogs_list catalogs_import catalogs_preview catalogs_export catalog_set_run agents_versions
       ].freeze
 
       # The kinds input_requests_answer answers. An approval and a secret are
@@ -320,6 +320,17 @@ module ActionAgent
             required: [ "trace_id" ]
           }
         },
+        {
+          name: "traces_export",
+          description: "One trace, whole, as the payload POST <mount>/api/traces ingests ({ traces: [trace], sdk }): " \
+                       "its spans untruncated, with the owner's credentials masked, so the trace can be sent to another " \
+                       "dashboard with that dashboard's ingest key. Read one to work with it instead: traces_get.",
+          inputSchema: {
+            type: "object",
+            properties: { trace_id: { type: "string", description: "The trace's id, its OpenTelemetry trace id, or that id's first 8 characters" } },
+            required: [ "trace_id" ]
+          }
+        },
         {
           name: "input_requests_list",
           description: "List the requests for input this key's paused agent runs are waiting on, newest first: each " \
@@ -364,11 +375,50 @@ module ActionAgent
             type: "object",
             properties: {
               document: { type: "string", description: "The catalog as YAML" },
-              name: { type: "string", description: "The catalog key when the document sets no `catalog:`" }
+              name: { type: "string", description: "The catalog key when the document sets no `catalog:`" },
+              mode: {
+                type: "string", enum: ScenarioCatalogImport::MODES,
+                description: "replace (the default) makes the catalog the document; merge keeps what the document leaves out"
+              }
+            },
+            required: [ "document" ]
+          }
+        },
+        {
+          name: "catalogs_preview",
+          description: "What catalogs_import of this document would change, without writing anything: whether the " \
+                       "catalog would be created, updated or left unchanged, how many products, sets and scenarios " \
+                       "would be created, updated, removed (or kept, in merge mode), and the first " \
+                       "#{ScenarioCatalogImport::PREVIEW_LIMIT} changes by path.",
+          inputSchema: {
+            type: "object",
+            properties: {
+              document: { type: "string", description: "The catalog as YAML" },
+              name: { type: "string", description: "The catalog key when the document sets no `catalog:`" },
+              mode: {
+                type: "string", enum: ScenarioCatalogImport::MODES,
+                description: "replace (the default) makes the catalog the document; merge keeps what the document leaves out"
+              }
             },
             required: [ "document" ]
           }
         },
+        {
+          name: "catalogs_export",
+          description: "A catalog's canonical document from its records, as YAML (the default) or JSON: the whole " \
+                       "catalog, or one product or one set of it, as a document of the catalog's key that a merge " \
+                       "import reads back. The same document the dashboard's Export YAML downloads.",
+          inputSchema: {
+            type: "object",
+            properties: {
+              catalog: { type: "string", description: "The catalog's key" },
+              product: { type: "string", description: "Only this product, by key" },
+              set: { type: "string", description: "Only this set of the product, by key" },
+              format: { type: "string", enum: %w[yaml json], description: "yaml (the default) or json" }
+            },
+            required: [ "catalog" ]
+          }
+        },
         {
           name: "catalog_set_run",
           description: "Run one set of a catalog as an evaluation of the agent under test: the product's agent, the " \
@@ -388,6 +438,20 @@ module ActionAgent
             },
             required: %w[catalog product set]
           }
+        },
+        {
+          name: "agents_versions",
+          description: "An agent's versions, newest first: each with its number, what it changed from the version " \
+                       "before (diff), who made it, whether it is the agent's current version, and whether it was cut " \
+                       "from the agent's code on deploy (release) rather than edited on the dashboard.",
+          inputSchema: {
+            type: "object",
+            properties: {
+              agent: { type: "string", description: "The agent's slug or id" },
+              limit: { type: "integer", description: "At most this many (default #{LIST_LIMIT}, max #{MAX_LIST_LIMIT})" }
+            },
+            required: [ "agent" ]
+          }
         }
       ].freeze
 
@@ -426,11 +490,15 @@ module ActionAgent
         when "evaluation_runs_compare" then evaluation_runs_compare_tool
         when "traces_search" then traces_search_tool
         when "traces_get" then traces_get_tool
+        when "traces_export" then traces_export_tool
         when "input_requests_list" then input_requests_list_tool
         when "input_requests_answer" then input_requests_answer_tool
         when "catalogs_list" then catalogs_list_tool
         when "catalogs_import" then catalogs_import_tool
+        when "catalogs_preview" then catalogs_preview_tool
+        when "catalogs_export" then catalogs_export_tool
         when "catalog_set_run" then catalog_set_run_tool
+        when "agents_versions" then agents_versions_tool
         end
       end
 
@@ -821,18 +889,8 @@ module ActionAgent
         }
       end
 
-      # Looked up as Api::TraceReportsController#show looks a trace up: the
-      # OpenTelemetry trace id, then a prefix of it, then the record id.
       def traces_get_tool
-        id = tool_argument(:trace_id).to_s
-        raise MCPController::McpError.new("Missing required argument: trace_id", MCPController::JSONRPC_INVALID_PARAMS) if id.blank?
-
-        scope = owned_traces
-        trace = scope.find_by(trace_id: id) ||
-          scope.where("trace_id LIKE ?", "#{ActionAgent.trace_model.sanitize_sql_like(id)}%").first ||
-          (id.match?(/\A\d+\z/) && scope.find_by(id: id)) or
-          raise ToolError, "No trace #{id.truncate(64)} was found"
-
+        trace = find_tool_trace!
         detail = TelemetryTraceSerializer.detail(trace)
         spans = detail.delete(:spans)
         failed_spans = spans.select { |span| span[:error] }.map do |span|
@@ -849,6 +907,43 @@ module ActionAgent
         PayloadBounds.bound(payload, max_string: MAX_STRING, max_items: MAX_TRACE_SPANS)
       end
 
+      # The trace as Api::TracesController#create takes it, whole: the
+      # stored trace's spans and resource attributes with the SDK that
+      # reported it, so a POST of the result to another install's
+      # <mount>/api/traces stores the same trace there (an install skips a
+      # trace_id it already holds). Not bounded as traces_get bounds a trace,
+      # since the point is a copy; the owner's credentials are masked from
+      # it as from every tool's result.
+      def traces_export_tool
+        trace = find_tool_trace!
+
+        {
+          traces: [ {
+            trace_id: trace.trace_id,
+            service_name: trace.service_name,
+            environment: trace.environment,
+            timestamp: trace.timestamp&.iso8601(6),
+            resource_attributes: trace.resource_attributes.presence || {},
+            spans: Array(trace.spans)
+          } ],
+          sdk: trace.sdk_info.presence || {}
+        }
+      end
+
+      # The trace `trace_id` names, looked up as Api::TraceReportsController#show
+      # looks a trace up: the OpenTelemetry trace id, then a prefix of it,
+      # then the record id.
+      def find_tool_trace!
+        id = tool_argument(:trace_id).to_s
+        raise MCPController::McpError.new("Missing required argument: trace_id", MCPController::JSONRPC_INVALID_PARAMS) if id.blank?
+
+        scope = owned_traces
+        scope.find_by(trace_id: id) ||
+          scope.where("trace_id LIKE ?", "#{ActionAgent.trace_model.sanitize_sql_like(id)}%").first ||
+          (id.match?(/\A\d+\z/) && scope.find_by(id: id)) or
+          raise ToolError, "No trace #{id.truncate(64)} was found"
+      end
+
       def input_requests_list_tool
         InputRequest.expire_overdue!(owner_input_requests)
         scope = owner_input_requests.pending.for_listing.includes(:subject).recent
@@ -948,19 +1043,16 @@ module ActionAgent
       end
 
       # Imports a catalog document as POST /api/scenario_catalogs does: the
-      # owner's agents and projects resolve the products' targets.
+      # owner's agents and projects resolve the products' targets, and `mode`
+      # is replace (the default) or merge, as there.
       def catalogs_import_tool
-        document = required_tool_argument!(:document).to_s
-        raise ToolError, "document is larger than #{ScenarioCatalog::MAX_BYTES} bytes" if document.bytesize > ScenarioCatalog::MAX_BYTES
-
+        document = catalog_document_argument!
         authorize_catalog_write!(ScenarioCatalog.new)
-        catalog = ScenarioCatalogImport.new(
-          owner: current_owner, document: document, name: tool_argument(:name).to_s.presence,
-          source_kind: "api", agents: owner_agents, projects: owned(Project)
-        ).call
+        catalog = catalog_import(document).call
 
         {
           catalog: ScenarioCatalogSerializer.summary(catalog),
+          mode: catalog_mode_argument,
           products: catalog.products.map do |product|
             { key: product.key, agent: product.agent&.name, project_id: product.project_id,
               sets: product.sets.map { |set| { key: set.key, scenario_count: set.scenarios.size } } }
@@ -970,12 +1062,95 @@ module ActionAgent
         raise ToolError, e.message
       end
 
+      # What catalogs_import of the document would change, as POST
+      # /api/scenario_catalogs/preview answers it, writing nothing.
+      def catalogs_preview_tool
+        catalog_import(catalog_document_argument!).preview
+      rescue ScenarioCatalogImport::Invalid => e
+        raise ToolError, e.message
+      end
+
+      # The catalog's canonical document from its records, as GET
+      # /api/scenario_catalogs/:id/export serves it, whole or narrowed to one
+      # product or one set.
+      def catalogs_export_tool
+        catalog = find_tool_catalog!
+        format = tool_argument(:format).to_s.presence || "yaml"
+        raise ToolError, "format is yaml or json" unless %w[yaml json].include?(format)
+
+        selection = {}
+        product = set = nil
+        if (product_key = tool_argument(:product).to_s.presence)
+          product = catalog.products.find_by(key: product_key) ||
+            raise(ToolError, "No product #{product_key.inspect} in catalog #{catalog.key}")
+          if (set_key = tool_argument(:set).to_s.presence)
+            set = product.sets.find_by(key: set_key) || raise(ToolError, "No set #{set_key.inspect} in product #{product.key}")
+            selection[:set_ids] = [ set.id ]
+          else
+            selection[:product_ids] = [ product.id ]
+          end
+        elsif tool_argument(:set).present?
+          raise ToolError, "set names a set of a product: give product too"
+        end
+
+        exported = catalog.export_catalog(**selection)
+        {
+          catalog: { id: catalog.id, key: catalog.key, name: catalog.name, digest: catalog.digest },
+          product: product&.key,
+          set: set&.key,
+          format: format,
+          digest: exported.digest,
+          document: format == "json" ? JSON.pretty_generate(exported.to_h) : exported.to_yaml
+        }
+      end
+
+      def catalog_import(document)
+        ScenarioCatalogImport.new(
+          owner: current_owner, document: document, name: tool_argument(:name).to_s.presence,
+          source_kind: "api", agents: owner_agents, projects: owned(Project), mode: catalog_mode_argument
+        )
+      end
+
+      def catalog_document_argument!
+        document = required_tool_argument!(:document).to_s
+        raise ToolError, "document is larger than #{ScenarioCatalog::MAX_BYTES} bytes" if document.bytesize > ScenarioCatalog::MAX_BYTES
+
+        document
+      end
+
+      # replace unless the call says merge; ScenarioCatalogImport refuses
+      # anything else.
+      def catalog_mode_argument
+        tool_argument(:mode).to_s.presence || "replace"
+      end
+
+      # The owner's catalog `catalog` names by key.
+      def find_tool_catalog!
+        key = required_tool_argument!(:catalog).to_s
+        owned(ScenarioCatalog).find_by(key: key) || raise(ToolError, "No catalog #{key.inspect}; catalogs_list names them")
+      end
+
+      # An agent's versions as GET /api/agents/:id/versions lists them, each
+      # with its diff from the version before, newest first.
+      def agents_versions_tool
+        agent = resolve_tool_agent!(required_tool_argument!(:agent))
+        limit = integer_argument(:limit, default: LIST_LIMIT, min: 1, max: MAX_LIST_LIMIT)
+        versions = agent.agent_versions.recent.limit(limit + 1).to_a
+
+        {
+          agent: { id: agent.id, slug: agent.slug, name: agent.name, version_count: agent.agent_versions.count },
+          versions: versions.first(limit).map do |version|
+            PayloadBounds.bound(AgentVersionSerializer.call(version, include_diff: true), max_string: MAX_STRING)
+          end,
+          truncated: versions.size > limit
+        }
+      end
+
       # Runs one set as POST /api/scenario_catalogs/:id/sets/:set_id/run
       # does, gated as evaluations_run is. A project's sandbox must already
       # be running: booting one is a dashboard action, not a tool's.
       def catalog_set_run_tool
-        catalog = owned(ScenarioCatalog).find_by(key: required_tool_argument!(:catalog).to_s) ||
-          raise(ToolError, "No catalog #{tool_argument(:catalog).inspect}; catalogs_list names them")
+        catalog = find_tool_catalog!
         product = catalog.products.find_by(key: required_tool_argument!(:product).to_s) ||
           raise(ToolError, "No product #{tool_argument(:product).inspect} in catalog #{catalog.key}")
         set = product.sets.find_by(key: required_tool_argument!(:set).to_s) ||

data/app/jobs/action_agent/github_webhook_job.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+module ActionAgent
+  # Applies a GitHub App webhook delivery that Api::GithubAppWebhooksController
+  # verified and recorded, so Settings -> Integrations learns of a change on
+  # GitHub when it happens rather than when a token mint is next refused.
+  #
+  # +payload+ is the slice of the delivery GithubWebhookJob.payload_for keeps.
+  # A delivery about an installation no owner linked changes nothing, and so
+  # does an event or action not handled here.
+  #
+  # Each handler sets state from the payload rather than toggling it, so
+  # running one twice leaves the same result; the delivery record is what
+  # keeps an old delivery from being replayed over a newer one.
+  class GithubWebhookJob < ApplicationJob
+    queue_as :default
+
+    EVENTS = %w[installation installation_repositories github_app_authorization].freeze
+
+    # What the job needs from a delivery's +payload+, so the job's arguments
+    # carry neither the sender's profile nor every repository's details.
+    def self.payload_for(event, payload)
+      installation = payload["installation"].is_a?(Hash) ? payload["installation"] : {}
+      repositories = ->(key) { Array(payload[key]).filter_map { |repo| repo.slice("id", "full_name") if repo.is_a?(Hash) } }
+      sender = payload["sender"].is_a?(Hash) ? payload["sender"] : {}
+
+      {
+        "action" => payload["action"].to_s,
+        "installation" => installation.slice("id", "permissions", "repository_selection", "suspended_at"),
+        "repositories_added" => event == "installation_repositories" ? repositories.call("repositories_added") : [],
+        "repositories_removed" => event == "installation_repositories" ? repositories.call("repositories_removed") : [],
+        "sender_id" => sender["id"]
+      }
+    end
+
+    def perform(event, payload)
+      case event
+      when "installation" then installation(payload)
+      when "installation_repositories" then installation_repositories(payload)
+      when "github_app_authorization" then authorization(payload)
+      end
+    end
+
+    private
+
+    def installation(payload)
+      record = linked_installation(payload) or return
+      reported = payload["installation"]
+
+      case payload["action"]
+      when "deleted"
+        record.update!(removed_at: Time.current) if record.removed_at.nil?
+      when "suspend"
+        record.update!(suspended_at: parse_time(reported["suspended_at"]) || Time.current)
+      when "unsuspend"
+        record.update!(suspended_at: nil)
+      when "new_permissions_accepted"
+        record.update!(permissions: reported["permissions"]) if reported["permissions"].is_a?(Hash)
+      end
+    end
+
+    # The repository picker lists what the installation reaches from GitHub
+    # each time it opens, so an added repository needs nothing stored; a
+    # removed one leaves the owner's selection, which is what a checkout
+    # trusts.
+    def installation_repositories(payload)
+      record = linked_installation(payload) or return
+      return unless payload["action"].in?(%w[added removed])
+
+      removed = payload["repositories_removed"].map { |repo| repo["id"].to_i }.to_set
+      attributes = { repositories: record.repositories.reject { |repo| removed.include?(repo["id"].to_i) } }
+      selection = payload.dig("installation", "repository_selection")
+      attributes[:repository_selection] = selection if selection.present?
+      record.update!(attributes)
+    end
+
+    # GitHub revoked the user's authorization of the App. The App's own user
+    # tokens are never stored (see Api::GithubInstallationsController), so
+    # this reaches a stored GithubConnection only when the OAuth connection
+    # flow authorizes through this same App (github_client_id is the App's
+    # client id). A connection made through a separate OAuth App is a grant
+    # this revocation does not touch.
+    def authorization(payload)
+      return unless payload["action"] == "revoked"
+      return if payload["sender_id"].blank?
+      return unless ActionAgent.github_client_id.present? && ActionAgent.github_client_id == ActionAgent.github_app_client_id
+
+      GithubConnection.where(github_user_id: payload["sender_id"].to_i).destroy_all
+    end
+
+    def linked_installation(payload)
+      id = payload.dig("installation", "id")
+      GithubInstallation.find_by(installation_id: id.to_i) if id.present?
+    end
+
+    def parse_time(value)
+      Time.iso8601(value) if value.is_a?(String)
+    rescue ArgumentError
+      nil
+    end
+  end
+end

data/app/models/action_agent/github_connection.rb

@@ -38,6 +38,27 @@ module ActionAgent
       GithubClient.new(access_token)
     end
 
+    # Every repository the token reaches, whether selected or not. The same
+    # three methods are on GithubInstallation, so a project reaches a
+    # repository through either.
+    def reachable_repositories
+      client.repositories
+    end
+
+    # The repository +full_name+ names, as the token reaches it, or nil.
+    def find_repository(full_name)
+      client.repository(full_name)
+    end
+
+    # A client that reads +repo+'s files: the connection's own token.
+    def contents_client(_repo)
+      client
+    end
+
+    def checkout_source
+      "oauth"
+    end
+
     # The checkout a sandbox backend clones: repository, ref, and an
     # authenticated HTTPS clone URL. Carries the token — hand it to a backend,
     # never to a response.

data/app/models/action_agent/github_installation.rb

@@ -49,7 +49,8 @@ module ActionAgent
 
     # Whether GitHub will still mint tokens for this installation, as far as
     # the dashboard last heard: false once a mint found it removed or
-    # suspended, until a later mint succeeds or it is linked again.
+    # suspended, or a webhook delivery reported it (GithubWebhookJob), until
+    # a later mint succeeds, an unsuspend is delivered, or it is linked again.
     def usable?
       removed_at.nil? && suspended_at.nil?
     end
@@ -102,6 +103,32 @@ module ActionAgent
       GithubClient.new(mint_token!(permissions: LISTING_PERMISSIONS))
     end
 
+    # The repositories GitHub lists for the installation, whether selected
+    # or not (GithubClient#repositories' shape). Mints a listing token.
+    def reachable_repositories
+      listing_client.installation_repositories
+    end
+
+    # The repository +full_name+ names, as the installation reaches it, or
+    # nil when it reaches none: asked of GitHub by name, so it also finds one
+    # the owner has not selected. Mints a listing token.
+    def find_repository(full_name)
+      listing_client.repository(full_name)
+    end
+
+    # A client that reads the files of the one repository +repo+ (a
+    # repository row with an "id"), with a freshly minted token limited to
+    # its contents, for a project's preflight and secret discovery. The
+    # token is held by the client only.
+    def contents_client(repo)
+      GithubClient.new(mint_token!(permissions: CHECKOUT_PERMISSIONS, repository_ids: [ repo["id"] ]))
+    end
+
+    # How a project or sandbox says where its repository is reached through.
+    def checkout_source
+      "app"
+    end
+
     # Records what GitHub reported about the installation when it was linked.
     def assign_from_github(installation)
       account = installation["account"] || {}

data/app/models/action_agent/github_webhook_delivery.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module ActionAgent
+  # A GitHub App webhook delivery the dashboard accepted, by its
+  # X-GitHub-Delivery id. Api::GithubAppWebhooksController records one before
+  # it enqueues the delivery's GithubWebhookJob, so a redelivery of the same
+  # id (from GitHub's retry or its Redeliver button) finds it and is a no-op:
+  # a replayed +suspend+ cannot undo a later +unsuspend+.
+  #
+  # A row instead of Rails.cache: the unique index makes the check and the
+  # record one atomic insert across every web process, whatever cache store
+  # the host runs. Rows hold no payload and are pruned after RETENTION, a
+  # little longer than GitHub keeps a delivery redeliverable.
+  #
+  # Not owned: a delivery is about an installation, whichever owner (if any)
+  # linked it.
+  class GithubWebhookDelivery < ApplicationRecord
+    RETENTION = 7.days
+
+    validates :delivery_id, :event, presence: true
+
+    # Records the delivery, and answers whether it is the first time this id
+    # was seen. Rows older than RETENTION are pruned on the way.
+    #
+    # @return [Boolean] false for a redelivery
+    def self.record!(delivery_id:, event:, event_action: nil, installation_id: nil)
+      where(created_at: ...RETENTION.ago).delete_all
+
+      # A savepoint, so a duplicate inside a caller's transaction does not
+      # abort it on PostgreSQL.
+      transaction(requires_new: true) do
+        create!(delivery_id: delivery_id, event: event, event_action: event_action, installation_id: installation_id)
+      end
+      true
+    rescue ActiveRecord::RecordNotUnique
+      false
+    end
+
+    # Forgets the delivery, so GitHub's redelivery of it is processed. For a
+    # delivery that was recorded but could not be enqueued.
+    def self.forget!(delivery_id)
+      where(delivery_id: delivery_id).delete_all
+    end
+  end
+end

data/app/models/action_agent/provider_key.rb

@@ -261,7 +261,14 @@ module ActionAgent
       # +owner+ itself — unwrapped from a SimpleDelegator-style decorator —
       # once it is known to be an instance of the owner model.
       def owner_record(owner)
-        owner = owner.__getobj__ while defined?(::Delegator) && owner.is_a?(::Delegator)
+        # Not `... while defined?(::Delegator) && ...`: Prism (Ruby 3.4 and
+        # 4.0) miscompiles `defined?` inside a `while` modifier's condition
+        # when the source arrives as a string, which is how bootsnap 1.24.6+
+        # compiles files on those Rubies, and the whole engine then fails to
+        # boot with "argument stack underflow".
+        if defined?(::Delegator)
+          owner = owner.__getobj__ while owner.is_a?(::Delegator)
+        end
         association = owner_association
         return owner if owner.nil? || association.nil?
 

data/app/models/action_agent/scenario_catalog.rb

@@ -69,10 +69,16 @@ module ActionAgent
     # that hold them), as a document of this catalog's key that a merge
     # import (ScenarioCatalogImport mode "merge") reads back into it.
     def export_yaml(product_ids: nil, set_ids: nil, scenario_ids: nil)
+      export_catalog(product_ids: product_ids, set_ids: set_ids, scenario_ids: scenario_ids).to_yaml
+    end
+
+    # The records as an ActiveAgent::Evals::Catalog, whole or narrowed as
+    # #export_yaml narrows it, for the YAML or the JSON of the document.
+    def export_catalog(product_ids: nil, set_ids: nil, scenario_ids: nil)
       selection = { product_ids: ids(product_ids), set_ids: ids(set_ids), scenario_ids: ids(scenario_ids) }
-      return to_catalog.to_yaml if selection.values.all?(&:nil?)
+      return to_catalog if selection.values.all?(&:nil?)
 
-      ActiveAgent::Evals::Catalog.new([ to_document(**selection) ], name: key).to_yaml
+      ActiveAgent::Evals::Catalog.new([ to_document(**selection) ], name: key)
     end
 
     # A key for a new product, set or scenario: +text+ as a key, made unique

data/app/serializers/action_agent/agent_version_serializer.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module ActionAgent
+  # JSON for one of an agent's versions: what GET /api/agents/:id/versions
+  # lists and the MCP facade's agents_versions returns.
+  module AgentVersionSerializer
+    module_function
+
+    # +include_diff+ adds `diff`, what the version changed from the one
+    # before it ({ key => { from:, to: } }), when there is one.
+    def call(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 && (previous = version.previous)
+        json[:diff] = version.diff(previous)
+      end
+      json
+    end
+  end
+end

data/app/serializers/action_agent/evaluation_serializer.rb

@@ -86,6 +86,7 @@ module ActionAgent
       {
         id: run.id,
         number: number,
+        run_id: export_run_id(run),
         status: run.status,
         average_score: average_score(run),
         samples_evaluated: run.samples_evaluated,
@@ -98,6 +99,14 @@ module ActionAgent
       }
     end
 
+    # The run_id the run exports under (EvaluationReportExport.run_id_for),
+    # the handle `GET <mount>/api/evaluation_reports/:run_id` and the CLI's
+    # `evals report` take; nil on an install whose runs predate the report
+    # identity migration.
+    def export_run_id(run)
+      EvaluationRun.column_names.include?("external_run_id") ? EvaluationReportExport.run_id_for(run) : nil
+    end
+
     # Returns up to +limit+ of the evaluation's runs, newest first. Sorts the
     # preloaded association when one was loaded rather than issuing one
     # ORDER BY query per evaluation.