support_desk 0.1.3 → 0.3.0

data/lib/support_desk/console_engine.rb

@@ -48,6 +48,8 @@ module SupportDesk
     # that makes a later precedence bug much harder to read. SupportDesk
     # ::Engine already ships them for both namespaces.
     paths["config/locales"] = []
+    # The requester engine owns task discovery too; both share this root.
+    paths["lib/tasks"] = []
 
     # `concerns: :support_console` in the HOST's routes file. Registered from
     # an initializer, which is early enough: the app's routes are not drawn

data/lib/support_desk/console_routes.rb

@@ -1,15 +1,20 @@
 # frozen_string_literal: true
 
 module SupportDesk
-  # The `:support_console` routing concern — the one line that turns two
+  # The `:support_console` routing concern — the one line that turns a few
   # RESTful actions into a working console:
   #
   #   namespace :madmin do
-  #     resources :support_tickets, only: %i[index show], concerns: :support_console
+  #     resources :support_tickets, only: %i[index show new], concerns: :support_console
   #   end
   #
-  # It draws the collection route first and the member routes after, which is
-  # what keeps `/madmin/support_tickets/next` from being swallowed by
+  # `new` stays yours — add it to `only:` when you render the form the
+  # console's `open_conversation` posts to ("Write to someone"). The concern
+  # draws the collection routes (`next`, `open_conversation`) and every
+  # member verb.
+  #
+  # It draws the collection routes first and the member routes after, which
+  # is what keeps `/madmin/support_tickets/next` from being swallowed by
   # `/madmin/support_tickets/:id` (a `resources` block draws its concerns
   # before its own member mappings, so "next" wins).
   #
@@ -26,8 +31,11 @@ module SupportDesk
     # The name a host writes in their routes file.
     CONCERN = :support_console
 
-    # The member verbs, in the order an agent uses them.
-    MEMBER_VERBS = %i[reply take assign hand_off release close reopen note change_topic].freeze
+    # The verbs, from the ONE table that has them: the concern that answers
+    # them owns it, so a verb can never be routed without an action or
+    # answered without a route. Kept here as an alias for a release, because
+    # a host may have read it.
+    MEMBER_VERBS = SupportDesk::Console::MEMBER_VERBS
 
     # Rails' own message for this ("can't use collection outside resource(s)
     # scope") is true and says nothing about which concern caused it, which
@@ -82,12 +90,16 @@ module SupportDesk
       # to every route, which is how `concerns :support_console, path: "t"`
       # keeps working.
       def call(mapper, options = {})
+        # Read at DRAW time, from SupportDesk::Console — which is loaded by
+        # the spine long before any routes file runs, so there is no
+        # load-order risk in taking the verbs from the concern that answers
+        # them rather than keeping a second list here.
         mapper.collection do
-          mapper.get :next, **options
+          SupportDesk::Console::COLLECTION_VERBS.each { |verb, method| mapper.public_send(method, verb, **options) }
         end
 
         mapper.member do
-          MEMBER_VERBS.each { |verb| mapper.post verb, **options }
+          SupportDesk::Console::MEMBER_VERBS.each { |verb| mapper.post verb, **options }
         end
       rescue ArgumentError => e
         raise unless e.message.include?("outside resource")

data/lib/support_desk/context_card.rb

@@ -59,9 +59,40 @@ module SupportDesk
       Chats.avatar_for(requester)
     end
 
+    # Key/value pairs about the PERSON, from `Requester#support_context` —
+    # the same idea as #pairs, one row up: `pairs` describes the thing the
+    # case is about, these describe whoever is asking. Empty unless the host
+    # filled it in.
+    def requester_pairs
+      requester.try(:support_context) || {}
+    end
+
     # When this requester joined — context for "is this a new user?".
     def requester_since = requester.try(:created_at)
 
+    # Who opened the case, as the console should print it: their name when
+    # the record still resolves, the desk's name in front of it when WE
+    # wrote first, and an honest label when there is no record to name.
+    #
+    # The three unnameable cases are not the same thing and must not read the
+    # same way: no provenance at all, an actor whose record is gone, and a
+    # requester-opened case, which is just their name.
+    #
+    # "Not recorded" rather than "automation": 0.2 opens every case as a
+    # record (automation openers are refused — docs/12-open-questions.md
+    # Q17), so a NULL pair is a row 0.1 wrote and nobody has backfilled yet,
+    # which is exactly what `SupportDesk.doctor` asks somebody to do.
+    def opened_by_label
+      opener = ticket.opened_by
+      return I18n.t("support_desk.console.context.not_recorded") if ticket.opened_by_id.blank?
+      return I18n.t("support_desk.console.context.unavailable") if opener.nil?
+
+      name = opener.try(:support_agent_name) || Chats.display_name_for(opener)
+      return name if ticket.opened_by_requester?
+
+      "#{ticket.desk.name} · #{name}"
+    end
+
     # How many open cases this requester has right now, this one included.
     def requester_open_tickets
       Ticket.not_closed.where(requester: requester).count
@@ -79,7 +110,8 @@ module SupportDesk
         requester: {
           name: requester_name,
           since: requester_since,
-          open_tickets: requester_open_tickets
+          open_tickets: requester_open_tickets,
+          context: requester_pairs
         }
       }
     end

data/lib/support_desk/doctor.rb

@@ -103,6 +103,13 @@ module SupportDesk
           ok_with("#{tree.count} topic(s), #{tree.leaves.size} leaf/leaves")
         end
 
+        checks << check("opening lines (#{desk.key})") do
+          problems = desk.opening_line_problems
+          next fail_with(problems.join("; ")) if problems.any?
+
+          ok_with("resolve")
+        end
+
         checks << check("supportables (#{desk.key})") do
           missing = desk.topics.about_class_names.reject do |name|
             klass = name.safe_constantize
@@ -114,6 +121,81 @@ module SupportDesk
         end
       end
 
+      checks << check("find_requester") do
+        callable = SupportDesk.config.find_requester
+        next ok_with("not set — the console takes a GlobalID from your own pages") if callable.nil?
+        next fail_with("find_requester must respond to #call") unless callable.respond_to?(:call)
+
+        # Asked of the SHAPE, never by calling it: a diagnostic that runs a
+        # host's lookup is a diagnostic that queries production. A callable
+        # object is as valid as a lambda, so `arity` (Proc-only) is out.
+        parameters = callable.respond_to?(:parameters) ? callable.parameters : callable.method(:call).parameters
+        required = parameters.count { |type, _| type == :req }
+        open_ended = parameters.any? { |type, _| %i[opt rest].include?(type) }
+        unless required <= 1 && (required == 1 || open_ended)
+          next fail_with("find_requester takes #{required} required argument(s); the console calls it with one")
+        end
+
+        ok_with("the console can look people up")
+      end
+
+      if SupportDesk.config.assistants.any?
+        checks << check("assistants (config)") do
+          problems = []
+          warnings = []
+          SupportDesk.config.assistants.each_value do |assistant|
+            problems.concat(assistant.line_problems)
+            warnings << "#{assistant.key} has no max_turns — a loop with no bound is a loop" if
+              assistant.max_turns.nil?
+            warnings << "#{assistant.key} has no responds_within — nothing will notice if she goes quiet" if
+              assistant.responds_within.nil?
+          end
+          SupportDesk.config.desks.each_value do |desk|
+            key = desk.assistant_key
+            next if key.nil? || SupportDesk.config.assistant?(key)
+
+            problems << "desk #{desk.key} points at assistant #{key.inspect}, which isn't configured"
+          end
+          next fail_with(problems.join("; ")) if problems.any?
+          next warn_with(warnings.join("; ")) if warnings.any?
+
+          ok_with("#{SupportDesk.config.assistants.size} assistant(s) configured")
+        end
+
+        checks << check("assistant turn subscriber") do
+          next ok_with("no assistant on any desk") if assistant_desks.empty?
+          next warn_with("nothing subscribes to :assistant_turn — no harness will ever answer. See the " \
+                         "README's assistants section") if SupportDesk.subscribers[:assistant_turn].empty?
+
+          ok_with("#{SupportDesk.subscribers[:assistant_turn].size} subscriber(s)")
+        end
+
+        checks << check("assistant authorship") do
+          blank = assistant_desks.filter_map do |desk|
+            assistant = desk.assistant
+            assistant.key if Chats.display_name_for(assistant).blank?
+          end
+          next fail_with("chats has no display name for #{blank.join(", ")} — a signed message would go out " \
+                         "unsigned; check `Chats.config.messager_display_name`") if blank.any?
+
+          ok_with("every assistant has a name chats can print")
+        end
+
+        checks << check("ai agents without policy") do
+          strays = SupportDesk.agent_class_names.select do |name|
+            klass = name.safe_constantize
+            next false if klass.nil? || klass == SupportDesk::Assistant
+            next false unless klass.respond_to?(:support_desk_agent_options)
+
+            klass.support_desk_agent_options[:kind] == :ai
+          end
+          next warn_with("#{strays.join(", ")} declares `kind: :ai` but isn't this gem's assistant — every " \
+                         "support write by it, or to it, is refused") if strays.any?
+
+          ok_with("no unmanaged AI agents")
+        end
+      end
+
       checks << check("engine mount") do
         path = SupportDesk.root_path
         next warn_with("SupportDesk::Engine isn't mounted — requesters have nowhere to write") if path.nil?
@@ -162,7 +244,7 @@ module SupportDesk
       return [ check("database") { warn_with("support_desk tables are missing — run rails db:migrate") } ] unless
         tables?
 
-      [
+      checks = [
         check("conversations") do
           orphans = Ticket.where(conversation_id: nil).count
           next fail_with("#{orphans} ticket(s) without a conversation") if orphans.positive?
@@ -185,8 +267,33 @@ module SupportDesk
 
           ok_with("assignee matches the open assignment")
         end,
+        check("provenance") do
+          next warn_with("no opened_by column — run `rails g support_desk:upgrade` and migrate") unless
+            Ticket.column_names.include?("opened_by_id")
+
+          half = Ticket.where(opened_by_type: nil).where.not(opened_by_id: nil)
+                       .or(Ticket.where.not(opened_by_type: nil).where(opened_by_id: nil)).count
+          next fail_with("#{half} ticket(s) with half an opened_by (a type and no id, or the reverse)") if
+            half.positive?
+
+          # NULL is not automation: nothing in this version writes it, so
+          # every one of these is a row 0.1 opened, or one an old process
+          # wrote during the upgrade window.
+          legacy = Ticket.where(opened_by_id: nil).count
+          next warn_with("#{legacy} case(s) don't say who opened them — run " \
+                         "`rake support_desk:backfill_opened_by`") if legacy.positive?
+
+          ok_with("every case says who opened it")
+        end,
         check("awaiting") do
-          stale = Ticket.awaiting_reply.where("last_agent_message_at > last_requester_message_at").count
+          # The NULL leg is not decoration: `last_agent_message_at >
+          # last_requester_message_at` is NULL when the requester has never
+          # written, so a case waiting on the desk that only the desk has
+          # spoken in slips past a plain comparison.
+          stale = Ticket.awaiting_reply.where(
+            "last_agent_message_at > last_requester_message_at OR " \
+            "(last_agent_message_at IS NOT NULL AND last_requester_message_at IS NULL)"
+          ).count
           next fail_with("#{stale} ticket(s) waiting on the desk after the desk already answered") if stale.positive?
 
           ok_with("awaiting agrees with the transcript")
@@ -198,6 +305,92 @@ module SupportDesk
           ok_with("references are unique")
         end
       ]
+
+      checks.concat(assistant_invariant_checks)
+      checks
+    end
+
+    # The assistants' own invariants: nobody sitting on a case they may not
+    # work, nobody silently not answering, one pending proposal per case.
+    #
+    # Every one of them is asked of EVIDENCE — a seat, a timestamp, a row —
+    # and never of the policy's own verdict. A policy cannot page anybody
+    # about its own bug.
+    def assistant_invariant_checks
+      # Nothing about a feature nobody turned on: a host with no assistant
+      # configured runs not one extra query (I1).
+      return [] if SupportDesk.config.assistants.empty?
+      return [] unless assistants_migrated?
+
+      checks = []
+
+      SupportDesk.config.assistants.each_key do |key|
+        assistant = SupportDesk.assistant(key)
+        window = assistant&.responds_within
+        next if window.nil?
+
+        checks << check("assistant silence (#{key})") do
+          quiet = Ticket.open.assigned_to(assistant).awaiting_reply.waiting_over(window).count
+          next fail_with("#{quiet} case(s) have waited longer than #{window.inspect} for #{key} — is the " \
+                         "harness running? `rake support_desk:release_silent_assistants` hands them over") if
+            quiet.positive?
+
+          ok_with("nobody is waiting on #{key}")
+        end
+      end
+
+      checks << check("assistant seats") do
+        seated = Ticket.open.held_by_assistants.to_a
+        wrong = seated.reject { |ticket| ticket.assistant_policy.may_hold? }
+        next fail_with("#{wrong.size} case(s) held by an assistant who may not hold them " \
+                       "(#{wrong.first(3).map(&:reference).join(", ")}) — release them") if wrong.any?
+
+        ok_with("#{seated.size} seat(s), all of them allowed")
+      end
+
+      assistant_desks.each do |desk|
+        window = desk.assistant.responds_within
+        next if window.nil?
+
+        checks << check("assistant idle turns (#{desk.key})") do
+          idle = Ticket.open.for_desk(desk.key).assistant_idle_since((window * 3).ago).count
+          next warn_with("#{idle} case(s) have had no answer and no assistant action — the harness may be " \
+                         "down; `rake support_desk:redispatch_assistant_turns` re-emits their turns") if
+            idle.positive?
+
+          ok_with("every turn has been picked up")
+        end
+      end
+
+      checks << check("drafts") do
+        duplicated = Draft.pending.group(:ticket_id).having("COUNT(*) > 1").count.size
+        next fail_with("#{duplicated} case(s) with more than one pending proposal") if duplicated.positive?
+
+        orphaned = Draft.pending.where(ticket_id: Ticket.closed.select(:id)).count
+        next warn_with("#{orphaned} pending proposal(s) on closed cases — a close expires them, so these " \
+                       "predate 0.3 or were written by hand") if orphaned.positive?
+
+        ok_with("at most one pending proposal per case")
+      end
+
+      checks
+    end
+
+    # The desks that actually have an assistant, as Desk records.
+    def assistant_desks
+      SupportDesk.config.desks.each_key.filter_map do |key|
+        desk = SupportDesk.desk(key)
+        desk if desk&.assistant?
+      end
+    rescue StandardError
+      []
+    end
+
+    def assistants_migrated?
+      Ticket.column_names.include?("human_required_at") &&
+        ActiveRecord::Base.connection.table_exists?(Draft.table_name)
+    rescue StandardError
+      false
     end
 
     def tables?

data/lib/support_desk/engine.rb

@@ -135,6 +135,16 @@ module SupportDesk
       # the worst shape for a bug. Found by the CarHey integration (#2).
       _desk = SupportDesk::Desk
 
+      # And the assistant, for the THIRD registry with the same shape:
+      # `acts_as_support_agent` registers a class when that class loads, and
+      # both `SupportDesk.agent_class?` and the doctor's "ai agents without
+      # policy" check read that registry. Under lazy autoloading nothing has
+      # referenced her before the first case is answered, so the doctor would
+      # report a healthy desk as having no assistant at all. A constant
+      # reference and nothing else: no row is created and no connection is
+      # needed to load the class.
+      _assistant = SupportDesk::Assistant
+
       SupportDesk.config.validate_classes! if SupportDesk.configured?
     end
   end

data/lib/support_desk/errors.rb

@@ -17,6 +17,11 @@ module SupportDesk
   # agent (no `acts_as_support_agent`, or its `if:` said no).
   class NotAnAgent < Error; end
 
+  # Raised when the record handed to a requester-side operation isn't an
+  # eligible requester (no `has_support_tickets`, or its `if:` said no) — a
+  # closed account, for instance, can neither ask nor be written to.
+  class NotARequester < Error; end
+
   # Raised by `hand_off!` when the actor doesn't currently hold the ticket.
   class NotTheAssignee < Error; end
 
@@ -46,4 +51,41 @@ module SupportDesk
 
   # Raised when a requester is already at `config.max_open_tickets`.
   class TooManyOpenTickets < Error; end
+
+  # Raised when an AI-kind actor is not the desk's own SupportDesk::Assistant.
+  # A host model declared `acts_as_support_agent kind: :ai` never inherits
+  # human authority: every support write by it, or to it, is refused rather
+  # than quietly treated as a human's (see the README's assistants section).
+  class NotAnAssistant < NotAnAgent; end
+
+  # Raised when the assistant's policy forbids the verb on this case. It
+  # carries the policy that refused and the verb that was asked for, so a
+  # host can log the RULE rather than parse the sentence.
+  class AssistantNotAllowed < NotAllowed
+    attr_reader :policy, :verb
+
+    def initialize(policy, verb:, message: nil)
+      @policy = policy
+      @verb = verb.to_sym
+      super(message || default_message)
+    end
+
+    private
+
+    # "rose may not reply on T-AB12CD: topic payments caps rose at draft" —
+    # who, what, where, and the rule that decided it.
+    def default_message
+      return "an assistant may not #{@verb} here" if @policy.nil?
+
+      "#{@policy.assistant&.key || "the assistant"} may not #{@verb} on " \
+        "#{@policy.ticket&.reference || "this case"}: #{@policy.because}"
+    end
+  end
+
+  # Raised when an assistant acts on a turn that is no longer the case's:
+  # somebody (the requester, a human, the assistant itself) changed the case
+  # since it was read. A subclass of InvalidTransition, so a host that
+  # rescues that still catches it — and a late, retried or redelivered job
+  # writes nothing.
+  class StaleTurn < InvalidTransition; end
 end

data/lib/support_desk/events.rb

@@ -34,6 +34,17 @@ module SupportDesk
       ticket_topic_changed: "ticket, from:, to:, by:",
       subject_attached: "ticket, subject, by:",
       note_added: "ticket, event",
+      # The assistants (0.3). `assistant_turn` is the one a harness
+      # subscribes to: everything else is something to notify a human about.
+      assistant_turn: "ticket, assistant, message, turn:",
+      draft_proposed: "ticket, draft",
+      draft_sent: "ticket, draft, message, by:",
+      draft_rejected: "ticket, draft, by:, reason:",
+      assistant_withheld: "ticket, assistant, reason:, policy:",
+      ticket_escalated: "ticket, from:, reason:, by:",
+      human_requested: "ticket, by:, reason:",
+      assistant_paused: "ticket, by:",
+      assistant_resumed: "ticket, by:",
       ticket_transitioned: "ticket, kind, by:, request:, payload:"
     }.freeze
 
@@ -112,11 +123,7 @@ module SupportDesk
     end
 
     def report_subscriber_error(error, event)
-      if defined?(Rails) && Rails.respond_to?(:error) && Rails.error
-        Rails.error.report(error, handled: true, source: "support_desk", context: { event: event })
-      else
-        logger&.error("[support_desk] subscriber raised on #{event}: #{error.class}: #{error.message}")
-      end
+      report_error(error, context: { event: event, hook: :subscriber })
     end
   end
 end

data/lib/support_desk/macros.rb

@@ -20,11 +20,15 @@ module SupportDesk
   module Macros
     # The requester side. `desk:` names which desk this model writes to;
     # `as:` records a role on every ticket ("driver", "passenger") so the
-    # console can tell two kinds of requester apart.
-    def has_support_tickets(desk: :default, as: nil)
+    # console can tell two kinds of requester apart; `if:` is the per-record
+    # check for "may this person ask for help — and be written to — right
+    # now" (`if: :kept?` for a host with soft-deleted accounts).
+    def has_support_tickets(desk: :default, as: nil, **options)
+      condition = Macros.condition!(options, macro: "has_support_tickets", known: ":if, :desk, :as")
+
       include SupportDesk::Requester
 
-      self.support_desk_requester_options = { desk: desk.to_sym, as: as&.to_s }.freeze
+      self.support_desk_requester_options = { desk: desk.to_sym, as: as&.to_s, if: condition }.freeze
       SupportDesk.register_requester(self)
     end
 
@@ -48,26 +52,51 @@ module SupportDesk
 
     # The agent side: who may answer. `if:` is the per-record eligibility
     # check (a Symbol method name or a callable); `kind:` is :human or :ai.
-    # No verbs are added — the ticket is the subject of every sentence
-    # (`ticket.assign!(to: lucia)`), never the agent.
+    # One verb is added — `open_support_conversation_with!`, the only agent
+    # action that has no ticket yet. Everything else keeps the ticket as the
+    # 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 }.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
+    # question asked of a different side, and two copies of it would be two
+    # places to fix the day one grows a third shape.
+    def self.condition!(options, macro:, known:)
       unknown = options.keys - [ :if ]
       if unknown.any?
         raise ConfigurationError,
-              "unknown acts_as_support_agent option#{"s" if unknown.size > 1} " \
-              "#{unknown.map(&:inspect).join(", ")} — known options are :if, :kind"
+              "unknown #{macro} option#{"s" if unknown.size > 1} " \
+              "#{unknown.map(&:inspect).join(", ")} — known options are #{known}"
       end
 
       condition = options[:if]
       unless condition.nil? || condition.is_a?(Symbol) || condition.respond_to?(:call)
         raise ConfigurationError,
-              "acts_as_support_agent if: must be a method name or a callable, got #{condition.inspect}"
+              "#{macro} if: must be a method name or a callable, got #{condition.inspect}"
       end
 
-      include SupportDesk::Agent
-
-      self.support_desk_agent_options = { if: condition, kind: kind.to_sym }.freeze
-      SupportDesk.register_agent(self)
+      condition
     end
   end
 end

data/lib/support_desk/models/assignment.rb

@@ -11,7 +11,9 @@ module SupportDesk
   class Assignment < ApplicationRecord
     self.table_name = "support_desk_assignments"
 
-    REASONS = %w[taken assigned handed_off routed drop_in_takeover escalated reopened].freeze
+    # `opened`: the agent who wrote first holds the case. It is a seat nobody
+    # was told about — see Ticket.open!(by:) — not an assignment somebody made.
+    REASONS = %w[taken assigned handed_off routed drop_in_takeover escalated reopened opened].freeze
     RELEASE_REASONS = %w[handed_off released shift_end closed escalated].freeze
 
     belongs_to :ticket, class_name: "SupportDesk::Ticket", inverse_of: :assignments