actionagent 1.6.0 → 1.6.3

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

@@ -33,8 +33,8 @@ module ActionAgent
         scope = scope.where(agent_id: params[:agent_id]) if params[:agent_id].present?
         scope = scope.where(status: params[:status]) if params[:status].present?
 
-        page = (params[:page] || 1).to_i
-        per_page = (params[:per_page] || 20).to_i
+        page = integer_param(:page, default: 1)
+        per_page = integer_param(:per_page, default: 20)
         total = scope.count
         runs = scope.offset((page - 1) * per_page).limit(per_page)
 

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

@@ -132,9 +132,9 @@ module ActionAgent
       # observed from telemetry have no AgentRun rows at all, so a runs-only
       # list showed them as empty while their scorecard reported real traffic.
       def runs
-        minutes = params[:minutes].presence&.then { |m| m.to_i.clamp(1, 60 * 24 * 90) }
-        page = (params[:page] || 1).to_i
-        per_page = (params[:per_page] || 20).to_i
+        minutes = integer_param(:minutes)&.clamp(1, 60 * 24 * 90)
+        page = integer_param(:page, default: 1)
+        per_page = integer_param(:per_page, default: 20)
 
         executions = AgentExecutions.new(
           agents: [ @agent ],
@@ -282,7 +282,7 @@ module ActionAgent
       # with all-zero metrics beside a card and a runs list reporting real
       # traffic.
       def analytics
-        days = (params[:days] || 30).to_i
+        days = integer_param(:days, default: 30)
         start_date = days.days.ago.beginning_of_day
 
         runs = @agent.agent_runs.where("created_at >= ?", start_date)
@@ -532,7 +532,10 @@ module ActionAgent
           change_summary: version.change_summary,
           created_by: version.created_by,
           created_at: version.created_at,
-          is_latest: version.latest?
+          is_latest: version.latest?,
+          release: version.release?,
+          release_digest: version.release_digest,
+          revision: version.revision
         }
 
         if include_diff && version.previous

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

@@ -5,7 +5,7 @@ module ActionAgent
     class AnalyticsController < BaseController
       # GET /api/analytics
       def index
-        days = (params[:days] || 30).to_i
+        days = integer_param(:days, default: 30)
         start_date = days.days.ago.beginning_of_day
 
         # Table names are interpolated rather than written literally: the

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

@@ -129,6 +129,26 @@ module ActionAgent
         render json: { error: "Agent execution is disabled on this dashboard" }, status: :forbidden
       end
 
+      # An integer query param. A value can arrive as a container
+      # (`minutes[]=1&minutes[]=2`, or `page[x]=1`), and neither Array nor
+      # ActionController::Parameters responds to `to_i`: reading them
+      # directly raised NoMethodError and turned a malformed query into a
+      # 500. A multi-valued param means its first value; anything else that
+      # is not a scalar falls back to the default.
+      def integer_param(name, default: nil)
+        raw = params[name]
+        raw = raw.first if raw.is_a?(Array)
+        return default if raw.blank? || !(raw.is_a?(String) || raw.is_a?(Numeric))
+
+        raw.to_s.to_i
+      end
+
+      # integer_param, then clamped into [min, max]. Non-numeric input becomes
+      # 0 and is then clamped up to `min`.
+      def clamped_param(name, default:, min:, max:)
+        integer_param(name, default: default).clamp(min, max)
+      end
+
       def not_found
         render json: { error: "Record not found" }, status: :not_found
       end

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

@@ -16,7 +16,7 @@ module ActionAgent
 
       # GET /api/interactions
       def index
-        limit = params.fetch(:limit, DEFAULT_LIMIT).to_i.clamp(1, 200)
+        limit = clamped_param(:limit, default: DEFAULT_LIMIT, min: 1, max: 200)
 
         contexts = interactions_scope
           .includes(:contextable)
@@ -140,8 +140,8 @@ module ActionAgent
       def window_minutes
         return @window_minutes if defined?(@window_minutes)
 
-        raw = params[:minutes].presence
-        @window_minutes = raw ? raw.to_i.clamp(1, MAX_WINDOW_MINUTES) : nil
+        raw = integer_param(:minutes)
+        @window_minutes = raw ? raw.clamp(1, MAX_WINDOW_MINUTES) : nil
       end
 
       def interactions_scope

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

@@ -18,11 +18,16 @@ module ActionAgent
       # POST /api/sandboxes/compare
       # Run multiple providers in a single sandbox using parallel generation jobs
       def compare
-        providers = params[:providers] || %w[anthropic openai ollama]
+        providers = params[:providers].nil? ? %w[anthropic openai ollama] : params[:providers]
         task = params[:task]
         sandbox_id = params[:sandbox_id]
 
         return render json: { error: "Task required" }, status: :bad_request unless task.present?
+        # A bare string or a nested object is a malformed request, not a list
+        # of one provider: reading it as a list raised NoMethodError.
+        unless providers.is_a?(Array) && providers.all? { |name| name.is_a?(String) }
+          return render json: { error: "providers must be a list of provider names" }, status: :bad_request
+        end
         return render json: { error: "At least 2 providers required" }, status: :bad_request if providers.size < 2
 
         # Validate providers

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

@@ -13,6 +13,12 @@ module ActionAgent
 
       before_action :set_recording, only: [ :show, :actions, :snapshot, :export, :handoff ]
 
+      # Browser state that must never leave the server in a read response:
+      # the handoff state a recording carries is a copy of the visitor's
+      # cookies and web storage. Only #handoff returns it, to the owner, when
+      # they continue the session.
+      SENSITIVE_STATE_KEYS = %w[cookies session_storage local_storage].freeze
+
       # GET /api/session_recordings
       # List recordings with optional filters
       def index
@@ -36,8 +42,8 @@ module ActionAgent
         end
 
         # Pagination
-        page = (params[:page] || 1).to_i
-        per_page = [ (params[:per_page] || 20).to_i, 100 ].min
+        page = integer_param(:page, default: 1)
+        per_page = [ integer_param(:per_page, default: 20), 100 ].min
         offset = (page - 1) * per_page
 
         total = recordings.count
@@ -79,10 +85,10 @@ module ActionAgent
 
         # Support pagination for large recordings
         if params[:after_sequence].present?
-          actions = actions.where("sequence > ?", params[:after_sequence].to_i)
+          actions = actions.where("sequence > ?", integer_param(:after_sequence, default: 0))
         end
 
-        limit = [ params[:limit]&.to_i || 100, 500 ].min
+        limit = [ integer_param(:limit, default: 100), 500 ].min
         actions = actions.limit(limit)
 
         render json: {
@@ -332,7 +338,7 @@ module ActionAgent
           created_at: recording.created_at.iso8601,
           updated_at: recording.updated_at.iso8601,
           timeline: recording.timeline,
-          handoff_state: recording.metadata["handoff_state"],
+          handoff_state: safe_handoff_state(recording.metadata["handoff_state"]),
           agent: recording.agent_run&.agent&.slice(:id, :name),
           sandbox_session: recording.sandbox_session&.summary
         }
@@ -343,9 +349,20 @@ module ActionAgent
         action&.screenshot_url(expires_in: 1.hour)
       end
 
+      # Strips the browser state at the top level and inside handoff_state,
+      # which the model stores nested (a recording's metadata carries the
+      # handoff as one key), so a show response never ships a session cookie.
       def safe_metadata(metadata)
-        # Remove sensitive data from metadata
-        metadata.except("cookies", "session_storage", "local_storage")
+        safe = (metadata || {}).except(*SENSITIVE_STATE_KEYS)
+        return safe unless safe["handoff_state"].is_a?(Hash)
+
+        safe.merge("handoff_state" => safe_handoff_state(safe["handoff_state"]))
+      end
+
+      def safe_handoff_state(handoff_state)
+        return handoff_state unless handoff_state.is_a?(Hash)
+
+        handoff_state.except(*SENSITIVE_STATE_KEYS)
       end
 
       def generate_visitor_id

data/app/models/action_agent/agent.rb

@@ -11,6 +11,14 @@ module ActionAgent
     has_many :agent_runs, dependent: :destroy
     has_many :evaluations, dependent: :destroy
     has_many :agent_memories, as: :memorable, dependent: :destroy
+    # Generations hang off AgentContext polymorphically, which is an
+    # implementation detail of how contexts are modelled — so without these a
+    # host that wants an agent's recorded history writes that join itself and is
+    # coupled to the shape. Deliberately no `dependent:` on the contexts: the
+    # association is added to read them, and destroying an agent has never taken
+    # its conversations with it. Making it do so is a separate call.
+    has_many :agent_contexts, as: :contextable
+    has_many :generations, through: :agent_contexts
 
     # Polymorphic rows (agent_memories, agent_contexts) store this string.
     # A host app that grew these tables under its own Agent constant keeps
@@ -219,6 +227,46 @@ module ActionAgent
       agent_versions.order(version_number: :desc).first
     end
 
+    # The most recent version cut from the agent's code, if any.
+    # @return [AgentVersion, nil]
+    def latest_release
+      agent_versions.releases.order(version_number: :desc).first
+    end
+
+    # Cuts a version for a release of the agent's code, identified by the
+    # digest ActiveAgent::Release computes from what the model is given.
+    # Returns the existing version when the latest release already carries
+    # this digest — a redeploy of an unchanged agent is not a new version —
+    # so it is safe to call on every deploy.
+    #
+    # The version's snapshot is the dashboard configuration plus the release
+    # manifest under "release", so the Versions tab can diff two releases the
+    # same way it diffs two dashboard edits.
+    #
+    # @param digest [String] ActiveAgent::Release digest of the host class
+    # @param manifest [Hash, nil] the class's release manifest
+    # @param revision [String, nil] the deploy (git SHA, release label)
+    # @param released_by [String, nil]
+    # @return [AgentVersion]
+    def record_release!(digest:, manifest: nil, revision: nil, released_by: nil)
+      current = latest_release
+      if current && current.release_digest == digest
+        update_columns(release_digest: digest) if release_digest != digest
+        return current
+      end
+
+      version = agent_versions.create!(
+        version_number: (latest_version&.version_number || 0) + 1,
+        change_summary: release_summary(digest, revision, current&.configuration_snapshot&.dig("release"), manifest),
+        configuration_snapshot: configuration_snapshot.merge("release" => manifest || {}),
+        release_digest: digest,
+        revision: revision,
+        created_by: released_by || "release"
+      )
+      update_columns(release_digest: digest)
+      version
+    end
+
     # Maps each historical instructions digest to the first version that
     # introduced it ("v3"), so run cohorts can label instruction changes with
     # real agent versions instead of raw hashes.
@@ -396,6 +444,18 @@ module ActionAgent
       end
     end
 
+    # "Release 1a2b3c4d5e6f · abc1234: templates, tools" — the digest, the
+    # deploy, and which parts of the manifest moved since the last release.
+    def release_summary(digest, revision, previous_manifest, manifest)
+      label = [ "Release #{digest}", revision.presence ].compact.join(" · ")
+      return "#{label}: first release" if previous_manifest.blank? || manifest.blank?
+
+      changed = (previous_manifest.keys | manifest.stringify_keys.keys).select do |key|
+        previous_manifest[key] != manifest.stringify_keys[key]
+      end
+      changed.any? ? "#{label}: #{changed.sort.join(', ')}" : label
+    end
+
     def create_initial_version
       agent_versions.create!(
         version_number: 1,

data/app/models/action_agent/agent_run.rb

@@ -3,6 +3,10 @@
 module ActionAgent
   class AgentRun < ApplicationRecord
     belongs_to :agent
+    # The version of the agent this run executed under — the latest at the
+    # time, since a run is against the agent as it is.
+    belongs_to :agent_version, optional: true
+    before_create { self.agent_version_id ||= agent&.latest_version&.id }
 
     # Raised when a caller hands a run files to attach in a host app that
     # has nowhere to keep them.

data/app/models/action_agent/agent_version.rb

@@ -9,6 +9,9 @@ module ActionAgent
 
     # Scopes
     scope :recent, -> { order(version_number: :desc) }
+    # Versions cut from the agent's code on deploy, as opposed to edits made
+    # in the dashboard.
+    scope :releases, -> { where.not(release_digest: [ nil, "" ]) }
     scope :by_version, ->(num) { where(version_number: num) }
 
     # Compare two versions
@@ -36,6 +39,13 @@ module ActionAgent
     end
 
     # Check if this is the latest version
+    # Whether this version was cut from the agent's code (it carries the
+    # release digest) rather than from a dashboard edit.
+    # @return [Boolean]
+    def release?
+      release_digest.present?
+    end
+
     def latest?
       agent.latest_version&.id == id
     end

data/app/models/action_agent/evaluation.rb

@@ -35,6 +35,17 @@ module ActionAgent
 
     scope :recent, -> { order(updated_at: :desc) }
 
+    # MySQL cannot give a JSON column a default, so a row inserted there
+    # without `criteria` or `config` reads back nil. Both readers answer with
+    # the empty value the column default supplies on other databases.
+    def criteria
+      super || []
+    end
+
+    def config
+      super || {}
+    end
+
     def latest_run
       evaluation_runs.order(created_at: :desc).first
     end
@@ -89,10 +100,16 @@ module ActionAgent
     # ActiveAgent::Evals::ScenarioParser output). Keys already in the suite keep their records, so
     # earlier runs' results still resolve to their scenario, and keep their
     # enabled flag unless the attributes set it (a paste cannot).
-    def replace_scenarios!(attributes)
+    # `on_removed:` decides what happens to a scenario the new attributes no
+    # longer name: `:destroy` drops it, `:disable` keeps the row with
+    # `enabled: false` so runs that scored it still resolve their results.
+    def replace_scenarios!(attributes, on_removed: :destroy)
+      raise ArgumentError, "on_removed must be :destroy or :disable" unless %i[destroy disable].include?(on_removed)
+
       transaction do
         keep = attributes.map { |attrs| attrs["key"] }
-        scenarios.where.not(key: keep).destroy_all
+        removed = scenarios.where.not(key: keep)
+        on_removed == :disable ? removed.update_all(enabled: false) : removed.destroy_all
 
         attributes.each_with_index do |attrs, index|
           scenario = scenarios.find_or_initialize_by(key: attrs["key"])

data/app/models/action_agent/evaluation_run.rb

@@ -8,6 +8,10 @@ module ActionAgent
   # See #average_score, which is what has to tolerate both shapes.
   class EvaluationRun < ApplicationRecord
     belongs_to :evaluation
+    # The version of the evaluated agent this run scored, so a pass rate is
+    # a statement about a release rather than about "the agent".
+    belongs_to :agent_version, optional: true
+    before_create { self.agent_version_id ||= evaluation&.agent&.latest_version&.id }
     has_many :scenario_results, class_name: "EvaluationScenarioResult", dependent: :destroy
 
     enum :status, { pending: 0, running: 1, complete: 2, failed: 3 }

data/app/models/action_agent/telemetry_trace.rb

@@ -43,6 +43,8 @@ module ActionAgent
     scope :for_date_range, ->(start_date, end_date) { where(timestamp: start_date..end_date) }
     # The dashboard agent this trace was attributed to on ingest, if any.
     belongs_to :agent, class_name: "ActionAgent::Agent", optional: true
+    # The release of the agent this trace came from (see #attach_agent_version!).
+    belongs_to :agent_version, class_name: "ActionAgent::AgentVersion", optional: true
 
     scope :for_account, ->(account) { where(account: account) if ActionAgent.multi_tenant? }
 
@@ -252,7 +254,10 @@ module ActionAgent
       # dashboard-authored agent by guessing a primary key.
       attrs[:agent_id] = agent&.id
 
-      create!(attrs).tap { |record| AgentRegistrar.call(record) }
+      create!(attrs).tap do |record|
+        AgentRegistrar.call(record)
+        record.attach_agent_version!
+      end
     end
 
 
@@ -265,6 +270,28 @@ module ActionAgent
       tokens.fetch("input", 0).to_i + tokens.fetch("output", 0).to_i + tokens.fetch("thinking", 0).to_i
     end
 
+    # Pins this trace to the version of its agent that produced it. The
+    # instrumentation stamps the root span with `agent.version` — the digest
+    # ActiveAgent::Release computes from the class — and a release cut on
+    # deploy carries the same digest, so the two meet here. A trace from a
+    # dashboard run carries no digest and takes the agent's latest version.
+    #
+    # @return [AgentVersion, nil]
+    def attach_agent_version!
+      return if agent_version_id.present? || agent_id.blank?
+
+      digest = root_span&.dig("attributes", "agent.version").presence
+      version = if digest
+        AgentVersion.find_by(agent_id: agent_id, release_digest: digest)
+      else
+        AgentVersion.where(agent_id: agent_id).order(version_number: :desc).first
+      end
+      return unless version
+
+      update_columns(agent_version_id: version.id)
+      version
+    end
+
     # Returns the root span of this trace.
     #
     # @return [Hash, nil] The root span or nil

data/app/services/action_agent/agent_execution_service.rb

@@ -33,9 +33,13 @@ module ActionAgent
     # so a multi-gigabyte log named .csv costs a fixed slice of memory rather
     # than its whole size. Four bytes per character is UTF-8's worst case.
     ATTACHMENT_TEXT_BYTE_LIMIT = ATTACHMENT_TEXT_LIMIT * 4
+    # What one prompt-span attribute stores. The value is a preview for reading,
+    # so it is clipped; a size that has to stay exact travels as its own
+    # `*.tokens` attribute instead.
+    PROMPT_SPAN_ATTRIBUTE_LIMIT = 6000
     # The prompt span records the transcript, not the data URIs; keep the
     # whole serialized list within the same budget as the other attributes.
-    PROMPT_SPAN_MESSAGE_LIMIT = 6000
+    PROMPT_SPAN_MESSAGE_LIMIT = PROMPT_SPAN_ATTRIBUTE_LIMIT
     # Prior turns sent with a pinned conversation: the most recent ones,
     # trimmed oldest-first to a character budget.
     HISTORY_TURN_LIMIT = 40
@@ -164,11 +168,19 @@ module ActionAgent
     def record_prompt_span(root_span)
       span = root_span.add_span("agent.prompt", span_type: :prompt)
       if composed_instructions.present?
-        span.set_attribute("prompt.input.instructions", composed_instructions.to_s.byteslice(0, 6000).to_s.scrub)
-      end
-      if tool_schemas.present?
-        span.set_attribute("prompt.input.tools", tool_schemas.to_json.byteslice(0, 6000).to_s.scrub)
+        instructions = composed_instructions.to_s
+        span.set_attribute("prompt.input.instructions", instructions.byteslice(0, PROMPT_SPAN_ATTRIBUTE_LIMIT).to_s.scrub)
+        span.set_attribute("prompt.input.instructions.tokens", estimated_tokens(instructions))
       end
+      # MCP and toolbox schemas are attributed separately so the meter can name
+      # which half fills the window, and each carries its size. The content
+      # attributes are truncated previews for reading: sizing the context from
+      # one understates it by whatever the clip dropped, which for a twelve-tool
+      # agent is most of the schema.
+      record_tool_schema_attributes(span)
+      full_transcript_json = prompt_turn[:transcript].map do |message|
+        { role: message[:role], content: message[:content].to_s }
+      end.to_json
       transcript = prompt_turn[:transcript].map do |message|
         { role: message[:role], content: message[:content].to_s.byteslice(0, 4000).to_s.scrub }
       end
@@ -181,6 +193,13 @@ module ActionAgent
       end
       span.set_attribute("prompt.input.messages", serialized)
       span.set_attribute("messages.count", transcript.size)
+      # The stored attribute is the tail of the history that fit, so its size is
+      # not the transcript's. The meter apportions the provider's prompt_tokens
+      # across the segments it can size, and a transcript missing from that set
+      # is not merely imprecise: the segments that remain are scaled up to cover
+      # it, so a long conversation reads as an enormous system prompt. Measured
+      # over the full turn, before either the per-message clip or the trim.
+      span.set_attribute("prompt.input.messages.tokens", estimated_tokens(full_transcript_json))
       span.finish
     rescue StandardError => e
       Rails.logger.warn("[AgentExecutionService] prompt span failed: #{e.message}")
@@ -385,6 +404,30 @@ module ActionAgent
       @mcp_dispatcher ||= MCPToolDispatcher.new(@agent_record)
     end
 
+    # Splits the offered schemas the way `tool_schemas` assembles them, so the
+    # span reports what the model was actually sent: nothing for a mock run, and
+    # one MCP round trip rather than a second one for telemetry.
+    def record_tool_schema_attributes(span)
+      mcp_definitions, toolbox_definitions = tool_schema_halves
+      {
+        "prompt.input.tools" => toolbox_definitions,
+        "prompt.input.mcp_tools" => mcp_definitions
+      }.each do |key, definitions|
+        next if definitions.blank?
+
+        json = definitions.to_json
+        span.set_attribute(key, json.byteslice(0, PROMPT_SPAN_ATTRIBUTE_LIMIT).to_s.scrub)
+        span.set_attribute("#{key}.tokens", estimated_tokens(json))
+      end
+    end
+
+    # ~4 chars/token, the same approximation the context meter applies to content
+    # it sizes itself. Taken before truncation, so the meter reads the whole
+    # schema rather than the preview the attribute stores.
+    def estimated_tokens(text)
+      (text.length / 4.0).round
+    end
+
     def call_agent(slug:, message:)
       depth = Thread.current[:agent_call_depth].to_i
       return { error: "call_agent depth limit (#{MAX_CALL_DEPTH}) reached" } if depth >= MAX_CALL_DEPTH
@@ -562,13 +605,21 @@ module ActionAgent
     # server-side implementations (none for mock runs — the mock provider
     # doesn't do tool calling).
     def tool_schemas
-      return [] if provider == :mock
-
-      # The agent's own MCP servers describe their tools; the toolbox describes
-      # the rest. Without the first half a tool the agent declares is never
-      # offered to the model, which then answers from memory instead of calling
-      # it.
-      mcp_dispatcher.tool_definitions + AgentToolbox.definitions_for(@agent_record.tools)
+      mcp_definitions, toolbox_definitions = tool_schema_halves
+      mcp_definitions + toolbox_definitions
+    end
+
+    # The agent's own MCP servers describe their tools; the toolbox describes the
+    # rest. Without the first half a tool the agent declares is never offered to
+    # the model, which then answers from memory instead of calling it. Memoized
+    # because listing a server's tools is a request to that server.
+    def tool_schema_halves
+      @tool_schema_halves ||=
+        if provider == :mock
+          [ [], [] ]
+        else
+          [ mcp_dispatcher.tool_definitions, AgentToolbox.definitions_for(@agent_record.tools) ]
+        end
     end
 
     # Persists the tool interaction stream to the solid_agent conversation

data/app/services/action_agent/agent_registrar.rb

@@ -77,8 +77,22 @@ module ActionAgent
       ActionAgent.multi_tenant? ? @trace.try(:account) : nil
     end
 
+    # The set an observed agent is deduplicated within.
+    #
+    # `for_owner(nil)` is `none` — correct for a multi-tenant read, where an
+    # unresolved tenant must see nothing. But a single-tenant dashboard has no
+    # owner to resolve and legitimately registers with `owner` nil (see
+    # #owner_for_trace), and `none` makes every dedupe lookup miss: each trace
+    # created another copy of the same agent, and the MAX_OBSERVED_PER_OWNER
+    # cap never engaged because the count it reads was always zero. Scoping to
+    # the whole table when there is no owner concept is what `for_owner`
+    # already does for a model with no owner association.
+    def agents_for_owner(owner)
+      owner.nil? && !ActionAgent.multi_tenant? ? Agent.all : Agent.for_owner(owner)
+    end
+
     def find_or_create_agent(owner)
-      agents = Agent.for_owner(owner)
+      agents = agents_for_owner(owner)
       existing = agents.find_by(
         service_name: @trace.service_name,
         agent_class_name: agent_class,
@@ -86,6 +100,14 @@ module ActionAgent
       )
       return existing if existing
 
+      # A host that mirrors its agent classes into the dashboard (a sync, a
+      # release) names the class on the record and nothing else: that record
+      # stands for every action of the class, so a trace from the class is
+      # its trace — not an observed twin's. Observed records are per action
+      # and are only ever matched on all three keys above.
+      mirrored = agents.where.not(status: "observed").find_by(agent_class_name: agent_class)
+      return mirrored if mirrored
+
       return if agents.observed_agents.count >= MAX_OBSERVED_PER_OWNER
 
       create_observed_agent(owner)

data/app/services/action_agent/agent_release.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module ActionAgent
+  # Cuts a version of every dashboard agent that mirrors a host class, from
+  # that class's release digest — what a deploy runs so the dashboard's
+  # versions line up with the code that shipped.
+  #
+  # The host owns the mirror: whatever syncs its ActiveAgent classes into
+  # Agent records sets `agent_class_name`, and this reads it back. A record
+  # whose class no longer resolves, or whose class predates
+  # ActiveAgent::Release, is reported and skipped rather than failed.
+  #
+  # Idempotent: a redeploy of an unchanged agent cuts nothing, so running it
+  # on every deploy is the intended use (`rake action_agent:agents:release`).
+  class AgentRelease
+    Row = Struct.new(:agent, :version, :cut, :skipped, keyword_init: true)
+    Result = Struct.new(:rows, :revision, keyword_init: true) do
+      def cut = rows.select(&:cut)
+      def skipped = rows.select(&:skipped)
+    end
+
+    # @param revision [String, nil] the deploy (git SHA, release label);
+    #   ActiveAgent::Release.revision when nil
+    # @param agents [ActiveRecord::Relation] the records to release; every
+    #   record naming a host class by default
+    # @param released_by [String, nil] recorded on each version cut
+    def self.call(revision: nil, agents: nil, released_by: nil)
+      new(revision: revision, agents: agents, released_by: released_by).call
+    end
+
+    def initialize(revision: nil, agents: nil, released_by: nil)
+      @revision = revision.presence || ActiveAgent::Release.revision
+      @agents = agents || Agent.where.not(agent_class_name: [ nil, "" ])
+      @released_by = released_by
+    end
+
+    # @return [Result]
+    def call
+      rows = @agents.order(:name).map { |agent| release(agent) }
+      Result.new(rows: rows, revision: @revision)
+    end
+
+    private
+
+    def release(agent)
+      klass = agent.agent_class_name.to_s.safe_constantize
+      unless klass.respond_to?(:release_digest)
+        return Row.new(agent: agent, version: nil, cut: false, skipped: "#{agent.agent_class_name} does not resolve to a releasable class")
+      end
+
+      before = agent.latest_version&.id
+      version = agent.record_release!(
+        digest: klass.release_digest,
+        manifest: klass.release_manifest,
+        revision: @revision,
+        released_by: @released_by
+      )
+      Row.new(agent: agent, version: version, cut: version.id != before, skipped: nil)
+    end
+  end
+end