actionagent 1.8.1 → 1.9.0

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

@@ -0,0 +1,280 @@
+# frozen_string_literal: true
+
+module ActionAgent
+  module Api
+    # GitHub App installations (Settings -> Integrations): installing the App
+    # and linking the installation, choosing the repositories checkout
+    # sandboxes may use on it, and unlinking it. Unlinking leaves the App
+    # installed on GitHub.
+    #
+    # #install and #callback are browser navigations rather than fetches, so
+    # they answer with redirects back into the dashboard's Settings view,
+    # reporting the outcome as ?github_app=<outcome>.
+    class GithubInstallationsController < BaseController
+      STATE_SESSION_KEY = :action_agent_github_app_state
+
+      before_action :require_owner!
+      before_action :require_github_app!, except: [ :index, :destroy ]
+      before_action :set_installation, only: [ :repositories, :update, :destroy ]
+      # The repository listing too: an installation can reach repositories a
+      # member cannot see on GitHub, and the listing exists only to choose
+      # them.
+      before_action :authorize_github!, only: [ :install, :callback, :repositories, :update, :destroy ]
+
+      # Later handlers win, so the subclasses are registered last.
+      rescue_from GithubClient::Error, with: :github_unavailable
+      rescue_from GithubClient::Unauthorized, with: :github_app_rejected
+      rescue_from GithubClient::InstallationUnavailable, with: :installation_unavailable
+
+      # GET /api/github_installations
+      def index
+        render json: {
+          configured: ActionAgent.github_app_configured?,
+          installations: owned(GithubInstallation).order(:id).map(&:as_summary)
+        }
+      end
+
+      # GET /api/github_installations/:id/repositories — what the
+      # installation reaches, each marked with whether the owner selected it.
+      def repositories
+        selected = @installation.repository_names.map(&:downcase).to_set
+
+        render json: {
+          repositories: @installation.listing_client.installation_repositories.map do |repo|
+            repo.merge("selected" => selected.include?(repo["full_name"].downcase))
+          end
+        }
+      end
+
+      # PATCH /api/github_installations/:id { repositories: ["owner/name", ...] }
+      #
+      # Only names GitHub lists for the installation are kept: the selection
+      # is what a checkout sandbox trusts, so it is never taken from the
+      # client.
+      def update
+        # Not params.require: an empty list (clear the selection) is valid.
+        requested = params[:repositories]
+        unless requested.is_a?(Array) && requested.all? { |name| name.is_a?(String) }
+          return render json: { error: "repositories must be a list of owner/name strings" }, status: :bad_request
+        end
+
+        available = @installation.listing_client.installation_repositories.index_by { |repo| repo["full_name"].downcase }
+        unknown = requested.reject { |name| available.key?(name.downcase) }
+        if unknown.any?
+          return render json: { error: "Not reachable through this GitHub App installation: #{unknown.join(', ')}" },
+            status: :unprocessable_entity
+        end
+
+        @installation.update!(repositories: requested.map { |name| available.fetch(name.downcase) }.uniq { |repo| repo["id"] })
+        render json: { installation: @installation.as_summary }
+      end
+
+      # DELETE /api/github_installations/:id
+      def destroy
+        @installation.destroy!
+        head :no_content
+      end
+
+      # GET /api/github_installations/install — sends the admin to GitHub to
+      # install the App on the repositories they choose.
+      def install
+        redirect_to GithubClient.installation_url(state: issue_state), allow_other_host: true
+      end
+
+      # GET /api/github_installations/callback?installation_id=&setup_action=&code=&state=
+      #
+      # Where GitHub returns from an installation, and from the App's user
+      # authorization. A code is exchanged only together with a state this
+      # session issued for the signed-in user. Two returns go through the
+      # App's user authorization with a fresh state first: one with no state
+      # (an install started on GitHub), and one from #install that carries no
+      # code (GitHub returning from a change to an installation that already
+      # existed).
+      def callback
+        # Single use: read and cleared before anything else can fail.
+        issued = session.delete(STATE_SESSION_KEY)
+        return redirect_to_settings(github_app: "denied") if params[:error].present?
+        # A member asked an organization owner to install the App. GitHub
+        # installs nothing until the owner approves, so there is nothing to
+        # link yet.
+        return redirect_to_settings(github_app: "pending") if params[:setup_action] == "request"
+
+        if params[:state].blank?
+          return start_user_authorization(installation_id_param) if installation_id_param
+
+          return redirect_to_settings(github_app: "invalid_state")
+        end
+        return redirect_to_settings(github_app: "invalid_state") unless issued_here?(issued, params[:state])
+
+        installation_id = issued["installation_id"] || installation_id_param
+        return redirect_to_settings(github_app: "missing_installation") unless installation_id
+
+        unless params[:code].is_a?(String) && params[:code].present?
+          # A state that already carries an installation was issued for the
+          # user authorization, which has nothing left to retry.
+          return redirect_to_settings(github_app: "missing_code") if issued.key?("installation_id")
+
+          return start_user_authorization(installation_id)
+        end
+
+        redirect_to_settings(github_app: link_installation(installation_id, params[:code]))
+      rescue GithubClient::Error => e
+        Rails.logger.warn("[ActionAgent] GitHub App installation callback failed: #{e.message}")
+        redirect_to_settings(github_app: "error")
+      end
+
+      private
+
+      # Links +installation_id+ to the owner when the user the code belongs
+      # to administers the account the App is installed on, and answers the
+      # outcome. The user token is held in this method only, for the checks,
+      # and is never stored or logged.
+      def link_installation(installation_id, code)
+        grant = GithubClient.exchange_code(
+          code: code, redirect_uri: callback_url,
+          client_id: ActionAgent.github_app_client_id, client_secret: ActionAgent.github_app_client_secret
+        )
+        github = GithubClient.new(grant[:access_token])
+        github_user = github.user
+
+        # The installation_id GitHub put in the URL is only a claim: it has
+        # to be one this user can reach.
+        installation = github.user_installations.find { |candidate| candidate["id"].to_i == installation_id }
+        return "not_found" unless installation
+        return "not_admin" unless administers?(github, github_user, installation["account"])
+
+        record = GithubInstallation.find_by(installation_id: installation_id)
+        return "taken" if record && !owned(GithubInstallation).exists?(record.id)
+
+        record ||= owned(GithubInstallation).new(installation_id: installation_id)
+        record.user_id = current_user.id if ActionAgent.user_class.present? && current_user.respond_to?(:id)
+        record.assign_from_github(installation)
+        record.save!
+        "linked"
+      # Another owner linked the same installation between the lookup and
+      # the save.
+      rescue ActiveRecord::RecordNotUnique
+        "taken"
+      rescue ActiveRecord::RecordInvalid => e
+        return "taken" if e.record.errors.of_kind?(:installation_id, :taken)
+
+        Rails.logger.warn("[ActionAgent] GitHub App installation #{installation_id} was not linked: #{e.record.errors.full_messages.to_sentence}")
+        "error"
+      end
+
+      # Whether +github_user+ administers +account+: is that user account, or
+      # an active admin of that organization.
+      def administers?(github, github_user, account)
+        account = {} unless account.is_a?(Hash)
+
+        case account["type"]
+        when "User"
+          github_user["id"].present? && account["id"].to_i == github_user["id"].to_i
+        when "Organization"
+          membership = github.organization_membership(account["login"].to_s)
+          membership.is_a?(Hash) && membership["state"] == "active" && membership["role"] == "admin"
+        else
+          false
+        end
+      end
+
+      # A fresh single-use state bound to this session, the signed-in user and
+      # the owner. +installation_id+ is carried for the user authorization of
+      # an install started on GitHub, which returns without one.
+      def issue_state(installation_id: nil)
+        state = SecureRandom.urlsafe_base64(32)
+        session[STATE_SESSION_KEY] = {
+          "state" => state,
+          "user_id" => current_user_id,
+          "owner_id" => current_owner_id,
+          "installation_id" => installation_id
+        }.compact
+        state
+      end
+
+      def issued_here?(issued, given)
+        issued.is_a?(Hash) && issued["state"].is_a?(String) && given.is_a?(String) &&
+          ActiveSupport::SecurityUtils.secure_compare(issued["state"], given) &&
+          issued["user_id"] == current_user_id && issued["owner_id"] == current_owner_id
+      end
+
+      def start_user_authorization(installation_id)
+        url = GithubClient.authorize_url(
+          redirect_uri: callback_url, state: issue_state(installation_id: installation_id),
+          client_id: ActionAgent.github_app_client_id, scope: nil
+        )
+        redirect_to url, allow_other_host: true
+      end
+
+      def installation_id_param
+        value = params[:installation_id]
+        value.to_i if value.is_a?(String) && value.match?(/\A[1-9]\d{0,18}\z/)
+      end
+
+      def current_user_id
+        current_user.respond_to?(:id) ? current_user.id.to_s : nil
+      end
+
+      def current_owner_id
+        current_owner.respond_to?(:id) ? current_owner.id.to_s : nil
+      end
+
+      def set_installation
+        @installation = owned(GithubInstallation).find(params[:id])
+      end
+
+      # Asks about the installation acted on, or about an unsaved one when
+      # #install or #callback may create it.
+      def authorize_github!
+        authorize_action!(:manage_github, @installation || owned(GithubInstallation).new)
+      end
+
+      # #install and #callback return a refusal to Settings like their other
+      # outcomes. The callback's state is discarded with it.
+      def permission_denied(action)
+        return super unless navigation?
+
+        session.delete(STATE_SESSION_KEY)
+        redirect_to_settings(github_app: "forbidden")
+      end
+
+      def require_github_app!
+        return if ActionAgent.github_app_configured?
+        return redirect_to_settings(github_app: "not_configured") if navigation?
+
+        render json: { error: "No GitHub App is configured on this dashboard", code: "github_app_not_configured" },
+          status: :not_found
+      end
+
+      def navigation?
+        action_name.in?(%w[install callback])
+      end
+
+      def callback_url
+        "#{request.base_url}#{request.script_name}/api/github_installations/callback"
+      end
+
+      def redirect_to_settings(**query)
+        redirect_to "#{request.script_name}/settings?#{{ tab: 'integrations' }.merge(query).to_query}"
+      end
+
+      def github_unavailable(exception)
+        render json: { error: exception.message }, status: :bad_gateway
+      end
+
+      def github_app_rejected
+        render json: { error: "GitHub rejected the GitHub App's credentials. Check github_app_id and github_app_private_key." },
+          status: :bad_gateway
+      end
+
+      def installation_unavailable(exception)
+        state = exception.reason == :suspended ? "is suspended" : "was removed"
+        render json: {
+          error: "This GitHub App installation #{state} on GitHub. Reinstall the GitHub App, or unlink it.",
+          reinstall_required: true,
+          installation: @installation&.reload&.as_summary
+        }, status: :unprocessable_entity
+      end
+    end
+  end
+end

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

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module ActionAgent
+  module Api
+    # The requests for input paused runs are waiting on, and the answers that
+    # resume them.
+    #
+    # Every request is read through the runs the caller can see
+    # (owner_input_requests), so one outside them answers 404. Answering or
+    # declining asks InputRequest#answerable_by? (403 when denied), and the
+    # request must still be pending and unexpired (409). Neither is allowed
+    # while agent execution is disabled (403).
+    class InputRequestsController < BaseController
+      LIST_LIMIT = 100
+
+      before_action :require_owner!
+      # Settling a pause resumes its run, which calls the model.
+      before_action :require_execution_enabled!, only: [ :answer, :decline ]
+      before_action :set_input_request, only: [ :answer, :decline ]
+      before_action :authorize_answer!, only: [ :answer, :decline ]
+
+      # GET /api/input_requests
+      #
+      # Pending requests unless `status` names another (or `all`), filtered by
+      # `agent_id` and `run_id`, newest first. Overdue requests are expired
+      # first, so none is listed as pending.
+      def index
+        InputRequest.expire_overdue!(owner_input_requests)
+        scope = owner_input_requests.for_listing.includes(:subject).recent
+        status = params[:status].presence || "pending"
+        unless status == "all"
+          return render json: { error: "Unknown status #{status.to_s.truncate(32)}" }, status: :bad_request unless InputRequest.statuses.key?(status)
+
+          scope = scope.where(status: status)
+        end
+        scope = scope.where(subject_type: AgentRun.polymorphic_name, subject_id: params[:run_id].to_s) if params[:run_id].present?
+        if params[:agent_id].present?
+          scope = scope.where(subject_type: AgentRun.polymorphic_name, subject_id: AgentRun.where(agent_id: params[:agent_id].to_s).select(:id))
+        end
+
+        render json: { input_requests: scope.limit(LIST_LIMIT).map { |request| InputRequestSerializer.call(request) } }
+      end
+
+      # POST /api/input_requests/:id/answer
+      #
+      # `answer` is the answer. A `confirm` request is approved by `true` or
+      # by no answer, and declined by `false`.
+      def answer
+        settle { @input_request.answer!(params[:answer], user: current_user) }
+      end
+
+      # POST /api/input_requests/:id/decline
+      def decline
+        settle { @input_request.decline!(user: current_user) }
+      end
+
+      private
+
+      def set_input_request
+        @input_request = owner_input_requests.find(params[:id])
+      end
+
+      def authorize_answer!
+        permission_denied(:answer_input_request) unless @input_request.answerable_by?(current_user)
+      end
+
+      def settle
+        yield
+        render json: { input_request: InputRequestSerializer.call(@input_request) }
+      rescue InputRequest::Conflict => e
+        render json: { error: e.message, code: "conflict", status: @input_request.reload.status }, status: :conflict
+      rescue InputRequest::InvalidAnswer => e
+        render json: { error: e.message, code: "invalid_answer" }, status: :unprocessable_entity
+      end
+    end
+  end
+end

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

@@ -116,14 +116,20 @@ module ActionAgent
         @owner
       end
 
-      # The key's user when it records one. Otherwise the owner, unless the
+      # The key's creator when it records one. Otherwise the owner, unless the
       # owner is an account: a tenant is never a user.
       def current_user
-        return @api_key.user if @api_key.respond_to?(:user) && @api_key.user
+        return key_creator if key_creator
 
         ActionAgent.multi_tenant? ? nil : @owner
       end
 
+      def key_creator
+        return @key_creator if defined?(@key_creator)
+
+        @key_creator = @api_key&.creator
+      end
+
       # The agents this key can reach. A key belongs to whoever owns it, and
       # a single-user install has no owner, so the key reaches every agent
       # the dashboard holds.
@@ -133,9 +139,9 @@ module ActionAgent
 
       # The caller an MCP-invoked run executes on behalf of.
       #
-      # The key's owner is the identity that authenticated this request, so
-      # it is the default; a host issuing keys per end user overrides it
-      # with ActionAgent.agent_actor_resolver, which is handed this
+      # The default is the user who created the key when the key records
+      # one, else the key's owner. A host issuing keys per end user overrides
+      # it with ActionAgent.agent_actor_resolver, which is handed this
       # controller and can read the request however it likes.
       #
       # The agent's own callbacks decide what the actor may do — that is the
@@ -147,7 +153,7 @@ module ActionAgent
           if (resolver = ActionAgent.agent_actor_resolver)
             resolver.arity.zero? ? resolver.call : resolver.call(self)
           else
-            @api_key.respond_to?(:user) && @api_key.user ? @api_key.user : @owner
+            key_creator || @owner
           end
       end
 
@@ -178,11 +184,19 @@ module ActionAgent
                "resource returns the agent's live scorecard."
         return text unless ActionAgent.mcp_dashboard_tools?
 
-        "#{text} The evaluations_, evaluation_runs_ and traces_ tools work on this account's evaluations and " \
-          "telemetry: edit the agent in your own checkout, start a run with evaluations_run (pass sandbox_id to run " \
-          "against a checkout sandbox), poll evaluation_runs_get for its status, results and fix items, compare runs " \
-          "with evaluation_runs_compare, and read a failing result's trace with traces_get (traces_search finds " \
-          "recent failures)."
+        "#{text} The evaluations_, scenarios_, explorations_, evaluation_runs_ and traces_ tools work on this " \
+          "account's evaluations and telemetry: create an evaluation with evaluations_create and add scenarios to it " \
+          "with scenarios_merge, which never removes or disables a scenario it was not given (neither tool runs " \
+          "anything), or submit the questions you found by exploring a project's app with explorations_submit, for a " \
+          "person to review and accept on the dashboard (it returns each candidate's verdict), edit the agent " \
+          "in your own checkout, start a run with evaluations_run (pass sandbox_id to run against a checkout " \
+          "sandbox), poll evaluation_runs_get for its status, results and fix items, compare runs with " \
+          "evaluation_runs_compare, and read a failing result's trace with traces_get (traces_search finds recent " \
+          "failures). A run_<slug> call that pauses to ask for input returns its input request ids: " \
+          "input_requests_list shows what paused runs are waiting on, and input_requests_answer answers a text or " \
+          "choice request. Scenarios kept as a YAML catalog of products and sets (an .activeagents/evals file) are " \
+          "imported with catalogs_import, listed with catalogs_list, and one set is run as an evaluation named " \
+          "catalog/product/set with catalog_set_run (pass project_id to run against a project's running sandbox)."
       end
 
       MESSAGE_INPUT_SCHEMA = {
@@ -261,7 +275,9 @@ module ActionAgent
         run = agent.test_execute(message, action: action, actor: agent_actor)
         ActionAgent.record_usage(@owner, :execution)
 
-        if run.failed?
+        if run.awaiting_input?
+          awaiting_input_result(run)
+        elsif run.failed?
           # A refusal is not a result. An agent that declined on this
           # caller's behalf answers as a JSON-RPC error, so the client sees
           # "not allowed" rather than an empty, confident answer — the
@@ -283,6 +299,24 @@ module ActionAgent
         end
       end
 
+      # A run that paused to ask a person: its id, status and pending
+      # requests, which the dashboard, or input_requests_answer for a text or
+      # choice request, answers.
+      def awaiting_input_result(run)
+        requests = run.pending_input_requests.to_a
+        lines = requests.map { |request| "- input request #{request.id} (#{request.kind}): #{request.prompt}" }
+
+        {
+          content: [ { type: "text", text: "The agent paused to ask for input:\n#{lines.join("\n")}" } ],
+          structuredContent: {
+            run_id: run.id,
+            trace_id: run.trace_id,
+            status: run.status,
+            input_request_ids: requests.map(&:id)
+          }
+        }
+      end
+
       # Calls a schema tool directly, as this key's caller. No generation runs,
       # so neither the execution switch nor the execution quota applies: this
       # is a read of the host's records through the host's own scope.

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

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module ActionAgent
+  module Api
+    # The members of the signed-in owner, for the Organization view's Team
+    # Members table. The engine keeps no memberships: the host lists them
+    # through ActionAgent.members_resolver, and each member carries only
+    # id, name, email and role.
+    class MembersController < BaseController
+      before_action :require_owner!
+
+      # GET /api/members — { members: [{ id, name, email, role }] }. With no
+      # resolver, or one that raised, the signed-in user alone: as "owner" on
+      # a single-tenant install, with no role on a multi-tenant one, where
+      # the engine cannot know it.
+      def index
+        members = ActionAgent.members_for(current_owner) || signed_in_member
+
+        render json: { members: members }
+      end
+
+      private
+
+      def signed_in_member
+        return [] if current_user.nil?
+
+        [ {
+          id: current_user.try(:id),
+          name: current_user.try(:display_name) || current_user.try(:name) || current_user.try(:email_address),
+          email: current_user.try(:email_address) || current_user.try(:email),
+          role: ActionAgent.multi_tenant? ? nil : "owner"
+        } ]
+      end
+    end
+  end
+end

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

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module ActionAgent
+  module Api
+    # Starts the engine's explorer on a project:
+    #
+    #   POST /api/projects/:project_id/explorations { budget: { minutes:, steps:, cost: } }
+    #
+    # The host's quota is asked about :exploration first, and a denial
+    # answers 402 with nothing started. Otherwise the project's ready
+    # sandbox gets a browser (started headless with the project's saved
+    # sign-in when none runs, which the quota is asked about as
+    # :browser_minutes), the explorer's run and the exploration are created,
+    # :exploration usage is recorded once, and ExplorationJob walks the app.
+    # An explorer exploration of the project that is still walking answers
+    # 409. The budget defaults to Exploration::DEFAULT_BUDGET.
+    class ProjectExplorationsController < BaseController
+      include ProjectBrowser
+
+      before_action :require_owner!
+      before_action :require_execution_enabled!
+      before_action :set_project
+
+      rescue_from Exploration::InvalidCandidate, with: :invalid_budget
+
+      def create
+        budget = Exploration.budget_from(params[:budget])
+        enforce_quota!(:exploration)
+        return if performed?
+
+        unless @project.target_agent
+          return render json: { error: "Choose the agent to evaluate first", code: "no_target" }, status: :conflict
+        end
+        if Exploration.where(project_id: @project.id, source: "explorer", status: %w[pending running]).exists?
+          return render json: { error: "An exploration of this project is already running", code: "exploration_running" },
+            status: :conflict
+        end
+
+        sandbox = ready_project_sandbox!(@project) or return
+        sandbox, started = ensure_project_browser!(@project, sandbox)
+        return if performed?
+
+        exploration = create_exploration!(sandbox, budget)
+        ActionAgent.record_usage(current_owner, :exploration)
+        ExplorationJob.perform_later(exploration.id, started)
+
+        render json: { exploration: exploration.summary }, status: :created
+      end
+
+      private
+
+      def set_project
+        @project = owned(Project).find(params[:project_id])
+      end
+
+      def create_exploration!(sandbox, budget)
+        agent = @project.explorer_agent!
+        Exploration.transaction do
+          run = agent.agent_runs.create!(
+            input_prompt: "Explore #{@project.repository}, starting at #{@project.start_url}.",
+            input_params: AgentRun.params_with_actor({}, current_user).merge(
+              AgentRun::SANDBOX_PARAM => sandbox.runtime_server_key, AgentRun::BROWSER_PARAM => sandbox.browser_server_key
+            ),
+            trace_id: SecureRandom.uuid,
+            status: :pending
+          )
+          exploration = Exploration.build_for(project: @project, source: "explorer", status: "pending", budget: budget)
+          exploration.assign_attributes(agent_run: run, sandbox_session: sandbox,
+            session_recording: SessionRecording.recording.where(sandbox_session_id: sandbox.id).order(:id).last)
+          exploration.save!
+          exploration
+        end
+      end
+
+      def invalid_budget(exception)
+        render json: { error: exception.message }, status: :unprocessable_entity
+      end
+    end
+  end
+end