support_desk 0.1.3 → 0.3.0

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/console_generator.rb

@@ -60,7 +60,7 @@ module SupportDesk
         say "  1. One route line:"
         say "       # config/routes.rb"
         say "       namespace :#{target} do"
-        say "         resources :support_tickets, only: %i[index show], concerns: :support_console"
+        say "         resources :support_tickets, only: %i[index show new], concerns: :support_console"
         say "       end"
 
         say "  2. A badge in your admin nav:"

data/lib/generators/support_desk/install_generator.rb

@@ -27,6 +27,23 @@ module SupportDesk
                            File.join(db_migrate_path, "create_support_desk_tables.rb")
       end
 
+      # Who opened each case. A SEPARATE migration, copied from the same
+      # template `support_desk:upgrade` hands an existing install, so one
+      # file owns those two columns and their index wherever they came from
+      # — and a fresh install's `down` removes exactly what its `up` added.
+      def create_opened_by_migration
+        migration_template "add_opened_by_to_support_desk_tickets.rb.erb",
+                           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
@@ -72,6 +89,15 @@ module SupportDesk
         say "  # app/mailboxes/application_mailbox.rb"
         say "  #   routing(/^support@/i => :support_desk)"
 
+        say "\n  Already installed and bumping the version? 'rails g support_desk:upgrade' copies"
+        say "  only the migrations the new version needs (0.2.0: who opened the case), and"
+        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

data/lib/generators/support_desk/templates/add_assistants_to_support_desk.rb.erb

@@ -0,0 +1,236 @@
+# frozen_string_literal: true
+
+# support_desk 0.3.0 — ASSISTANTS.
+#
+# Two new tables (the assistant herself, and the replies she proposes) and
+# nine columns on the tickets table: the turn, the pointer the turn reads,
+# her budget, and the three independent human-side flags (a person was
+# asked for, she was paused here, this case caps her).
+#
+# Every statement is guarded, so this is safe to run against a schema that
+# already has some of it — a half-finished migration, an upgrade run twice,
+# a host who added a column by hand.
+#
+# Column types are read from the columns they POINT AT, never from today's
+# generator setting: `ticket_id` follows support_desk_tickets.id, message
+# ids follow chats_messages.id, and the polymorphic ids follow the ones
+# support_desk_assignments already uses for an agent. An app that changed
+# `primary_key_type` after installing would otherwise be handed bigint
+# columns for uuid ids.
+class AddAssistantsToSupportDesk < ActiveRecord::Migration<%= migration_version %>
+  TICKET_INDEX = "index_support_desk_tickets_on_needs_human"
+
+  def up
+    create_assistants_table
+    create_drafts_table
+    add_ticket_columns
+    backfill_requester_pointer
+  end
+
+  # Exactly what `up` added. Only meaningful BEFORE an assistant has
+  # answered anything: dropping these tables throws away every proposal a
+  # human reviewed and every reason a case was handed over. A code rollback
+  # to 0.2 does NOT need this — the columns are nullable and the tables are
+  # simply ignored.
+  def down
+    remove_index :support_desk_tickets, name: TICKET_INDEX if
+      index_exists?(:support_desk_tickets, [ :desk_id, :human_required_at ], name: TICKET_INDEX)
+
+    ticket_columns.each_key do |name|
+      remove_column :support_desk_tickets, name if column_exists?(:support_desk_tickets, name)
+    end
+
+    drop_table :support_desk_drafts if table_exists?(:support_desk_drafts)
+    drop_table :support_desk_assistants if table_exists?(:support_desk_assistants)
+  end
+
+  private
+
+  # ---------------------------------------------------------------------------
+  # support_desk_assistants
+  #
+  # Who she is, and whether she is on. Everything she MAY DO lives in the
+  # initializer, in code — so a policy change is a deploy and a diff, not a
+  # row somebody edited. `active` is the exception on purpose: it is the
+  # cross-process kill switch, read fresh before every write she makes.
+  # ---------------------------------------------------------------------------
+  def create_assistants_table
+    unless table_exists?(:support_desk_assistants)
+      create_table :support_desk_assistants, id: primary_key_type do |t|
+        t.string :key, null: false
+        t.boolean :active, null: false, default: true
+        t.send(json_column_type, :settings, default: json_column_default)
+
+        t.timestamps
+      end
+    end
+
+    return if index_exists?(:support_desk_assistants, :key, name: "index_support_desk_assistants_on_key")
+
+    add_index :support_desk_assistants, :key, unique: true, name: "index_support_desk_assistants_on_key"
+  end
+
+  # ---------------------------------------------------------------------------
+  # support_desk_drafts
+  #
+  # A reply she proposed and a human sent, edited or threw away. `body` is
+  # what she wrote and `sent_body` what went out when they differ, so the
+  # verbatim/edited/rejected split a host reads before raising her level is
+  # a query and not a guess. `proposed_turn` is the case's turn when she
+  # wrote it — what makes `stale?` mean "the conversation moved on".
+  # ---------------------------------------------------------------------------
+  def create_drafts_table
+    unless table_exists?(:support_desk_drafts)
+      create_table :support_desk_drafts, id: primary_key_type do |t|
+        t.column :ticket_id, sql_type_of(:support_desk_tickets, "id"), null: false
+        t.string :author_type, null: false
+        t.column :author_id, sql_type_of(:support_desk_assignments, "agent_id"), null: false
+        t.string :reviewed_by_type
+        t.column :reviewed_by_id, sql_type_of(:support_desk_assignments, "agent_id")
+        t.column :sent_message_id, sql_type_of(:chats_messages, "id")
+
+        t.string :proposed_turn, null: false
+        # Null for an attachment-only proposal — a screenshot with nothing
+        # to add is a whole answer.
+        t.text :body
+        t.text :sent_body
+        t.string :status, null: false, default: "pending"
+        # 0.000 to 1.000: what the model declared, never what it was worth.
+        t.decimal :confidence, precision: 4, scale: 3
+        t.send(json_column_type, :sources, default: json_column_default)
+        t.send(json_column_type, :metadata, default: json_column_default)
+        t.string :rejection_reason
+        t.datetime :reviewed_at
+
+        t.timestamps
+      end
+
+      add_foreign_key :support_desk_drafts, :support_desk_tickets, column: :ticket_id
+    end
+
+    unless index_exists?(:support_desk_drafts, [ :ticket_id, :created_at ],
+                         name: "index_support_desk_drafts_on_ticket")
+      add_index :support_desk_drafts, [ :ticket_id, :created_at ], name: "index_support_desk_drafts_on_ticket"
+    end
+
+    unless index_exists?(:support_desk_drafts, [ :author_type, :author_id, :status ],
+                         name: "index_support_desk_drafts_on_author")
+      add_index :support_desk_drafts, [ :author_type, :author_id, :status ],
+                name: "index_support_desk_drafts_on_author"
+    end
+
+    # ONE pending proposal per case — the belt under the row lock that
+    # serialises them. Enforced on every adapter that has partial indexes
+    # (all but MySQL, Trilogy included); elsewhere the model's
+    # supersede-then-create is the whole story and `doctor` checks it.
+    return unless partial_indexes?
+    return if index_exists?(:support_desk_drafts, :ticket_id, name: "index_support_desk_drafts_on_pending")
+
+    add_index :support_desk_drafts, :ticket_id, unique: true, where: "status = 'pending'",
+              name: "index_support_desk_drafts_on_pending"
+  end
+
+  # ---------------------------------------------------------------------------
+  # support_desk_tickets (+)
+  #
+  # `assistant_revision` is the turn: one integer, bumped by every
+  # registered message and every transition, which is what makes a late or
+  # redelivered answer a no-op instead of a second reply.
+  #
+  # The three human-side flags are THREE columns and not one status, because
+  # they are three different decisions made by three different people:
+  # somebody asked for a person, a human paused her here, and this case caps
+  # her (what a reopen after she closed it writes). Resuming her lifts one
+  # of them, and only an explicit hand-back lifts all three.
+  # ---------------------------------------------------------------------------
+  def add_ticket_columns
+    ticket_columns.each do |name, options|
+      next if column_exists?(:support_desk_tickets, name)
+
+      add_column :support_desk_tickets, name, options[:type], **options.except(:type)
+    end
+
+    return if index_exists?(:support_desk_tickets, [ :desk_id, :human_required_at ], name: TICKET_INDEX)
+
+    add_index :support_desk_tickets, [ :desk_id, :human_required_at ], name: TICKET_INDEX
+  end
+
+  def ticket_columns
+    {
+      assistant_revision: { type: :bigint, null: false, default: 0 },
+      last_requester_message_id: { type: sql_type_of(:chats_messages, "id") },
+      assistant_turns_count: { type: :integer, null: false, default: 0 },
+      assistant_acted_at: { type: :datetime },
+      assistant_paused_at: { type: :datetime },
+      assistant_paused_reason: { type: :string },
+      assistant_cap: { type: :string },
+      human_required_at: { type: :datetime },
+      human_required_reason: { type: :string }
+    }
+  end
+
+  # The pointer the turn's reconciliation reads: which requester message the
+  # clocks are standing on, by id and not only by time.
+  #
+  # SQL, and deliberately not the model: a backfill that loaded today's
+  # Ticket would run this release's validations, callbacks and events over
+  # last release's rows. ORDER BY rather than MAX(id), because ids can be
+  # uuids and "the biggest uuid" is not "the newest message".
+  def backfill_requester_pointer
+    execute(<<~SQL.squish)
+      UPDATE support_desk_tickets SET last_requester_message_id = (
+        SELECT m.id FROM chats_messages m
+         WHERE m.conversation_id = support_desk_tickets.conversation_id
+           AND m.sender_type = support_desk_tickets.requester_type
+           AND m.sender_id = support_desk_tickets.requester_id
+           AND m.kind = 'text'
+         ORDER BY m.created_at DESC, m.id DESC LIMIT 1)
+       WHERE last_requester_message_id IS NULL AND conversation_id IS NOT NULL
+    SQL
+  end
+
+  # The storage this schema already uses for that column — uuid, bigint,
+  # integer. A new column that points at those records has to be stored the
+  # same way, whatever the generator is configured with today.
+  def sql_type_of(table, column)
+    found = connection.columns(table).find { |candidate| candidate.name == column }
+    unless found
+      raise ActiveRecord::MigrationError,
+            "#{table} has no #{column} column — run support_desk's and chats' install migrations first."
+    end
+
+    found.sql_type
+  end
+
+  # Honor the host's configured primary key type (uuid vs bigint) for the
+  # tables this migration CREATES. Everything it points at is derived above.
+  def primary_key_type
+    config = Rails.configuration.generators
+    config.options[config.orm][:primary_key_type] || :primary_key
+  end
+
+  # Whether this adapter can enforce a rule over SOME rows ("one pending
+  # draft per case"). Everything but MySQL can — and Trilogy is MySQL under
+  # a different ADAPTER_NAME, so a /mysql/ pattern alone would hand such a
+  # host an index it cannot create.
+  def partial_indexes?
+    !connection.adapter_name.match?(/mysql|trilogy/i)
+  end
+
+  # jsonb on every PostgreSQL adapter — matched by prefix because PostGIS
+  # answers "PostGIS", not "PostgreSQL".
+  def json_column_type
+    return :jsonb if connection.adapter_name.match?(/\Apostg/i)
+
+    :json
+  end
+
+  # MySQL 8+ doesn't allow default values on JSON columns. `sources`
+  # defaults to [] in Ruby (see SupportDesk::Draft) for the same reason it
+  # can't default here.
+  def json_column_default
+    return nil if connection.adapter_name.match?(/mysql|trilogy/i)
+
+    {}
+  end
+end

data/lib/generators/support_desk/templates/add_opened_by_to_support_desk_tickets.rb.erb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+# support_desk 0.2.0 — WHO OPENED THE CASE.
+#
+# `opened_by` is a record, exactly like `closed_by`: the requester when they
+# asked, the agent when the desk wrote first. It is nullable for one reason
+# only — rows written by 0.1.x have no provenance to state — and this
+# migration backfills every one of them to its requester, because 0.1 had no
+# way to open a case as anybody else.
+#
+# The new column's type is read from the tickets table's OWN `requester_id`
+# rather than from today's generator setting: both columns point at the same
+# host records, so an app that changed `primary_key_type` after installing
+# would otherwise be handed a bigint column for uuid ids.
+class AddOpenedByToSupportDeskTickets < ActiveRecord::Migration<%= migration_version %>
+  INDEX_NAME = "index_support_desk_tickets_on_opened_by"
+
+  def up
+    ensure_columns_are_ours!
+
+    add_reference :support_desk_tickets, :opened_by, polymorphic: true, null: true,
+                                                     type: opened_by_id_type, index: false
+    add_index :support_desk_tickets, [ :opened_by_type, :opened_by_id ], name: INDEX_NAME
+
+    # SQL, and deliberately not the model: a backfill that loaded today's
+    # Ticket would run this release's validations, callbacks and events over
+    # last release's rows, in a migration that must only move two columns.
+    execute(<<~SQL.squish)
+      UPDATE support_desk_tickets
+         SET opened_by_type = requester_type,
+             opened_by_id = requester_id
+       WHERE opened_by_id IS NULL
+    SQL
+  end
+
+  # Exactly what `up` added, and nothing else. Note that this DESTROYS
+  # provenance: every case the desk opened stops being distinguishable from
+  # one the requester opened. It is here for a failed deploy of the schema
+  # alone, never as the way back from a code rollback.
+  def down
+    remove_index :support_desk_tickets, name: INDEX_NAME if
+      index_exists?(:support_desk_tickets, [ :opened_by_type, :opened_by_id ], name: INDEX_NAME)
+
+    remove_column :support_desk_tickets, :opened_by_type if
+      column_exists?(:support_desk_tickets, :opened_by_type)
+    remove_column :support_desk_tickets, :opened_by_id if
+      column_exists?(:support_desk_tickets, :opened_by_id)
+  end
+
+  private
+
+  # A column we did not add is a schema we cannot reason about: its type may
+  # not match, it may hold something else's data, and `down` would drop it.
+  # Say so with the way out rather than skipping the backfill and the index
+  # in silence.
+  def ensure_columns_are_ours!
+    existing = %i[opened_by_type opened_by_id].select { |name| column_exists?(:support_desk_tickets, name) }
+    return if existing.empty?
+
+    raise ActiveRecord::MigrationError,
+          "support_desk_tickets already has #{existing.join(" and ")}. This migration owns those two columns " \
+          "and #{INDEX_NAME}, so it won't overwrite them. Verify both column types, the index and existing " \
+          "provenance against this migration before reconciling its version in schema_migrations. " \
+          "db:migrate:up runs this method again; it does not mark it as already run. Preserve existing data."
+  end
+
+  # The storage this table already uses for a host record's id — uuid,
+  # bigint, integer. `opened_by_id` points at the same records as
+  # `requester_id`, so it has to be stored the same way.
+  def opened_by_id_type
+    column = connection.columns(:support_desk_tickets).find { |candidate| candidate.name == "requester_id" }
+    unless column
+      raise ActiveRecord::MigrationError,
+            "support_desk_tickets has no requester_id column — run support_desk's install migration first."
+    end
+
+    column.sql_type
+  end
+end

data/lib/generators/support_desk/templates/assistant/service.rb.erb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Support
+  # <%= assistant_name %>'s mind. Everything the gem knows how to do stops at the
+  # door of this file: which provider you call, what you put in the prompt,
+  # how you cache, what you spend, and what you refuse to answer are yours.
+  #
+  # What comes in:
+  #
+  # * `brief` — a SupportDesk::Brief. `brief.to_h` is versioned data;
+  #   `brief.to_text` is the same facts as plain text. It carries the desk,
+  #   the case, the requester, and `may` / `may_not` — the authorization,
+  #   so you never have to re-derive the rules this case is under.
+  # * `transcript` — a SupportDesk::Transcript. `to_text` is the readable
+  #   rendering; `to_a` is Turns (`role`, `name`, `body`, `at`,
+  #   `attachments`, `assisted`).
+  #
+  # ⚠️ Both of these go to whatever you call. `support_context` (the
+  # subject's and the requester's) is host data, chosen by you, and it
+  # leaves your building the moment this method does. Decide what belongs in
+  # a prompt before you fill those in, not after.
+  #
+  # What goes out: an Answer. Nothing else — this method never touches the
+  # ticket. The job owns the writes, so the turn, the policy and the lock
+  # are checked in exactly one place.
+  class <%= key.camelize %>
+    # `kind` is the whole decision:
+    #
+    #   :answer   — say this. `text` required; `confidence` (0..1) and
+    #               `sources` ([{ title:, url: }]) are shown to the agent
+    #               reviewing the proposal, so fill them in honestly.
+    #   :hand_off — a person should take this. `reason` required, `summary`
+    #               is the paragraph the next human reads first.
+    #   :note     — leave a staff note and stop. Never reaches the customer.
+    #   :nothing  — do nothing. The case stays in the humans' queue.
+    Answer = Struct.new(:kind, :text, :confidence, :sources, :reason, :summary, :metadata,
+                        keyword_init: true) do
+      def initialize(**attributes)
+        super
+        self.kind ||= :nothing
+        self.sources ||= []
+        self.metadata ||= {}
+      end
+    end
+
+    # Answer one case.
+    #
+    #   def self.answer(brief, transcript)
+    #     reply = MyModel.complete(system: PROMPT, user: brief.to_text)
+    #     return Answer.new(kind: :hand_off, reason: "unsure") if reply.confidence < 0.6
+    #
+    #     Answer.new(kind: :answer, text: reply.text, confidence: reply.confidence)
+    #   end
+    def self.answer(brief, transcript)
+      raise NotImplementedError,
+            "#{self} has no answer yet. Write one — the contract is the Assistants " \
+            "section of the support_desk README (brief in, Answer out, no ticket writes)."
+    end
+  end
+end