actionagent 1.8.0 → 1.9.0

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

@@ -7,6 +7,7 @@ module ActionAgent
 
       # GET /api/runs/:id
       def show
+        @run.expire_overdue_input_requests!
         render json: {
           run: run_json(@run),
           messages: interaction_messages(@run),
@@ -28,7 +29,7 @@ module ActionAgent
       def index
         # Scoped to the caller's own agents: this listed (and counted) every
         # run in the database regardless of who owned it.
-        scope = AgentRun.includes(:agent).with_attachments.where(agent: owner_agents).recent
+        scope = AgentRun.includes(:agent, :pending_input_requests).with_attachments.where(agent: owner_agents).recent
 
         scope = scope.where(agent_id: params[:agent_id]) if params[:agent_id].present?
         scope = scope.where(status: params[:status]) if params[:status].present?
@@ -124,6 +125,7 @@ module ActionAgent
           output_tokens: run.output_tokens,
           total_tokens: run.total_tokens,
           error_message: run.error_message,
+          input_requests: run.pending_input_requests.map { |request| InputRequestSerializer.call(request) },
           trace_id: run.trace_id,
           attachments: run.attachment_manifest,
           context_id: run.context_id,

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

@@ -544,6 +544,7 @@ module ActionAgent
           action_prompts: [ :name, :prompt, :expose_as_tool ],
           instruction_sets: [],
           tools: [],
+          approval_required_tools: [],
           model_config: {},
           response_format: {}
         )

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

@@ -15,8 +15,15 @@ module ActionAgent
       end
 
       # POST /api/api_keys
+      #
+      # The key records the user who created it, so a call made with an
+      # account's key acts as that user rather than as the whole account.
       def create
-        api_key = owned(ApiKey).create!(name: params.require(:name))
+        api_key = owned(ApiKey).new(name: params.require(:name))
+        api_key.user_id = current_user.id if ActionAgent.user_class.present? && current_user.respond_to?(:id)
+        return unless authorize_action!(:manage_api_keys, api_key)
+
+        api_key.save!
 
         render json: {
           api_key: serialize(api_key).merge(token: api_key.token)
@@ -25,7 +32,10 @@ module ActionAgent
 
       # DELETE /api/api_keys/:id
       def destroy
-        owned(ApiKey).find(params[:id]).destroy!
+        api_key = owned(ApiKey).find(params[:id])
+        return unless authorize_action!(:manage_api_keys, api_key)
+
+        api_key.destroy!
         head :no_content
       end
 

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

@@ -17,7 +17,8 @@ module ActionAgent
     # 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
+    # evaluation report collector (Api::EvaluationReportsController), a
+    # recording's event ingest (Api::RecordingEventIngestController) and the
     # MCP facade (Api::MCPController) — are exempt.
     class BaseController < ActionAgent::ApplicationController
       # Rails 8.2 verifies forgery protection from the browser's Sec-Fetch-Site
@@ -60,9 +61,11 @@ module ActionAgent
       # nothing owns) come back unfiltered.
       # An unresolved owner scopes to nothing rather than to
       # `where(id: nil)`, which would match every unowned row and leak them
-      # across tenants.
+      # across tenants. Only the rows the model's .owned_rows admits are
+      # returned, so a personal provider key never comes back from here.
       def owned(relation)
         klass = relation.respond_to?(:klass) ? relation.klass : relation
+        relation = relation.merge(klass.owned_rows) if klass.respond_to?(:owned_rows)
 
         case klass.owner_association
         when :account then current_account ? relation.where(account_id: current_account.id) : relation.none
@@ -78,12 +81,54 @@ module ActionAgent
         ActionAgent.agents_for(current_owner)
       end
 
+      # The requests for input the caller can see: those of the runs of
+      # owner_agents, the runs `GET /api/runs/:id` shows.
+      def owner_input_requests
+        InputRequest.where(subject_type: AgentRun.polymorphic_name, subject_id: AgentRun.where(agent: owner_agents).select(:id))
+      end
+
       # Reported traces visible to the caller. Scoped to the tenant in a
       # multi-tenant install; every trace otherwise.
       def owned_traces
         ActionAgent.trace_model.for_account(current_account)
       end
 
+      # The recordings the caller may open: those the caller owns, plus those
+      # made inside a sandbox the caller owns. 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)))
+      end
+
+      # What a session timeline may reach on the caller's behalf.
+      def timeline_scope
+        SessionTimeline::Scope.new(agents: owner_agents, traces: owned_traces, recordings: reachable_recordings)
+      end
+
+      # Rows read per kind of credential by #owner_credentials.
+      OWNER_CREDENTIAL_LIMIT = 100
+
+      # Returns the credentials the caller owns, for masking with
+      # SecretScrubber: provider keys, GitHub tokens, checkout sandboxes'
+      # runtime tokens, dashboard API keys (newest first) and the owner's
+      # telemetry key. Raises what a lookup raises, such as a credential that
+      # cannot be decrypted, so each caller decides whether to go on without
+      # the list.
+      # @return [Array<String>]
+      def owner_credentials
+        @owner_credentials ||= [
+          *owned(ProviderKey).limit(OWNER_CREDENTIAL_LIMIT).pluck(:credential, :api_key).flatten,
+          *owned(GithubConnection).limit(OWNER_CREDENTIAL_LIMIT).pluck(:access_token),
+          *owned(SandboxSession).where.not(runtime_mcp_token: nil).order(id: :desc).limit(OWNER_CREDENTIAL_LIMIT).pluck(:runtime_mcp_token),
+          *owned(ApiKey).order(id: :desc).limit(OWNER_CREDENTIAL_LIMIT).pluck(:token),
+          current_owner.try(:telemetry_api_key)
+        ].compact
+      end
+
       # The caller an agent run executes on behalf of.
       #
       # The host's seam first (ActionAgent.agent_actor_resolver), then the
@@ -116,6 +161,22 @@ module ActionAgent
         render json: { error: "No account" }, status: :unauthorized
       end
 
+      # Returns whether the signed-in user may perform +action+ (one of
+      # ActionAgent::PERMISSION_ACTIONS) on +subject+, per
+      # ActionAgent.permission_checker. When not, renders the refusal first,
+      # so a caller returns unless this is true.
+      def authorize_action!(action, subject)
+        return true if ActionAgent.permitted?(current_user, action, subject)
+
+        permission_denied(action)
+        false
+      end
+
+      def permission_denied(action)
+        render json: { error: "You do not have permission to do this", code: "forbidden", permission: action },
+          status: :forbidden
+      end
+
       # Asks the host app whether this owner may do +kind+ (:execution or
       # :trace_ingest). Unlimited unless the app said otherwise.
       def enforce_quota!(kind)

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

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module ActionAgent
+  module Api
+    class ClaudeLoginsController < BaseController
+      DISCONNECTED = { status: "disconnected", logged_in: false, auth_method: nil }.freeze
+      # Where a sign-in stops without a login and without leaving the CLI's
+      # config behind. "completed" is not one: a CLI that completed with
+      # another kind of account still holds that credential until logout.
+      ENDED = %w[expired failed cancelled disconnected].freeze
+
+      before_action :require_owner!
+      before_action :require_execution_enabled!
+      before_action :set_sandbox
+
+      # Polled while the sign-in dialog is open, so it takes no lock: the
+      # fix verification holds the sandbox's row while the runtime restarts.
+      def show
+        return render json: { login: DISCONNECTED } unless mine?
+
+        login = orchestrator.claude_login_status(@sandbox)
+        # A sign-in that ended without a login leaves no credential behind
+        # (the supervisor removes the config), so it stops holding the sandbox.
+        @sandbox.update_columns(claude_login_user_id: nil) if ended?(login)
+        render json: { login: login }
+      end
+
+      def create
+        login = nil
+        @sandbox.with_lock do
+          unless @sandbox.claude_login_user_id.nil? || mine? || ended?(orchestrator.claude_login_status(@sandbox))
+            return render json: { error: "This sandbox has another member's login. Start your own sandbox or use the account API key." }, status: :conflict
+          end
+          return busy if @sandbox.code_sessions.where(status: [ :queued, :running ]).exists?
+          login = orchestrator.start_claude_login(@sandbox)
+          @sandbox.update!(claude_login_user_id: current_user.id)
+        end
+        render json: { login: login }, status: :accepted
+      end
+
+      def code
+        # Filtered by engine.filter_parameters. Never interpolate this value
+        # into an error, an event, a model, or a log line.
+        login = nil
+        @sandbox.with_lock do
+          return forbidden unless mine?
+          login = orchestrator.submit_claude_login_code(@sandbox, params[:claude_login_code])
+        end
+        render json: { login: login }
+      end
+
+      def destroy
+        @sandbox.with_lock do
+          return forbidden unless mine?
+          return busy if @sandbox.code_sessions.where(status: [ :queued, :running ]).exists?
+          orchestrator.claude_logout(@sandbox)
+          @sandbox.update!(claude_login_user_id: nil)
+        end
+        render json: { login: DISCONNECTED }
+      end
+
+      rescue_from LocalSandboxBackend::Error, SandboxOrchestrator::UnsupportedBackendError, SandboxOrchestrator::BackendError do
+        # Backend errors may include command output; login endpoints expose
+        # a fixed message, never raw exception text.
+        render json: { error: "Claude sign-in could not complete. Check that Claude Code is installed, then start again." }, status: :unprocessable_entity
+      end
+
+      private
+
+      def set_sandbox
+        scope = owned(SandboxSession)
+        scope = scope.where(account_id: current_account.id) if current_account
+        @sandbox = scope.find_by!(session_id: params[:sandbox_id])
+        unless ClaudeCodeAuth.sandbox_login? && current_user.respond_to?(:id) && current_user.id.present?
+          return render json: { error: "Sandbox subscription login requires a signed-in user and :sandbox_login mode" }, status: :unprocessable_entity
+        end
+        if (refusal = ClaudeCodeAuth.backend_refusal(orchestrator))
+          return render json: { error: refusal }, status: :unprocessable_entity
+        end
+        unless @sandbox.app_runtime? && @sandbox.ready? && @sandbox.active?
+          render json: { error: "Sign in after this checkout sandbox is ready" }, status: :unprocessable_entity
+        end
+        response.headers["Cache-Control"] = "no-store"
+      end
+
+      def mine? = @sandbox.claude_login_user_id == current_user.id
+      def ended?(login) = !login[:logged_in] && ENDED.include?(login[:status].to_s)
+      def orchestrator = @orchestrator ||= SandboxOrchestrator.new
+      def forbidden = render(json: { error: "This login belongs to another user" }, status: :forbidden)
+      def busy = render(json: { error: "Wait for the running code session before changing its login" }, status: :conflict)
+    end
+  end
+end

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

@@ -12,6 +12,11 @@ module ActionAgent
     # is execution — gated, and counted against the host app's quota, like
     # running an agent.
     class CodeSessionsController < BaseController
+      include EvaluationRunStarting
+
+      # How long an unverified fix holds its checkout (see #busy_session).
+      VERIFICATION_HOLD = 1.hour
+
       before_action :require_owner!
       before_action :require_execution_enabled!, only: [ :create ]
       before_action :set_sandbox
@@ -29,7 +34,11 @@ module ActionAgent
 
       # POST /api/sandboxes/:sandbox_id/code_sessions
       def create
-        if (refusal = refusal_for(@sandbox))
+        runner = params[:runner].nil? ? "claude_code" : params[:runner]
+        unless CodeSession::RUNNERS.include?(runner)
+          return render json: { error: "runner must be claude_code or codex" }, status: :unprocessable_entity
+        end
+        if (refusal = refusal_for(@sandbox, runner: runner))
           return render json: { error: refusal }, status: :unprocessable_entity
         end
 
@@ -41,10 +50,13 @@ module ActionAgent
           sandbox_session: @sandbox,
           prompt: string_param(:prompt),
           model: string_param(:model).presence,
-          # Owned like the sandbox it runs in.
-          user_id: @sandbox.try(:user_id),
+          runner: runner,
+          # Subscription use always belongs to the person who clicked Run.
+          user_id: current_user.respond_to?(:id) ? current_user.id : @sandbox.try(:user_id),
           account_id: @sandbox.try(:account_id)
         )
+        code_session.credential_mode = runner == "claude_code" ? ClaudeCodeAuth.credential_mode(@sandbox, user_id: current_user&.id) : "api_key"
+        attach_fix!(code_session) if params[:evaluation_run_id].present?
         if (error = invalid_request(code_session))
           return render json: { error: error }, status: :unprocessable_entity
         end
@@ -57,6 +69,10 @@ module ActionAgent
         current = nil
         @sandbox.with_lock do
           current = busy_session
+          if !current && (refusal = refusal_for(@sandbox, runner: runner))
+            return render json: { error: refusal }, status: :unprocessable_entity
+          end
+          code_session.credential_mode = ClaudeCodeAuth.credential_mode(@sandbox, user_id: current_user&.id) if runner == "claude_code"
           code_session.save! unless current
         end
         return render json: busy_body(current), status: :conflict if current
@@ -111,31 +127,74 @@ module ActionAgent
       end
 
       # Why +sandbox+ cannot take a Claude Code session now, or nil.
-      def refusal_for(sandbox)
-        return "Claude Code sessions run only in a checkout (app_runtime) sandbox" unless sandbox.app_runtime?
+      def refusal_for(sandbox, runner: "claude_code")
+        label = runner == "codex" ? "Codex" : "Claude Code"
+        return "#{label} sessions run only in a checkout (app_runtime) sandbox" unless sandbox.app_runtime?
         return "The sandbox has expired; start a new one" if sandbox.ready? && !sandbox.active?
         return "The sandbox is #{sandbox.status}; wait until it is ready" unless sandbox.ready?
 
         orchestrator = SandboxOrchestrator.new
-        unless orchestrator.supports?(:code_session)
-          return "The #{orchestrator.backend_name} sandbox backend cannot run Claude Code sessions"
+        unless orchestrator.supports_code_runner?(runner)
+          return "The #{orchestrator.backend_name} sandbox backend cannot run #{label} sessions"
         end
 
-        ClaudeCodeAuth.backend_refusal(orchestrator) || ClaudeCodeAuth.credential_refusal(sandbox)
+        if (refusal = ClaudeCodeAuth.login_owner_refusal(sandbox, user_id: current_user&.id))
+          return refusal
+        end
+        if runner == "codex"
+          return "Codex is not connected: connect an OpenAI API key in Settings -> Integrations first" if sandbox.runtime_environment(runner: runner).blank?
+          return
+        end
+        ClaudeCodeAuth.backend_refusal(orchestrator) || ClaudeCodeAuth.credential_refusal(sandbox, user_id: current_user&.id)
       end
 
       # The session of this sandbox that is queued or running, if any: one
-      # checkout, one Claude Code at a time.
+      # checkout, one Claude Code at a time. A fix whose verification has not
+      # finished holds the checkout too, so no edit lands under the run that
+      # is meant to verify it, but only for VERIFICATION_HOLD: a worker lost
+      # mid-run must not lock the sandbox until it expires.
       def busy_session
-        @sandbox.code_sessions.where(status: [ :queued, :running ]).first
+        @sandbox.code_sessions.where(status: [ :queued, :running ]).first ||
+          @sandbox.code_sessions.where.not(evaluation_run_id: nil).where(finished_at: VERIFICATION_HOLD.ago..).recent.detect do |session|
+            session.succeeded? && session.diff.present? && session.verification_error.blank? &&
+              (session.verification_run_id.nil? || session.verification_run&.status.in?(%w[pending running]))
+          end
       end
 
       def busy_body(current)
-        { error: "A Claude Code session is already #{current.status} in this sandbox", code_session: current.summary }
+        label = current.runner == "codex" ? "Codex" : "Claude Code"
+        state = current.succeeded? ? "being verified" : current.status
+        { error: "A #{label} session is already #{state} in this sandbox", code_session: current.summary }
+      end
+
+      def attach_fix!(session)
+        raise EvaluationFix::Invalid, "Evaluation fixes use Claude Code" unless session.runner == "claude_code"
+        scope = EvaluationRun.joins(:evaluation).where(evaluation: Evaluation.where(agent: owner_agents))
+        run = scope.find(params[:evaluation_run_id])
+        project = Project.for_evaluation(run.evaluation)
+        unless project && @sandbox.project_id == project.id
+          raise EvaluationFix::Invalid, "Choose a checkout of this evaluation's project"
+        end
+        evaluation_run_sandbox(run.evaluation, @sandbox.session_id)
+        raise EvaluationFix::Invalid, "The sandbox backend cannot refresh the app runtime for verification" unless SandboxOrchestrator.new.supports?(:refresh_runtime)
+        request_item = params[:fix_item]
+        raise EvaluationFix::Invalid, "Choose a fix card" unless request_item.respond_to?(:permit)
+        fix = EvaluationFix.new(run, request_item.permit(:kind, :fault, :quote, scenario_keys: [], models: []).to_h)
+        previous = @sandbox.code_sessions.find(params[:previous_code_session_id]) if params[:previous_code_session_id].present?
+        if previous && (previous.evaluation_run_id != run.id || previous.fix_item != fix.item || !previous.finished?)
+          raise EvaluationFix::Invalid, "The previous session must implement this same fix"
+        end
+        session.assign_attributes(evaluation_run: run, fix_item: fix.item, previous_code_session: previous,
+          prompt: fix.prompt(previous: previous))
+      end
+
+      rescue_from EvaluationFix::Invalid do |error|
+        render json: { error: error.message }, status: :unprocessable_entity
       end
 
       def invalid_request(code_session)
-        return "model is not a Claude Code model name" if code_session.model && !code_session.model.match?(MODEL_NAME)
+        label = code_session.runner == "codex" ? "Codex" : "Claude Code"
+        return "model is not a #{label} model name" if code_session.model && !code_session.model.match?(MODEL_NAME)
 
         code_session.errors.full_messages.to_sentence unless code_session.valid?
       end

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

@@ -13,12 +13,12 @@ module ActionAgent
       rescue_from DashboardAssistantService::SetupRequired, with: :setup_required
 
       def show
-        render json: DashboardAssistantService.new(owner: current_owner).configuration
+        render json: DashboardAssistantService.new(owner: current_owner, actor: current_user).configuration
       end
 
       def create
         input = params.to_unsafe_h.symbolize_keys.slice(:message, :history, :provider, :model, :allow_provider_processing)
-        assistant = DashboardAssistantService.new(owner: current_owner, **input)
+        assistant = DashboardAssistantService.new(owner: current_owner, actor: current_user, **input)
         assistant.validate!
         record_execution_usage
         render json: assistant.call

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

@@ -0,0 +1,248 @@
+# frozen_string_literal: true
+
+module ActionAgent
+  module Api
+    # Opening a pull request from one of the caller's checkout sandboxes
+    # (Settings -> Integrations -> Open draft PR): the preview of what would
+    # be published, the publish itself, the pull request it opened, and the
+    # patch to download where publishing is not available. See
+    # DraftPullRequestPublisher for how changes are read, filtered and
+    # written.
+    #
+    # Publishing is an explicit request from a signed-in user: it asks
+    # ActionAgent.permission_checker about :publish_pull_request, and
+    # DraftPullRequestJob asks again before it writes. Preview, status and
+    # patch find the sandbox the way its other endpoints do.
+    class DraftPullRequestsController < BaseController
+      before_action :require_owner!
+      before_action :set_sandbox
+
+      rescue_from DraftPullRequestPublisher::Refused, with: :refused
+
+      # GET /api/sandboxes/:sandbox_id/pull_request — the latest pull request
+      # opened from this sandbox (its state read again from GitHub at most
+      # once a minute), and whether publishing is available.
+      def show
+        @sandbox.draft_pull_requests.fail_stalled!
+        record = @sandbox.draft_pull_requests.recent.first
+        DraftPullRequestPublisher.refresh_status!(record) if record && !record.in_progress?
+
+        render json: { pull_request: record&.summary, publishing: publishing_status }
+      end
+
+      # POST /api/sandboxes/:sandbox_id/pull_request/preview { allowlist: [patterns] }
+      def preview
+        render json: { preview: publisher.preview(allowlist: allowlist_param), publishing: publishing_status }
+      end
+
+      # POST /api/sandboxes/:sandbox_id/pull_request
+      #
+      #   { title:, body:, branch:, files: [{ path:, digest: }], allowlist: }
+      #       publishes the files as a new branch and opens a draft pull
+      #       request; each digest is the one the preview reported
+      #   { update: true, files:, message:, allowlist: }
+      #       publishes the files as a new commit on the branch of the latest
+      #       pull request, with +message+ as the commit's message; the pull
+      #       request's title and description stay as they are
+      #   { open: true }
+      #       opens a draft pull request for the latest branch that was
+      #       published without one
+      #   { regular: true }
+      #       opens a regular pull request for that branch instead
+      #
+      # Answers 202 with the queued record, which GET reports on.
+      def create
+        return open_branch(regular: true) if boolean_param(:regular)
+        return open_branch(regular: false) if boolean_param(:open)
+        return update_latest if boolean_param(:update)
+
+        record = @sandbox.draft_pull_requests.new(
+          operation: "create", repository: @sandbox.repository, branch: string_param(:branch).to_s.strip,
+          title: string_param(:title).to_s.strip, body: string_param(:body)
+        )
+        if params[:code_session_id].present?
+          session = @sandbox.code_sessions.find(params[:code_session_id])
+          unless session.evaluation_run_id && session.verification_run&.complete?
+            raise DraftPullRequestPublisher::Refused.new("Wait for this fix's verification before publishing", code: "not_live")
+          end
+          room = DraftPullRequest::MAX_BODY_CHARACTERS - (record.body.present? ? record.body.length + 2 : 0)
+          section = EvaluationFixComparison.new(session).pull_request_body(mount: "#{request.base_url}#{request.script_name}", limit: room)
+          record.body = [ record.body.presence, section.presence ].compact.join("\n\n")
+        end
+        assign_owner(record)
+        return unless authorize_action!(:publish_pull_request, record)
+
+        branch_refusal = DraftPullRequestPublisher.branch_refusal(record.branch)
+        raise DraftPullRequestPublisher::Refused.new(branch_refusal, code: "invalid_branch") if branch_refusal
+
+        queue(record, allowlist: allowlist_param)
+      end
+
+      # GET /api/sandboxes/:sandbox_id/pull_request/patch?paths[]=…&title=…
+      # The chosen files (every publishable one when none are named) as a
+      # patch for `git am` or `git apply`.
+      def patch
+        paths = params[:paths]
+        paths = nil unless paths.is_a?(Array) && paths.all? { |path| path.is_a?(String) }
+        data = publisher.patch(paths: paths, title: string_param(:title), body: string_param(:body))
+
+        send_data data, type: "text/x-diff", disposition: "attachment",
+          filename: "#{@sandbox.repository.tr('/', '-')}-#{@sandbox.session_id.first(8)}.patch"
+      end
+
+      private
+
+      # A checkout runs on its account's GitHub access, so in a multi-tenant
+      # install it is found within the caller's current account, as
+      # CodeSessionsController finds it.
+      def set_sandbox
+        scope = owned(SandboxSession)
+        scope = scope.where(account_id: current_account.id) if current_account
+        @sandbox = scope.find_by!(session_id: params[:sandbox_id])
+      end
+
+      def publisher
+        @publisher ||= DraftPullRequestPublisher.new(@sandbox, user: current_user)
+      end
+
+      # A new commit goes only onto the branch of a pull request that is open
+      # on GitHub: a branch without one is opened first (see #open_branch).
+      def update_latest
+        record = @sandbox.draft_pull_requests.recent.where.not(head_commit: nil).first
+        if record.nil?
+          return render json: { error: "Nothing was published from this sandbox yet", code: "nothing_published" }, status: :unprocessable_entity
+        end
+        unless record.opened?
+          return render json: { error: "The branch #{record.branch} has no pull request yet. Open one for it first", code: "not_opened" },
+            status: :unprocessable_entity
+        end
+        if record.state.in?(%w[closed merged])
+          return render json: { error: "The pull request is #{record.state}. Open a new one instead", code: "pull_request_closed" },
+            status: :unprocessable_entity
+        end
+
+        record.assign_attributes(operation: "update",
+          commit_message: string_param(:message).to_s.strip.presence || DraftPullRequest::DEFAULT_UPDATE_MESSAGE)
+        assign_owner(record)
+        return unless authorize_action!(:publish_pull_request, record)
+
+        queue(record, allowlist: allowlist_param)
+      end
+
+      # Opens a pull request for the branch of the latest publish, which was
+      # pushed without one: a draft, or with +regular+ a regular one.
+      def open_branch(regular:)
+        record = @sandbox.draft_pull_requests.recent.first
+        unless record&.branch_only?
+          return render json: { error: "No branch of this sandbox is waiting to be opened as a pull request", code: "nothing_published" },
+            status: :unprocessable_entity
+        end
+
+        record.assign_attributes(operation: regular ? "open_regular" : "open_draft")
+        assign_owner(record)
+        return unless authorize_action!(:publish_pull_request, record)
+
+        queue(record, files: false)
+      end
+
+      # Checks the request against the sandbox as it is now, then queues the
+      # publish: one at a time per sandbox, under its row lock. A record that
+      # is itself queued or publishing is busy too.
+      def queue(record, allowlist: nil, files: true)
+        refusal = publisher.read_refusal
+        raise refusal if refusal
+
+        credential = publisher.credential
+        unless credential.available?
+          return render json: { error: credential.refusal, code: "no_credential", patch_available: true }, status: :unprocessable_entity
+        end
+
+        if files
+          selection = selection_param
+          changes = publisher.changes(allowlist: allowlist, paths: selection.keys)
+          chosen = publisher.select!(changes, selection)
+          record.base_commit = changes.base_commit
+          record.files = chosen.map { |file| { "path" => file.path, "status" => file.status, "mode" => file.mode, "digest" => file.digest } }
+        end
+        record.assign_attributes(status: "queued", credential_kind: credential.kind, error_code: nil, error_message: nil)
+        return render json: { error: record.errors.full_messages.to_sentence }, status: :unprocessable_entity unless record.valid?
+
+        busy = nil
+        @sandbox.with_lock do
+          @sandbox.draft_pull_requests.fail_stalled!
+          busy = @sandbox.draft_pull_requests.where(status: %w[queued publishing]).first
+          record.save! unless busy
+        end
+        if busy
+          return render json: { error: "A publish from this sandbox is already #{busy.status}", pull_request: busy.summary },
+            status: :conflict
+        end
+
+        DraftPullRequestJob.perform_later(record.id)
+        render json: { pull_request: record.summary }, status: :accepted
+      end
+
+      # The user who publishes, and the owner: the sandbox's account where
+      # the account owns records.
+      def assign_owner(record)
+        record.user_id = current_user.id if ActionAgent.user_class.present? && current_user.respond_to?(:id)
+        record.account_id = @sandbox.account_id if @sandbox.has_attribute?(:account_id) && @sandbox.account_id
+      end
+
+      def publishing_status
+        refusal = publisher.read_refusal
+        credential = refusal ? nil : publisher.credential
+        {
+          supported: refusal&.code != "unsupported",
+          available: refusal.nil? && credential.available?,
+          refusal: refusal&.message || credential&.refusal,
+          refusal_code: refusal&.code || (credential&.available? == false ? "no_credential" : nil),
+          credential: credential&.kind,
+          # A patch needs only the live checkout.
+          patch_available: refusal.nil?
+        }
+      end
+
+      # [{ path:, digest: }] as { path => digest }.
+      def selection_param
+        files = params[:files]
+        files = files.map { |file| file.respond_to?(:permit) ? file.permit(:path, :digest).to_h : file } if files.is_a?(Array)
+        unless files.is_a?(Array) && files.all? { |file| file.is_a?(Hash) && file["path"].is_a?(String) && file["digest"].is_a?(String) }
+          raise DraftPullRequestPublisher::Refused.new("files must be a list of { path, digest } from the preview", code: "nothing_selected")
+        end
+
+        files.to_h { |file| [ file["path"], file["digest"] ] }
+      end
+
+      def allowlist_param
+        allowlist = params[:allowlist]
+        return nil if allowlist.nil?
+        unless allowlist.is_a?(Array) && allowlist.all? { |pattern| pattern.is_a?(String) && pattern.present? }
+          raise DraftPullRequestPublisher::Refused.new("allowlist must be a list of path patterns", code: "not_publishable")
+        end
+
+        allowlist
+      end
+
+      def string_param(name)
+        value = params[name]
+        value.is_a?(String) ? value : nil
+      end
+
+      def boolean_param(name)
+        ActiveModel::Type::Boolean.new.cast(params[name]) == true
+      end
+
+      def refused(error)
+        status = error.code == "changed_since_preview" ? :conflict : :unprocessable_entity
+        render json: { error: error.message, code: error.code, patch_available: patch_offered?(error) }, status: status
+      end
+
+      # A patch of the same files fails the same way when they were too
+      # many or too large.
+      def patch_offered?(error)
+        !error.code.in?(%w[unsupported not_live unreadable too_large]) && publisher.read_refusal.nil?
+      end
+    end
+  end
+end