actionagent 1.8.0 → 1.9.0

data/app/models/action_agent/github_installation.rb

@@ -0,0 +1,159 @@
+# frozen_string_literal: true
+
+module ActionAgent
+  # A GitHub App installation an owner linked (Settings -> Integrations), and
+  # the repositories they made available on it.
+  #
+  # Nothing here is a credential. A checkout or a repository listing mints an
+  # installation token when it needs one, limited to one repository where it
+  # can be and to the permission that step needs, and the token is never
+  # stored. +repositories+ holds only what GitHub listed for the installation
+  # when the owner chose them (see Api::GithubInstallationsController#update).
+  #
+  # The +github_account_*+ columns describe the GitHub user or organization
+  # the App is installed on, and are unrelated to the owner's +account_id+.
+  # An installation is linked to one owner at most: +installation_id+ is
+  # unique across every owner.
+  class GithubInstallation < ApplicationRecord
+    include Ownable
+    owned_by :account, :user
+
+    ACCOUNT_TYPES = %w[User Organization].freeze
+    # The permission a checkout's fetch needs.
+    CHECKOUT_PERMISSIONS = { contents: "read" }.freeze
+    # The permission listing an installation's repositories needs.
+    LISTING_PERMISSIONS = { metadata: "read" }.freeze
+
+    validates :installation_id, :github_account_id, :github_account_login, presence: true
+    validates :installation_id, uniqueness: true
+    validates :github_account_type, inclusion: { in: ACCOUNT_TYPES }
+
+    # JSON columns carry no default on MySQL or SQLite (see the migration), so
+    # an unset column reads as nil.
+    def repositories
+      Array(super)
+    end
+
+    def permissions
+      value = super
+      value.is_a?(Hash) ? value : {}
+    end
+
+    def repository_names
+      repositories.map { |repo| repo["full_name"] }
+    end
+
+    def repository(full_name)
+      repositories.find { |repo| repo["full_name"].casecmp?(full_name.to_s) }
+    end
+
+    # Whether GitHub will still mint tokens for this installation, as far as
+    # the dashboard last heard: false once a mint found it removed or
+    # suspended, until a later mint succeeds or it is linked again.
+    def usable?
+      removed_at.nil? && suspended_at.nil?
+    end
+
+    # Mints an installation token limited to +permissions+ and, when given,
+    # +repository_ids+. A refusal because the installation was removed or
+    # suspended is recorded on the row before it is raised again, and a
+    # successful mint clears that record, since GitHub mints for neither.
+    #
+    # @raise [GithubClient::InstallationUnavailable]
+    # @return [String] the token, which the caller must not store
+    def mint_token!(permissions:, repository_ids: nil)
+      token = GithubClient.mint_installation_token(installation_id, permissions: permissions, repository_ids: repository_ids)
+      update_columns(removed_at: nil, suspended_at: nil) if persisted? && !usable?
+      token
+    rescue GithubClient::InstallationUnavailable => e
+      mark_unavailable!(e.reason)
+      raise
+    end
+
+    # The checkout of +full_name+ a sandbox backend clones, without a token.
+    # Reading it calls nothing; #checkout_spec! is the one that mints.
+    #
+    # @raise [ArgumentError] when +full_name+ is not a selected repository
+    def checkout_spec(full_name, ref: nil, token: nil)
+      repo = repository(full_name) or raise ArgumentError, "#{full_name} is not an available repository"
+
+      {
+        repository: repo["full_name"],
+        ref: ref.presence || repo["default_branch"],
+        clone_url: "https://github.com/#{repo["full_name"]}.git",
+        username: "x-access-token",
+        token: token
+      }
+    end
+
+    # #checkout_spec with a freshly minted token that reads the contents of
+    # that one repository. Carries the token: hand it to a backend, never to
+    # a response.
+    def checkout_spec!(full_name, ref: nil)
+      repo = repository(full_name) or raise ArgumentError, "#{full_name} is not an available repository"
+
+      token = mint_token!(permissions: CHECKOUT_PERMISSIONS, repository_ids: [ repo["id"] ])
+      checkout_spec(full_name, ref: ref, token: token)
+    end
+
+    # A client for the installation's repository listing, with a token that
+    # can read repository metadata and nothing else.
+    def listing_client
+      GithubClient.new(mint_token!(permissions: LISTING_PERMISSIONS))
+    end
+
+    # Records what GitHub reported about the installation when it was linked.
+    def assign_from_github(installation)
+      account = installation["account"] || {}
+      assign_attributes(
+        github_account_id: account["id"],
+        github_account_login: account["login"],
+        github_account_type: account["type"],
+        repository_selection: installation["repository_selection"],
+        permissions: installation["permissions"].is_a?(Hash) ? installation["permissions"] : {},
+        suspended_at: installation["suspended_at"],
+        removed_at: nil
+      )
+    end
+
+    def as_summary
+      {
+        id: id,
+        installation_id: installation_id,
+        account_login: github_account_login,
+        account_type: github_account_type,
+        repository_selection: repository_selection,
+        permissions: permissions,
+        repositories: repositories,
+        status: status,
+        settings_url: settings_url,
+        linked_at: created_at&.iso8601,
+        updated_at: updated_at&.iso8601
+      }
+    end
+
+    # "active", "suspended" or "removed".
+    def status
+      return "removed" if removed_at
+      return "suspended" if suspended_at
+
+      "active"
+    end
+
+    # Where the installation's repository access is changed on GitHub.
+    def settings_url
+      if github_account_type == "Organization"
+        "https://github.com/organizations/#{github_account_login}/settings/installations/#{installation_id}"
+      else
+        "https://github.com/settings/installations/#{installation_id}"
+      end
+    end
+
+    private
+
+    def mark_unavailable!(reason)
+      column = reason == :suspended ? :suspended_at : :removed_at
+      update_column(column, Time.current) if persisted? && self[column].nil?
+    end
+  end
+end

data/app/models/action_agent/input_request.rb

@@ -0,0 +1,291 @@
+# frozen_string_literal: true
+
+module ActionAgent
+  # A question a paused run put to a person, and the answer the run resumes
+  # with.
+  #
+  # A tool asks by returning an ActiveAgent::InputRequest, which ends the
+  # generation paused. AgentRun#record_result! then stores one of these per
+  # paused tool call. The requests of one pause share a `pause_key` and the
+  # pause's checkpoint, and the run resumes (AgentResumeJob) once every one of
+  # them is answered or declined.
+  #
+  # Statuses:
+  #   - `pending`   waiting for a person
+  #   - `answered`  answered; an answered `confirm` request is an approval
+  #   - `declined`  declined; the paused tool does not run
+  #   - `expired`   not answered before `expires_at`
+  #   - `cancelled` the run was cancelled, or ended without the answer
+  #
+  # The owner columns are copied from the subject's agent when the request is
+  # created. `answer` and `checkpoint` are encrypted at rest and are never
+  # serialized (InputRequestSerializer).
+  class InputRequest < ApplicationRecord
+    include Ownable
+    owned_by :account, :user
+
+    # Raised when the request can no longer be answered or declined: it was
+    # settled already, or it expired.
+    class Conflict < StandardError; end
+
+    # Raised when an answer does not fit the request.
+    class InvalidAnswer < StandardError; end
+
+    KINDS = ActiveAgent::InputRequest::KINDS.map(&:to_s).freeze
+    # The answers that approve a `confirm` request, no answer among them, and
+    # the answers that decline it.
+    CONFIRM_APPROVALS = [ nil, true, "true" ].freeze
+    CONFIRM_DECLINES = [ false, "false" ].freeze
+    # The shortest answer a `secret` request takes. A secret is scrubbed from
+    # what a run records wherever it appears inside a value, so a short one
+    # would also replace the same characters in unrelated values.
+    SECRET_MIN_LENGTH = 8
+    # The only subjects a request is created for. Later subjects join this list.
+    SUBJECT_TYPES = %w[ActionAgent::AgentRun].freeze
+
+    belongs_to :subject, polymorphic: true
+
+    if ActionAgent.encrypt_credentials
+      encrypts :answer
+      encrypts :checkpoint
+    end
+
+    enum :status, { pending: 0, answered: 1, declined: 2, expired: 3, cancelled: 4 }
+
+    validates :kind, inclusion: { in: KINDS }
+    validates :subject_type, inclusion: { in: SUBJECT_TYPES }
+    validates :prompt, :pause_key, presence: true
+
+    before_validation :copy_owner_from_subject, on: :create
+
+    scope :recent, -> { order(created_at: :desc, id: :desc) }
+    # Pending requests past their `expires_at`.
+    scope :overdue, -> { pending.where(expires_at: ..Time.current) }
+    # Every column but the answer and the checkpoint, which no listing shows
+    # and which hold a whole conversation.
+    scope :for_listing, -> { select(*(column_names - %w[answer checkpoint]).map { |name| arel_table[name] }) }
+
+    # Stores the requests of one pause, sharing a pause key and the checkpoint
+    # the run resumes from.
+    #
+    # @param subject [AgentRun] the paused run
+    # @param requests [Array<ActiveAgent::InputRequest>] one per paused tool call
+    # @param checkpoint [Hash] the paused response's checkpoint
+    # @return [Array<InputRequest>]
+    def self.record_pause!(subject, requests, checkpoint:)
+      pause_key = SecureRandom.uuid
+      stored_checkpoint = checkpoint.to_json
+      expires_at = ActionAgent.input_request_ttl&.from_now
+      requested_by_id = user_id_of(subject.try(:actor))
+
+      requests.map do |request|
+        create!(
+          subject: subject,
+          pause_key: pause_key,
+          kind: request.kind.to_s,
+          prompt: request.prompt,
+          options: request.options,
+          answer_schema: request.schema,
+          tool_call_id: request.tool_call_id,
+          tool_name: request.tool_name,
+          arguments: request.kind.to_s == "confirm" ? request.metadata.to_h["arguments"] : nil,
+          checkpoint: stored_checkpoint,
+          expires_at: expires_at,
+          requested_by_id: requested_by_id
+        )
+      end
+    end
+
+    # Expires every overdue request in +relation+ (see #expire!).
+    #
+    # @param relation [ActiveRecord::Relation] the requests to look through
+    # @return [Integer] how many requests it expired
+    def self.expire_overdue!(relation = all)
+      relation.overdue.for_listing.find_each.count(&:expire!)
+    end
+
+    # The id of +user+ when it is a record of the configured user class, so
+    # an account or a service object is never stored as a person.
+    def self.user_id_of(user)
+      user_class = ActionAgent.user_class&.safe_constantize
+      user.id if user_class && user.is_a?(user_class)
+    end
+
+    # The requests the same pause raised, this one included.
+    # @return [ActiveRecord::Relation]
+    def pause_requests
+      self.class.where(subject_type: subject_type, subject_id: subject_id, pause_key: pause_key)
+    end
+
+    # Whether every request of the pause is answered or declined, so the run
+    # can resume.
+    def pause_settled?
+      pause_requests.where.not(status: [ :answered, :declined ]).none?
+    end
+
+    # Whether this request belongs to the latest pause of its subject. A run
+    # resumed from one pause may pause again, and then only the later pause's
+    # checkpoint continues it.
+    def current_pause?
+      self.class.where(subject_type: subject_type, subject_id: subject_id).order(id: :desc).pick(:pause_key) == pause_key
+    end
+
+    # The checkpoint the pause stored, as a Hash.
+    def checkpoint_data
+      JSON.parse(checkpoint.to_s)
+    end
+
+    # What the paused tool call is dispatched again with: `false` for a
+    # declined request, `true` for an approved `confirm`, the answer
+    # otherwise.
+    def resume_answer
+      return false if declined?
+      return true if kind == "confirm"
+
+      answer
+    end
+
+    # The values a `choice` answer may take: each option, or its `value` when
+    # the option is a hash.
+    # @return [Array<String>]
+    def choice_values
+      Array(options).map { |option| option.is_a?(Hash) ? option.fetch("value", option["label"]) : option }.map(&:to_s)
+    end
+
+    # Whether +user+ may answer or decline this request. A multi-tenant
+    # install refuses a nil user, so every answer names who gave it.
+    # Otherwise a configured permission checker decides
+    # (:answer_input_request). Without one:
+    #
+    #   - multi-tenant: only the run's actor answers a request that records
+    #     one (`requested_by_id`), because the run acts as that person
+    #   - single-tenant: anyone may answer
+    #
+    # The handler of a `secret` request can refuse on top of that (see
+    # SecretRequests).
+    def answerable_by?(user)
+      return false if ActionAgent.multi_tenant? && user.nil?
+      return false unless SecretRequests.answerable_by?(self, user)
+      return ActionAgent.permitted?(user, :answer_input_request, self) if ActionAgent.permission_checker
+      return true unless ActionAgent.multi_tenant? && requested_by_id
+
+      self.class.user_id_of(user) == requested_by_id
+    end
+
+    # Answers the request, and enqueues AgentResumeJob when it was the last
+    # of its pause to settle. A `confirm` request is approved by `true` or by
+    # no answer, and declined by `false` (see #decline!), the way
+    # ActiveAgent::InputRequest reads `false`.
+    #
+    # @param value [String, Boolean, nil] the answer
+    # @param user [Object, nil] who answered
+    # @raise [Conflict] when the request is no longer pending or has expired
+    # @raise [InvalidAnswer] when the answer is blank, not text, not one of a
+    #   `choice` request's options, shorter than SECRET_MIN_LENGTH for a
+    #   `secret` request, or neither `true` nor `false` for a `confirm`
+    #   request
+    # @return [self]
+    def answer!(value, user: nil)
+      return decline!(user: user) if kind == "confirm" && CONFIRM_DECLINES.include?(value)
+
+      settle!(:answered, value: value, user: user)
+    end
+
+    # Expires the request when it is still pending past `expires_at`. The
+    # rest of its pause is cancelled, and its run fails, because it can no
+    # longer resume. Returns whether it expired the request.
+    def expire!
+      expired = false
+      subject.with_lock do
+        reload
+        next unless pending? && expires_at&.past?
+
+        expire_pause!
+        expired = true
+      end
+      subject.try(:broadcast_update) if expired
+      expired
+    end
+
+    # Declines the request: its tool does not run, and the model reads an
+    # error as the call's result.
+    #
+    # @raise [Conflict] when the request is no longer pending or has expired
+    # @return [self]
+    def decline!(user: nil)
+      settle!(:declined, user: user)
+    end
+
+    private
+
+    # Every settlement of a pause takes the subject's row lock, so two answers
+    # to the same pause are applied one after the other and the second sees
+    # the first. A failure is raised after the lock's transaction commits,
+    # so an expiry it recorded is kept.
+    def settle!(status, value: nil, user: nil)
+      failure = nil
+      resume = false
+
+      subject.with_lock do
+        reload
+        failure = settle_failure(status, value)
+        next if failure
+
+        update!(
+          status: status,
+          answer: status == :answered && kind != "confirm" ? value.to_s : nil,
+          answered_by_id: self.class.user_id_of(user),
+          answered_at: Time.current
+        )
+        resume = pause_settled?
+      end
+      raise failure if failure
+
+      AgentResumeJob.perform_later(id) if resume && subject.is_a?(AgentRun)
+      self
+    end
+
+    def settle_failure(status, value)
+      return Conflict.new("This request was already #{self.status}") unless pending?
+
+      if expires_at&.past?
+        expire_pause!
+        return Conflict.new("This request expired at #{expires_at.iso8601}")
+      end
+
+      message = status == :answered ? answer_error(value) : nil
+      InvalidAnswer.new(message) if message
+    end
+
+    # Marks this request expired and the rest of its pause cancelled, and
+    # fails the run, which can no longer resume.
+    def expire_pause!
+      update!(status: :expired)
+      pause_requests.pending.update_all(status: self.class.statuses[:cancelled], updated_at: Time.current)
+      return unless subject.try(:awaiting_input?)
+
+      subject.update!(status: :failed, completed_at: Time.current, error_message: "An input request expired before it was answered")
+    end
+
+    def answer_error(value)
+      if kind == "confirm"
+        return CONFIRM_APPROVALS.include?(value) ? nil : "Answer a confirm request with true or false"
+      end
+
+      return "Answer with text" unless value.is_a?(String) || value.is_a?(Numeric)
+      return "An answer is required" if value.to_s.strip.empty?
+      return "A secret must be at least #{SECRET_MIN_LENGTH} characters" if kind == "secret" && value.to_s.length < SECRET_MIN_LENGTH
+      return nil unless kind == "choice"
+
+      "#{value.to_s.truncate(64).inspect} is not one of the options" unless choice_values.include?(value.to_s)
+    end
+
+    def copy_owner_from_subject
+      source = subject.respond_to?(:agent) ? subject.agent : subject
+      return unless source
+
+      self.account_id = source.try(:account_id)
+      self.user_id = source.try(:user_id)
+    end
+  end
+end