actionagent 1.6.4 → 1.7.0

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

@@ -90,7 +90,7 @@ module ActionAgent
         if @agent.save
           render json: { agent: agent_json(@agent, include_details: true) }, status: :created
         else
-          render json: { errors: @agent.errors.full_messages }, status: :unprocessable_entity
+          render json: agent_errors_json(@agent), status: :unprocessable_entity
         end
       end
 
@@ -99,7 +99,7 @@ module ActionAgent
         if @agent.update(agent_params)
           render json: { agent: agent_json(@agent, include_details: true) }
         else
-          render json: { errors: @agent.errors.full_messages }, status: :unprocessable_entity
+          render json: agent_errors_json(@agent), status: :unprocessable_entity
         end
       end
 
@@ -495,6 +495,12 @@ module ActionAgent
         @agent = owner_agents.find(params[:id])
       end
 
+      # +errors+ for a form-level summary; +field_errors+ (attribute => full
+      # messages) so the builder and editor can put each under its field.
+      def agent_errors_json(agent)
+        { errors: agent.errors.full_messages, field_errors: agent.errors.to_hash(true) }
+      end
+
       def agent_params
         permitted = params.require(:agent).permit(
           :name, :description, :provider, :model, :instructions,

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

@@ -12,11 +12,23 @@ module ActionAgent
     # install, a per-user install and a multi-tenant platform all read the
     # same controllers.
     #
-    # Note this is not the telemetry ingest endpoint — that authenticates
-    # with a bearer token and lives in Api::TracesController.
+    # Because it authenticates with the host's session cookie, it keeps the
+    # forgery protection ApplicationController turns on: the dashboard sends
+    # the page's CSRF token with every mutating request (frontend
+    # utils/apiFetch.mjs). Endpoints that authenticate with a bearer token
+    # instead — the telemetry ingest endpoint (Api::TracesController), the
+    # evaluation report collector (Api::EvaluationReportsController) and the
+    # MCP facade (Api::MCPController) — are exempt.
     class BaseController < ActionAgent::ApplicationController
-      skip_forgery_protection
-
+      # Rails 8.2 verifies forgery protection from the browser's Sec-Fetch-Site
+      # header, renamed the failure to InvalidCrossOriginRequest, and deprecated
+      # the old name. Rescue whichever names the running Rails defines, so a
+      # rejected request answers with the dashboard's JSON either way.
+      # const_defined? does not fire the deprecation the bare constant would.
+      rescue_from ActionController::InvalidCrossOriginRequest, with: :invalid_authenticity_token
+      if ActionController.const_defined?(:InvalidAuthenticityToken, false)
+        rescue_from ActionController::InvalidAuthenticityToken, with: :invalid_authenticity_token
+      end
       rescue_from ActiveRecord::RecordNotFound, with: :not_found
       rescue_from ActiveRecord::RecordInvalid, with: :unprocessable_entity
       rescue_from ActionController::ParameterMissing, with: :bad_request
@@ -24,6 +36,10 @@ module ActionAgent
 
       private
 
+      def invalid_authenticity_token
+        render json: { error: "Refresh the dashboard and try again", code: "invalid_csrf_token" }, status: :unprocessable_entity
+      end
+
       # API keys and provider credentials are encrypted at rest, which needs
       # Active Record Encryption keys. The engine derives fallback keys when
       # the host set none (see Engine's action_agent.active_record_encryption

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

@@ -3,8 +3,6 @@
 module ActionAgent
   module Api
     class DashboardAssistantController < BaseController
-      protect_from_forgery with: :exception
-
       before_action :require_assistant_enabled!
       before_action :require_owner!
       before_action :require_execution_enabled!, only: :create
@@ -13,15 +11,6 @@ module ActionAgent
       rescue_from DashboardAssistantService::InvalidInput, with: :invalid_input
       rescue_from DashboardAssistantService::ProcessingConsentRequired, with: :processing_consent_required
       rescue_from DashboardAssistantService::SetupRequired, with: :setup_required
-      # Rails 8.2 verifies forgery protection from the browser's Sec-Fetch-Site
-      # header, renamed the failure to InvalidCrossOriginRequest, and deprecated
-      # the old name. Rescue whichever names the running Rails defines, so a
-      # rejected request answers with the dashboard's JSON either way.
-      # const_defined? does not fire the deprecation the bare constant would.
-      rescue_from ActionController::InvalidCrossOriginRequest, with: :invalid_authenticity_token
-      if ActionController.const_defined?(:InvalidAuthenticityToken, false)
-        rescue_from ActionController::InvalidAuthenticityToken, with: :invalid_authenticity_token
-      end
 
       def show
         render json: DashboardAssistantService.new(owner: current_owner).configuration

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

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+module ActionAgent
+  module Api
+    # Collector for evaluation reports an application ran itself and
+    # published with ActiveAgent::Evals::Publisher:
+    # POST <mount>/api/evaluation_reports (e.g. /activeagents/api/evaluation_reports).
+    #
+    # Authenticated exactly as trace ingest is (IngestAuthentication), and
+    # 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.
+    #   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
+    #   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
+    #         over RATE_LIMIT new reports a minute from one key
+    #   413 — a body over EvaluationReportImport::MAX_BYTES
+    #   415 — a body that is not declared application/json
+    #   400 — a body that is not JSON
+    #   401 — a missing or unknown key
+    #   501 — an install with no evaluation tables, or not yet migrated
+    #   503 — another import for the same agent held the lock too long
+    class EvaluationReportsController < ActionController::API
+      include IngestAuthentication
+
+      # New reports one key may store per minute.
+      RATE_LIMIT = 30
+
+      wrap_parameters false
+
+      before_action :require_json!
+      before_action :require_report_store!
+
+      # POST <mount>/api/evaluation_reports
+      def create
+        # The header, not request.content_length, which reads a chunked body
+        # in full to measure it.
+        return report_too_large if request.get_header("CONTENT_LENGTH").to_i > EvaluationReportImport::MAX_BYTES
+
+        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
+
+        render json: receipt(run, duplicate), status: duplicate ? :ok : :created
+      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
+      rescue EvaluationReportImport::Conflict => e
+        render json: { error: e.message }, status: :conflict
+      rescue EvaluationReportImport::Refused => e
+        render json: { error: e.message }, status: :forbidden
+      rescue EvaluationReportImport::Denied => e
+        render json: e.denial, status: :too_many_requests
+      rescue EvaluationReportImport::Busy => e
+        response.headers["Retry-After"] = "5"
+        render json: { error: e.message }, status: :service_unavailable
+      end
+
+      private
+
+      # Rails reads and parses a JSON body into params before any callback
+      # runs, for the request log among others. With none to parse, the body
+      # is read only by #create, and only up to the size limit.
+      def process_action(*)
+        request.request_parameters = {}
+        super
+      end
+
+      # A cross-site page can send a text/plain or form POST without a CORS
+      # preflight; it cannot send application/json.
+      def require_json!
+        return if request.media_type == "application/json"
+
+        render json: { error: "Content-Type must be application/json" }, status: :unsupported_media_type
+      end
+
+      def require_report_store!
+        reason = EvaluationReportImport.unavailable_reason
+        render json: { error: reason }, status: :not_implemented if reason
+      end
+
+      # What refuses a report that would be stored, or nil: the rate limit,
+      # then the host app's quota checker, asked with kind :evaluation_report.
+      # Never asked for an identical retry.
+      def admission_denial
+        return { error: "Too many evaluation reports; retry in a minute" } if rate_limited?
+
+        denial = ActionAgent.quota_denial(@account, :evaluation_report)
+        quota_denial_body(denial, "Evaluation report limit reached") if denial.present?
+      end
+
+      # Counts a new report against its key's bucket, in the store Rails'
+      # own rate_limit uses. One bucket per key: the tenant's on a
+      # multi-tenant install, the install's own on a single-tenant one.
+      def rate_limited?
+        bucket = @account ? "account:#{@account.id}" : "install"
+        count = self.class.cache_store.increment("rate-limit:#{controller_path}:#{bucket}", 1, expires_in: 1.minute)
+        count.present? && count > RATE_LIMIT
+      end
+
+      def receipt(run, duplicate)
+        {
+          id: run.id,
+          evaluation_id: run.evaluation_id,
+          run_id: run.external_run_id,
+          status: run.status,
+          duplicate: duplicate,
+          url: run_url(run)
+        }
+      end
+
+      # The dashboard page that shows the run, as a path on this host. A host
+      # that routes to this controller from outside the engine's mount
+      # overrides it.
+      def run_url(run)
+        "#{request.script_name}/evaluations/#{run.evaluation_id}/runs/#{run.id}"
+      end
+
+      # 413 by number: Rack named it :payload_too_large before 3.1 and
+      # :content_too_large since, and the engine supports both.
+      def report_too_large
+        render json: { error: "Report exceeds #{EvaluationReportImport::MAX_BYTES / 1.megabyte} MiB" }, status: 413
+      end
+    end
+  end
+end

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

@@ -46,14 +46,20 @@ module ActionAgent
         render json: { evaluations: evaluations.map { |evaluation| serialize(evaluation) } }
       end
 
+      # Runs listed per evaluation on GET /api/evaluations/:id. The rest of
+      # the history stays reachable by run id; `run_count` says how long it is.
+      RUN_HISTORY_LIMIT = 20
+
       # GET /api/evaluations/:id
       def show
         evaluation = evaluations_scope.find(params[:id])
+        run_count = evaluation.evaluation_runs.count
+        runs = evaluation.evaluation_runs.recent.limit(RUN_HISTORY_LIMIT).to_a
 
         render json: {
           evaluation: serialize(evaluation).merge(
             scenarios: evaluation.scenarios.ordered.map(&:as_json_summary),
-            runs: evaluation.evaluation_runs.recent.limit(20).map { |run| serialize_run(run) }
+            runs: runs.each_with_index.map { |run, index| serialize_run(run, number: run_count - index) }
           )
         }
       end
@@ -98,8 +104,12 @@ module ActionAgent
       def run
         evaluation = current_evaluation
         run = start_run(evaluation, selection_params)
+        evaluation.reload
 
-        render json: { evaluation: serialize(evaluation.reload), run: serialize_run(run) }
+        render json: {
+          evaluation: serialize(evaluation),
+          run: serialize_run(run, number: evaluation.evaluation_runs.count)
+        }
       end
 
       # GET /api/evaluations/:id/runs/:run_id
@@ -116,7 +126,8 @@ module ActionAgent
 
         render json: {
           evaluation: serialize(evaluation),
-          run: serialize_run(run).merge(results: results.map(&:as_json_summary), fix_items: safe_fix_items(run))
+          run: serialize_run(run, number: run_number(evaluation, run))
+            .merge(results: results.map(&:as_json_summary), fix_items: safe_fix_items(run))
         }
       end
 
@@ -328,7 +339,9 @@ module ActionAgent
       end
 
       def serialize(evaluation)
-        latest = evaluation.latest_run
+        # size reads the preloaded association on index and COUNTs elsewhere.
+        run_count = evaluation.evaluation_runs.size
+        latest, previous = recent_runs(evaluation, 2)
 
         {
           id: evaluation.id,
@@ -344,22 +357,50 @@ module ActionAgent
           scenario_count: evaluation.scenarios.size,
           scenario_groups: evaluation.scenario_suite? ? evaluation.scenario_groups : [],
           created_at: evaluation.created_at.iso8601,
-          latest_run: latest ? serialize_run(latest) : nil
+          run_count: run_count,
+          latest_run: latest ? serialize_run(latest, number: run_count) : nil,
+          # Just enough of the run before it for the list to show movement
+          # ("+3 passed vs #2") without a request per evaluation.
+          previous_run: previous ? serialize_run_summary(previous, number: run_count - 1) : nil
         }
       end
 
-      def serialize_run(run)
-        {
-          id: run.id,
-          status: run.status,
+      # Newest first. Sorts the preloaded association when index loaded it
+      # rather than issuing one ORDER BY query per evaluation.
+      def recent_runs(evaluation, limit)
+        runs = evaluation.evaluation_runs
+        if runs.loaded?
+          runs.sort_by { |run| [ run.created_at, run.id ] }.reverse.first(limit)
+        else
+          runs.recent.limit(limit).to_a
+        end
+      end
+
+      # A run's position in its evaluation's history, oldest = 1.
+      def run_number(evaluation, run)
+        evaluation.evaluation_runs.where("created_at < ? OR (created_at = ? AND id <= ?)", run.created_at, run.created_at, run.id).count
+      end
+
+      # `number` is the run's position in its evaluation's history, oldest =
+      # 1, so the dashboard can say "Run #3" and "vs #2".
+      def serialize_run(run, number: nil)
+        serialize_run_summary(run, number: number).merge(
           scores: run.scores,
           selection: run.selection,
           models: run.models,
+          usage: run.usage,
+          error_message: run.error_message
+        )
+      end
+
+      def serialize_run_summary(run, number: nil)
+        {
+          id: run.id,
+          number: number,
+          status: run.status,
           average_score: safe_average_score(run),
           samples_evaluated: run.samples_evaluated,
           samples_passed: run.samples_passed,
-          usage: run.usage,
-          error_message: run.error_message,
           completed_at: run.completed_at&.iso8601,
           created_at: run.created_at.iso8601
         }

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

@@ -127,13 +127,12 @@ module ActionAgent
       end
 
       # Traces belong to an agent by foreign key once AgentRegistrar attributes
-      # them; older rows predate that, so fall back to the class name.
+      # them; older rows predate that, so fall back to the agent's identity.
       def traces_for_agent(agent_id)
         agent = owner_agents.find_by(id: agent_id)
         return ActionAgent.trace_model.none unless agent
 
-        ActionAgent.trace_model.where(agent_id: agent.id)
-          .or(ActionAgent.trace_model.where(agent_id: nil, agent_class: agent.telemetry_agent_class))
+        owned_traces.where(agent_id: agent.id).or(agent.unattributed_telemetry_traces(owned_traces))
       end
 
       # The dashboard-wide time window, shared with Traces. Absent means "all".

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

@@ -24,8 +24,10 @@ module ActionAgent
     #   { "type": "http", "url": "https://activeagents.ai/mcp",
     #     "headers": { "Authorization": "Bearer aa_..." } }
     class MCPController < BaseController
-      # Authenticated by API key rather than by the host app's sessions.
+      # Authenticated by API key rather than by the host app's sessions, so
+      # there is no session cookie for a cross-site request to ride on.
       allow_unauthenticated_access
+      skip_forgery_protection
       before_action :authenticate_api_key!, except: [ :unsupported ]
 
       PROTOCOL_VERSION = "2025-03-26"

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

@@ -92,12 +92,15 @@ module ActionAgent
         nil
       end
 
+      # The whole catalog, never a prefix of it: OpenRouter serves several
+      # hundred models, and a cap after sorting left everything late in the
+      # alphabet (openai/*, qwen/*, ...) unselectable. The editor filters it.
       def live_openrouter_models
         data = Rails.cache.fetch("provider_models:openrouter", expires_in: 1.hour) do
           fetch_json(URI.parse("https://openrouter.ai/api/v1/models"))
         end
         ids = Array(data&.dig("data")).filter_map { |model| model["id"] }
-        [ ids.sort.first(100), "live" ] if ids.any?
+        [ ids.sort, "live" ] if ids.any?
       rescue StandardError => e
         Rails.logger.warn("[ProviderModels] openrouter lookup failed: #{e.message}")
         nil

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

@@ -16,9 +16,19 @@ module ActionAgent
       DEFAULT_LIMIT = 500
 
       # GET /api/traces
+      #
+      # Params:
+      #   minutes   the window in minutes, DEFAULT_WINDOW_MINUTES when absent
+      #   agent_id  an agent the caller can see. Everything in the response,
+      #             `agents` and `agent_ids` included, is narrowed to that
+      #             agent's traces (Agent#telemetry_traces). 404 for an agent
+      #             the caller cannot see.
+      #   agent     an agent_class, narrowing `traces` only
+      #   service   a service_name, narrowing `traces` only
+      #   status    "error" for failed traces only
       def index
         window = params.fetch(:minutes, DEFAULT_WINDOW_MINUTES).to_i.clamp(1, MAX_WINDOW_MINUTES)
-        window_scope = traces_scope.for_date_range(window.minutes.ago, Time.current)
+        window_scope = agent_scope(traces_scope).for_date_range(window.minutes.ago, Time.current)
 
         scope = window_scope
         scope = scope.for_agent(params[:agent]) if params[:agent].present?
@@ -54,6 +64,15 @@ module ActionAgent
         ActionAgent.trace_model.for_account(current_account)
       end
 
+      # +scope+ narrowed to the traces of the agent `agent_id` names, looked
+      # up among the agents the caller can see.
+      def agent_scope(scope)
+        agent_id = integer_param(:agent_id)
+        return scope unless agent_id
+
+        owner_agents.find(agent_id).telemetry_traces(scope)
+      end
+
       # One grouped query. A class can appear under several agent records
       # (same class, different action); the most recently active one wins,
       # since that's what the operator most likely means by "this agent".

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

@@ -34,8 +34,8 @@ module ActionAgent
     #   }
     #
     class TracesController < ActionController::API
-      before_action :authenticate_api_key!, if: -> { ActionAgent.multi_tenant? }
-      before_action :authenticate_ingest_key!, unless: -> { ActionAgent.multi_tenant? }
+      include IngestAuthentication
+
       before_action :enforce_ingest_quota!
 
       # POST <mount>/api/traces  (e.g. /activeagents/api/traces)
@@ -75,64 +75,15 @@ module ActionAgent
 
       private
 
-      # Authenticates the request using Bearer token from Authorization header.
-      # Only used in multi-tenant mode.
-      def authenticate_api_key!
-        token = extract_bearer_token
-
-        if token.blank?
-          render json: { error: "Missing Authorization header" }, status: :unauthorized
-          return
-        end
-
-        account_class = ActionAgent.account_class.constantize
-        @account = account_class.find_by(telemetry_api_key: token)
-
-        if @account.nil?
-          render json: { error: "Invalid API key" }, status: :unauthorized
-          return
-        end
-
-        # Track usage for rate limiting (if the account responds to it)
-        @account.increment_telemetry_usage! if @account.respond_to?(:increment_telemetry_usage!)
-      end
-
-      # Requires the configured single-tenant ingest key when one is set.
-      # The telemetry reporter and ruby_llm_telemetry both send their
-      # api_key as a Bearer header, so remote apps work unchanged.
-      def authenticate_ingest_key!
-        expected = ActionAgent.ingest_api_key
-        return if expected.blank?
-
-        token = extract_bearer_token
-        return if token.present? && ActiveSupport::SecurityUtils.secure_compare(token, expected)
-
-        render json: { error: "Invalid API key" }, status: :unauthorized
-      end
-
-      # The host app's quota checker, asked with kind :trace_ingest — the
-      # counterpart to Api::BaseController#enforce_quota!, which asks with
-      # :execution. Denials are 429 here rather than 402: a reporter that is
-      # over its ingest allowance should back off, not upgrade mid-flush.
-      # Same body shape, so a checker's message or Hash payload reads the
-      # same on both.
+      # The host app's quota checker, asked with kind :trace_ingest.
       def enforce_ingest_quota!
-        denial = ActionAgent.quota_denial(@account, :trace_ingest)
-        return if denial.blank?
-
-        body = { error: "Trace ingest limit reached" }
-        body = denial.is_a?(Hash) ? body.merge(denial) : body.merge(message: denial)
-
-        render json: body, status: :too_many_requests
+        enforce_ingest_quota_for!(:trace_ingest, "Trace ingest limit reached")
       end
 
-      # Extracts Bearer token from Authorization header.
-      def extract_bearer_token
-        auth_header = request.headers["Authorization"]
-        return nil if auth_header.blank?
-
-        match = auth_header.match(/^Bearer\s+(.+)$/i)
-        match[1] if match
+      # Counts the request against the tenant, when its account model
+      # defines the hook.
+      def record_ingest_request
+        @account.increment_telemetry_usage! if @account.respond_to?(:increment_telemetry_usage!)
       end
 
       # Process traces synchronously for local development.

data/app/controllers/action_agent/application_controller.rb

@@ -5,6 +5,10 @@ module ActionAgent
   #
   # Handles authentication and provides helper methods for multi-tenant mode.
   class ApplicationController < ActionController::Base
+    # Ahead of the engine's own callbacks, so a concern's before_action or
+    # around_action runs before the dashboard authenticates.
+    ActionAgent.controller_concern_modules.each { |concern| include concern }
+
     protect_from_forgery with: :exception
 
     before_action :authenticate_dashboard!

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

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module ActionAgent
+  module Api
+    # Bearer-token authentication for the endpoints other applications post
+    # to: trace ingest (Api::TracesController) and published evaluation
+    # reports (Api::EvaluationReportsController). Neither is a dashboard
+    # controller, so neither sees the host's session or controller concerns.
+    #
+    # A multi-tenant install authenticates the tenant's key and sets
+    # `@account` to the tenant it names. A single-tenant install requires
+    # ActionAgent.ingest_api_key when one is set and leaves `@account` nil.
+    module IngestAuthentication
+      extend ActiveSupport::Concern
+
+      included do
+        before_action :authenticate_api_key!, if: -> { ActionAgent.multi_tenant? }
+        before_action :authenticate_ingest_key!, unless: -> { ActionAgent.multi_tenant? }
+      end
+
+      private
+
+      # Finds the tenant whose `telemetry_api_key` is the bearer token.
+      # Only used in multi-tenant mode.
+      def authenticate_api_key!
+        token = extract_bearer_token
+
+        if token.blank?
+          render json: { error: "Missing Authorization header" }, status: :unauthorized
+          return
+        end
+
+        account_class = ActionAgent.account_class.constantize
+        @account = account_class.find_by(telemetry_api_key: token)
+
+        if @account.nil?
+          render json: { error: "Invalid API key" }, status: :unauthorized
+          return
+        end
+
+        record_ingest_request
+      end
+
+      # Called once the tenant has authenticated. Counts nothing here: trace
+      # ingest counts the request through the tenant's
+      # increment_telemetry_usage!, and the report collector records a stored
+      # report through ActionAgent.usage_recorder instead.
+      def record_ingest_request; end
+
+      # Requires the configured single-tenant ingest key when one is set.
+      # The telemetry reporter, ruby_llm_telemetry and
+      # ActiveAgent::Evals::Publisher all send their api_key as a Bearer
+      # header, so remote apps work unchanged.
+      def authenticate_ingest_key!
+        expected = ActionAgent.ingest_api_key
+        return if expected.blank?
+
+        token = extract_bearer_token
+        return if token.present? && ActiveSupport::SecurityUtils.secure_compare(token, expected)
+
+        render json: { error: "Invalid API key" }, status: :unauthorized
+      end
+
+      # Asks the host app's quota checker whether the tenant may do +kind+,
+      # and renders 429 with +error+ when it may not. The counterpart to
+      # Api::BaseController#enforce_quota!, which answers 402: a client that
+      # is over its ingest allowance should back off, not upgrade mid-flush.
+      # Same body shape, so a checker's message or Hash payload reads the
+      # same on both.
+      def enforce_ingest_quota_for!(kind, error)
+        denial = ActionAgent.quota_denial(@account, kind)
+        return if denial.blank?
+
+        render json: quota_denial_body(denial, error), status: :too_many_requests
+      end
+
+      # The 429 body for a quota checker's +denial+: its Hash merged in, or
+      # its String as the message.
+      def quota_denial_body(denial, error)
+        body = { error: error }
+        denial.is_a?(Hash) ? body.merge(denial) : body.merge(message: denial)
+      end
+
+      # Extracts Bearer token from Authorization header.
+      def extract_bearer_token
+        auth_header = request.headers["Authorization"]
+        return nil if auth_header.blank?
+
+        match = auth_header.match(/^Bearer\s+(.+)$/i)
+        match[1] if match
+      end
+    end
+  end
+end