support_desk 0.2.0 → 0.3.0

data/lib/support_desk/outcome.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module SupportDesk
+  # What `Ticket#respond!` did — the one verb whose answer depends on policy,
+  # so the harness can hand over an answer without first working out what it
+  # is allowed to become.
+  #
+  #   outcome = ticket.respond!(text, by: rose, turn: turn)
+  #   outcome.sent?       # it went to the requester
+  #   outcome.drafted?    # a human will send it
+  #   outcome.withheld?   # nothing was written, and #reason says why
+  #   outcome.turn        # the successor turn, for a second action in the same run
+  Outcome = Struct.new(:action, :message, :draft, :policy, :reason, :turn, keyword_init: true) do
+    def sent? = action == :sent
+    def drafted? = action == :drafted
+    def withheld? = action == :withheld
+
+    # Whether the case was ALSO handed to a person: the budget ran out
+    # mid-conversation, so the draft is waiting and so is a human.
+    def escalated? = reason == :max_turns
+
+    # Ids, not records: this is what a log line or a job argument wants.
+    def to_h
+      {
+        action: action,
+        message: message&.id,
+        draft: draft&.id,
+        reason: reason,
+        turn: turn,
+        policy: policy&.to_h
+      }
+    end
+
+    def inspect
+      "#<SupportDesk::Outcome #{action}#{" #{reason}" if reason} turn=#{turn}>"
+    end
+  end
+end

data/lib/support_desk/queue.rb

@@ -14,7 +14,7 @@ module SupportDesk
   class Queue
     # Every tab a queue can answer for, in display order. `scope` and
     # `counts` both cover all of them.
-    TABS = %i[awaiting mine unassigned open snoozed closed].freeze
+    TABS = %i[awaiting needs_human mine unassigned open snoozed closed].freeze
 
     # Tabs whose FEATURE hasn't shipped yet. Snoozing lands in 0.2: until a
     # ticket can actually be snoozed, the tab is a permanent column of
@@ -24,7 +24,8 @@ module SupportDesk
     # by name — but nothing offers the tab.
     UNRELEASED_TABS = %i[snoozed].freeze
 
-    # The tabs a console should render, in display order.
+    # The tabs a console should render, in display order. `needs_human` is
+    # in the list but not always shown — see #visible_tabs.
     VISIBLE_TABS = (TABS - UNRELEASED_TABS).freeze
 
     # How long a nav badge may lie. Long enough that a busy console isn't
@@ -72,6 +73,14 @@ module SupportDesk
       scoped.open.awaiting_reply.most_urgent_first
     end
 
+    # Open, and somebody has asked for a person on it: the assistant handed
+    # it over, the customer pressed the door, or the silent sweep did. First
+    # in the list on purpose — a case a machine could not finish is the one
+    # that must never be the one nobody looks at.
+    def needs_human
+      scoped.open.needs_human.most_urgent_first
+    end
+
     # Put aside until a date, the soonest to wake first (0.2).
     def snoozed = scoped.snoozed.order(:snoozed_until)
 
@@ -87,10 +96,10 @@ module SupportDesk
     # (status, awaiting, assignee) and adding up in Ruby costs one round
     # trip; six `.count` calls cost six.
     def counts
-      rows = scoped.group(:status, :awaiting, :assignee_type, :assignee_id).count
+      rows = scoped.group(:status, :awaiting, :assignee_type, :assignee_id, needs_human_grouping).count
 
       counts = TABS.index_with(0)
-      rows.each do |(status, awaiting, assignee_type, assignee_id), count|
+      rows.each do |(status, awaiting, assignee_type, assignee_id, needs_human), count|
         assigned_to_me = agent_key == [ assignee_type, assignee_id.to_s ]
 
         case status
@@ -99,6 +108,7 @@ module SupportDesk
           counts[:mine] += count if assigned_to_me
           counts[:unassigned] += count if assignee_id.nil?
           counts[:awaiting] += count if awaiting == "agent"
+          counts[:needs_human] += count if needs_human.to_i.positive?
         when "snoozed" then counts[:snoozed] += count
         when "closed" then counts[:closed] += count
         end
@@ -106,6 +116,18 @@ module SupportDesk
       counts
     end
 
+    # The tabs THIS desk should render. `needs_human` only means something
+    # where a machine answers, so a desk without an assistant and without a
+    # single flagged case is not given a column of zeros to learn to ignore.
+    #
+    # Takes the numbers when the caller already has them (`tabs` does), so
+    # rendering a tab bar is one query and not two.
+    def visible_tabs(numbers = counts)
+      return VISIBLE_TABS if desk.assistant? || numbers[:needs_human].to_i.positive?
+
+      VISIBLE_TABS - [ :needs_human ]
+    end
+
     # The nav badge: open tickets this agent should feel responsible for —
     # theirs, plus everything nobody has picked up. Cached briefly per agent.
     def badge
@@ -124,7 +146,7 @@ module SupportDesk
     # ready to render.
     def tabs
       numbers = counts
-      VISIBLE_TABS.map { |tab| [ tab, I18n.t("support_desk.queue.tabs.#{tab}"), numbers[tab] ] }
+      visible_tabs(numbers).map { |tab| [ tab, I18n.t("support_desk.queue.tabs.#{tab}"), numbers[tab] ] }
     end
 
     # The relation behind a tab name, so a console can route `params[:tab]`
@@ -149,6 +171,20 @@ module SupportDesk
       Ticket.where(desk: desk)
     end
 
+    # "Has somebody asked for a person on this case?", as something every
+    # adapter can GROUP BY. A boolean column would group differently on
+    # three databases; a CASE expression counts the same everywhere.
+    #
+    # Built when it is CALLED, and from `table_name` rather than
+    # `quoted_table_name`: an identifier assembled at class-definition time
+    # is one more thing that has to work during `assets:precompile` in a
+    # container with no database, and the rest of this gem keeps every
+    # identifier inside a lambda or a method for exactly that reason. The
+    # name is the gem's own constant, so there is nothing to quote.
+    def needs_human_grouping
+      Arel.sql("CASE WHEN #{Ticket.table_name}.human_required_at IS NULL THEN 0 ELSE 1 END")
+    end
+
     def mine_or_unassigned
       scoped.open.where(
         Ticket.arel_table[:assignee_id].eq(nil).or(

data/lib/support_desk/test_helpers.rb

@@ -101,6 +101,158 @@ module SupportDesk
                    "expected no #{kind} event on #{ticket.reference}"
     end
 
+    # --- Assistants -------------------------------------------------------------
+
+    # The assistant record for +key+ (the desk's default when omitted).
+    def support_assistant(key = nil)
+      SupportDesk.assistant(key)
+    end
+
+    # Answer as the assistant and let policy decide what that becomes.
+    # Returns the SupportDesk::Outcome.
+    def respond_as(assistant, ticket, body = nil, turn: ticket.assistant_turn, **options)
+      ticket.respond!(body, by: assistant, turn: turn, **options)
+    end
+
+    # Propose a reply as the assistant. Returns the SupportDesk::Draft.
+    def draft_as(assistant, ticket, body = nil, turn: ticket.assistant_turn, **options)
+      ticket.draft!(body, by: assistant, turn: turn, **options)
+    end
+
+    # --- Assistant assertions ---------------------------------------------------
+
+    # There is a proposal waiting, optionally matching its text (a String is
+    # a substring, a Regexp is a match). Returns the draft.
+    def assert_pending_draft(ticket, body: nil)
+      ticket.reload
+      draft = ticket.pending_draft
+
+      refute_nil draft, "expected a pending proposal on #{ticket.reference}, found " \
+                        "#{ticket.drafts.map(&:status).join(", ").presence || "none"}"
+      case body
+      when Regexp then assert_match body, draft.body.to_s
+      when String then assert_includes draft.body.to_s, body
+      end
+      draft
+    end
+
+    # Nothing is waiting to be sent.
+    def refute_pending_draft(ticket)
+      ticket.reload
+
+      assert_nil ticket.pending_draft,
+                 "expected no pending proposal on #{ticket.reference}, found #{ticket.pending_draft&.body.inspect}"
+    end
+
+    # Somebody has asked for a person on this case, optionally for this
+    # reason ("requester_request", "phrase", "assistant_silent", …).
+    def assert_needs_human(ticket, reason: nil)
+      ticket.reload
+
+      assert_predicate ticket, :human_required?,
+                       "expected #{ticket.reference} to need a person"
+      return if reason.nil?
+
+      assert_equal reason.to_s, ticket.human_required_reason,
+                   "#{ticket.reference} needs a person for a different reason"
+    end
+
+    # Nobody has.
+    def refute_needs_human(ticket)
+      ticket.reload
+
+      refute_predicate ticket, :human_required?,
+                       "expected #{ticket.reference} not to need a person " \
+                       "(#{ticket.human_required_reason})"
+    end
+
+    # The assistant is sitting on this case.
+    def assert_held_by_assistant(ticket, assistant = nil)
+      ticket.reload
+
+      assert_predicate ticket, :held_by_assistant?,
+                       "expected #{ticket.reference} to be held by an assistant, was #{ticket.assignee.inspect}"
+      return if assistant.nil?
+
+      assert ticket.assigned_to?(assistant),
+             "expected #{ticket.reference} to be held by #{assistant.key}, was #{ticket.assignee.inspect}"
+    end
+
+    # No machine has said anything to the requester in this case.
+    def refute_assistant_spoke(ticket)
+      ticket.reload
+      spoken = ticket.conversation.messages.to_a.select { |message| ticket.assistant_message?(message) }
+
+      assert_empty spoken.map(&:body),
+                   "expected the assistant to have said nothing on #{ticket.reference}"
+    end
+
+    # What she may do here, and why. `because:` takes a String (substring) or
+    # a Regexp, because the sentence is the point: a level with no reason is
+    # a refusal nobody can act on.
+    def assert_assistant_policy(ticket, level, because: nil)
+      policy = ticket.reload.assistant_policy
+
+      assert_equal level.to_sym, policy.level,
+                   "expected #{ticket.reference} to be at #{level} for the assistant (#{policy.because})"
+      case because
+      when Regexp then assert_match because, policy.because
+      when String then assert_includes policy.because, because
+      end
+      policy
+    end
+
+    # --- Assistant configuration ------------------------------------------------
+
+    # Run a block with different assistant settings, then put them back:
+    #
+    #   with_assistant_config(autonomy: :reply) { … }
+    #   with_assistant_config(:rose, max_turns: 1) { … }
+    def with_assistant_config(key = nil, **overrides)
+      key ||= SupportDesk.config.default_assistant_key
+      configuration = SupportDesk.config.assistant(key)
+      previous = overrides.keys.index_with { |name| configuration.read(name) }
+      had = overrides.keys.index_with { |name| configuration.own?(name) }
+
+      overrides.each { |name, value| configuration.public_send(:"#{name}=", value) }
+      yield
+    ensure
+      previous.each do |name, value|
+        had[name] ? configuration.public_send(:"#{name}=", value) : configuration.send(:reset_setting, name)
+      end
+    end
+
+    # Run a block with one topic capped, then put the tree back.
+    #
+    # The tree is frozen at boot, so this REBUILDS it with the cap applied —
+    # the same shape a host would have declared with `topic :payments,
+    # assistant: :draft`, without asking a test to restate the whole tree.
+    def with_topic_assistant_cap(path, level, desk: :default)
+      configuration = SupportDesk.config.desk(desk)
+      original = configuration.topics
+      configuration.instance_variable_set(:@topics, rebuild_topics_with_cap(original, path.to_s, level))
+      yield
+    ensure
+      configuration.instance_variable_set(:@topics, original)
+    end
+
+    private
+
+    def rebuild_topics_with_cap(tree, path, level) # :nodoc:
+      rebuilt = SupportDesk::TopicTree.new
+      copy = lambda do |node, parent|
+        options = node.options.dup
+        options[:assistant] = level if node.path == path
+        fresh = SupportDesk::Topic.new(key: node.key, parent: parent, **options)
+        rebuilt.add(fresh, parent: parent)
+        node.children.each { |child| copy.call(child, fresh) }
+      end
+      tree.roots.each { |root| copy.call(root, nil) }
+      rebuilt.freeze!
+    end
+
+    public
+
     # --- Configuration ----------------------------------------------------------
 
     # Run a block with different desk settings, then put them back:

data/lib/support_desk/timeline.rb

@@ -7,41 +7,60 @@ module SupportDesk
   #   ticket.timeline.each { |entry| … }
   #   ticket.timeline.print          # in `rails c`
   #
-  # Entries wrap either a Chats::Message or a SupportDesk::Event, and answer
-  # the same three questions — when, who, what.
+  # Entries wrap a Chats::Message, a SupportDesk::Event or a decided
+  # SupportDesk::Draft, and answer the same three questions — when, who,
+  # what.
+  #
+  # A draft is here because it is the only part of the story with no message
+  # and no event of its own to carry it: the event says a proposal was sent
+  # or discarded, and the row is what the proposal actually SAID. A pending
+  # one is not history yet, so it stays out — it is on the screen above,
+  # waiting for somebody.
   class Timeline
     include Enumerable
 
     # One moment in a case.
     class Entry
-      attr_reader :at, :message, :event
+      attr_reader :at, :message, :event, :draft
 
-      # One moment: a message, or an event, and when it happened.
-      def initialize(at:, message: nil, event: nil)
+      # One moment: a message, an event or a decided proposal, and when it
+      # happened.
+      def initialize(at:, message: nil, event: nil, draft: nil)
         @at = at
         @message = message
         @event = event
+        @draft = draft
       end
 
-      # Which of the two this moment is.
+      # Which of the three this moment is.
       def message? = !message.nil?
       def event? = !event.nil?
+      def draft? = !draft.nil?
 
-      # :message, or the event's kind (:assigned, :closed, :note…).
+      # :message, :draft, or the event's kind (:assigned, :closed, :note…).
       def kind
-        message? ? :message : event.kind.to_sym
+        return :message if message?
+        return :draft if draft?
+
+        event.kind.to_sym
       end
 
       # Who is responsible for this moment: a message's author (the agent
-      # who signed it) or sender, or an event's actor.
+      # who signed it) or sender, an event's actor, or — for a proposal —
+      # the person who decided about it, falling back to the machine that
+      # wrote it when nobody did.
       def actor
+        return draft.reviewed_by || draft.author if draft?
         return event.actor_or_system if event?
 
         message.try(:author) || message.sender
       end
 
-      # What was said, or what a note said. Nil for the rest.
+      # What was said, what a note said, or what a proposal proposed. Nil
+      # for the rest.
       def body
+        return draft.final_body if draft?
+
         message? ? message.try(:visible_body) : event.note
       end
 
@@ -71,7 +90,8 @@ module SupportDesk
 
     # Every moment, oldest first.
     def entries
-      @entries ||= (message_entries + event_entries).sort_by { |entry| [ entry.at || Time.at(0), entry.kind.to_s ] }
+      @entries ||= (message_entries + event_entries + draft_entries)
+                   .sort_by { |entry| [ entry.at || Time.at(0), entry.kind.to_s ] }
     end
 
     # How many moments the case has had, and the latest one.
@@ -100,5 +120,14 @@ module SupportDesk
     def event_entries
       ticket.events.chronological.map { |event| Entry.new(at: event.created_at, event: event) }
     end
+
+    # Proposals somebody decided about — sent, discarded, or overtaken.
+    # One query, and on the overwhelming majority of desks it returns
+    # nothing at all, because nothing has ever proposed anything.
+    def draft_entries
+      ticket.drafts.where.not(status: "pending").chronological.includes(:author, :reviewed_by).map do |draft|
+        Entry.new(at: draft.created_at, draft: draft)
+      end
+    end
   end
 end

data/lib/support_desk/topic.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "active_model/type"
+require_relative "assistant_policy"
 
 module SupportDesk
   # What a ticket is about, as a value object.
@@ -190,6 +191,24 @@ module SupportDesk
     # An agent scope or proc that wins over desk routing for this subtree.
     def route_to = inherited_or_own(:route_to)
 
+    # The most the assistant may produce on a case filed here: the MINIMUM
+    # over this node's own cap and every ancestor's own cap, or nil when
+    # nobody capped anything.
+    #
+    # Deliberately not an INHERITED_OPTION. Inheritance would let a child
+    # widen what its parent narrowed — `payments` capped at :draft with a
+    # `payments/refund` declared :reply would be a child handing itself
+    # authority its parent refused. A minimum can only tighten.
+    def assistant_cap
+      caps = [ self, *ancestors ].filter_map(&:own_assistant_cap)
+      caps.min_by { |level| AssistantPolicy::RANK.fetch(level) }
+    end
+
+    # This node's OWN cap, ignoring the tree (what #assistant_cap minimises).
+    def own_assistant_cap # :nodoc:
+      options[:assistant]&.to_sym
+    end
+
     # The desk key tickets under this topic belong to.
     def desk_key
       desk_override || :default
@@ -254,6 +273,9 @@ module SupportDesk
 
       def unknown? = true
       def retired? = true
+      # A path no tree knows is a path nobody has reasoned about, so the
+      # assistant may look and nothing else.
+      def assistant_cap = :observe
       def label = translate(i18n_key(:label)) || @path.tr("/", " ").humanize
       def about = []
       def subject_mode = :none

data/lib/support_desk/topic_tree.rb

@@ -163,7 +163,7 @@ module SupportDesk
 
       KNOWN_OPTIONS = %i[
         label about ask candidates subject prefill placeholder only priority route_to desk retired icon
-        free_form
+        free_form assistant
       ].freeze
 
       def validate!(key, options)
@@ -190,6 +190,12 @@ module SupportDesk
                 "got #{options[:priority].inspect}"
         end
 
+        if options.key?(:assistant) && !AssistantPolicy::LEVELS.include?(options[:assistant]&.to_sym)
+          raise ConfigurationError,
+                "topic #{key.inspect}: assistant must be one of #{AssistantPolicy::LEVELS.inspect}, " \
+                "got #{options[:assistant].inspect}"
+        end
+
         %i[candidates only prefill].each do |option|
           next unless options.key?(option)
           next if option == :prefill && options[option].is_a?(String)