support_desk 0.2.0 → 0.3.0

data/lib/support_desk/transcript.rb

@@ -0,0 +1,237 @@
+# 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
+  #
+  # An assistant's name is read from the message's own provenance stamp
+  # first (`metadata["support_desk"]["assistant"]`, the KEY), resolved
+  # through the configuration when she is still declared, and only then
+  # falls back to the `display_name` the message was written with. So a
+  # transcript reads "Rose" while Rose is configured, keeps saying what the
+  # customer was actually shown for an assistant nobody declares any more,
+  # and never invents a name for a message written under a nameless
+  # disclosure mode.
+  #
+  # == 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
+
+    # The key the message was stamped with, resolved to the name that key
+    # has NOW — and the stored display name when nothing declares her any
+    # more. A message written by the record rather than by `speak!` (an
+    # import, a host that posts its own) has neither, so the record answers.
+    def assistant_name(message)
+      stamp = provenance(message)
+      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

data/lib/support_desk/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module SupportDesk
-  VERSION = "0.2.0"
+  VERSION = "0.3.0"
 end

data/lib/support_desk.rb

@@ -11,6 +11,7 @@ require "chats"
 require_relative "support_desk/version"
 require_relative "support_desk/errors"
 require_relative "support_desk/events"
+require_relative "support_desk/assistant_policy"
 require_relative "support_desk/topic"
 require_relative "support_desk/topic_tree"
 require_relative "support_desk/configuration"
@@ -93,6 +94,7 @@ module SupportDesk
       @configured = false
       @subscribers = nil
       @desks = nil
+      @assistants = nil
       self
     end
 
@@ -103,6 +105,99 @@ module SupportDesk
       self
     end
 
+    # --- Assistants -----------------------------------------------------------
+
+    # The assistant record for +key+, memoised per process — or the desk's
+    # default when called with nothing. nil when this installation has no
+    # assistant at all, which is the answer every existing host gets.
+    #
+    # Found or created exactly like a desk, and never INSERT-first: an
+    # assistant is read on every transition and written once in her life.
+    def assistant(key = nil)
+      key = (key || config.default_assistant_key)
+      return nil if key.nil?
+
+      key = key.to_sym
+      unless config.assistant?(key)
+        raise ConfigurationError,
+              "no assistant #{key.inspect} is configured — declare it with " \
+              "`config.assistant #{key.inspect} do |assistant| … end`"
+      end
+
+      assistants[key] ||= Assistant.for(key)
+    end
+
+    # Every assistant record this process has resolved, keyed by key.
+    def assistants # :nodoc:
+      @assistants ||= {}
+    end
+
+    # Forget the memoised Assistant records without touching configuration —
+    # for tests that truncate tables between examples.
+    def reset_assistants!
+      @assistants = nil
+      self
+    end
+
+    # Whether +record+ is a machine rather than a person. Duck-typed, because
+    # a host's own `acts_as_support_agent kind: :ai` model answers it too —
+    # and is then refused everywhere, which is the point (I2).
+    def ai_actor?(record)
+      record.respond_to?(:support_agent_kind) && record.support_agent_kind == :ai
+    end
+
+    # Release every assistant who has sat on a case longer than her
+    # `responds_within` without answering — and ask for a person on it.
+    #
+    # This is the net under a dead harness: a queue worker that stopped, a
+    # model provider that is down, a job that raised its last retry away.
+    # Run it every minute (`rake support_desk:release_silent_assistants`).
+    # Returns how many cases it moved.
+    def release_silent_assistants!
+      moved = 0
+      config.assistants.each_key do |key|
+        agent = assistant(key)
+        window = agent&.responds_within
+        next if window.nil?
+
+        Ticket.open.assigned_to(agent).awaiting_reply.waiting_over(window).find_each do |ticket|
+          next if ticket.human_required?
+
+          ticket.escalate!(by: :system, reason: "assistant_silent",
+                           summary: "no answer in #{humanize_duration(window)}")
+          moved += 1 if ticket.human_required?
+        rescue StandardError => e
+          report_error(e, context: { hook: :release_silent_assistants, ticket: ticket.id })
+        end
+      end
+      logger&.info("[support_desk] silent assistants: #{moved} case(s) handed to a person") if moved.positive?
+      moved
+    end
+
+    # Re-emit `:assistant_turn` for cases whose turn nobody acted on — a
+    # harness that was down when the event fired, a job that was dropped.
+    #
+    # At-least-once on purpose: a duplicate turn is harmless, because the
+    # turn is consumed by the first action and every later one is a
+    # StaleTurn. Run it every five minutes. Returns how many it re-emitted.
+    def redispatch_assistant_turns!(older_than: 1.minute)
+      older_than = older_than.to_i.seconds unless older_than.respond_to?(:ago)
+      emitted = 0
+
+      config.desks.each_key do |key|
+        agent = desk(key)&.assistant
+        next if agent.nil?
+
+        Ticket.open.for_desk(key).assistant_idle_since(older_than.ago).find_each do |ticket|
+          next unless ticket.assistant_policy(agent).may_observe?
+
+          ticket.send(:emit_assistant_turn)
+          emitted += 1
+        end
+      end
+      emitted
+    end
+
     # --- Desks ------------------------------------------------------------------
 
     # The desk record for +key+, memoised per process.
@@ -224,6 +319,19 @@ module SupportDesk
       defined?(::Rails) ? ::Rails.logger : nil
     end
 
+    # Report an exception the way the event dispatcher does: `Rails.error`
+    # when there is one, the log otherwise. Extracted because every hook the
+    # gem runs on a host's behalf — a `hand_off_when` block, a turn
+    # emission, a sweep — has to report and carry on rather than take a
+    # transition down with it.
+    def report_error(error, context: {}) # :nodoc:
+      if defined?(Rails) && Rails.respond_to?(:error) && Rails.error
+        Rails.error.report(error, handled: true, source: "support_desk", context: context)
+      else
+        logger&.error("[support_desk] #{error.class}: #{error.message} #{context.inspect}")
+      end
+    end
+
     # Where the host mounted the requester-facing engine
     # ("/messages/support"), or nil when they haven't. Used for the grouped
     # inbox row's link and by `doctor`.

data/lib/tasks/support_desk.rake

@@ -25,3 +25,49 @@ namespace :support_desk do
     puts "[support_desk] #{updated} case(s) now point at their requester."
   end
 end
+
+namespace :support_desk do
+  desc "Hand over every case an assistant has sat on without answering (run every minute)"
+  task release_silent_assistants: :environment do
+    # The net under a dead harness: a queue worker that stopped, a provider
+    # that is down, a job that spent its last retry. Each case it finds has
+    # its seat released AND a person asked for — a case that waited that
+    # long deserves one, whatever the assistant would have said.
+    moved = SupportDesk.release_silent_assistants!
+
+    puts "[support_desk] #{moved} case(s) handed to a person."
+  end
+
+  desc "Re-emit the turn for cases nobody answered (OLDER_THAN=60 seconds; run every 5 minutes)"
+  task redispatch_assistant_turns: :environment do
+    # At-least-once, and that is safe: the turn is consumed by the first
+    # action, so a duplicate one is a StaleTurn and writes nothing.
+    older_than = (ENV["OLDER_THAN"] || 60).to_i.seconds
+    emitted = SupportDesk.redispatch_assistant_turns!(older_than: older_than)
+
+    puts "[support_desk] #{emitted} turn(s) re-emitted (idle for more than #{older_than.inspect})."
+  end
+
+  desc "What the assistants are doing right now (read-only)"
+  task assistant_status: :environment do
+    if SupportDesk.config.assistants.empty?
+      puts "[support_desk] no assistant is configured."
+      next
+    end
+
+    SupportDesk.config.assistants.each_key do |key|
+      assistant = SupportDesk.assistant(key)
+      held = assistant.held_tickets.count
+      idle_window = assistant.responds_within
+      idle = if idle_window
+        SupportDesk::Ticket.open.assistant_idle_since(idle_window.ago).count
+      end
+
+      puts "[support_desk] #{key} (#{assistant.active? ? "active" : "inactive"}, #{assistant.autonomy}): " \
+           "#{held} case(s) held, #{idle || "—"} idle turn(s)"
+    end
+
+    puts "[support_desk] #{SupportDesk::Ticket.open.needs_human.count} case(s) need a person, " \
+         "#{SupportDesk::Draft.pending.count} proposal(s) waiting to be reviewed."
+  end
+end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: support_desk
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - rameerez
 bindir: exe
 cert_chain: []
-date: 2026-09-18 00:00:00.000000000 Z
+date: 2026-09-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -106,11 +106,18 @@ dependencies:
 description: 'support_desk adds a customer support desk to any Rails app: tickets
   that are conversations. A requester asks for help about something in your app (a
   ride, an order, a withdrawal) or about nothing in particular, your desk answers,
-  humans or bots sign the answers, and your team works a queue. It is a product gem
-  on the `chats` kernel: chats owns the transcript, realtime, attachments, read state
-  and moderation; support_desk owns cases, topics, assignment, routing and the console
-  API. One macro makes a model ask for help (`has_support_tickets`), one makes a domain
-  record something to ask about (`supportable`), one makes a person answer (`acts_as_support_agent`).
+  humans sign the answers, and your team works a queue — alongside AI agents that
+  are first-class citizens of the desk: an assistant has a seat, a name, a turn budget
+  and a level (observe, draft, reply, resolve) enforced inside every transition; she
+  proposes replies a person sends, or answers herself where you let her, hands off
+  when unsure, and can never touch a human-held case, a capped topic or a customer
+  who asked for a person. The gem ships the policy, the drafts and review, the turn
+  that makes a late model answer harmless, disclosure and the two exits — and no LLM:
+  any provider, any prompt, in a ten-line job. It is a product gem on the `chats`
+  kernel: chats owns the transcript, realtime, attachments, read state and moderation;
+  support_desk owns cases, topics, assignment, routing and the console API. One macro
+  makes a model ask for help (`has_support_tickets`), one makes a domain record something
+  to ask about (`supportable`), one makes a person answer (`acts_as_support_agent`).
   Topics are a tree defined in code that drives the wizard, the picker, routing and
   metrics; assignment is a history, not a column; every transition writes an append-only
   event row and emits an error-isolated event your app can subscribe to. Batteries
@@ -142,6 +149,7 @@ files:
 - app/views/support_desk/console/tickets/_assignment.html.erb
 - app/views/support_desk/console/tickets/_composer.html.erb
 - app/views/support_desk/console/tickets/_context_card.html.erb
+- app/views/support_desk/console/tickets/_draft.html.erb
 - app/views/support_desk/console/tickets/_message.html.erb
 - app/views/support_desk/console/tickets/_nav_badge.html.erb
 - app/views/support_desk/console/tickets/_new_conversation_form.html.erb
@@ -154,6 +162,7 @@ files:
 - app/views/support_desk/console/tickets/show.html.erb
 - app/views/support_desk/tickets/_context_card.html.erb
 - app/views/support_desk/tickets/_door.html.erb
+- app/views/support_desk/tickets/_human_door.html.erb
 - app/views/support_desk/tickets/_pick_thing.html.erb
 - app/views/support_desk/tickets/_pick_topic.html.erb
 - app/views/support_desk/tickets/_ticket_row.html.erb
@@ -172,9 +181,14 @@ files:
 - gemfiles/rails_7.2.gemfile
 - gemfiles/rails_8.0.gemfile
 - gemfiles/rails_8.1.gemfile
+- lib/generators/support_desk/assistant_generator.rb
 - lib/generators/support_desk/console_generator.rb
 - lib/generators/support_desk/install_generator.rb
+- lib/generators/support_desk/templates/add_assistants_to_support_desk.rb.erb
 - lib/generators/support_desk/templates/add_opened_by_to_support_desk_tickets.rb.erb
+- lib/generators/support_desk/templates/assistant/service.rb.erb
+- lib/generators/support_desk/templates/assistant/turn_job.rb.erb
+- lib/generators/support_desk/templates/assistant/turn_job_test.rb.erb
 - lib/generators/support_desk/templates/console/controller.rb.erb
 - lib/generators/support_desk/templates/console/resource.rb.erb
 - lib/generators/support_desk/templates/create_support_desk_tables.rb.erb
@@ -182,6 +196,8 @@ files:
 - lib/generators/support_desk/upgrade_generator.rb
 - lib/generators/support_desk/views_generator.rb
 - lib/support_desk.rb
+- lib/support_desk/assistant_policy.rb
+- lib/support_desk/brief.rb
 - lib/support_desk/configuration.rb
 - lib/support_desk/console.rb
 - lib/support_desk/console_engine.rb
@@ -195,18 +211,23 @@ files:
 - lib/support_desk/macros.rb
 - lib/support_desk/models/application_record.rb
 - lib/support_desk/models/assignment.rb
+- lib/support_desk/models/assistant.rb
 - lib/support_desk/models/concerns/agent.rb
 - lib/support_desk/models/concerns/requester.rb
 - lib/support_desk/models/concerns/supportable.rb
 - lib/support_desk/models/desk.rb
+- lib/support_desk/models/draft.rb
 - lib/support_desk/models/event.rb
 - lib/support_desk/models/ticket.rb
+- lib/support_desk/models/ticket/assistance.rb
+- lib/support_desk/outcome.rb
 - lib/support_desk/queue.rb
 - lib/support_desk/summary.rb
 - lib/support_desk/test_helpers.rb
 - lib/support_desk/timeline.rb
 - lib/support_desk/topic.rb
 - lib/support_desk/topic_tree.rb
+- lib/support_desk/transcript.rb
 - lib/support_desk/version.rb
 - lib/support_desk/wizard.rb
 - lib/tasks/support_desk.rake
@@ -236,5 +257,6 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 3.6.2
 specification_version: 4
-summary: Add customer support (tickets that are conversations) to your Rails app
+summary: 'Customer support for your Rails app: tickets that are conversations, worked
+  by your team and by AI agents with real guardrails'
 test_files: []