support_desk 0.2.0 → 0.3.2

data/lib/support_desk/models/ticket.rb

@@ -59,8 +59,15 @@ module SupportDesk
     # readonly record refuses to be destroyed. Deleting a ticket is the one
     # thing that takes its timeline with it, and it needs no callbacks.
     has_many :events, class_name: "SupportDesk::Event", inverse_of: :ticket, dependent: :delete_all
+    has_many :message_registrations, class_name: "SupportDesk::MessageRegistration", dependent: :delete_all
     has_many :messages, through: :conversation, source: :messages
 
+    # The assistant surface — the turn, the policy gates, her two verbs and
+    # the two exits — in its own file. The GATES inside the verbs below stay
+    # here, next to the verbs they guard: a reader looking at `close!` has to
+    # see what stops a machine closing a case.
+    include Assistance
+
     # Persist only the path. Resolving behavior needs this ticket's desk;
     # an attribute caster has no record context and cannot choose the tree.
     attribute :topic, Topic::Type.new
@@ -224,12 +231,14 @@ module SupportDesk
         # something to infer from Current.actor, and an agent passed as their
         # own requester is asking for help, not writing to themselves.
         by_support = !same_actor?(opener, requester)
-        ensure_opener!(opener) if by_support
+        ensure_opener!(opener, desk) if by_support
 
         # The subject is checked BEFORE the topic: "this isn't supportable" is
         # the useful error, and an unsupportable record has no topic to find.
         validate_subject!(about, requester)
         node = resolve_topic!(topic, about, desk, requester, about, by_support: by_support)
+        # The topic is what caps her, so the cap is checked once it is known.
+        ensure_assistant_may_open!(opener, requester, desk, node) if by_support && SupportDesk.ai_actor?(opener)
 
         cardinality = cardinality_key_for(requester: requester, subject: about, topic: node)
         existing = existing_for(requester: requester, desk: desk, subject: about, topic: node)
@@ -333,10 +342,14 @@ module SupportDesk
 
       # A loaded instance may predate revocation or deletion. Check the row,
       # just as requester eligibility does; this does not serialize revocation.
+      #
+      # Returns the FRESH record, so a caller that goes on to read a runtime
+      # flag off it (the assistant's `active?`, which the policy reads) is
+      # reading the row and not the copy it was handed (R9).
       def ensure_agent_record!(record) # :nodoc:
         if record.respond_to?(:persisted?) && record.persisted? && record.respond_to?(:support_agent?)
           current = record.class.uncached { record.class.find_by(id: record.id) }
-          return if current&.support_agent?
+          return current if current&.support_agent?
         end
 
         raise NotAnAgent, "#{record.class} is not a currently eligible, persisted support agent — " \
@@ -362,7 +375,7 @@ module SupportDesk
       # Automation (`by: :system`) is refused by name rather than by
       # NoMethodError three frames in — it is deferred work, not a typo (see
       # docs/12-open-questions.md Q17).
-      def ensure_opener!(opener)
+      def ensure_opener!(opener, desk)
         if opener.is_a?(Symbol)
           raise NotAnAgent, "can't open a ticket as #{opener.inspect} — a case is opened by somebody who can " \
                             "answer it, and automation openers aren't supported yet; pass an agent record"
@@ -371,6 +384,37 @@ module SupportDesk
           raise NotAnAgent, "can't open a ticket as an unsaved #{opener.class} — save the agent first"
         end
         ensure_agent_record!(opener)
+        return unless SupportDesk.ai_actor?(opener)
+
+        # Writing to somebody who never wrote to you is the one thing an
+        # assistant does that nobody asked for, so it takes its own
+        # permission on top of everything else.
+        unless opener.is_a?(SupportDesk::Assistant) && same_actor?(opener, desk.assistant)
+          raise NotAnAssistant,
+                "only desk #{desk.key}'s own assistant can open a case, and only when she may"
+        end
+        unless opener.may_open_conversations?
+          raise AssistantNotAllowed.new(nil, verb: :open,
+                                             message: "#{opener.key} may not open conversations — set " \
+                                                      "`may_open_conversations = true` if that is the intent")
+        end
+        return if AssistantPolicy::RANK.fetch(opener.autonomy) >= AssistantPolicy::RANK.fetch(:reply)
+
+        raise AssistantNotAllowed.new(nil, verb: :open,
+                                           message: "#{opener.key} works at #{opener.autonomy}: opening a " \
+                                                    "case means speaking first, which takes :reply")
+      end
+
+      # The topic's cap and the host's `cap` block, asked of the case this is
+      # ABOUT to be. Her per-case budget is not checked here: a brand new
+      # case has spent none of it, so the only way it could refuse is
+      # `max_turns 0`, and the policy below covers her level anyway.
+      def ensure_assistant_may_open!(opener, requester, desk, node)
+        candidate = new(desk: desk, requester: requester, topic: node)
+        policy = AssistantPolicy.for(candidate, opener)
+        return if policy.may_reply?
+
+        raise AssistantNotAllowed.new(policy, verb: :open)
       end
 
       def describe_record(record)
@@ -560,9 +604,12 @@ module SupportDesk
       # subscriber then finds the message already registered and does
       # nothing.
       def post_opening!(ticket, message, files:, by:, by_support:)
-        notice = post_opening_line!(ticket)
+        notices = [ post_opening_line!(ticket) ]
 
-        posted = if by_support
+        posted = if by_support && SupportDesk.ai_actor?(by)
+          notices << ticket.send(:post_disclosure_notice!, by) if by.notice?
+          ticket.send(:post_assistant_opening!, message, files: files, assistant: by)
+        elsif by_support
           # Never the inbound "no message, hand the ticket back" shortcut: a
           # desk that writes first with nothing to say is a chats validation
           # error, and this whole transaction goes with it.
@@ -572,7 +619,8 @@ module SupportDesk
         end
 
         ticket.send(:record_registration!, posted) if posted
-        pin_opening_line!(ticket, notice, posted)
+        ticket.send(:stamp_assistant_action!) if by_support && SupportDesk.ai_actor?(by)
+        pin_opening_lines!(ticket, notices, posted)
         ticket
       end
 
@@ -595,11 +643,16 @@ module SupportDesk
       # Only this new notice moves, never anybody's real message, and the
       # human message still owns the conversation's last-message pointer, so
       # nothing has to be recomputed afterwards.
-      def pin_opening_line!(ticket, notice, posted)
-        return if notice.nil?
+      def pin_opening_lines!(ticket, notices, posted)
+        notices = Array(notices).compact
+        return if notices.empty?
 
         anchor = posted&.created_at || ticket.opened_at
-        notice.update_columns(created_at: anchor - ordering_tick)
+        # Backwards, one tick each, so the last line written sits closest to
+        # the message and the first one opens the thread.
+        notices.reverse.each_with_index do |notice, index|
+          notice.update_columns(created_at: anchor - (ordering_tick * (index + 1)))
+        end
         # When there IS a first message it owns the conversation's
         # last-message pointer and nothing needs repairing. When there isn't,
         # the notice is that pointer, and chats denormalised its timestamp
@@ -622,8 +675,10 @@ module SupportDesk
       # running before any of it.
       def reply_into!(ticket, message, files:, by:, by_support:, request:, authorize_reuse:)
         if by_support
+          # Only this private outreach path supplies the current turn internally.
+          # Public replies must present the token their harness observed.
           ticket.send(:reply_under_lock!, message, by: by, files: files, request: request,
-                                                   authorize: authorize_reuse)
+                                                   authorize: authorize_reuse, outreach: true)
         else
           ticket.with_lock(requires_new: true) do
             authorize_reuse&.call(ticket)
@@ -803,21 +858,40 @@ module SupportDesk
     # by whoever answers first and a drop-in on somebody else's ticket is
     # recorded; under :take_over the drop-in takes it; under :assignee_only
     # it raises SupportDesk::NotAllowed. Returns the Chats::Message.
-    def reply!(body = nil, by: nil, files: [], request: nil)
+    #
+    # `by:` the assistant needs `turn:` and her policy's permission — see
+    # SupportDesk::Ticket::Assistance. `metadata:` rides on the message
+    # (provenance for a draft a human sent; hosts nest their own under
+    # "host").
+    def reply!(body = nil, by: nil, files: [], request: nil, metadata: {}, turn: nil)
       actor = resolve_actor(by)
       ensure_agent!(actor)
+      reconcile_and_commit! if SupportDesk.ai_actor?(actor)
 
-      reply_under_lock!(body, by: actor, files: files, request: request)
+      reply_under_lock!(body, by: actor, files: files, request: request, metadata: metadata, turn: turn)
     end
 
     # An internal note: in the timeline and the console, never in the
     # conversation, never mirrored to any channel. Returns the Event.
-    def note!(body, by: nil, request: nil)
+    def note!(body, by: nil, request: nil, turn: nil)
       actor = resolve_actor(by)
       ensure_agent!(actor)
+      machine = SupportDesk.ai_actor?(actor)
       raise ArgumentError, "a note needs something to say" if body.blank?
 
-      event = write_transition!(:note, actor: actor, request: request) { { "note" => body.to_s } }
+      assistant = nil
+      event = write_transition!(:note, actor: actor, request: request) do
+        if machine
+          # Under the lock, from the row: a kill switch that commits while
+          # this call waits for the case is a kill switch that stops it (R9).
+          assistant = resolve_assistant!(actor)
+          ensure_current_turn!(turn)
+          policy = assistant_policy(assistant)
+          raise AssistantNotAllowed.new(policy, verb: :note) unless policy.may_observe?
+        end
+        { "note" => body.to_s }
+      end
+      stamp_assistant_action! if assistant && event
       SupportDesk.emit_after_commit(:note_added, self, event) if event
       event
     end
@@ -825,26 +899,44 @@ module SupportDesk
     # Give the ticket to an agent. `assign!(to: lucia, by: lucia)` is
     # somebody taking it; `assign!(to: pedro, by: admin)` is somebody being
     # handed it. Repeating an assignment to the current holder does nothing.
-    def assign!(to:, by: nil, reason: nil, note: nil, request: nil)
+    def assign!(to:, by: nil, reason: nil, note: nil, request: nil, turn: nil)
       actor = resolve_actor(by)
       ensure_agent!(actor)
       ensure_assignable!(to)
 
       reason ||= to == actor ? :taken : :assigned
+      # A PERSON giving the case back to the assistant is the one action that
+      # lifts the three human-side flags — and it says so out loud, in the
+      # payload, because nothing else may clear them (I9).
+      handing_back = SupportDesk.ai_actor?(to) && !SupportDesk.ai_actor?(actor)
       assignment = nil
 
       event = write_transition!(:assigned, actor: actor, request: request) do
         raise InvalidTransition, "can't assign a closed ticket — reopen it first" if closed?
+        # Every mutable question about a seat is asked HERE, under the row
+        # lock, from the reloaded row: who holds the case, what her policy
+        # says, which turn she is on. Asked before the lock (0.3.0) they
+        # were answers about a case that has since moved, and a stale
+        # instance could take a seat a person had already been given (R2).
+        ensure_assistant_may_assign!(actor, to, turn: turn)
+        ensure_assistant_may_hold!(to)
         next false if assigned_to?(to)
 
         assignment = Assignment.open!(ticket: self, agent: to, by: actor, reason: reason, note: note)
-        update!(assignee: to)
-        { "assignee" => SupportDesk.actor_key(to), "reason" => reason.to_s }
+        attributes = { assignee: to }
+        if handing_back
+          attributes.merge!(human_required_at: nil, human_required_reason: nil, assistant_paused_at: nil,
+                            assistant_paused_reason: nil, assistant_cap: nil)
+        end
+        update!(attributes)
+        { "assignee" => SupportDesk.actor_key(to), "reason" => reason.to_s,
+          "handed_back" => (true if handing_back) }.compact
       end
       return self unless event
 
       announce_assignment!(to, first: assignments.count <= 1)
       SupportDesk.emit_after_commit(:ticket_assigned, self, assignment)
+      emit_assistant_turn if handing_back && awaiting_reply?
       self
     end
 
@@ -853,7 +945,13 @@ module SupportDesk
     def hand_off!(to:, note: nil, by: nil, request: nil)
       actor = resolve_actor(by)
       ensure_agent!(actor)
+      if SupportDesk.ai_actor?(actor)
+        # She does not choose who picks a case up. `escalate!` is her way
+        # out: it asks for a person rather than naming one.
+        raise AssistantNotAllowed.new(assistant_policy(resolve_assistant!(actor)), verb: :hand_off)
+      end
       ensure_assignable!(to)
+      handing_back = SupportDesk.ai_actor?(to)
       from = nil
       assignment = nil
       event = write_transition!(:handed_off, actor: actor, request: request) do
@@ -862,28 +960,48 @@ module SupportDesk
                                 "(#{assignee ? describe_actor(assignee) : "nobody"} does) — use assign! to override"
         end
         raise InvalidTransition, "can't hand off a closed ticket" if closed?
+        ensure_assistant_may_hold!(to)
         next false if assigned_to?(to)
 
         from = assignee
         assignment = Assignment.open!(ticket: self, agent: to, by: actor, reason: :handed_off, note: note,
                                       release_reason: :handed_off)
-        update!(assignee: to)
-        { "from" => SupportDesk.actor_key(from), "to" => SupportDesk.actor_key(to), "note" => note }
+        attributes = { assignee: to }
+        if handing_back
+          attributes.merge!(human_required_at: nil, human_required_reason: nil, assistant_paused_at: nil,
+                            assistant_paused_reason: nil, assistant_cap: nil)
+        end
+        update!(attributes)
+        { "from" => SupportDesk.actor_key(from), "to" => SupportDesk.actor_key(to), "note" => note,
+          "handed_back" => (true if handing_back) }
       end
       return self unless event
 
       announce_assignment!(to, first: false)
       SupportDesk.emit_after_commit(:ticket_handed_off, self, assignment, from: from, note: note)
+      emit_assistant_turn if handing_back && awaiting_reply?
       self
     end
 
     # Put the ticket back in the unassigned pile.
-    def release!(by: nil, reason: :released, request: nil)
+    def release!(by: nil, reason: :released, request: nil, turn: nil)
       actor = resolve_actor(by)
       ensure_agent!(actor)
       from = nil
       event = write_transition!(:released, actor: actor, request: request) do
         raise InvalidTransition, "can't release a closed ticket" if closed?
+        assistant = (resolve_assistant!(actor) if SupportDesk.ai_actor?(actor))
+        if assistant
+          # Giving a seat back is an action like any other, so it holds the
+          # turn it read: a run that finished after the case moved on must
+          # not release the seat a newer one took (R2).
+          ensure_current_turn!(turn)
+          policy = assistant_policy(assistant)
+          raise AssistantNotAllowed.new(policy, verb: :release) unless policy.may_observe?
+          # Her own seat, and only hers: putting a PERSON's case back in the
+          # pile is not something a machine gets to decide.
+          raise AssistantNotAllowed.new(policy, verb: :release) unless assigned_to?(assistant)
+        end
         next false if unassigned?
 
         from = assignee
@@ -898,17 +1016,37 @@ module SupportDesk
     end
 
     # Close the case. Closing a closed ticket is a no-op, not an error.
-    def close!(by: nil, request: nil)
+    def close!(by: nil, request: nil, turn: nil)
       actor = resolve_actor(by)
       ensure_agent!(actor)
+      machine = SupportDesk.ai_actor?(actor)
+      reconcile_and_commit! if machine
 
       event = write_transition!(:closed, actor: actor, request: request) do
+        if machine
+          # Resolved under the lock, so the kill switch is read after the
+          # wait rather than before it (R9).
+          assistant = resolve_assistant!(actor)
+          lock_conversation!
+          reconcile_unregistered_messages!
+          ensure_current_turn!(turn)
+          policy = assistant_policy(assistant)
+          # Four conditions, and every one of them is somebody else's word:
+          # her level allows it, she is the one holding the case, the
+          # customer has the last word (so nothing is waiting for an answer)
+          # and nobody has asked for a person.
+          raise AssistantNotAllowed.new(policy, verb: :close) unless policy.may_close?
+          raise AssistantNotAllowed.new(policy, verb: :close) unless assigned_to?(assistant)
+          raise AssistantNotAllowed.new(policy, verb: :close) unless awaiting_requester?
+          raise AssistantNotAllowed.new(policy, verb: :close) if human_required?
+        end
         next false if closed?
 
+        expired = expire_pending_drafts!
         assignments.open.each { |assignment| assignment.release!(reason: :closed) }
         update!(status: "closed", closed_at: Time.current, closed_by: record_actor(actor),
                 awaiting: "none", waiting_since: nil)
-        {}
+        { "expired_drafts" => (expired if expired.positive?) }
       end
       return self unless event
 
@@ -924,10 +1062,17 @@ module SupportDesk
     # the pool.
     def reopen!(by: nil, request: nil)
       actor = resolve_actor(by)
+      if SupportDesk.ai_actor?(actor)
+        raise AssistantNotAllowed.new(assistant_policy(resolve_assistant!(actor)), verb: :reopen)
+      end
 
       event = write_transition!(:reopened, actor: actor, request: request) do
         next false unless closed?
 
+        # Read BEFORE the update clears it: whether the case we are bringing
+        # back is one the assistant closed is the whole question behind the
+        # cap below, and `closed_by` is where it is written down.
+        closed_by_assistant = closed_by_type == SupportDesk::Assistant.polymorphic_name
         # Order matters: waiting_since is DERIVED from awaiting, so awaiting
         # has to be the reopened value before it is read. Computing both in
         # one update! hash reads the closed ticket's "none" and stores nil —
@@ -937,8 +1082,8 @@ module SupportDesk
                           cardinality_key: "reopened:#{id}")
         self.waiting_since = waiting_since_from_clocks
         save!
-        restore_assignment!(by: actor)
-        { "reopen_count" => reopen_count }
+        capped = restore_assignment!(by: actor, closed_by_assistant: closed_by_assistant)
+        { "reopen_count" => reopen_count, "assistant_capped" => (true if capped) }.compact
       end
       return self unless event
 
@@ -953,6 +1098,12 @@ module SupportDesk
       # Agents may file onto any topic in the tree, including ones no
       # requester is offered (`only:`); requesters may not file at all.
       ensure_agent!(actor)
+      # Triage is where authority comes from — a topic decides the cap she
+      # works under, so refiling her own case would be widening her own
+      # policy (I10). 0.3 refuses it outright.
+      if SupportDesk.ai_actor?(actor)
+        raise AssistantNotAllowed.new(assistant_policy(resolve_assistant!(actor)), verb: :triage)
+      end
       node = desk_config.topics.find(to.to_s) ||
              raise(UnknownTopic, "no topic #{to.inspect} on desk #{desk.key}")
 
@@ -962,7 +1113,11 @@ module SupportDesk
 
         update!(topic: node, priority: [ priority.to_i, node.priority ].max,
                 cardinality_key: recomputed_cardinality_key(subject: subject, topic: node))
-        { "from" => from&.path, "to" => node.path }
+        # A refile onto a capped topic is a refile onto a case she may no
+        # longer answer, so her seat goes with it — in the same transition,
+        # so the queue never shows a machine holding a case it can't work.
+        released = release_assistant_if_unfit!
+        { "from" => from&.path, "to" => node.path, "assistant_released" => (true if released) }
       end
       return self unless event
 
@@ -974,6 +1129,11 @@ module SupportDesk
     def attach_subject!(record, by: nil, request: nil)
       actor = resolve_actor(by)
       ensure_agent!(actor)
+      # Same reason as `change_topic!`: what a case is ABOUT decides what may
+      # be done on it, so a machine does not get to say.
+      if SupportDesk.ai_actor?(actor)
+        raise AssistantNotAllowed.new(assistant_policy(resolve_assistant!(actor)), verb: :triage)
+      end
       unless record.respond_to?(:supportable?) && record.supportable?
         raise NotSupportable, "#{record.class} isn't supportable — add `supportable topic: :something` to it"
       end
@@ -1052,6 +1212,9 @@ module SupportDesk
     # test instead of quietly moving the boundary.
     def actions_for(agent)
       return [] unless agent.respond_to?(:support_agent?) && agent.support_agent?
+      # A machine's verbs are its policy's, filtered by the same state. Same
+      # boundary, different vocabulary — see #assistant_actions_for.
+      return assistant_actions_for(agent) if SupportDesk.ai_actor?(agent)
       # Off duty is a real answer: the console can still show the case, and
       # an agent passing by can still leave a note, but nothing that speaks
       # to the requester is offered to somebody who isn't working.
@@ -1070,6 +1233,11 @@ module SupportDesk
         actions << :release if assigned?
         actions << :change_topic
         actions << :close
+        if pending_draft
+          actions << :send_draft if may_reply?(agent) && !requester_unavailable?
+          actions << :reject_draft
+        end
+        actions << (assistant_paused? ? :resume_assistant : :pause_assistant) if assistant
       end
       actions
     end
@@ -1077,6 +1245,10 @@ module SupportDesk
     # Whether +agent+ may answer right now under this desk's reply policy.
     def may_reply?(agent)
       return false unless agent.respond_to?(:support_agent?) && agent.support_agent?
+      # A case a machine is holding is a case any person may answer,
+      # whatever the desk says about assignees: `:assignee_only` exists so
+      # two people don't answer at once, and she is not one (I8).
+      return true if held_by_assistant? && !SupportDesk.ai_actor?(agent)
       return true unless desk_config.reply_policy == :assignee_only
 
       assigned_to?(agent)
@@ -1086,9 +1258,11 @@ module SupportDesk
     # the whole on-duty pool while it's unheld. The gem computes it; the
     # host delivers it.
     def agents_to_notify
-      return [ assignee ].compact if assigned?
+      # A case the assistant holds is a case no person has seen, so the pool
+      # hears about it: notifying a machine is notifying nobody.
+      return [ assignee ].compact if assigned? && !held_by_assistant?
 
-      desk.on_duty_agents.to_a
+      desk.on_duty_agents.to_a.reject { |agent| SupportDesk.ai_actor?(agent) }
     end
 
     # Generic on purpose: a lock screen shouldn't spell out what somebody's
@@ -1132,8 +1306,15 @@ module SupportDesk
     # Post a message as the DESK, signed by the agent who wrote it — every
     # answer, and the desk's first word when it writes first. One place knows
     # "the desk sends, the human signs".
-    def post_agent_message!(body, files: [], by:) # :nodoc:
-      desk.message!(conversation, body, files: files, author: by)
+    # `metadata:` is the provenance a message carries: who drafted it, what
+    # policy allowed it, what the machine declared about it. Posted through
+    # `messages.create!` rather than `desk.message!` for one reason only —
+    # chats' sugar takes no metadata, and the validations are the same.
+    def post_agent_message!(body, files: [], by:, metadata: {}) # :nodoc:
+      attributes = { sender: desk, body: body, author: by }
+      attributes[:files] = files if files.present?
+      attributes[:metadata] = metadata if metadata.present?
+      conversation.messages.create!(**attributes)
     end
 
     def inspect
@@ -1172,8 +1353,50 @@ module SupportDesk
       ensure_agent!(agent)
     end
 
+    # "Could she hold this case once the human-side flags were lifted?" —
+    # the hand-back question, so the very flags a hand-back exists to clear
+    # are not what refuses it. Her autonomy, the topic and the host's cap
+    # block still decide.
+    #
+    # Asked UNDER THE LOCK (R2): a cap that lands while a take waits for the
+    # row is the cap that applies to it.
+    def ensure_assistant_may_hold!(agent)
+      return unless SupportDesk.ai_actor?(agent)
+
+      policy = assistant_policy(agent, hand_back: true)
+      raise AssistantNotAllowed.new(policy, verb: :take) unless policy.may_hold?
+    end
+
+    # An assistant may take a case, and that is all: only herself, only when
+    # nobody holds it, only at a level that may answer, and only holding the
+    # turn she read. Called under the row lock, from the reloaded row.
+    def ensure_assistant_may_assign!(actor, to, turn:)
+      return unless SupportDesk.ai_actor?(actor)
+
+      assistant = resolve_assistant!(actor)
+      ensure_current_turn!(turn)
+      policy = assistant_policy(assistant)
+      unless self.class.same_actor?(actor, to)
+        raise AssistantNotAllowed.new(policy, verb: :assign,
+                                              message: "#{assistant.key} may not give #{reference} to " \
+                                                       "anybody — an assistant can only take a case herself")
+      end
+      raise AssistantNotAllowed.new(policy, verb: :take) unless unassigned?
+      raise AssistantNotAllowed.new(policy, verb: :take) unless policy.may_hold?
+    end
+
     def ensure_agent!(actor)
       return if actor.is_a?(Symbol)
+      # An AI-kind actor that is not a SupportDesk::Assistant is refused on
+      # every write, by it or to it (I2). A host model declared `kind: :ai`
+      # is a machine the gem knows nothing about, and treating it as a human
+      # agent — which is what 0.2 did — hands it every human's authority.
+      if SupportDesk.ai_actor?(actor) && !actor.is_a?(SupportDesk::Assistant)
+        raise NotAnAssistant,
+              "#{describe_actor(actor)} is declared `acts_as_support_agent kind: :ai` but isn't this gem's " \
+              "assistant — configure one with `config.assistant` and act as SupportDesk.assistant(key)"
+      end
+
       self.class.ensure_agent_record!(actor)
     end
 
@@ -1211,17 +1434,52 @@ module SupportDesk
     # `authorize:` is the console's hook (see Ticket.open_or_reply!): it runs
     # under this lock, before any policy side effect, and a raise there rolls
     # the whole thing back.
-    def reply_under_lock!(body, by:, files:, request:, authorize: nil)
+    def reply_under_lock!(body, by:, files:, request:, authorize: nil, metadata: {}, turn: nil, outreach: false)
       with_lock(requires_new: true) do
         authorize&.call(self)
+        next assistant_reply_under_lock!(body, assistant: by, files: files, request: request,
+                                               metadata: metadata, turn: turn, outreach: outreach) if SupportDesk.ai_actor?(by)
+
+        # Fold committed inputs before a human answer too. A delayed callback
+        # must not later turn an already-answered question back into work.
+        lock_conversation!
+        reconcile_unregistered_messages!
         ensure_writable!
         apply_reply_policy!(by, request: request)
-        posted = post_agent_message!(body, files: files, by: by)
+        posted = post_agent_message!(body, files: files, by: by, metadata: metadata)
+        # A person answering makes every machine proposal on this case out of
+        # date — including one they are about to send, which is why the draft
+        # being sent says so and is left alone.
+        supersede_pending_drafts!(except: metadata.dig("support_desk", "draft_id"))
         record_registration!(posted)
         posted
       end
     end
 
+    # `reply!` by the assistant: her full rules, under the lock the caller
+    # already holds. Everything here is also what `respond!` runs — this is
+    # the path for a host that decided to answer rather than ask policy.
+    def assistant_reply_under_lock!(body, assistant:, files:, request:, metadata:, turn:, outreach: false)
+      assistant = resolve_assistant!(assistant)
+      # Private outreach supplies a token only after acquiring both locks;
+      # public replies compare the caller's actual observed token.
+      lock_conversation!
+      reconcile_unregistered_messages!
+      turn = assistant_turn if outreach
+      ensure_current_turn!(turn)
+      ensure_writable!
+
+      policy = assistant_policy(assistant)
+      raise AssistantNotAllowed.new(policy, verb: :reply) unless policy.may_reply?
+      raise AssistantNotAllowed.new(policy, verb: :not_your_turn) unless awaiting_reply?
+
+      left = assistant_turns_left
+      raise AssistantNotAllowed.new(policy, verb: :max_turns) if left&.zero?
+
+      speak!(body, assistant, policy: policy, turn: turn, files: files, confidence: nil, sources: [],
+                              metadata: metadata, request: request)
+    end
+
     def apply_reply_policy!(actor, request: nil)
       # A closed case has no seat to take: an agent adding one last word
       # posts it and the case stays closed. (A REQUESTER writing is what
@@ -1236,14 +1494,27 @@ module SupportDesk
                             "take it first"
         end
 
-        assign!(to: actor, by: actor, request: request)
+        # This private path already validated the reply while holding the lock.
+        # Seat-taking consumes the real current token, not a public sentinel.
+        assign!(to: actor, by: actor, request: request, turn: assistant_turn)
       elsif !assigned_to?(actor)
+        # Humans outrank assistants, under EVERY reply policy (I8). A person
+        # answering a case a machine is holding takes it over: there is
+        # nothing to ask about "who owns this" when one of the two can't
+        # want it, and leaving her seated would keep her answering next.
+        if held_by_assistant? && !SupportDesk.ai_actor?(actor)
+          return assign!(to: actor, by: actor, reason: :drop_in_takeover, request: request, turn: assistant_turn)
+        end
+        # Belt: the `held_by_human` floor already turned this into a draft,
+        # so an assistant reaching here is a bug, not a policy question.
+        raise AssistantNotAllowed.new(assistant_policy(actor), verb: :reply) if SupportDesk.ai_actor?(actor)
+
         case policy
         when :assignee_only
           raise NotAllowed, "ticket #{reference} is held by #{describe_actor(assignee)} and this desk only " \
                             "lets the assignee reply"
         when :take_over
-          assign!(to: actor, by: actor, reason: :drop_in_takeover, request: request)
+          assign!(to: actor, by: actor, reason: :drop_in_takeover, request: request, turn: assistant_turn)
         else
           write_transition!(:drop_in, actor: actor, request: request) do
             { "assignee" => SupportDesk.actor_key(assignee) }
@@ -1270,7 +1541,11 @@ module SupportDesk
       payload = yield
       return nil if payload == false || payload.nil?
 
-      Event.record!(ticket: self, kind: kind, actor: actor, payload: payload.compact)
+      event = Event.record!(ticket: self, kind: kind, actor: actor, payload: payload.compact)
+      # A real transition changed the case, so it moves the turn — a
+      # no-op one wrote no event and moves nothing.
+      bump_assistant_revision!
+      event
     end
 
     # The half that tells the world, once the write is durable. Every
@@ -1288,6 +1563,10 @@ module SupportDesk
     end
 
     def announce_assignment!(agent, first:)
+      # "Rose se ocupa de tu consulta" is a promise about a person. Her
+      # disclosure line is her announcement, and it is the only one.
+      return if SupportDesk.ai_actor?(agent)
+
       mode = desk_config.announce_assignments
       return if mode == :never
       return if mode == :first_only && !first
@@ -1310,27 +1589,37 @@ module SupportDesk
     # caller is not always the lock holder it thinks it is.
     def record_registration!(message) # :nodoc:
       return self if role_of(message) == :system
+      unless message.persisted? && message.conversation_id == conversation_id
+        raise ArgumentError, "message must belong to this ticket's conversation"
+      end
       # Re-check under the lock: the same message can reach us twice (a
       # redelivered event, a hand-written replay), and an SLA clock that
       # moves twice for one message is a lie.
       return self if registered?(message)
 
+      message_registrations.create!(message_id: message.id)
       role = role_of(message)
       opening = opening_message?
       reopened = false
       reopen_event = nil
 
       attributes = { last_registered_message_id: message.id }
+      closed_by_assistant = false
       case role
       when :requester
-        attributes[:last_requester_message_at] = message.created_at
+        attributes[:last_requester_message_at] = [ last_requester_message_at, message.created_at ].compact.max
+        # The pointer the turn's reconciliation reads: which requester
+        # message the clocks are standing on, by id and not only by time.
+        attributes[:last_requester_message_id] = message.id if after_requester_watermark?(message)
         if closed? && message.created_at > closed_at && desk_config.closed_tickets == :reopen_on_reply
+          # Read before the merge below clears it — see #reopen!.
+          closed_by_assistant = closed_by_type == SupportDesk::Assistant.polymorphic_name
           attributes.merge!(status: "open", closed_at: nil, closed_by: nil,
                             reopen_count: reopen_count.to_i + 1, cardinality_key: "reopened:#{id}")
           reopened = true
         end
       when :agent
-        attributes[:last_agent_message_at] = message.created_at
+        attributes[:last_agent_message_at] = [ last_agent_message_at, message.created_at ].compact.max
         # A first REPLY answers something. An agent message with no earlier
         # requester message is the desk opening the conversation, or a word
         # into an empty case — neither is a reply, and a requester clock that
@@ -1345,41 +1634,74 @@ module SupportDesk
       end
 
       assign_attributes(attributes)
-      self.awaiting = closed? ? "none" : awaiting_from_clocks
+      self.awaiting = if closed?
+        "none"
+      elsif role == :requester
+        "agent"
+      else
+        awaiting_from_clocks
+      end
       self.waiting_since = waiting_since_from_clocks
       save!
+      # Every registered message moves the case on, so every one of them
+      # moves the turn: an assistant holding the turn she read a second ago
+      # is holding a case that has not changed since (I4).
+      bump_assistant_revision!
 
       if reopened
-        restore_assignment!(by: :system)
-        reopen_event = record_transition!(:reopened, actor: requester) { { "via" => "requester_reply" } }
+        capped = restore_assignment!(by: :system, closed_by_assistant: closed_by_assistant)
+        reopen_event = record_transition!(:reopened, actor: requester) do
+          { "via" => "requester_reply", "assistant_capped" => (true if capped) }.compact
+        end
       end
 
+      # After the bump, and after any reopen: the hook decides about a case
+      # in the state this message left it in.
+      evaluate_hand_off_phrase!(message) if role == :requester && !closed?
+
       publish_transition(reopen_event, :reopened, requester, nil) if reopen_event
       announce_registration(message, role: role, opening: opening, reopened: reopened)
       self
     end
 
-    # Whether this message is already folded in. The last-id check catches
-    # the common redelivery; the clock check catches the rest, because a
-    # REPLAY can arrive in any order and an older message must never rewind
-    # `awaiting`, restart an SLA clock, or reopen a case that was closed
-    # after it.
-    #
-    # The comparison is `<=`, so a message whose timestamp already sits on
-    # the clock counts as folded in: idempotency is the documented promise,
-    # and the cost of the rare tie is one clock that doesn't advance until
-    # the next message.
+    # Receipt identity, not transcript order, decides whether a callback is a
+    # replay. A later commit may have an earlier timestamp or a smaller UUID.
     def registered?(message)
-      return true if last_registered_message_id.present? && last_registered_message_id.to_s == message.id.to_s
+      message_registrations.exists?(message_id: message.id)
+    end
 
-      clock = case role_of(message)
-      when :requester then last_requester_message_at
-      when :agent then last_agent_message_at
-      end
+    # Advance the requester clock pointer only in transcript order. Receipt
+    # identity decides registration separately, so late arrivals cannot rewind
+    # clocks or be discarded as replays.
+    def after_requester_watermark?(message)
+      watermark = last_requester_message_at
+      return true if watermark.blank?
+      return true if message.created_at > watermark
+      return false if message.created_at < watermark
+      # A tie with no pointer to break it (a 0.2 row whose backfill found
+      # nothing) is new: the alternative silently drops it.
+      return true if last_requester_message_id.blank?
+
+      compare_message_ids(message.id, last_requester_message_id).positive?
+    end
 
-      clock.present? && message.created_at <= clock
+    # Order two chats message ids the way the DATABASE orders that column,
+    # because the reconciliation query compares them in SQL and this one
+    # compares them in Ruby. Integers compare numerically (10 is after 9);
+    # anything else — a uuid, a ULID — compares as a string, which is how
+    # every adapter orders those columns too.
+    def compare_message_ids(one, other)
+      if one.is_a?(Integer) && other.is_a?(Integer)
+        one <=> other
+      elsif integerish?(one) && integerish?(other)
+        one.to_i <=> other.to_i
+      else
+        one.to_s <=> other.to_s
+      end
     end
 
+    def integerish?(value) = value.to_s.match?(/\A-?\d+\z/)
+
     def opening_message?
       last_registered_message_id.blank? && last_requester_message_at.nil? && last_agent_message_at.nil?
     end
@@ -1432,14 +1754,26 @@ module SupportDesk
     # disagree on a live ticket. A closed ticket keeps its assignee as the
     # record of who dealt with it, with no open row — that pair is the one
     # shape `doctor` expects to see.
-    def restore_assignment!(by:)
-      return if unassigned?
+    def restore_assignment!(by:, closed_by_assistant: false)
+      return false if unassigned?
+
+      # A case the assistant closed and the customer reopened is a case she
+      # got wrong (12 #21). It comes back to PEOPLE — unassigned, and capped
+      # at :draft on this case for good, whatever her level is elsewhere. An
+      # explicit hand-back is the only thing that lifts it, and the cap can
+      # only tighten: an existing :observe stays :observe.
+      if closed_by_assistant
+        cap = [ assistant_cap&.to_sym, :draft ].compact.min_by { |level| AssistantPolicy::RANK.fetch(level) }
+        update!(assignee: nil, assistant_cap: cap.to_s)
+        return true
+      end
 
       if assignee.respond_to?(:support_agent?) && assignee.support_agent?
         Assignment.open!(ticket: self, agent: assignee, by: by, reason: :reopened)
       else
         update!(assignee: nil)
       end
+      false
     end
 
     def awaiting_from_clocks
@@ -1464,6 +1798,10 @@ module SupportDesk
 
       case role
       when :requester
+        # The opening message included: a case that starts with a question
+        # is a case with something to answer, and the harness should hear
+        # about it the same way it hears about every later message.
+        emit_assistant_turn(message)
         SupportDesk.emit_after_commit(:requester_replied, self, message) unless opening
       when :agent
         # The desk's OWN first word announces nothing: it is the start of a
@@ -1497,11 +1835,21 @@ module SupportDesk
       conversation.messages.visible.oldest_first.map do |message|
         {
           at: message.created_at,
-          from: role_of(message) == :requester ? "you" : "support",
+          # "assistant" in every disclosure mode, silent ones included: what
+          # a customer was told is a product decision, what an export says a
+          # machine wrote is not.
+          from: export_from(message),
           body: message.visible_body,
           attachments: message.try(:files)&.map { |file| file.try(:filename).to_s } || []
         }
       end
     end
+
+    def export_from(message)
+      return "you" if role_of(message) == :requester
+      return "assistant" if assistant_message?(message)
+
+      "support"
+    end
   end
 end