support_desk 0.2.0 → 0.3.2

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)

data/lib/support_desk/transcript.rb

@@ -0,0 +1,234 @@
+# frozen_string_literal: true
+
+module SupportDesk
+  # The conversation as something other than HTML: one flat, ordered list of
+  # turns, each one saying who spoke, what they said and when.
+  #
+  #   ticket.transcript.to_text
+  #   # [2026-09-18 10:02] Alice: No me han pagado
+  #   # [2026-09-18 10:03] Rose: Lo estoy mirando ahora mismo
+  #   # [2026-09-18 10:07] Lucía: Ya está resuelto [justificante.pdf]
+  #
+  #   ticket.transcript(limit: 20).last(5)
+  #   ticket.transcript.since(message)
+  #
+  # It exists for the harness that has to hand a conversation to a model
+  # without reading chats' tables, and for anything else that wants the
+  # transcript as data: an export, a summary job, a console that renders
+  # JSON. `Brief` embeds it.
+  #
+  # == Four roles, not three
+  #
+  # `Ticket#role_of` answers +:requester+, +:agent+ or +:system+, because
+  # that is what the CLOCKS care about — whose turn it is does not change
+  # depending on whether a person or a machine wrote the desk's last word.
+  # A reader does care, so this is a SEPARATE serializer with its own
+  # vocabulary: +:requester+, +:human+, +:assistant+, +:system+. Neither
+  # one is derived from the other, and `role_of` is deliberately left
+  # alone — the day a third kind of author appears, only this file moves.
+  #
+  # == Names survive renames
+  #
+  # The assistant's original name is stored on new messages. Older assistant
+  # messages fall back to their stored display name, then to configuration or
+  # the author record only when there is no message snapshot. Exported turns
+  # retain AI provenance even when their requester-facing mode is nameless.
+  #
+  # == Deleted messages are turns too
+  #
+  # A tombstone renders as `support_desk.transcript.deleted` with no
+  # attachments, rather than vanishing: a model that cannot see that
+  # something was said and withdrawn will answer as if it never was, and a
+  # gap in a numbered transcript is worse than a marked one.
+  class Transcript
+    include Enumerable
+
+    # One line of the conversation. A value: built once, then only read.
+    #
+    # * +role+        — :requester | :human | :assistant | :system
+    # * +name+        — who to print; the desk's name for system lines
+    # * +body+        — what was said, or the tombstone copy
+    # * +at+          — when (a Time)
+    # * +attachments+ — filenames, as Strings
+    # * +assisted+    — a human sent it, a machine proposed it
+    # * +message+     — the Chats::Message itself, for anything else
+    Turn = Struct.new(:role, :name, :body, :at, :attachments, :assisted, :message, keyword_init: true) do
+      def requester? = role == :requester
+      def human? = role == :human
+      def assistant? = role == :assistant
+      def system? = role == :system
+
+      # Whether a person sent a machine's words. Provenance, not authorship:
+      # the message is the human's (see SupportDesk::Draft).
+      def assisted? = !!assisted
+
+      # "[2026-09-18 10:02] Alice: No me han pagado [justificante.pdf]"
+      #
+      # UTC, to the minute, always: a transcript that a model reads is
+      # compared against itself line by line, and a stamp that moves with
+      # the reader's zone or carries seconds is noise in a diff.
+      def to_line
+        said = [ body.to_s.strip.presence, *attachments.map { |file| "[#{file}]" } ].compact
+        "[#{at&.utc&.strftime("%Y-%m-%d %H:%M")}] #{name}: #{said.join(" ")}"
+      end
+
+      alias_method :to_s, :to_line
+
+      def to_h
+        { role: role, name: name, body: body, at: at, attachments: attachments, assisted: assisted }
+      end
+    end
+
+    attr_reader :ticket, :limit
+
+    # The transcript of +ticket+. `limit:` keeps the LAST n turns — the end
+    # of a conversation is the part that is still being answered.
+    def initialize(ticket, limit: nil)
+      @ticket = ticket
+      @limit = limit&.to_i
+    end
+
+    # Every turn, oldest first.
+    def each(&block)
+      turns.each(&block)
+    end
+
+    def to_a = turns.dup
+
+    def size = turns.size
+
+    alias_method :length, :size
+
+    # The last +count+ turns, oldest first.
+    def last(count = 1)
+      turns.last(count)
+    end
+
+    # Everything said after +message+ — "what has happened since the one I
+    # answered". A message this transcript doesn't hold (older than `limit:`,
+    # from another case, deleted outright) yields the whole window rather
+    # than nothing: the caller has seen none of it, and an empty answer would
+    # read as "nothing happened".
+    def since(message)
+      return to_a if message.nil?
+
+      index = turns.index { |turn| turn.message&.id.to_s == message.id.to_s }
+      return to_a if index.nil?
+
+      turns[(index + 1)..] || []
+    end
+
+    # The whole thing as one block of text, for a prompt or a log line.
+    def to_text
+      turns.map(&:to_line).join("\n")
+    end
+
+    alias_method :to_s, :to_text
+
+    # The transcript as data. `truncated` is the honest half of `limit:`:
+    # a reader that is seeing the last 50 of 300 turns has to know it.
+    def to_h
+      {
+        size: total,
+        truncated: total > turns.size,
+        turns: turns.map(&:to_h)
+      }
+    end
+
+    def inspect
+      "#<SupportDesk::Transcript #{ticket.reference} #{turns.size} turn(s)>"
+    end
+
+    private
+
+    # Built once per instance: a transcript is a snapshot of a conversation
+    # at the moment somebody asked for it, and a second read that disagreed
+    # with the first would make `since` and `last` answer about two
+    # different conversations.
+    def turns
+      @turns ||= messages.map { |message| turn_for(message) }
+    end
+
+    def messages
+      return [] if ticket.conversation.nil?
+
+      scope = ticket.conversation.messages.oldest_first
+      all = scope.to_a
+      @total = all.size
+      limit ? all.last(limit) : all
+    end
+
+    def total
+      turns # force the read, which is what counts
+      @total.to_i
+    end
+
+    def turn_for(message)
+      role = role_for(message)
+      tombstone = message.respond_to?(:deleted?) && message.deleted?
+
+      Turn.new(
+        role: role,
+        name: name_for(role, message),
+        body: tombstone ? I18n.t("support_desk.transcript.deleted") : message.body,
+        at: message.created_at,
+        attachments: tombstone ? [] : attachment_names(message),
+        assisted: assisted?(message),
+        message: message
+      )
+    end
+
+    # System first (a disclosure notice is a system line, whatever wrote
+    # it), then the machine, then the two kinds of person.
+    def role_for(message)
+      return :system if message.respond_to?(:system?) && message.system?
+      return :assistant if ticket.assistant_message?(message)
+
+      case ticket.send(:role_of, message)
+      when :requester then :requester
+      when :agent then :human
+      else :system
+      end
+    end
+
+    def name_for(role, message)
+      case role
+      when :requester then Chats.display_name_for(ticket.requester)
+      when :assistant then assistant_name(message)
+      when :human then message.author.try(:support_agent_name) || ticket.desk&.name
+      else ticket.desk&.name
+      end
+    end
+
+    # Message snapshots survive configuration changes. Imports without a
+    # snapshot use the configured key or author as a legacy fallback.
+    def assistant_name(message)
+      stamp = provenance(message)
+      return stamp["name"] if stamp["name"].is_a?(String) && stamp["name"].present?
+      return stamp["display_name"] if stamp["display_name"].is_a?(String) && stamp["display_name"].present?
+
+      key = stamp["assistant"]
+      if key.present? && SupportDesk.config.assistant?(key)
+        return SupportDesk.config.assistant(key).name
+      end
+
+      stamp["display_name"].presence || message.author.try(:name) || ticket.desk&.name
+    end
+
+    def assisted?(message)
+      provenance(message)["drafted_by"].present?
+    end
+
+    def provenance(message)
+      stamp = message.try(:metadata)
+      return {} unless stamp.is_a?(Hash)
+
+      nested = stamp["support_desk"]
+      nested.is_a?(Hash) ? nested : {}
+    end
+
+    def attachment_names(message)
+      message.try(:files)&.map { |file| file.try(:filename).to_s } || []
+    end
+  end
+end