actionagent 1.8.1 → 1.9.0

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

@@ -0,0 +1,302 @@
+# frozen_string_literal: true
+
+module ActionAgent
+  module Api
+    # Scenario catalogs: the YAML catalogs of evaluation scenarios an owner
+    # keeps, imported from a document, an uploaded file or a connected
+    # repository at a ref, exported as YAML, synced to Active Storage, and
+    # run one set at a time against an agent or a project.
+    #
+    # Importing and running change evaluation scenarios, so both need the
+    # :replace_scenarios permission, as replacing an evaluation's scenarios
+    # does. A run executes the agent, so it is gated as POST
+    # /api/evaluations/:id/run is: the execution switch and the owner's
+    # execution quota.
+    class ScenarioCatalogsController < BaseController
+      before_action :require_owner!
+      before_action :set_catalog, only: [ :show, :update, :destroy, :export, :sync, :run_set, :materialize_set ]
+      before_action :require_execution_enabled!, :enforce_execution_quota!, only: [ :run_set ]
+
+      rescue_from ScenarioCatalogImport::Invalid, ScenarioSet::NoAgent do |error|
+        render json: { errors: [ error.message ] }, status: :unprocessable_entity
+      end
+
+      # GET /api/scenario_catalogs
+      def index
+        catalogs = owned(ScenarioCatalog).ordered.includes(products: { sets: :scenarios }).to_a
+        render json: {
+          catalogs: catalogs.map { |catalog| ScenarioCatalogSerializer.summary(catalog) },
+          storage_available: ScenarioCatalog.attachments_available?
+        }
+      end
+
+      # GET /api/scenario_catalogs/:id
+      def show
+        render json: { catalog: ScenarioCatalogSerializer.full(@catalog) }
+      end
+
+      # POST /api/scenario_catalogs
+      # One of:
+      #   catalog:    { key, name, description } for an empty catalog, built
+      #               up in the dashboard (see ScenarioCatalogEntriesController)
+      #   document:   the catalog's YAML text
+      #   file:       an uploaded .yml
+      #   repository: owner/name of a connected repository, with ref (its
+      #               default branch when omitted) and path (a directory of
+      #               .yml files, .activeagents/evals by default, or one file)
+      # mode is "replace" (the default: the document is the catalog) or
+      # "merge" (what the document leaves out is kept). Answers the imported
+      # catalogs. A repository the GitHub connection has not selected needs
+      # :manage_github, as reading one for a project does.
+      def create
+        return unless authorize_action!(:replace_scenarios, ScenarioCatalog.new)
+        return create_empty if params[:document].blank? && params[:file].blank? && params[:repository].blank? && params[:catalog].present?
+
+        catalogs =
+          if params[:repository].present?
+            import_from_repository or return
+          else
+            [ import_document(document_param, name: params[:name].presence, source_path: params[:source_path].presence) ]
+          end
+
+        render json: { catalogs: catalogs.map { |catalog| ScenarioCatalogSerializer.full(catalog) } }, status: :created
+      end
+
+      # PATCH /api/scenario_catalogs/:id
+      # With a document or file, re-imports it into this catalog (its
+      # products, sets and scenarios become the document's); otherwise
+      # renames or describes the catalog.
+      def update
+        return unless authorize_action!(:replace_scenarios, @catalog)
+
+        if params[:document].present? || params[:file].present?
+          import_document(document_param, catalog: @catalog, source_path: params[:source_path].presence || @catalog.source_path)
+        else
+          attributes = params.require(:catalog).permit(:name, :description)
+          @catalog.update!(attributes)
+          @catalog.refresh_document!
+          @catalog.sync_to_storage!
+        end
+
+        render json: { catalog: ScenarioCatalogSerializer.full(@catalog.reload) }
+      end
+
+      # DELETE /api/scenario_catalogs/:id
+      # The evaluations the catalog's sets became stay, with their runs.
+      def destroy
+        return unless authorize_action!(:replace_scenarios, @catalog)
+
+        @catalog.destroy!
+        head :no_content
+      end
+
+      # POST /api/scenario_catalogs/preview
+      # What POST /api/scenario_catalogs would change, with the same
+      # document, file or repository and mode, without writing: one
+      # ScenarioCatalogImport#preview per catalog.
+      def preview
+        previews =
+          if params[:repository].present?
+            preview_repository or return
+          else
+            [ build_import(document_param, name: params[:name].presence).preview ]
+          end
+
+        render json: { previews: previews }
+      end
+
+      # GET /api/scenario_catalogs/:id/export?product_ids=&set_ids=&scenario_ids=
+      # The canonical YAML, as a download: the whole catalog, or only the
+      # products, sets or scenarios named (comma-separated ids or arrays).
+      # disposition=inline answers it as text, for copying.
+      def export
+        yaml = @catalog.export_yaml(product_ids: params[:product_ids], set_ids: params[:set_ids], scenario_ids: params[:scenario_ids])
+        if params[:disposition].to_s == "inline"
+          render plain: yaml, content_type: "application/x-yaml"
+        else
+          suffix = [ params[:product_ids], params[:set_ids], params[:scenario_ids] ].any?(&:present?) ? "-selection" : ""
+          send_data yaml, filename: "#{@catalog.key.tr('/', '-')}#{suffix}.yml", type: "application/x-yaml", disposition: "attachment"
+        end
+      end
+
+      # POST /api/scenario_catalogs/:id/sync
+      # direction=push (the default) writes the document to Active Storage;
+      # direction=pull replaces the records with the stored document.
+      def sync
+        return unless authorize_action!(:replace_scenarios, @catalog)
+        unless ScenarioCatalog.attachments_available?
+          return render json: { error: "Active Storage is off for this dashboard (ActionAgent.active_storage)", code: "no_storage" },
+            status: :unprocessable_entity
+        end
+
+        if params[:direction].to_s == "pull"
+          @catalog.restore_from_storage!
+        else
+          @catalog.sync_to_storage!
+        end
+
+        render json: { catalog: ScenarioCatalogSerializer.full(@catalog.reload) }
+      rescue ActiveRecord::RecordNotFound => e
+        render json: { error: e.message, code: "no_document" }, status: :not_found
+      end
+
+      # POST /api/scenario_catalogs/:id/sets/:set_id/materialize
+      # Creates or refreshes the evaluation the set runs as, on agent_id or
+      # the product's target, without running it.
+      def materialize_set
+        return unless authorize_action!(:replace_scenarios, @catalog)
+
+        set = find_set
+        evaluation = set.materialize!(agent: requested_agent)
+        render json: { set: set.reload.summary, evaluation: EvaluationSerializer.summary(evaluation) }
+      end
+
+      # POST /api/scenario_catalogs/:id/sets/:set_id/run
+      # Runs the set against agent_id, against project_id (the project's
+      # sandbox is booted if it is not running, and every replay reaches it
+      # and its browser), or against the product's own target. models and
+      # keys narrow the run as they do for an evaluation.
+      def run_set
+        return unless authorize_action!(:replace_scenarios, @catalog)
+
+        set = find_set
+        project = owned(Project).find(params[:project_id]) if params[:project_id].present?
+        agent = requested_agent || project&.target_agent || set.product.target_agent(owner_agents)
+        if agent.nil?
+          return render json: { error: "Choose the agent to run against", code: "no_target" }, status: :unprocessable_entity
+        end
+        if agent.observed?
+          return render json: { error: "Observed agents are read-only — duplicate this agent to create an executable copy" },
+            status: :unprocessable_entity
+        end
+        if project
+          boot_project_sandbox!(project) or return
+        end
+
+        selection = evaluation_run_selection(params).except(:scenario_ids, :group)
+        run = set.run!(agent: agent, project: project, mount_url: "#{request.base_url}#{request.script_name}", **selection)
+        render json: {
+          set: set.reload.summary,
+          evaluation: EvaluationSerializer.summary(run.evaluation),
+          run: { id: run.id, status: run.status, evaluation_id: run.evaluation_id }
+        }, status: :accepted
+      end
+
+      private
+
+      include EvaluationRunStarting
+
+      def set_catalog
+        @catalog = owned(ScenarioCatalog).find(params[:id])
+      end
+
+      def find_set
+        ScenarioSet.where(scenario_product_id: @catalog.products.select(:id)).find(params[:set_id])
+      end
+
+      def requested_agent
+        params[:agent_id].present? ? owner_agents.find(params[:agent_id]) : nil
+      end
+
+      # The YAML given as text or as an uploaded file.
+      def document_param
+        file = params[:file]
+        return file.read if file.respond_to?(:read)
+
+        params[:document].to_s
+      end
+
+      def import_document(document, catalog: nil, name: nil, source_path: nil)
+        build_import(document, catalog: catalog, name: name, source_path: source_path).call
+      end
+
+      def build_import(document, catalog: nil, name: nil, source_path: nil)
+        ScenarioCatalogImport.new(
+          owner: current_owner, document: document, catalog: catalog, name: name,
+          source_kind: "upload", source_path: source_path,
+          agents: owner_agents, projects: owned(Project), mode: params[:mode].presence || "replace"
+        )
+      end
+
+      # An empty catalog from catalog: { key, name, description }; a blank
+      # key is made from the name.
+      def create_empty
+        attributes = params.require(:catalog).permit(:key, :name, :description).to_h.symbolize_keys
+        taken = owned(ScenarioCatalog).pluck(:key)
+        attributes[:key] = ScenarioCatalog.key_for(attributes[:name], taken) if attributes[:key].blank?
+        attributes[:name] = attributes[:key] if attributes[:name].blank?
+        catalog = ScenarioCatalog.new(attributes.merge(source_kind: "api"))
+        catalog.owner = current_owner
+        ScenarioCatalog.transaction do
+          catalog.save!
+          catalog.refresh_document!
+        end
+        catalog.sync_to_storage!
+
+        render json: { catalogs: [ ScenarioCatalogSerializer.full(catalog) ] }, status: :created
+      rescue ActiveRecord::RecordInvalid => e
+        render json: { errors: e.record.errors.full_messages }, status: :unprocessable_entity
+      end
+
+      # Imports from the connected repository params name. nil, with the
+      # refusal rendered, when there is no connection or the repository is
+      # not one the caller may read.
+      def import_from_repository
+        connection = GithubConnection.for_owner(current_owner).first
+        if connection.nil?
+          render json: { error: "Connect GitHub in Settings first", code: "no_github_connection" }, status: :unprocessable_entity
+          return nil
+        end
+
+        repository = params[:repository].to_s
+        if connection.repository(repository).nil? && !ActionAgent.permitted?(current_user, :manage_github, connection)
+          permission_denied(:manage_github)
+          return nil
+        end
+
+        repository_import(connection, repository).call
+      end
+
+      # Previews what the connected repository params name would import. nil,
+      # with the refusal rendered, as #import_from_repository.
+      def preview_repository
+        connection = GithubConnection.for_owner(current_owner).first
+        if connection.nil?
+          render json: { error: "Connect GitHub in Settings first", code: "no_github_connection" }, status: :unprocessable_entity
+          return nil
+        end
+
+        repository = params[:repository].to_s
+        if connection.repository(repository).nil? && !ActionAgent.permitted?(current_user, :manage_github, connection)
+          permission_denied(:manage_github)
+          return nil
+        end
+
+        repository_import(connection, repository).preview
+      end
+
+      def repository_import(connection, repository)
+        ScenarioCatalogRepositoryImport.new(
+          owner: current_owner, connection: connection, repository: repository,
+          ref: params[:ref].presence, path: params[:path].presence,
+          agents: owner_agents, projects: owned(Project), mode: params[:mode].presence || "replace"
+        )
+      end
+
+      # Boots the project's sandbox when none is running, as the project's
+      # own run does. nil, with the refusal rendered, when it cannot.
+      def boot_project_sandbox!(project)
+        before = project.current_sandbox_session_id
+        sandbox = project.ensure_sandbox!(confirm: ActiveModel::Type::Boolean.new.cast(params[:confirm]) == true, confirmed_by: current_user)
+        record_execution_usage if sandbox.id != before
+        sandbox
+      rescue ActiveRecord::RecordInvalid => e
+        raise unless e.record.is_a?(SandboxSession)
+
+        render json: { error: "The project's sandbox could not start: #{e.record.errors.full_messages.to_sentence}" },
+          status: :unprocessable_entity
+        nil
+      end
+    end
+  end
+end

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

@@ -11,21 +11,21 @@ module ActionAgent
       # own visitors should do so against its own endpoint, not one the
       # engine exposes on every host that mounts it.
 
-      before_action :set_recording, only: [ :show, :actions, :snapshot, :export, :handoff ]
+      before_action :require_dashboard_capture!, only: [ :create, :create_events ]
+      before_action :require_owner!, only: :create
+      before_action :set_recording, only: [ :show, :actions, :snapshot, :export, :handoff, :timeline, :events, :create_events ]
 
-      # 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
+      SENSITIVE_STATE_KEYS = SessionRecording::SENSITIVE_STATE_KEYS
+
+      # Recording event rows one page of #events returns at most, and the
+      # event bytes after which a page ends early.
+      EVENTS_PAGE_LIMIT = 100
+      EVENTS_PAGE_BYTES = 4.megabytes
 
       # GET /api/session_recordings
       # List recordings with optional filters
       def index
-        # Recordings the caller can reach, plus the shared demo. Ownership is
-        # a real column rather than a JSON metadata key, so this works on
-        # every adapter.
-        recordings = reachable_recordings.or(SessionRecording.where(name: "lander_demo")).recent
+        recordings = reachable_recordings.recent
 
         # Filter by status
         recordings = recordings.where(status: params[:status]) if params[:status].present?
@@ -79,25 +79,108 @@ module ActionAgent
       end
 
       # GET /api/session_recordings/:id/actions
-      # Get the action timeline for playback
+      # One page of the action timeline, in sequence order. Pass the last
+      # sequence received as after_sequence to get the next page; has_more
+      # says whether one exists. limit is 1..500, default 100.
       def actions
         actions = @recording.recording_actions.ordered
 
-        # Support pagination for large recordings
-        if params[:after_sequence].present?
-          actions = actions.where("sequence > ?", integer_param(:after_sequence, default: 0))
-        end
+        after_sequence = integer_param(:after_sequence)
+        actions = actions.where("sequence > ?", after_sequence) if after_sequence
 
-        limit = [ integer_param(:limit, default: 100), 500 ].min
-        actions = actions.limit(limit)
+        limit = clamped_param(:limit, default: 100, min: 1, max: 500)
+        # One row past the page tells whether another page follows.
+        page = actions.limit(limit + 1).to_a
+        has_more = page.size > limit
 
         render json: {
-          actions: actions.map(&:as_json_for_api),
-          has_more: actions.count == limit,
+          actions: page.first(limit).map(&:as_json_for_api),
+          has_more: has_more,
           total_actions: @recording.action_count
         }
       end
 
+      # GET /api/session_recordings/:id/timeline
+      # The recording's browser lane with the message, llm and tool lanes of
+      # its conversation or run (SessionTimeline).
+      def timeline
+        render json: RecordingEvent.generate_json(timeline: SessionTimeline.for_recording(@recording, timeline_scope).as_json)
+      end
+
+      # GET /api/session_recordings/:id/events
+      # The recording's events in time order, a page of rows at a time, with
+      # their payloads. rrweb only unless +kind+ names others (comma
+      # separated). +after+ is the id of the last row already read.
+      def events
+        kinds = params[:kind].to_s.split(",").map(&:strip) & RecordingEvent::KINDS
+        rows = @recording.recording_events.where(kind: kinds.presence || "rrweb").chronological
+        if params[:after].present?
+          cursor = @recording.recording_events.find_by(id: integer_param(:after))
+          return render(json: { error: "Unknown cursor" }, status: :unprocessable_entity) unless cursor
+
+          rows = rows.where(after_row(cursor))
+        end
+        limit = clamped_param(:limit, default: 20, min: 1, max: EVENTS_PAGE_LIMIT)
+        fetched = rows.limit(limit + 1).to_a
+        page = page_of_rows(fetched, limit)
+
+        render json: RecordingEvent.generate_json(
+          events: page.map { |row| event_row_json(row) },
+          has_more: fetched.size > page.size,
+          next_after: page.last&.id
+        )
+      end
+
+      # POST /api/session_recordings
+      # Starts the caller's recording of one visit to conversation
+      # +agent_context_id+ in the Run Agent workbench (`source: "dashboard"`),
+      # which the dashboard posts its rrweb batches to (201).
+      #
+      # Each visit gets a recording of its own. An rrweb stream replays only
+      # against the full snapshot it began with, so two tabs on one
+      # conversation need two recordings. The recording caps
+      # (ActionAgent.recording_limits) then bound one visit.
+      #
+      # 400 without a conversation id, 404 for a conversation of an agent the
+      # caller cannot reach. 401 when recordings have owners and the caller
+      # resolves to none, since the caller could not reach the recording
+      # afterwards.
+      def create
+        context_id = integer_param(:agent_context_id)
+        return render(json: { error: "agent_context_id is required" }, status: :bad_request) if context_id.nil?
+
+        context = AgentContext.for_agents(owner_agents).find(context_id)
+        owner = recording_owner
+        if owner.nil? && SessionRecording.owner_association
+          return render(json: { error: "Sign in to record this conversation" }, status: :unauthorized)
+        end
+
+        recording = SessionRecording.start!(agent_context: context, source: "dashboard", owner: owner)
+        render json: { recording: dashboard_recording_json(recording) }, status: :created
+      end
+
+      # POST /api/session_recordings/:id/events
+      # A batch of browser events (RecordingEventIngest) from a dashboard
+      # session, with the owner's credentials masked in it. A recorder holding
+      # the recording's ingest token posts to the same path, and is answered
+      # by RecordingEventIngestController.
+      #
+      # 503 when the credentials cannot be read: the batch is not stored
+      # without them masked.
+      def create_events
+        secrets =
+          begin
+            owner_credentials
+          rescue StandardError => e
+            Rails.logger.warn("[ActionAgent] credential lookup for a recording batch failed: #{e.class}: #{e.message}")
+            return render(json: { error: "The batch could not be checked for credentials", code: "credential_check_failed" },
+              status: :service_unavailable)
+          end
+
+        result = RecordingEventIngest.call(@recording, request.raw_post, secrets: secrets)
+        render json: result.body, status: result.status
+      end
+
       # GET /api/session_recordings/:id/snapshot/:action_id
       # Get a specific snapshot (screenshot or DOM)
       def snapshot
@@ -270,6 +353,7 @@ module ActionAgent
           render json: { error: "Not authorized" }, status: :forbidden
           return
         end
+        return unless authorize_action!(:manage_recordings, @recording)
 
         @recording.destroy!
         render json: { message: "Recording deleted" }
@@ -277,10 +361,9 @@ module ActionAgent
 
       private
 
-      # Scoped through can_manage_recording? rather than owned(): nothing in
-      # the engine writes user_id/account_id onto a recording, so an
-      # ownership scope would hide it from the person who made it. 404 rather
-      # than 403 so ids stay unenumerable.
+      # Opens a recording only when can_manage_recording? allows it, the
+      # reachability reachable_recordings lists by. 404 rather than 403 so
+      # ids stay unenumerable.
       def set_recording
         @recording = SessionRecording.find(params[:id])
         return if can_manage_recording?(@recording)
@@ -288,17 +371,30 @@ module ActionAgent
         not_found
       end
 
-      # What the list shows: recordings the caller owns, plus recordings made
-      # inside a sandbox the caller owns — the same reachability
-      # can_manage_recording? grants to a direct read, so a recording never
-      # opens by id while missing from the list. The second clause is what
-      # keeps recordings created before the owner column was written
-      # reachable.
-      def reachable_recordings
-        scope = owned(SessionRecording)
-        return scope if SessionRecording.owner_association.nil?
-
-        scope.or(SessionRecording.where(sandbox_session_id: owned(SandboxSession).select(:id)))
+      # Refuses the workbench's recordings and every batch a dashboard session
+      # posts when the host turned capture off.
+      def require_dashboard_capture!
+        return if ActionAgent.capture_dashboard_sessions?
+
+        render json: { error: "Session capture is turned off on this dashboard", code: "capture_disabled" }, status: :forbidden
+      end
+
+      # Whom a recording the caller starts belongs to: the record #owned
+      # scopes SessionRecording by, so the caller finds it again.
+      def recording_owner
+        case SessionRecording.owner_association
+        when :user then current_user
+        when :account then current_account
+        end
+      end
+
+      def dashboard_recording_json(recording)
+        {
+          id: recording.id,
+          agent_context_id: recording.agent_context_id,
+          source: recording.source,
+          status: recording.status
+        }
       end
 
       def can_manage_recording?(recording)
@@ -313,6 +409,41 @@ module ActionAgent
         false
       end
 
+      # The rows that sort after +row+ in RecordingEvent.chronological order.
+      def after_row(row)
+        table = RecordingEvent.arel_table
+        later_in_batch = table[:batch_index].gt(row.batch_index)
+          .or(table[:batch_index].eq(row.batch_index).and(table[:id].gt(row.id)))
+        table[:occurred_from].gt(row.occurred_from)
+          .or(table[:occurred_from].eq(row.occurred_from).and(later_in_batch))
+      end
+
+      # The first +limit+ of +rows+, ending early once EVENTS_PAGE_BYTES of
+      # events are in the page. Always at least one row.
+      def page_of_rows(rows, limit)
+        bytes = 0
+        rows.first(limit).take_while do |row|
+          fits = bytes.zero? || bytes + row.byte_size <= EVENTS_PAGE_BYTES
+          bytes += row.byte_size
+          fits
+        end
+      end
+
+      # rrweb events are returned as recorded, since a DOM attribute may carry
+      # any name and a stripped snapshot would not replay. Other kinds lose
+      # SessionRecording::SENSITIVE_STATE_KEYS, as they do in a timeline.
+      def event_row_json(row)
+        {
+          id: row.id,
+          kind: row.kind,
+          occurred_from: row.occurred_from.utc.iso8601(3),
+          occurred_to: row.occurred_to.utc.iso8601(3),
+          clock_offset_ms: row.clock_offset_ms,
+          event_count: row.event_count,
+          events: row.kind == "rrweb" ? row.events : SessionRecording.without_sensitive_state(row.events)
+        }
+      end
+
       def recording_summary(recording)
         {
           id: recording.id,

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

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+module ActionAgent
+  module Api
+    # The sessions a caller can replay (SessionIndex), and the timelines of
+    # sessions that need no recording: a conversation, a run, or the run that
+    # replayed an evaluation scenario. Each timeline adds the browser lane of
+    # any recording linked to it. See SessionTimeline.
+    class SessionsController < BaseController
+      # A filter value the index cannot read.
+      class InvalidFilter < ArgumentError; end
+
+      before_action :require_owner!, only: :index
+
+      # GET /api/sessions
+      #
+      # Parameters, each optional:
+      #   agent_id  one of the caller's agents
+      #   user      "me": sessions whose runs ran on behalf of the caller
+      #             (#agent_actor), and the caller's own browser recordings
+      #   source    dashboard, evaluation or agent
+      #   outcome   failed or passed
+      #   from, to  last activity in [from, to), ISO 8601 times or dates
+      #   before    the next_before of the previous page
+      #   per_page  25 by default, at most 100
+      def index
+        index = SessionIndex.new(
+          agents: owner_agents, recordings: reachable_recordings, filters: index_filters,
+          per_page: clamped_param(:per_page, default: SessionIndex::DEFAULT_PER_PAGE, min: 1, max: SessionIndex::MAX_PER_PAGE),
+          before: params[:before].is_a?(String) ? params[:before] : nil
+        )
+        render json: index.as_json
+      rescue InvalidFilter, SessionIndex::InvalidCursor => e
+        render json: { error: e.message }, status: :unprocessable_entity
+      end
+
+      # GET /api/sessions/:kind/:id/timeline, where +kind+ is context, run or
+      # scenario_result.
+      def timeline
+        timeline =
+          case params[:kind]
+          when "context" then SessionTimeline.for_context(owned_context, timeline_scope)
+          when "run" then SessionTimeline.for_run(owned_run(params[:id]), timeline_scope)
+          when "scenario_result" then SessionTimeline.for_run(scenario_result_run, timeline_scope)
+          end
+
+        render json: RecordingEvent.generate_json(timeline: timeline.retitle(params[:kind], integer_param(:id)).as_json)
+      end
+
+      private
+
+      # "Mine" compares the identity runs record (#agent_actor), which a host
+      # may resolve to a record other than its signed-in user.
+      def index_filters
+        mine = choice_param(:user, %w[me]).present?
+        SessionIndex::Filters.new(
+          agent_id: integer_param(:agent_id),
+          actor: mine ? agent_actor || SessionIndex::NO_ACTOR : nil,
+          user: mine ? current_user : nil,
+          source: choice_param(:source, SessionIndex::SOURCES),
+          outcome: choice_param(:outcome, SessionIndex::OUTCOMES),
+          from: time_param(:from),
+          to: time_param(:to)
+        )
+      end
+
+      # +name+'s value when it is one of +choices+, nil when absent.
+      # @raise [InvalidFilter] for any other value
+      def choice_param(name, choices)
+        value = params[name]
+        return nil if value.blank?
+        return value if value.is_a?(String) && choices.include?(value)
+
+        raise InvalidFilter, "#{name} must be one of: #{choices.join(', ')}"
+      end
+
+      # +name+ as a Time: an ISO 8601 time, or a date read as its first moment
+      # in the app's time zone. Nil when absent.
+      # @raise [InvalidFilter] for anything else
+      def time_param(name)
+        value = params[name]
+        return nil if value.blank?
+        raise ArgumentError unless value.is_a?(String)
+
+        value.match?(/\A\d{4}-\d{2}-\d{2}\z/) ? Date.iso8601(value).in_time_zone : Time.iso8601(value)
+      rescue ArgumentError
+        raise InvalidFilter, "#{name} must be an ISO 8601 time or date"
+      end
+
+      def owned_context
+        AgentContext.for_agents(owner_agents).find(params[:id])
+      end
+
+      def owned_run(id)
+        AgentRun.where(agent: owner_agents).find(id)
+      end
+
+      # The run a scenario result was replayed by. A result belongs to the
+      # caller through its evaluation's agent.
+      def scenario_result_run
+        evaluations = Evaluation.where(agent: owner_agents)
+        result = EvaluationScenarioResult
+          .where(evaluation_run: EvaluationRun.where(evaluation: evaluations))
+          .find(params[:id])
+        raise ActiveRecord::RecordNotFound unless result.agent_run_id
+
+        owned_run(result.agent_run_id)
+      end
+    end
+  end
+end