support_desk 0.2.0 → 0.3.2

data/lib/support_desk/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module SupportDesk
-  VERSION = "0.2.0"
+  VERSION = "0.3.2"
 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,142 @@ 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
+
+      # Resolving her is also when what she is CALLED is written down, so a
+      # message she signed still says the same thing after somebody takes
+      # her out of the initializer (R8). It writes only when configuration
+      # and the row disagree.
+      (assistants[key] ||= Assistant.for(key)).snapshot_disclosure!
+    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
+
+    # Give back every seat an assistant can no longer sit in — she was
+    # switched off, her configuration was removed, or her policy no longer
+    # lets her hold a case — and ask for a person on each of them.
+    #
+    # Invalid-assignee recovery, NOT silence detection: it reads the seats
+    # that exist rather than the assistants a running process happens to
+    # have configured, so a `deactivate!`, a flag flipped off and a topic
+    # cap tightened are all covered, with no `responds_within` and no
+    # overdue clock anywhere in it (R6). `release_silent_assistants!` runs
+    # it first; `rake support_desk:reclaim_assistant_seats` runs it alone.
+    #
+    # Returns how many seats it reclaimed.
+    def reclaim_assistant_seats!
+      return 0 unless Assistant.table_exists?
+
+      reclaimed = 0
+      Ticket.open.held_by_assistants.find_each do |ticket|
+        reclaimed += 1 if ticket.reclaim_assistant_seat!
+      rescue StandardError => e
+        report_error(e, context: { hook: :reclaim_assistant_seats, ticket: ticket.id })
+      end
+      logger&.info("[support_desk] reclaimed #{reclaimed} stranded assistant seat(s)") if reclaimed.positive?
+      reclaimed
+    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!
+      # A seat nobody can sit in any more is not a silence problem, and it
+      # must not need a `responds_within` to be noticed (R6).
+      moved = reclaim_assistant_seats!
+      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|
+          # Conditional, under the case's own lock: every predicate above was
+          # true when this row was SELECTED, and a person may have answered
+          # it since (R5).
+          moved += 1 if ticket.escalate_if_still_silent!(agent, window)
+        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
+        # Repair before deciding. A requester message whose registration was
+        # lost after commit leaves the clocks describing a case that no longer
+        # exists — and `assistant_idle_since` reads those clocks, so the case
+        # it most needs to find is the one it cannot see. Folding the message
+        # in COMMITS on its own and emits the turn it produces, so a dead
+        # process followed by nothing but this task still ends in an
+        # actionable turn (R3).
+        Ticket.for_desk(key).with_unregistered_requester_messages.find_each do |ticket|
+          emitted += 1 if ticket.reconcile_and_commit!.positive?
+        rescue StandardError => e
+          report_error(e, context: { hook: :redispatch_assistant_turns, ticket: ticket.id })
+        end
+
+        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 +362,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,60 @@ 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 "Give back every seat an assistant can no longer sit in (run every minute)"
+  task reclaim_assistant_seats: :environment do
+    # Invalid-assignee recovery: she was switched off, her configuration was
+    # taken away, or her policy no longer lets her hold a case. It needs no
+    # `responds_within` and no overdue clock — `release_silent_assistants`
+    # runs it first, and this is the same work on its own.
+    reclaimed = SupportDesk.reclaim_assistant_seats!
+
+    puts "[support_desk] #{reclaimed} stranded seat(s) given back to people."
+  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 "Report assistant status without changing tickets"
+  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.2
 platform: ruby
 authors:
 - rameerez
 bindir: exe
 cert_chain: []
-date: 2026-09-18 00:00:00.000000000 Z
+date: 2026-09-24 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,16 +181,24 @@ 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_message_registrations.rb.erb
 - lib/generators/support_desk/templates/create_support_desk_tables.rb.erb
 - lib/generators/support_desk/templates/initializer.rb
 - 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
@@ -193,20 +210,27 @@ files:
 - lib/support_desk/errors.rb
 - lib/support_desk/events.rb
 - lib/support_desk/macros.rb
+- lib/support_desk/message_signatures.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/message_registration.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 +260,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: []