support_desk 0.2.0 → 0.3.0

data/config/locales/support_desk.console.en.yml

@@ -22,6 +22,8 @@ en:
         topic: "Topic"
         subject_status: "Status"
         open_subject: "Open in admin"
+        assistant: "Assistant"
+        requester_context: "About this person"
       transcript:
         title: "Conversation"
         empty: "Nothing has been said yet."
@@ -44,6 +46,41 @@ en:
         note_hint: "Notes never leave the desk."
         closed: "This case is closed. Reopen it to answer."
         assignee_only: "%{agent} is handling this case, and this desk only lets the assignee reply."
+      draft:
+        title: "%{name}'s proposal"
+        from: "%{name}'s proposal"
+        confidence: "declared confidence %{percent} %"
+        sources: "Sources"
+        attachments: "Attachments"
+        stale: "The conversation has changed since this was proposed. Read it before you send."
+        editing: "Editing %{name}'s proposal"
+        cancel_edit: "cancel"
+        reason_placeholder: "Why are you discarding it? (optional)"
+        sent_by: "Proposal sent by %{name}"
+        rejected_by: "Proposal discarded by %{name}"
+        # The verb the "already %{status}" refusal reads.
+        statuses:
+          pending: "proposed"
+          sent: "sent"
+          rejected: "discarded"
+          superseded: "replaced"
+          expired: "expired"
+      badges:
+        needs_human: "Needs a person"
+        pending_draft: "Proposal ready"
+        assistant_holds: "%{name} has it · %{used}/%{max} turns"
+        assistant_holds_unlimited: "%{name} has it"
+      withheld_reasons:
+        policy: "this case's policy doesn't allow it"
+        not_your_turn: "it wasn't her turn"
+      # Why a case ended up with a person. The tokens are written by the gem
+      # or by the host's own harness; these are how they read.
+      escalation_reasons:
+        max_turns: "she ran out of turns"
+        assistant_silent: "the assistant didn't answer in time"
+        requester_request: "the customer asked for one"
+        phrase: "the customer asked in the conversation"
+        hand_off_when_error: "the assistant failed"
       assignment:
         title: "Who has it"
         held_by: "Held by %{agent}"
@@ -54,6 +91,16 @@ en:
       timeline:
         title: "Timeline"
         system: "System"
+        escalated: "%{actor} handed the case to a person: %{reason}"
+        human_requested: "The customer asked for a person"
+        assistant_paused: "%{actor} paused the assistant"
+        assistant_resumed: "%{actor} resumed the assistant"
+        draft_sent: "%{actor} sent %{assistant}'s proposal"
+        draft_sent_edited: "%{actor} sent %{assistant}'s proposal (edited)"
+        draft_rejected: "%{actor} discarded %{assistant}'s proposal"
+        assistant_withheld: "%{assistant} didn't answer: %{reason}"
+        draft_superseded: "Proposal replaced"
+        draft_expired: "Proposal expired when the case closed"
         kinds:
           message: "Message"
           opened: "Opened"
@@ -79,6 +126,12 @@ en:
         close: "Close"
         reopen: "Reopen"
         change_topic: "Refile"
+        send_draft: "Send"
+        send_edited_draft: "Send the edited proposal"
+        edit_draft: "Edit"
+        reject_draft: "Discard"
+        pause_assistant: "Pause the assistant"
+        resume_assistant: "Resume the assistant"
       flashes:
         message_sent: "Message sent to %{requester}."
         replied: "Answer sent."
@@ -91,6 +144,10 @@ en:
         noted: "Note saved."
         topic_changed: "Refiled."
         queue_empty: "Nothing is waiting for you."
+        draft_sent: "Proposal sent."
+        draft_rejected: "Proposal discarded."
+        assistant_paused: "The assistant is paused on this case."
+        assistant_resumed: "The assistant is back on this case."
       errors:
         forbidden: "You don't have access to the support console."
         not_allowed: "You can't do that on this case."
@@ -116,4 +173,10 @@ en:
         writing_to_yourself: "You can't open a support conversation with yourself. Ask for help as a customer instead."
         off_duty: "You're off duty, so you can't write to anybody right now."
         attachments_again: "If you attach files and something goes wrong, you'll have to pick them again."
+        unknown_draft: "That proposal is gone."
+        draft_already_reviewed: "That proposal was already %{status}."
+        no_pending_draft: "There is no proposal waiting on this case."
+        stale_turn: "The conversation has changed. Read it and send again."
+        assistant_not_allowed: "The assistant can’t do that on this case."
+        not_an_assistant: "That action is the assistant’s only."
         generic: "That didn't work."

data/config/locales/support_desk.console.es.yml

@@ -22,6 +22,8 @@ es:
         topic: "Tema"
         subject_status: "Estado"
         open_subject: "Abrir en el admin"
+        assistant: "Asistente"
+        requester_context: "Sobre la persona"
       transcript:
         title: "Conversación"
         empty: "Todavía no se ha dicho nada."
@@ -44,6 +46,43 @@ es:
         note_hint: "Las notas nunca salen del equipo."
         closed: "Este caso está cerrado. Vuelve a abrirlo para responder."
         assignee_only: "%{agent} lleva este caso y en esta mesa solo responde quien lo tiene."
+      draft:
+        title: "Propuesta de %{name}"
+        from: "propuesta de %{name}"
+        confidence: "confianza declarada %{percent} %"
+        sources: "Fuentes"
+        attachments: "Adjuntos"
+        stale: "La conversación ha cambiado desde esta propuesta. Léela antes de enviar."
+        editing: "Editando la propuesta de %{name}"
+        cancel_edit: "cancelar"
+        reason_placeholder: "¿Por qué la descartas? (opcional)"
+        sent_by: "Propuesta enviada por %{name}"
+        rejected_by: "Propuesta descartada por %{name}"
+        # The verb the "ya se %{status}" refusal reads. Never the English
+        # status: a Spanish desk reading "ya se sent" is the whole reason
+        # this map exists.
+        statuses:
+          pending: "propuso"
+          sent: "envió"
+          rejected: "descartó"
+          superseded: "sustituyó"
+          expired: "caducó"
+      badges:
+        needs_human: "Necesita persona"
+        pending_draft: "Propuesta lista"
+        assistant_holds: "%{name} se ocupa · %{used}/%{max} turnos"
+        assistant_holds_unlimited: "%{name} se ocupa"
+      withheld_reasons:
+        policy: "la política de este caso no se lo permite"
+        not_your_turn: "no era su turno"
+      # Por qué un caso acabó en manos de una persona. Los tokens los
+      # escribe el gem o el harness del host; aquí se leen en castellano.
+      escalation_reasons:
+        max_turns: "se quedó sin turnos"
+        assistant_silent: "el asistente no contestó a tiempo"
+        requester_request: "lo pidió el cliente"
+        phrase: "el cliente lo pidió en la conversación"
+        hand_off_when_error: "el asistente falló"
       assignment:
         title: "Quién lo lleva"
         held_by: "Lo lleva %{agent}"
@@ -54,6 +93,16 @@ es:
       timeline:
         title: "Historial"
         system: "Sistema"
+        escalated: "%{actor} pasó el caso a una persona: %{reason}"
+        human_requested: "El cliente pidió hablar con una persona"
+        assistant_paused: "%{actor} pausó el asistente"
+        assistant_resumed: "%{actor} reanudó el asistente"
+        draft_sent: "%{actor} envió la propuesta de %{assistant}"
+        draft_sent_edited: "%{actor} envió la propuesta de %{assistant} (editada)"
+        draft_rejected: "%{actor} descartó la propuesta de %{assistant}"
+        assistant_withheld: "%{assistant} no respondió: %{reason}"
+        draft_superseded: "Propuesta sustituida"
+        draft_expired: "Propuesta caducada al cerrar"
         kinds:
           message: "Mensaje"
           opened: "Abierto"
@@ -79,6 +128,12 @@ es:
         close: "Cerrar"
         reopen: "Reabrir"
         change_topic: "Cambiar tema"
+        send_draft: "Enviar"
+        send_edited_draft: "Enviar propuesta editada"
+        edit_draft: "Editar"
+        reject_draft: "Descartar"
+        pause_assistant: "Pausar asistente"
+        resume_assistant: "Reanudar asistente"
       flashes:
         message_sent: "Mensaje enviado a %{requester}."
         replied: "Respuesta enviada."
@@ -91,6 +146,10 @@ es:
         noted: "Nota guardada."
         topic_changed: "Tema cambiado."
         queue_empty: "No te espera nada."
+        draft_sent: "Propuesta enviada."
+        draft_rejected: "Propuesta descartada."
+        assistant_paused: "Asistente pausado en este caso."
+        assistant_resumed: "Asistente reanudado en este caso."
       errors:
         forbidden: "No tienes acceso a la consola de soporte."
         not_allowed: "No puedes hacer eso en este caso."
@@ -116,4 +175,10 @@ es:
         writing_to_yourself: "No puedes abrir una conversación de soporte contigo. Si necesitas ayuda, pídela como cliente."
         off_duty: "No estás de guardia, así que no puedes escribir a nadie ahora mismo."
         attachments_again: "Si adjuntas archivos y algo falla, tendrás que volver a seleccionarlos."
+        unknown_draft: "Esa propuesta ya no existe."
+        draft_already_reviewed: "Esa propuesta ya se %{status}."
+        no_pending_draft: "No hay ninguna propuesta pendiente en este caso."
+        stale_turn: "La conversación ha cambiado. Léela y vuelve a enviar."
+        assistant_not_allowed: "El asistente no puede hacer eso en este caso."
+        not_an_assistant: "Esa acción es solo para el asistente."
         generic: "No ha funcionado."

data/config/locales/support_desk.en.yml

@@ -3,17 +3,31 @@ en:
     system:
       assigned: "%{agent} is taking care of your request"
       reassigned: "%{agent} is now taking care of your request"
+      assistant_disclosure: "%{name} is %{desk}’s virtual assistant. If you’d rather talk to a person, use the button in this conversation."
+      handed_off_to_humans: "I’m passing you to somebody on the team."
+      handed_off_to_humans_with_promise: "I’m passing you to somebody on the team. We usually reply in under %{reply_within}."
+      human_requested: "Somebody from the team will take it from here."
+      human_requested_with_promise: "Somebody from the team will take it from here. We usually reply in under %{reply_within}."
+    assistant:
+      disclosed_name: "%{name} · virtual assistant"
     thread:
       closed_notice: "This conversation is closed. Start a new one if you need anything else."
       reopened_notice: "We reopened this conversation."
       promise: "We usually reply in under %{time}"
       opened_by_support: "%{desk} opened this conversation with you about “%{label}”. You can reply right here."
       unavailable_notice: "This account can no longer send or receive messages. The conversation stays here to read."
+      human_door: "I’d rather talk to a person"
+      human_requested_notice: "Done. Somebody from the team will take it from here."
+      handled_by_assistant: "Handled by %{name}"
+      handled_by_humans: "Somebody from the team will take it from here"
+    transcript:
+      deleted: "[message deleted]"
     notifications:
       title: "%{desk} · new message"
     queue:
       tabs:
         awaiting: "Needs a reply"
+        needs_human: "Needs a person"
         mine: "Mine"
         unassigned: "Unassigned"
         open: "Open"
@@ -21,6 +35,7 @@ en:
         closed: "Closed"
     summary:
       awaiting_reply: "awaiting reply"
+      needs_human: "needs a person"
       awaiting_requester: "awaiting requester"
       open: "open"
       closed: "closed"

data/config/locales/support_desk.es.yml

@@ -4,6 +4,17 @@ es:
     system:
       assigned: "%{agent} se ocupa de tu consulta"
       reassigned: "%{agent} se ocupa ahora de tu consulta"
+      # Las tres líneas del asistente. Cada una tiene su variante con
+      # promesa: una mesa que no promete un plazo no debe inventarlo.
+      assistant_disclosure: "%{name} es el asistente virtual de %{desk}. Si prefieres hablar con una persona, usa el botón de esta conversación."
+      handed_off_to_humans: "Te paso con una persona del equipo."
+      handed_off_to_humans_with_promise: "Te paso con una persona del equipo. Normalmente contestamos en menos de %{reply_within}."
+      human_requested: "Una persona del equipo seguirá con tu consulta."
+      human_requested_with_promise: "Una persona del equipo seguirá con tu consulta. Normalmente contestamos en menos de %{reply_within}."
+    assistant:
+      # La divulgación no es una insignia que alguien pueda no ver: cuando
+      # se divulga, el nombre mismo dice qué es.
+      disclosed_name: "%{name} · asistente virtual"
     thread:
       closed_notice: "Esta conversación está cerrada. Abre una nueva si necesitas algo más."
       reopened_notice: "Hemos vuelto a abrir esta conversación."
@@ -13,6 +24,16 @@ es:
       # qué es esto.
       opened_by_support: "%{desk} ha abierto esta conversación contigo sobre «%{label}». Puedes responder aquí mismo."
       unavailable_notice: "Esta cuenta ya no puede enviar ni recibir mensajes. La conversación se queda aquí para consultarla."
+      human_door: "Prefiero hablar con una persona"
+      human_requested_notice: "Hecho. Una persona del equipo seguirá con tu consulta."
+      handled_by_assistant: "Atendida por %{name}"
+      handled_by_humans: "Una persona del equipo seguirá con tu consulta"
+    transcript:
+      # Un mensaje borrado sigue siendo un turno. Quien lea la conversación
+      # después, una persona o el modelo al que el host se la pasa, tiene
+      # que ver que ahí se dijo algo y se retiró: un hueco sin marcar se lee
+      # como que nunca pasó nada.
+      deleted: "[mensaje eliminado]"
     notifications:
       # Generic on purpose: una pantalla de bloqueo no debe contar de qué va
       # el caso de nadie. El detalle va en el cuerpo.
@@ -20,6 +41,7 @@ es:
     queue:
       tabs:
         awaiting: "Pendientes"
+        needs_human: "Necesitan persona"
         mine: "Mi cola"
         unassigned: "Sin asignar"
         open: "Abiertos"
@@ -27,6 +49,7 @@ es:
         closed: "Cerrados"
     summary:
       awaiting_reply: "esperando respuesta"
+      needs_human: "necesita una persona"
       awaiting_requester: "esperando al cliente"
       open: "abierto"
       closed: "cerrado"

data/config/routes.rb

@@ -18,7 +18,13 @@ SupportDesk::Engine.routes.draw do
   # `show` redirects into the chats conversation — a stable URL for a case,
   # for emails and notifications, that never has to know where chats is
   # mounted.
-  resources :tickets, only: %i[create show]
+  resources :tickets, only: %i[create show] do
+    # The door out of a machine. It is a POST on the CASE rather than
+    # anything to do with chats, because it is a fact about the case: from
+    # here on a person is expected, whatever the assistant would have done
+    # next.
+    post :request_human, on: :member
+  end
 
   root to: "tickets#index"
 end

data/lib/generators/support_desk/assistant_generator.rb

@@ -0,0 +1,193 @@
+# frozen_string_literal: true
+
+require "rails/generators/base"
+
+module SupportDesk
+  module Generators
+    # `rails generate support_desk:assistant Rose --disclosure signature` —
+    # the harness, as files in YOUR app.
+    #
+    # The gem never calls a model. It emits `:assistant_turn` and it accepts
+    # `respond!` / `draft!` / `escalate!` / `note!`; everything between those
+    # two points — which provider, which prompt, which retries, what it
+    # costs — is yours. This generator writes that middle: a job wired to
+    # the event and a service with one method to fill in.
+    #
+    # Three things it deliberately does NOT do:
+    #
+    # * It never touches your initializer. `config.assistant` is a policy
+    #   decision, and a generator that appends one turns "let me look at
+    #   this" into a live assistant. The stanza is PRINTED; you paste it.
+    # * It never overwrites. Run it again after an upgrade and it tells you
+    #   which files it left alone.
+    # * It copies no locales. The copy an assistant speaks in is the gem's
+    #   (`support_desk.system.*`) until you override those keys in your own
+    #   locale file, where they belong.
+    #
+    # `--disclosure` is required and has no default. Whether a customer is
+    # told they are talking to a machine is not a thing a gem gets to decide
+    # for a host in a jurisdiction it knows nothing about, so the generator
+    # refuses to write anything until somebody has chosen.
+    class AssistantGenerator < Rails::Generators::Base
+      # The four modes, and what each one does to what the requester sees.
+      DISCLOSURE_MODES = {
+        "signature_and_notice" => "she signs every message AND the thread opens with a notice",
+        "signature" => "she signs every message; no notice",
+        "notice" => "the thread opens with a notice; her messages are unsigned, from the desk",
+        "none" => "nothing is said and nothing is signed — your legal process has to be the one that chose this"
+      }.freeze
+
+      source_root File.expand_path("templates/assistant", __dir__)
+
+      desc "Generate the harness for a support assistant: a turn job and a service"
+
+      argument :name, type: :string, banner: "Rose",
+               desc: "What she is called. Becomes her key (rose), her service and her job"
+
+      class_option :disclosure, type: :string, required: false, banner: "MODE",
+                   desc: "REQUIRED: #{DISCLOSURE_MODES.keys.join(" | ")}"
+      class_option :desk, type: :string, default: "default",
+                   desc: "The desk she works"
+      class_option :autonomy, type: :string, default: "draft",
+                   desc: AssistantPolicy::LEVELS.join(" | ")
+
+      # Everything is checked BEFORE the first file is written. A generator
+      # that writes two of its three files and then refuses the third leaves
+      # an app that neither boots nor regenerates.
+      def validate_options!
+        @refused = true
+        return say_disclosure_modes if options[:disclosure].blank?
+
+        unless DISCLOSURE_MODES.key?(disclosure)
+          say_status :error, "unknown disclosure #{options[:disclosure].inspect}", :red
+          return say_disclosure_modes
+        end
+        unless AssistantPolicy::LEVELS.map(&:to_s).include?(autonomy)
+          say_status :error, "unknown autonomy #{options[:autonomy].inspect} — one of " \
+                             "#{AssistantPolicy::LEVELS.join(", ")}", :red
+          return
+        end
+
+        @refused = false
+      end
+
+      def create_turn_job
+        return if refused?
+
+        template "turn_job.rb.erb", "app/jobs/support/#{key}_turn_job.rb", skip: true
+      end
+
+      def create_service
+        return if refused?
+
+        template "service.rb.erb", "app/services/support/#{key}.rb", skip: true
+      end
+
+      def create_job_test
+        return if refused?
+
+        template "turn_job_test.rb.erb", "test/jobs/support/#{key}_turn_job_test.rb", skip: true
+      end
+
+      # The four things a host still has to do by hand, in the order they
+      # have to happen. Printed, never written: each one is a decision.
+      def display_post_install_message
+        return if refused?
+
+        say "\n🤖 #{assistant_name}'s harness is in app/jobs/support/ and app/services/support/.", :green
+        say "\n  Existing files were left alone — nothing here is ever overwritten."
+
+        say "\n  1. Paste this into config/initializers/support_desk.rb, inside the configure block:"
+        say "\n#{initializer_stanza}"
+
+        say "  2. Subscribe the job to the one event the gem emits:"
+        say "\n#{subscription_stanza}"
+
+        say "  3. Schedule the two maintenance tasks. They are what makes a dead harness"
+        say "     a delay instead of a customer nobody answers:"
+        say "\n#{scheduler_stanza}"
+
+        say "  4. Write #{service_class}.answer — it raises NotImplementedError until you do."
+        say "     The README's Assistants section is the whole contract."
+
+        say "\n  Then: SupportDesk.doctor.print, and start at --autonomy draft. Every word"
+        say "  goes through a person until the numbers say otherwise.\n", :green
+      end
+
+      private
+
+      def refused? = @refused
+
+      # "Rose" → "rose"; "Customer Care" → "customer_care".
+      def key = name.to_s.strip.underscore.parameterize(separator: "_")
+
+      # What she is called, as typed — the `name` setting, not the key.
+      def assistant_name = name.to_s.strip
+
+      def service_class = "Support::#{key.camelize}"
+      def job_class = "Support::#{key.camelize}TurnJob"
+      def disclosure = options[:disclosure].to_s.strip
+      def autonomy = options[:autonomy].to_s.strip
+      def desk_key = options[:desk].to_s.strip.presence || "default"
+      def default_desk? = desk_key == "default"
+
+      def say_disclosure_modes
+        say "\nsupport_desk:assistant needs --disclosure. Nothing was written.", :yellow
+        say "\n  Whether a customer is told they are talking to a machine is a legal and"
+        say "  product decision, and it is yours. The four modes:\n\n"
+        DISCLOSURE_MODES.each { |mode, meaning| say "    --disclosure #{mode.ljust(21)} #{meaning}" }
+        say "\n  rails g support_desk:assistant #{name} --disclosure signature\n\n"
+      end
+
+      def initializer_stanza
+        lines = [
+          "  config.assistant :#{key} do |#{key}|",
+          "    #{key}.name       = #{assistant_name.inspect}",
+          "    #{key}.autonomy   = :#{autonomy}",
+          "    #{key}.disclosure = :#{disclosure}",
+          "    #{key}.max_turns  = 6",
+          "    #{key}.responds_within = 3.minutes",
+          "    # #{key}.hand_off_when { |_ticket, message| " \
+            "message.body.to_s.match?(/\\b(persona|humano|agente)\\b/i) }",
+          "    # #{key}.cap { |ticket| :draft if ticket.requester.try(:vip?) }",
+          "  end"
+        ]
+        lines << if default_desk?
+          "  config.default_assistant = :#{key}"
+        else
+          "  config.desk(:#{desk_key}) { |desk| desk.assistant = :#{key} }"
+        end
+        "#{lines.join("\n")}\n\n"
+      end
+
+      def subscription_stanza
+        <<~RUBY
+
+            SupportDesk.on(:assistant_turn, key: "support.#{key}.turn") do |ticket, assistant, _message, turn:|
+              #{job_class}.set(wait: 20.seconds).perform_later(ticket.id, assistant.key, turn)
+            end
+
+        RUBY
+      end
+
+      def scheduler_stanza
+        <<~YAML
+
+            # config/recurring.yml (solid_queue)
+            production:
+              support_desk_release_silent_assistants:
+                command: "SupportDesk.release_silent_assistants!"
+                schedule: every minute
+              support_desk_redispatch_assistant_turns:
+                command: "SupportDesk.redispatch_assistant_turns!"
+                schedule: every 5 minutes
+
+            # or cron
+            * * * * * cd /app && bin/rails support_desk:release_silent_assistants
+            */5 * * * * cd /app && bin/rails support_desk:redispatch_assistant_turns
+
+        YAML
+      end
+    end
+  end
+end

data/lib/generators/support_desk/install_generator.rb

@@ -36,6 +36,14 @@ module SupportDesk
                            File.join(db_migrate_path, "add_opened_by_to_support_desk_tickets.rb")
       end
 
+      # The assistants (0.3). The SAME file `support_desk:upgrade` copies,
+      # for the same reason: one migration owns those tables and columns
+      # wherever they came from.
+      def create_assistants_migration
+        migration_template "add_assistants_to_support_desk.rb.erb",
+                           File.join(db_migrate_path, "add_assistants_to_support_desk.rb")
+      end
+
       # The annotated initializer — every setting the gem has, with what it
       # means and what it defaults to.
       def create_initializer
@@ -86,6 +94,10 @@ module SupportDesk
         say "  nothing you own. Follow the CHANGELOG's drained cutover: migrate, pause"
         say "  support traffic, drain old web/workers, backfill, then serve only 0.2."
 
+        say "\n  Assistants (0.3): when a machine should answer first, 'rails g support_desk:assistant"
+        say "  Rose --disclosure signature' writes the harness and prints the stanza. Read the"
+        say "  README's Assistants section before you flip it on — disclosure is a required choice."
+
         say "\nCheck your work any time with SupportDesk.doctor.print"
         say "You now have support tickets that are real conversations. 🚀\n", :green
       end