support_desk 0.1.3 → 0.3.0

data/lib/generators/support_desk/templates/assistant/turn_job.rb.erb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module Support
+  # <%= assistant_name %>'s turn.
+  #
+  # The gem emits `:assistant_turn` when there is something to answer; this
+  # job is the only thing that runs between that event and a word reaching a
+  # customer.
+  #
+  # Four rules, and they are the whole contract (README → Assistants):
+  #
+  # 1. **Arguments are ids, never records and never a prompt.** A serialized
+  #    ticket is a ticket as it was when the job was enqueued, and by the
+  #    time a worker picks it up that is a guess.
+  # 2. **Check the turn before spending money.** `assistant_turn` moves on
+  #    every message and every transition, so a mismatch means the case
+  #    changed while this job waited — and the newer turn's job already
+  #    exists. Returning here costs nothing; calling a model costs money to
+  #    produce an answer that would be refused anyway.
+  # 3. **Hand the answer to exactly one verb**, all of them `by:` her and
+  #    `turn:` this turn. Each consumes the turn and returns the successor
+  #    (`Outcome#turn` / `ticket.assistant_turn`); a second action in the
+  #    same run uses that one.
+  # 4. **`SupportDesk::StaleTurn` and `Locked` are normal outcomes**, not
+  #    failures — hence `discard_on` below. `SupportDesk::AssistantNotAllowed`
+  #    is NOT: the brief said `may_not`, so reaching it is a bug in here.
+  class <%= key.camelize %>TurnJob < ApplicationJob
+    queue_as :support
+
+    # A late job, a redelivered one and a case that moved on all land as
+    # StaleTurn, and all three mean the same thing: somebody else has this.
+    # Locked means there is nobody to write to any more. RecordNotFound
+    # means the case is gone. None of them is worth a retry.
+    #
+    # Provider timeouts ARE worth one — put `retry_on` for those here. Note
+    # that a retry AFTER a committed action raises StaleTurn and is
+    # discarded, which is exactly right: the work was done.
+    discard_on SupportDesk::StaleTurn, SupportDesk::Locked, ActiveRecord::RecordNotFound
+
+    def perform(ticket_id, assistant_key, turn)
+      ticket = SupportDesk::Ticket.find(ticket_id)
+      return unless ticket.assistant_turn == turn          # the case moved on while we waited
+
+      <%= key %> = SupportDesk.assistant(assistant_key)
+      return unless ticket.assistant_policy(<%= key %>).may_observe?
+
+      answer = <%= service_class %>.answer(ticket.brief, ticket.transcript)
+
+      case answer.kind
+      when :answer
+        # `respond!` lets POLICY decide what this becomes: sent, proposed as
+        # a draft for a person to send, or withheld with a reason on the
+        # record. Never encode the level in here — it changes per case.
+        ticket.respond!(answer.text, by: <%= key %>, turn: turn, confidence: answer.confidence,
+                                     sources: answer.sources, metadata: answer.metadata)
+      when :hand_off
+        ticket.escalate!(by: <%= key %>, turn: turn, reason: answer.reason, summary: answer.summary)
+      when :note
+        # Staff only. Never reaches the conversation.
+        ticket.note!(answer.text, by: <%= key %>, turn: turn)
+      when :nothing
+        # She decided not to act. The turn is NOT consumed and the case
+        # stays in the humans' queue — which is why `SupportDesk.doctor`
+        # counts idle turns: a harness that always answers :nothing looks
+        # exactly like one that is down.
+        nil
+      else
+        raise ArgumentError, "unsupported answer kind #{answer.kind.inspect}"
+      end
+    end
+  end
+end

data/lib/generators/support_desk/templates/assistant/turn_job_test.rb.erb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require "test_helper"
+
+# The three things about a harness that are worth a test, and the only three
+# that are the same in every app: the level decides what her answer BECOMES,
+# raising the level changes that and nothing else, and a turn that is no
+# longer the case's writes nothing at all.
+#
+# <%= service_class %>.answer is stubbed throughout — this is a test of the
+# wiring, not of a model. Point `requester` and `agent` at your own fixtures
+# and it runs.
+class <%= key.camelize %>TurnJobTest < ActiveSupport::TestCase
+  include SupportDesk::TestHelpers
+
+  setup do
+    @<%= key %> = SupportDesk.assistant(:<%= key %>)
+    @ticket = open_support_ticket(for: requester, message: "No me han pagado")
+  end
+
+  test "at :draft her answer waits for a person" do
+    answering("Lo estamos revisando") do
+      <%= job_class %>.perform_now(@ticket.id, "<%= key %>", @ticket.assistant_turn)
+    end
+
+    draft = assert_pending_draft @ticket, body: "revisando"
+    assert_equal @<%= key %>, draft.author
+    # Nothing reached the customer: a proposal is not a message.
+    refute_assistant_spoke @ticket
+  end
+
+  test "at :reply she answers the customer herself" do
+    with_assistant_config(:<%= key %>, autonomy: :reply) do
+      answering("Lo estamos revisando") do
+        <%= job_class %>.perform_now(@ticket.id, "<%= key %>", @ticket.assistant_turn)
+      end
+    end
+
+    assert_awaiting_requester @ticket
+    refute_pending_draft @ticket
+  end
+
+  test "a stale turn writes nothing and costs nothing" do
+    stale = @ticket.assistant_turn
+    ask_again(@ticket, "¿hola?")   # the customer wrote again: the turn moved
+
+    called = false
+    <%= service_class %>.stub(:answer, ->(*) { called = true; answer_for("…") }) do
+      <%= job_class %>.perform_now(@ticket.id, "<%= key %>", stale)
+    end
+
+    assert_not called, "the job called the model on a turn that was no longer the case's"
+    refute_pending_draft @ticket
+    refute_assistant_spoke @ticket
+  end
+
+  private
+
+  # The person asking. Point this at your own fixture or factory.
+  def requester = users(:one)
+
+  def answer_for(text)
+    <%= service_class %>::Answer.new(kind: :answer, text: text, confidence: 0.9)
+  end
+
+  def answering(text, &block)
+    <%= service_class %>.stub(:answer, ->(*) { answer_for(text) }, &block)
+  end
+end

data/lib/generators/support_desk/templates/console/controller.rb.erb

@@ -16,7 +16,7 @@ module <%= module_name %>
   # The routes come from the `:support_console` routing concern:
   #
   #   namespace :<%= target %> do
-  #     resources :support_tickets, only: %i[index show], concerns: :support_console
+  #     resources :support_tickets, only: %i[index show new], concerns: :support_console
   #   end
   #
   # Both `index` and `show` are yours — the gem deliberately doesn't own the

data/lib/generators/support_desk/templates/initializer.rb

@@ -19,6 +19,23 @@ SupportDesk.configure do |config|
   #
   # config.agents { User.where(admin: true) }
 
+  # Who may ask, and who may answer, record by record — the macros' `if:`:
+  #
+  #   class User < ApplicationRecord
+  #     has_support_tickets if: :kept?          # a closed account can neither
+  #     acts_as_support_agent if: :admin?       # ask nor be written to
+  #   end
+  #
+  # `has_support_tickets if:` is a WRITE rule, not a screen rule: the thread
+  # and its history stay readable when it turns false.
+
+  # How the console finds the person an agent types in "Write to someone":
+  # email, phone, handle — your call. Given the typed string, return a
+  # requester record or nil. Without it the console accepts only a GlobalID
+  # from one of your own pages.
+  #
+  # config.find_requester { |query| User.find_by(email: query.to_s.strip.downcase) }
+
   # ==========================================================================
   # CONTROLLER INTEGRATION
   # ==========================================================================
@@ -105,6 +122,19 @@ SupportDesk.configure do |config|
   #
   # config.announce_assignments = :first_only
   #
+  # The system line a thread opens with, posted inside the opening
+  # transaction and before the first message. A String with %{label},
+  # %{desk} and %{reply_within}, a Symbol naming an I18n key, a block given
+  # the ticket, or nil for no line at all.
+  #
+  # The second one is for a case the DESK opened
+  # (`lucia.open_support_conversation_with!(alice, "Vimos que…")`): it has a
+  # default, because a message from a desk somebody never wrote to has to
+  # explain itself.
+  #
+  # config.opening_line = "Has abierto una conversación sobre «%{label}». Te contestamos aquí."
+  # config.opening_line_from_support = "%{desk} ha abierto esta conversación contigo sobre «%{label}»."
+  #
   # What a requester writing into a closed ticket does:
   #   :reopen_on_reply  the case comes back (no wall, no dead end)
   #   :locked           the composer is replaced by a notice
@@ -145,6 +175,39 @@ SupportDesk.configure do |config|
   # config.mirror_replies_by_email = :when_away   # :always | :when_away | :never
   # config.auto_close_after = nil                 # e.g. 7.days
 
+  # ==========================================================================
+  # AN ASSISTANT (0.3)
+  # ==========================================================================
+  #
+  # An AI agent, with the guardrails in code. `autonomy` is the most she may
+  # ever produce; topics only cap it DOWN. `disclosure` is REQUIRED — whether
+  # a customer is told they are talking to a machine is your decision, and
+  # `:none` is how you say "nothing", on purpose.
+  #
+  # config.assistant :rose do |rose|
+  #   rose.name            = "Rose"
+  #   rose.autonomy        = :draft                # :off :observe :draft :reply :resolve
+  #   rose.disclosure      = :signature_and_notice # :signature | :notice | :none
+  #   rose.max_turns       = 6
+  #   rose.responds_within = 3.minutes
+  #   rose.hand_off_when { |_ticket, message| message.body.to_s.match?(/\bpersona\b/i) }
+  #   rose.cap { |ticket| :draft if ticket.requester.try(:vip?) }
+  # end
+  # config.default_assistant = :rose
+  #
+  # The desk-level binding, for installations with more than one desk. An
+  # explicit nil means "no assistant HERE", which is not the same as
+  # inheriting the default one.
+  #
+  # config.desk(:billing) { |desk| desk.assistant = nil }
+  #
+  # Then subscribe your harness to the one event it needs — see the README's
+  # assistants section for the whole contract.
+  #
+  # SupportDesk.on(:assistant_turn, key: "support.rose.turn") do |ticket, assistant, _message, turn:|
+  #   Support::RoseTurnJob.set(wait: 20.seconds).perform_later(ticket.id, assistant.key, turn)
+  # end
+
   # ==========================================================================
   # MORE THAN ONE DESK
   # ==========================================================================

data/lib/generators/support_desk/upgrade_generator.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require "rails/generators/base"
+require "rails/generators/active_record"
+
+module SupportDesk
+  module Generators
+    # `rails generate support_desk:upgrade` — copy the migrations a version
+    # bump needs into an EXISTING install. Nothing else: the initializer, the
+    # views, the console and the routes you already own stay untouched.
+    #
+    # Currently writes the 0.2.0 migration (who opened the case), which is the
+    # SAME template a fresh install runs — one file owns those columns, so a
+    # fresh install and an upgraded one end up with the same schema and the
+    # same rollback. Running this twice writes nothing the second time: the
+    # migration already sitting in db/migrate is identical, and Rails skips it.
+    class UpgradeGenerator < Rails::Generators::Base
+      include ActiveRecord::Generators::Migration
+
+      source_root File.expand_path("templates", __dir__)
+      desc "Add the migrations a support_desk version bump needs (0.2.0: opened_by, 0.3.0: assistants)"
+
+      # Rails' migration numbering, borrowed from ActiveRecord's generators.
+      def self.next_migration_number(dir)
+        ActiveRecord::Generators::Base.next_migration_number(dir)
+      end
+
+      def create_opened_by_migration
+        migration_template "add_opened_by_to_support_desk_tickets.rb.erb",
+                           File.join(db_migrate_path, "add_opened_by_to_support_desk_tickets.rb")
+      end
+
+      def create_assistants_migration
+        migration_template "add_assistants_to_support_desk.rb.erb",
+                           File.join(db_migrate_path, "add_assistants_to_support_desk.rb")
+      end
+
+      def display_post_upgrade_message
+        say "\n🎫 support_desk upgrade migrations copied.", :green
+        say "\n  1. Run 'rails db:migrate'. It adds `opened_by` and points every existing"
+        say "     case at its requester — 0.1 had no other way to open one."
+        say "  2. New in 0.2.0:"
+        say "       lucia.open_support_conversation_with!(alice, \"Vimos que…\")   # the desk writes first"
+        say "       ticket.opened_by / opened_by_support? / opened_by_requester?"
+        say "       config.opening_line / config.opening_line_from_support / config.find_requester"
+        say "       has_support_tickets if: :kept?                                 # who may be written to"
+        say "  3. Migrate BEFORE 0.2 serves traffic. Pause support writes; stop and drain"
+        say "     ALL old web requests and workers. This is NOT a rolling deployment."
+        say "     Keep traffic paused, run 'rake support_desk:backfill_opened_by' under 0.2,"
+        say "     verify no NULL openers remain, then start only 0.2 and resume traffic."
+        say "  4. New in 0.3.0 — assistants. The migration is ADDITIVE and rolling-safe:"
+        say "     add `config.assistant` only once every process is on 0.3.0. Then"
+        say "       rails g support_desk:assistant Rose --disclosure signature"
+        say "     writes the harness and prints the stanza, the subscription and the two"
+        say "     scheduled tasks. It never edits your initializer."
+        say "  5. See the CHANGELOG for the full list.\n", :green
+      end
+
+      private
+
+      def migration_version
+        "[#{ActiveRecord::VERSION::STRING.to_f}]"
+      end
+    end
+  end
+end

data/lib/support_desk/assistant_policy.rb

@@ -0,0 +1,213 @@
+# frozen_string_literal: true
+
+module SupportDesk
+  # What the assistant may do on ONE case, right now, and why.
+  #
+  #   policy = ticket.assistant_policy
+  #   policy.level       # => :draft
+  #   policy.because     # => "topic payments caps rose at draft"
+  #   policy.may_reply?  # => false
+  #
+  # == Ceilings and floors
+  #
+  # A CEILING lowers what the assistant may ever produce here: her configured
+  # autonomy, the topic's cap (the minimum over the topic and every ancestor),
+  # the host's `cap` block, the case's persisted cap (what a reopen writes),
+  # and a pause. The lowest ceiling wins, and `because` names the rule that
+  # decided it — so a refusal can always be traced to one line of
+  # configuration.
+  #
+  # A FLOOR lowers the level because of the case's state: she is inactive,
+  # the case is closed, a person was asked for, or a human holds it. Floors
+  # run after ceilings and only ever lower.
+  #
+  # == It is the authorization, not a hint
+  #
+  # Every assistant verb asks this object, under the ticket's row lock, from
+  # freshly read state — `Ticket#actions_for` is a projection of the same
+  # decision, never a second opinion. No query: the topic is an in-memory
+  # lookup, the assignee is the loaded association, everything else is a
+  # column on the row we already hold.
+  class AssistantPolicy
+    # What the assistant may PRODUCE, from least to most. Ordered, and the
+    # order is the meaning: everything compares by RANK, never by name.
+    LEVELS = %i[off observe draft reply resolve].freeze
+    RANK = LEVELS.each_with_index.to_h.freeze
+
+    # The verbs each level unlocks. Every level's array is the previous one
+    # plus its own, written out rather than computed: a reader has to be able
+    # to see what ":reply" means without running anything.
+    VERBS_BY_LEVEL = {
+      off: [],
+      observe: %i[note escalate release],
+      draft: %i[note escalate release draft],
+      reply: %i[note escalate release draft reply take],
+      resolve: %i[note escalate release draft reply take close]
+    }.freeze
+
+    # Every verb the top level knows — what `forbidden_verbs` subtracts from.
+    ALL_VERBS = VERBS_BY_LEVEL.fetch(:resolve)
+
+    attr_reader :ticket, :assistant, :level, :because, :ceilings, :floors
+
+    # The policy for +assistant+ on +ticket+.
+    #
+    # `hand_back: true` asks a different question — "could she hold this case
+    # once the human-side flags were cleared?" — and is used by one caller,
+    # `Ticket#ensure_assignable!`, so that a human handing a case back is not
+    # refused by the very flags that hand-back exists to lift. The hard
+    # ceilings (autonomy, topic, the `cap` block) and the hard floors
+    # (inactive, closed) still apply.
+    def self.for(ticket, assistant = ticket.assistant, hand_back: false)
+      return Null.new(ticket, reason: "no assistant on desk #{ticket.desk&.key}") if assistant.nil?
+      unless SupportDesk::Ticket.same_actor?(assistant, ticket.assistant)
+        return Null.new(ticket, reason: "#{assistant.try(:key) || assistant.class} is not desk " \
+                                        "#{ticket.desk&.key}'s assistant")
+      end
+
+      config = assistant.config
+      ceilings = {
+        assistant: config.autonomy,
+        topic: ticket.topic&.assistant_cap,
+        cap: evaluate_cap(config, ticket),
+        case: (ticket.assistant_cap&.to_sym unless hand_back),
+        pause: (:off if ticket.assistant_paused? && !hand_back)
+      }.compact
+
+      # Hash#min_by yields [key, value]; destructuring it the other way round
+      # is how a policy starts reporting "the level caps her at :topic".
+      rule, level = ceilings.min_by { |_rule, value| RANK.fetch(value) }
+      because = ceiling_sentence(rule, level, assistant, ticket)
+      floors = []
+
+      if !assistant.active?
+        level = :off
+        because = "#{assistant.key} is inactive"
+        floors << :inactive
+      end
+      if ticket.closed? && RANK.fetch(level) > RANK.fetch(:observe)
+        level = :observe
+        because = "the case is closed"
+        floors << :closed
+      end
+      if !hand_back && ticket.human_required? && RANK.fetch(level) > RANK.fetch(:observe)
+        level = :observe
+        because = "a person was requested (#{ticket.human_required_reason})"
+        floors << :human_required
+      end
+      if !hand_back && ticket.assigned? && !ticket.assigned_to?(assistant) &&
+         RANK.fetch(level) > RANK.fetch(:draft)
+        level = :draft
+        because = "#{holder_name(ticket)} holds the case"
+        floors << :held_by_human
+      end
+
+      new(ticket: ticket, assistant: assistant, level: level, because: because,
+          ceilings: ceilings, floors: floors)
+    end
+
+    # Run the host's `cap` block and check what it said. A block that returns
+    # something that isn't a level is a configuration mistake, and it is
+    # named as one here rather than turning into a NoMethodError inside a
+    # transaction. A block that RAISES is the host's exception to see: it
+    # propagates (the one caller that can't afford that — the turn emitter —
+    # reports it and emits nothing).
+    def self.evaluate_cap(config, ticket) # :nodoc:
+      block = config.cap
+      return nil if block.nil?
+
+      value = block.call(ticket)
+      return nil if value.nil?
+
+      level = value.respond_to?(:to_sym) ? value.to_sym : value
+      unless LEVELS.include?(level)
+        raise ConfigurationError,
+              "assistant #{config.key}'s cap block must return one of #{LEVELS.map(&:inspect).join(", ")} " \
+              "or nil, got #{value.inspect}"
+      end
+
+      level
+    end
+
+    def self.ceiling_sentence(rule, level, assistant, ticket) # :nodoc:
+      case rule
+      when :assistant then "#{assistant.key}'s autonomy is #{level}"
+      when :topic then "topic #{ticket.topic&.path} caps #{assistant.key} at #{level}"
+      when :cap then "this desk's cap block caps #{assistant.key} at #{level}"
+      when :case then "this case caps #{assistant.key} at #{level}"
+      when :pause then "#{assistant.key} is paused on this case"
+      else "#{assistant.key} may work at #{level}"
+      end
+    end
+
+    def self.holder_name(ticket) # :nodoc:
+      ticket.assignee.try(:support_agent_name) || "somebody else"
+    end
+
+    private_class_method :ceiling_sentence, :holder_name
+
+    # Built by `.for`. The attributes are the whole object: a policy is a
+    # value, computed once under the lock and then only read.
+    def initialize(ticket:, assistant:, level:, because:, ceilings: {}, floors: [])
+      @ticket = ticket
+      @assistant = assistant
+      @level = level
+      @because = because
+      @ceilings = ceilings
+      @floors = floors
+    end
+
+    # Whether the effective level is at least +other+.
+    def at_least?(other)
+      RANK.fetch(level) >= RANK.fetch(other.to_sym)
+    end
+
+    # Whether this verb is unlocked at the effective level.
+    def may?(verb) = allowed_verbs.include?(verb.to_sym)
+
+    def may_observe? = at_least?(:observe)
+    def may_draft? = at_least?(:draft)
+    def may_reply? = at_least?(:reply)
+    # Holding a case means owing the next word, so it takes the level that
+    # may say one.
+    def may_hold? = may_reply?
+    def may_close? = at_least?(:resolve)
+
+    def allowed_verbs = VERBS_BY_LEVEL.fetch(level)
+    def forbidden_verbs = ALL_VERBS - allowed_verbs
+
+    # Whether this is the null policy — no assistant to ask about.
+    def null? = false
+
+    # The whole decision, as data: what goes into message metadata, a draft
+    # row and an event payload, so forensics never has to re-run the policy
+    # against a case that has moved on.
+    def to_h
+      {
+        assistant: assistant&.key,
+        level: level,
+        because: because,
+        ceilings: { assistant: ceilings[:assistant], topic: ceilings[:topic], cap: ceilings[:cap],
+                    case: ceilings[:case], pause: ceilings[:pause] },
+        floors: floors
+      }
+    end
+
+    # "draft — topic payments caps rose at draft"
+    def to_s = "#{level} — #{because}"
+
+    def inspect
+      "#<SupportDesk::AssistantPolicy #{assistant&.key || "none"} #{level} #{because.inspect}>"
+    end
+
+    # No assistant on this desk, or an assistant that is somebody else's.
+    # Every predicate says no, and `because` says which of the two it was.
+    class Null < AssistantPolicy
+      def initialize(ticket, reason:)
+        super(ticket: ticket, assistant: nil, level: :off, because: reason, ceilings: {}, floors: [])
+      end
+
+      def null? = true
+    end
+  end
+end