support_desk 0.2.0 → 0.3.0

data/lib/support_desk/macros.rb

@@ -57,13 +57,26 @@ module SupportDesk
     # subject of the sentence (`ticket.assign!(to: lucia)`).
     def acts_as_support_agent(kind: :human, **options)
       condition = Macros.condition!(options, macro: "acts_as_support_agent", known: ":if, :kind")
+      kind = Macros.kind!(kind)
 
       include SupportDesk::Agent
 
-      self.support_desk_agent_options = { if: condition, kind: kind.to_sym }.freeze
+      self.support_desk_agent_options = { if: condition, kind: kind }.freeze
       SupportDesk.register_agent(self)
     end
 
+    # Who the agent IS: a person, or a machine. There are two kinds because
+    # they are answerable to different rules, and an unknown third would be
+    # treated as a human by every check that isn't looking for :ai — so it
+    # fails at class definition instead.
+    def self.kind!(kind)
+      kind = kind.to_sym if kind.respond_to?(:to_sym)
+      return kind if %i[human ai].include?(kind)
+
+      raise ConfigurationError,
+            "acts_as_support_agent kind: must be :human or :ai, got #{kind.inspect}"
+    end
+
     # The `if:` both macros take: a method name or a callable, and the only
     # option either of them accepts beyond its own keywords. Written once
     # because "may this person answer" and "may this person ask" are the same

data/lib/support_desk/models/assistant.rb

@@ -0,0 +1,153 @@
+# frozen_string_literal: true
+
+module SupportDesk
+  # The assistant: an AI agent, as a record.
+  #
+  #   rose = SupportDesk.assistant(:rose)
+  #   rose.autonomy        # => :draft      (from configuration)
+  #   rose.deactivate!(by: lucia)           # the cross-process kill switch
+  #
+  # Two things live here and nothing else: WHO she is (a row a message can
+  # be authored by, an assignment can point at, and an audit log can name)
+  # and WHETHER she is on. Everything she may do lives in configuration, in
+  # code, so a policy change is a deploy and a diff — see
+  # SupportDesk::Configuration::AssistantConfiguration and
+  # SupportDesk::AssistantPolicy.
+  #
+  # `active` is the one runtime switch, and it is a DATABASE column on
+  # purpose: `rose.deactivate!(by: owner)` stops her everywhere within one
+  # transition, with no deploy, because `ensure_agent_record!` re-reads this
+  # row before every write. Rows are never destroyed — a case she answered in
+  # March must still be able to say who wrote it.
+  class Assistant < ApplicationRecord
+    self.table_name = "support_desk_assistants"
+
+    acts_as_support_agent kind: :ai, if: :active?
+
+    # Ruby-side default so settings is always a Hash even on MySQL, where a
+    # JSON column can't carry a DB default.
+    attribute :settings, default: -> { {} }
+
+    validates :key, presence: true
+
+    scope :active, -> { where(active: true) }
+
+    # The assistant for +key+, found or created. Never INSERT-first, exactly
+    # like Desk.for: read on every transition, written once.
+    def self.for(key)
+      key = key.to_s
+      find_by(key: key) || create_or_find_by!(key: key)
+    end
+
+    # --- Configuration ----------------------------------------------------------
+
+    # Her slice of the configuration. Raises ConfigurationError when nothing
+    # declares her any more — which is why everything below reads through
+    # #settings_config and falls back to the safest answer instead.
+    def config
+      SupportDesk.config.assistant(key)
+    end
+
+    # Whether this row still has configuration behind it. False for an
+    # assistant a host removed from the initializer and kept the history of.
+    def configured? = SupportDesk.config.assistant?(key)
+
+    def name = settings_config&.name || key.to_s.humanize
+
+    # Anything `image_tag` accepts, or nil. A callable is passed the record.
+    def avatar
+      value = settings_config&.avatar
+      value.respond_to?(:call) ? value.call(self) : value
+    end
+
+    # An unconfigured assistant is capped at :off by construction: there is
+    # no rule left saying what she may do, so she may do nothing.
+    def autonomy = settings_config&.autonomy || :off
+    def disclosure = settings_config&.disclosure
+    def max_turns = settings_config&.max_turns
+    def responds_within = settings_config&.responds_within
+    def may_open_conversations? = settings_config&.may_open_conversations? || false
+
+    def disclosed? = settings_config ? settings_config.disclosed? : false
+    def signs? = settings_config ? settings_config.signs? : false
+    def notice? = settings_config ? settings_config.notice? : false
+
+    # --- Who she looks like -----------------------------------------------------
+
+    # The name a REQUESTER sees. Disclosure is not a badge somebody might
+    # miss: when she discloses, the name itself says what she is.
+    def disclosed_name
+      return name unless disclosed?
+
+      I18n.t("support_desk.assistant.disclosed_name", name: name)
+    end
+
+    # chats reads a display name through the host's own lambda, which
+    # usually tries these in order — so all three answer the disclosed name
+    # and no host has to special-case a support assistant.
+    def display_name = disclosed_name
+    def to_s = disclosed_name
+    def support_agent_name = disclosed_name
+    def support_agent_avatar = avatar
+
+    # --- Duty -------------------------------------------------------------------
+
+    # The kill switch, read fresh from the row on every transition.
+    def on_duty? = active?
+
+    # Unlimited by construction: her ceiling is `max_turns` per case and the
+    # policy, not a number of cases.
+    def support_capacity = nil
+
+    # Stop her everywhere, now. Cases she holds are released by the silent
+    # sweep (`SupportDesk.release_silent_assistants!`), which also asks for a
+    # person on each of them — run it, or wait for its schedule, before
+    # calling the desk quiet.
+    def deactivate!(by:, reason: nil)
+      update!(active: false)
+      SupportDesk.logger&.warn(
+        "[support_desk] assistant #{key} deactivated by #{SupportDesk.actor_key(by) || "somebody"}" \
+        "#{": #{reason}" if reason.present?}"
+      )
+      self
+    end
+
+    # Put her back on duty.
+    def activate!(by:)
+      update!(active: true)
+      SupportDesk.logger&.info(
+        "[support_desk] assistant #{key} activated by #{SupportDesk.actor_key(by) || "somebody"}"
+      )
+      self
+    end
+
+    # --- Where she works --------------------------------------------------------
+
+    # The desks whose configuration points at her.
+    def desks
+      SupportDesk.config.desks.each_key.filter_map do |desk_key|
+        SupportDesk.desk(desk_key) if SupportDesk.config.desk(desk_key).assistant_key == key.to_sym
+      end
+    end
+
+    # The open cases she is sitting on.
+    def held_tickets
+      Ticket.open.assigned_to(self)
+    end
+
+    # The assistant, in one line.
+    def inspect
+      "#<SupportDesk::Assistant #{key} #{name.inspect} #{autonomy} #{active? ? "active" : "inactive"}>"
+    end
+
+    private
+
+    # Her configuration, or nil when nothing declares her any more. Every
+    # reader goes through this so a historical row still renders.
+    def settings_config
+      return nil unless configured?
+
+      config
+    end
+  end
+end

data/lib/support_desk/models/concerns/requester.rb

@@ -9,6 +9,12 @@ module SupportDesk
   #   alice.support_desk
   #   alice.awaiting_support_reply?
   #   alice.unread_support_count
+  #
+  #   class User < ApplicationRecord
+  #     has_support_tickets
+  #
+  #     def support_context = { "Plan" => plan.name, "Viajes" => rides.count }
+  #   end
   module Requester
     extend ActiveSupport::Concern
 
@@ -69,6 +75,18 @@ module SupportDesk
       )
     end
 
+    # Key/value pairs about the PERSON, the way `Supportable#support_context`
+    # is key/value pairs about the thing they are asking about: their plan,
+    # how long they have been here, whatever your agents always look up
+    # anyway. Rendered in the console's context card, and included in
+    # `Ticket#brief`.
+    #
+    # Empty by default, and it stays empty until you fill it — everything
+    # in here is read by whoever answers the case, and by whatever model a
+    # harness hands the brief to. Put what an agent needs to help; leave out
+    # what they don't.
+    def support_context = {}
+
     # True when any of this requester's open tickets is waiting on the desk.
     def awaiting_support_reply?
       support_tickets.not_closed.awaiting_reply.exists?

data/lib/support_desk/models/desk.rb

@@ -79,12 +79,35 @@ module SupportDesk
       config.read(:email) || settings["email"].presence
     end
 
-    # The agent pool, resolved from `config.agents`.
+    # The assistant who works this desk, or nil. Resolved through
+    # `SupportDesk.assistant`, so it is the same memoised record everywhere.
+    def assistant
+      key = config.assistant_key
+      return nil if key.nil?
+
+      SupportDesk.assistant(key)
+    end
+
+    # Whether this desk has one at all.
+    def assistant? = !assistant.nil?
+
+    # The PEOPLE in the pool. What `agents_to_notify` pages, what a human
+    # picker offers, and the reason a host never has to reject machines in
+    # its own notifier.
+    def humans
+      config.agent_pool.to_a.reject { |agent| SupportDesk.ai_actor?(agent) }
+    end
+
+    # Everybody who can answer here, the assistant included — pickers and
+    # routing. An Array, not a relation: the assistant isn't in the host's
+    # scope, and a pool that is half a query and half a record is a pool
+    # that can't be either.
     def agents
-      config.agent_pool
+      humans + [ assistant ].compact
     end
 
-    # The pool, minus anyone who says they're off duty.
+    # The pool, minus anyone who says they're off duty (a deactivated
+    # assistant says so).
     def on_duty_agents
       agents.select { |agent| !agent.respond_to?(:on_duty?) || agent.on_duty? }
     end

data/lib/support_desk/models/draft.rb

@@ -0,0 +1,266 @@
+# frozen_string_literal: true
+
+module SupportDesk
+  # A reply the assistant proposes and a human sends — or doesn't.
+  #
+  #   draft = ticket.pending_draft
+  #   draft.send!(by: lucia, seen_turn: ticket.assistant_turn)          # verbatim
+  #   draft.send!(by: lucia, seen_turn: …, body: "Casi: …")             # edited
+  #   draft.reject!(by: lucia, reason: "no es eso")
+  #
+  # == Who wrote it
+  #
+  # A sent draft is a message from the HUMAN who sent it (12 #20): they read
+  # it, they own it, and the requester sees their signature. What the machine
+  # contributed is provenance — `support_desk.drafted_by`, `draft_id` and
+  # `edited` in the message's metadata, and this row, which keeps the
+  # original body even when the sent one was edited.
+  #
+  # == Staleness is not a warning, it is the contract
+  #
+  # `proposed_turn` is the ticket's turn when the draft was written.
+  # `seen_turn` is the turn the reviewer was LOOKING at. Sending compares
+  # `seen_turn` against the case's turn right now, under its row lock — so a
+  # draft approved from a page that predates the customer's next message is
+  # refused (SupportDesk::StaleTurn) rather than sent into a conversation
+  # that has moved on. There is no "send anyway" flag: re-read the case and
+  # submit again with the current turn.
+  class Draft < ApplicationRecord
+    self.table_name = "support_desk_drafts"
+
+    # pending → sent | rejected (a human decided), or superseded (a newer
+    # proposal, a takeover, a pause) | expired (the case closed).
+    STATUSES = %w[pending sent rejected superseded expired].freeze
+
+    # Enough for any honest answer, and a ceiling on what a model can stuff
+    # into a JSON column.
+    MAX_SOURCES = 20
+    MAX_SOURCE_TITLE = 500
+    MAX_SOURCE_URL = 2048
+
+    belongs_to :ticket, class_name: "SupportDesk::Ticket", inverse_of: :drafts
+    belongs_to :author, polymorphic: true
+    belongs_to :reviewed_by, polymorphic: true, optional: true
+    belongs_to :sent_message, class_name: "Chats::Message", optional: true
+
+    # Attachments ride on ActiveStorage when the host has it installed —
+    # the same condition chats' own messages use.
+    has_many_attached :files if defined?(ActiveStorage)
+
+    # Ruby-side defaults so both are always usable even on MySQL, where a
+    # JSON column can't carry a DB default.
+    attribute :sources, default: -> { [] }
+    attribute :metadata, default: -> { {} }
+
+    validates :status, inclusion: { in: STATUSES }
+    validates :proposed_turn, presence: true
+    validates :confidence, numericality: { greater_than_or_equal_to: 0, less_than_or_equal_to: 1 },
+                           allow_nil: true
+    validate :body_or_files_present
+    validate :sources_well_formed
+
+    scope :pending, -> { where(status: "pending") }
+    scope :sent, -> { where(status: "sent") }
+    scope :rejected, -> { where(status: "rejected") }
+    scope :superseded, -> { where(status: "superseded") }
+    scope :expired, -> { where(status: "expired") }
+    # What a human actually decided about — the denominator every acceptance
+    # number in the README is measured against.
+    scope :reviewed, -> { where(status: %w[sent rejected]) }
+    scope :verbatim, -> { sent.where(sent_body: nil) }
+    scope :edited, -> { sent.where.not(sent_body: nil) }
+    scope :by, ->(author) { where(author_type: author.class.polymorphic_name, author_id: author.id) }
+    scope :chronological, -> { order(:created_at, :id) }
+    scope :newest_first, -> { order(created_at: :desc, id: :desc) }
+
+    def pending? = status == "pending"
+    def sent? = status == "sent"
+    def rejected? = status == "rejected"
+    def superseded? = status == "superseded"
+    def expired? = status == "expired"
+
+    # Whether the case has changed since this was proposed — a customer
+    # message, a human note, a takeover, anything. The turn is the whole
+    # answer: it moves for every one of them.
+    def stale?
+      pending? && proposed_turn.to_s != ticket.assistant_turn
+    end
+
+    # Whether the human rewrote it before sending.
+    def edited? = sent? && sent_body.present?
+
+    # What the requester got (or would get): the edit when there was one.
+    def final_body = sent_body.presence || body
+
+    # The declared confidence as a whole percentage, or nil.
+    def confidence_percent
+      return nil if confidence.nil?
+
+      (confidence.to_f * 100).round
+    end
+
+    # Who proposed it, as the stable key event payloads and metadata use.
+    def author_key = SupportDesk.actor_key(author)
+
+    # Whether this draft has attachments to carry to the message.
+    def files_attached? # :nodoc:
+      respond_to?(:files) && files.attached?
+    end
+
+    # --- The two decisions --------------------------------------------------------
+
+    # Send it: the message is the HUMAN's, the proposal is provenance.
+    # `seen_turn` is the case's turn as the reviewer's page rendered it, and
+    # a mismatch is a refusal — see the class comment. `body:` replaces the
+    # text (an edit); nil sends it verbatim. Returns the Chats::Message.
+    def send!(by:, seen_turn:, body: nil, request: nil)
+      human = ticket.send(:resolve_actor, by)
+      if human.is_a?(Symbol) || SupportDesk.ai_actor?(human)
+        raise NotAllowed,
+              "an assistant can't approve her own draft — a person sends it, and it is signed by them"
+      end
+      ticket.send(:ensure_agent!, human)
+      raise ArgumentError, "seen_turn: is required — send the turn the page was rendered with" if seen_turn.blank?
+      if !body.nil? && body.to_s.strip.empty? && !files_attached?
+        raise ArgumentError, "an edited draft can't be blank — reject it instead"
+      end
+
+      message = nil
+      ticket.with_lock(requires_new: true) do
+        reload
+        ticket.send(:reconcile_unregistered_messages!)
+        raise InvalidTransition, "draft #{id} is #{status}, not pending" unless pending?
+        unless seen_turn.to_s == ticket.assistant_turn
+          raise StaleTurn,
+                "the case changed since you read it (#{seen_turn} → #{ticket.assistant_turn}); read it again"
+        end
+
+        final = body.nil? ? self.body : body
+        edited = final != self.body
+        # BEFORE anything moves: `stale?` reads `pending?`, and the update
+        # below is what stops it being true.
+        was_stale = stale?
+
+        message = ticket.reply!(
+          final, by: human, files: (files_attached? ? files.blobs : []), request: request,
+          metadata: { "support_desk" => { "drafted_by" => author_key, "draft_id" => id.to_s, "edited" => edited } }
+        )
+        update!(status: "sent", reviewed_by: human, reviewed_at: Time.current, sent_message: message,
+                sent_body: (final if edited))
+        ticket.send(:reset_draft_associations!)
+        ticket.send(:write_transition!, :draft_sent, actor: human, request: request) do
+          { "draft" => id.to_s, "assistant" => author_key, "edited" => edited,
+            "was_stale" => was_stale, "message" => message.id.to_s }
+        end
+      end
+
+      SupportDesk.emit_after_commit(:draft_sent, ticket, self, message, by: human)
+      message
+    end
+
+    # Throw it away, with a reason worth reading later: the rejection reasons
+    # are what tell a host whether an assistant is ready for a higher level.
+    def reject!(by:, reason: nil, request: nil)
+      human = ticket.send(:resolve_actor, by)
+      if human.is_a?(Symbol) || SupportDesk.ai_actor?(human)
+        raise NotAllowed, "an assistant can't review her own draft"
+      end
+      ticket.send(:ensure_agent!, human)
+
+      ticket.with_lock(requires_new: true) do
+        reload
+        raise InvalidTransition, "draft #{id} is #{status}, not pending" unless pending?
+
+        update!(status: "rejected", reviewed_by: human, reviewed_at: Time.current,
+                rejection_reason: reason.presence&.to_s)
+        ticket.send(:reset_draft_associations!)
+        ticket.send(:write_transition!, :draft_rejected, actor: human, request: request) do
+          { "draft" => id.to_s, "assistant" => author_key, "reason" => reason.presence&.to_s }
+        end
+      end
+
+      SupportDesk.emit_after_commit(:draft_rejected, ticket, self, by: human, reason: reason)
+      self
+    end
+
+    # A newer proposal, a human reply, a takeover or a pause replaced it.
+    # Idempotent, and writes no event: nobody decided anything.
+    def supersede! # :nodoc:
+      return self unless pending?
+
+      update!(status: "superseded")
+      self
+    end
+
+    # The case closed under it.
+    def expire! # :nodoc:
+      return self unless pending?
+
+      update!(status: "expired")
+      self
+    end
+
+    # The draft, in one line.
+    def inspect
+      "#<SupportDesk::Draft #{id} #{status} ticket=#{ticket_id} #{author_key}>"
+    end
+
+    private
+
+    # A model wrote these, so the shape is whatever came back. `to_h` is the
+    # generous reading (a list of pairs, a hash-like object) and it RAISES on
+    # anything else — `["title", "x"]` is a TypeError, not a hash — so the
+    # coercion answers nil and the validation below says what it wanted,
+    # instead of taking the save down with an exception nobody can act on.
+    def coerce_source(entry)
+      return entry.stringify_keys if entry.is_a?(Hash)
+      return nil if entry.is_a?(String) || !entry.respond_to?(:to_h)
+
+      entry.to_h.stringify_keys
+    rescue TypeError, ArgumentError
+      nil
+    end
+
+    def body_or_files_present
+      return if body.present? || files_attached?
+
+      errors.add(:body, "can't be blank without an attachment")
+    end
+
+    # A model wrote these. They render as links in a console, so they are
+    # checked like anything a stranger typed: a list, of pairs, with http(s)
+    # URLs and nothing longer than a page can show.
+    def sources_well_formed
+      value = sources
+      return if value.blank?
+
+      unless value.is_a?(Array)
+        errors.add(:sources, "must be a list of { title:, url: } entries")
+        return
+      end
+      if value.size > MAX_SOURCES
+        errors.add(:sources, "can't have more than #{MAX_SOURCES} entries (got #{value.size})")
+        return
+      end
+
+      value.each do |original|
+        entry = coerce_source(original)
+        unless entry.is_a?(Hash)
+          errors.add(:sources, "entries must be { title:, url: } hashes, got #{original.class}")
+          next
+        end
+
+        title = entry["title"]
+        url = entry["url"]
+        errors.add(:sources, "every entry needs a title") if title.blank?
+        errors.add(:sources, "a title can't be longer than #{MAX_SOURCE_TITLE} characters") if
+          title.to_s.length > MAX_SOURCE_TITLE
+        next if url.blank?
+
+        errors.add(:sources, "a url can't be longer than #{MAX_SOURCE_URL} characters") if
+          url.to_s.length > MAX_SOURCE_URL
+        errors.add(:sources, "url #{url.inspect} must be http(s)") unless url.to_s.match?(%r{\Ahttps?://}i)
+      end
+    end
+  end
+end

data/lib/support_desk/models/event.rb

@@ -14,6 +14,16 @@ module SupportDesk
     KINDS = %w[
       opened assigned handed_off released drop_in closed reopened topic_changed subject_attached note
       snoozed woken escalated channel_added email_bounced email_unverified rated tagged
+      human_requested assistant_paused assistant_resumed draft_sent draft_rejected assistant_withheld
+    ].freeze
+
+    # The five kinds that describe how the desk works rather than what
+    # happened to the case. They join `note` and `drop_in` outside
+    # #requester_visible: a customer's export says a person was asked for
+    # (`escalated`, `human_requested`), never that a machine's proposal was
+    # discarded.
+    INTERNAL_KINDS = %w[
+      note drop_in assistant_paused assistant_resumed draft_sent draft_rejected assistant_withheld
     ].freeze
 
     belongs_to :ticket, class_name: "SupportDesk::Ticket", inverse_of: :events
@@ -28,7 +38,7 @@ module SupportDesk
     scope :notes, -> { where(kind: "note") }
     # Everything a requester may see in an export: their own case's story,
     # never the desk's internal reasoning.
-    scope :requester_visible, -> { where.not(kind: %w[note drop_in]) }
+    scope :requester_visible, -> { where.not(kind: INTERNAL_KINDS) }
 
     # Write one event. `actor` may be a record or a Symbol (`:system`,
     # `:routing`) — symbols are kept in the payload, since there is no row
@@ -64,6 +74,10 @@ module SupportDesk
     # The text of an internal note, for kind "note".
     def note = payload["note"]
 
+    # The one-paragraph "here is where I got to" an assistant leaves when she
+    # hands a case over, for kinds "escalated" and "human_requested".
+    def summary = payload["summary"]
+
     # The event, in one line.
     def inspect
       "#<SupportDesk::Event #{kind} ticket=#{ticket_id} #{created_at&.iso8601}>"