support_desk 0.1.3 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 587ddd67c318b1c6b4cbe7b496a65ec2bfb70b39818556a5d90ad81415db17c8
-  data.tar.gz: 3ab9972eca4fc07680e1b33d139400d7f1c6ef9116e3778967f070d05f5111e1
+  metadata.gz: 74ee479ece9f12d0c47800369c872e8d15f7535a40665592618dc95fc88b7f10
+  data.tar.gz: 66cba52c0c8ffdba13d921d831a804b170887cbc25e3048d9b748404a80573db
 SHA512:
-  metadata.gz: 27e60ca1419b9fd778e6d57ac35dea358b7f422829b92c36f00d123153b967a0171c8f7edfeeef8715e597b2e169fa48629325d4314aa2fdc2593f8c27662924
-  data.tar.gz: f04e5ba138fd6e847c0aad98ef5f42eeaf1018900eccd4f3b72af15a9ba82a00e9506bf2412e900145918a2eb97299b5b0fbb2d1b0bcabba0c23b890ae027fc3
+  metadata.gz: 305686f2b7f606e94fdb78230991992407408d4603677935d44b7e366792692d99f79f74ddb8e631bed6633a678bb35241d9955cd73c0c52fd7fdaf6985da687
+  data.tar.gz: 6d4e3a9e84e9e14979bea658e686b29f6df00064bf1f18f80f14a1c75911f9c2a9f86ab2b6be90aa005040b6503acf485e3bc6beae5add62447918621f8fe285

data/CHANGELOG.md

@@ -4,6 +4,64 @@ All notable changes to this project are documented here.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.2.0] - 2026-09-17
+
+**The desk can write first.** Until now a case could only start with somebody
+asking; now it can start with you, through the same seam and the same
+algorithm.
+
+### Added
+
+- `agent.open_support_conversation_with!(requester, message, about:, topic:, files:, via:, desk:)` — write first, as the desk: the message is the desk's, signed by the agent, and it lands in the requester's inbox as the desk. The only agent-side verb in the gem, because it is the only action with no ticket yet.
+- `SupportDesk::Ticket.open!(…, by: an_agent)` — the seam under it. `by:` defaults to the requester; an agent there is the desk writing first. A Symbol (`by: :system`) is refused with `NotAnAgent`: automation is deferred (docs 12, Q17).
+- `opened_by` on every case — a polymorphic record, exactly like `closed_by` — with `opened_by_requester?` / `opened_by_support?` and the `opened_by_requester` / `opened_by_support` scopes, which partition the table.
+- `config.opening_line` and `config.opening_line_from_support`: the system line a thread opens with, posted inside the opening transaction. A String (with `%{label}`, `%{desk}`, `%{reply_within}`), an I18n key, a block, or nil. The first defaults to nil; the second to the gem's own copy, because a message from a desk somebody never wrote to has to explain itself.
+- `config.find_requester`: how a console turns something an agent typed into the person they meant. Without it the console accepts only a GlobalID from one of your own pages.
+- `has_support_tickets if:` — who may ask, and who may be written to — with `support_requester?` and `support_desk` on the requester model.
+- Console: `new` (the form) and `open_conversation` (the send) as collection actions, with the "Write to someone" door in the mounted console and the generated one. `SupportDesk::Console::COLLECTION_VERBS` is the table the router reads.
+- Generators: `rails g support_desk:upgrade` copies the additive `opened_by` migration (the same file a fresh install runs), and `rake support_desk:backfill_opened_by` runs its catch-up after draining old processes and before admitting 0.2 traffic.
+- `SupportDesk::NotARequester`, and `SupportDesk.humanize_duration` (moved off `Wizard`, which keeps a delegation).
+
+### Changed
+
+Behaviour changes, not refactors. Read them before upgrading:
+
+- **System messages are never folded into the clocks.** They never reached the clocks through chats anyway; now a hand-written `register!` ignores them too, and so does a message from somebody who is neither the requester nor the desk. Neither moves `awaiting`, an SLA clock or the last-registered marker.
+- **`first_agent_reply_at` is only set when a requester message came first.** An agent writing into a case with nothing in it is not answering anything, and an out-of-order replay whose requester clock is later is not evidence either.
+- **`:agent_replied` is not emitted for the desk's own opening message** on a case the desk opened. An agent's first message into an old empty case the REQUESTER opened is still a reply, and still emits.
+- **The asking limits count only requester-opened cases.** `open_rate_limit` and `max_open_tickets` limit asking, not being asked, so cases you opened no longer spend somebody's allowance.
+- **Requester eligibility is checked at every message write.** `chat_locked?` is now "the requester can't be written to, or the case is closed on a desk that locks closed cases", re-read from the database rather than taken from a cached association. The thread, the queue row, the notes and the close are all unchanged; only new messages stop, and `actions_for` stops offering `:reply`.
+- **`reply!` registers its message inside its own lock**, in a savepoint that owns the whole operation — so a caller who rescues its failure and commits their own transaction commits none of ours. `open!` does the same for opening and for the reply a reused case turns into.
+- **The opening line is the gem's, and it is posted inside the opening transaction**, pinned one database tick above the message it introduces. Hosts that posted their own line after commit can delete that code.
+- **`Console::ERROR_KEYS` is gone**, replaced by the error's own name (`NotTheAssignee` → `not_the_assignee`) with a generic fallback. Every key the table listed is a name it derives to, so a host that overrode one keeps its wording.
+- `Console::TRANSITIONS` and `ConsoleRoutes::MEMBER_VERBS` are aliases of `Console::MEMBER_VERBS` for one release.
+- `Chats::Error` is rescued into a console flash; `Chats::ConfigurationError` is deliberately not.
+
+### Fixed
+
+- Stale revoked/deleted agents are refused using an uncached eligibility read, shared by opening and ordinary ticket transitions.
+- Malformed attachment inputs return the compose form with 422; signed blob failures do not discard the draft. Invalid explicit desks cannot silently change the sender, and host finder errors are not hidden as bad GlobalIDs.
+- Legacy NULL provenance remains requester-originated for quotas and reply metrics. The documented upgrade drains old web/workers before the catch-up and new traffic.
+- Rake tasks are discovered once across the two engines; migration collision guidance preserves existing provenance.
+- Valid draft fields survive malformed sibling fields, and unavailable recipients are explained before offering send.
+- `Ticket.open!` no longer reloads the case it just opened. The clocks are folded in on the same instance, inside the transaction, so the row that commits is already true.
+
+### Upgrading from 0.1
+
+**This upgrade requires a drained cutover, not a rolling deployment.** Old
+processes cannot release assignments with the new `opened` reason.
+
+1. Copy the upgrade migration with `rails generate support_desk:upgrade` and migrate before 0.2 serves traffic. The additive, nullable columns are compatible with 0.1.
+2. Pause incoming support writes and background producers. Stop and drain **all old web requests and workers**, including jobs already running; verify none remain. Keep support traffic paused. Do not start serving 0.2 alongside 0.1.
+3. With the 0.2 artifact available but traffic still paused, run `rake support_desk:backfill_opened_by`. Verify `SupportDesk::Ticket.where(opened_by_id: nil).count` is zero and inspect `SupportDesk.doctor`. The task is idempotent; repeating it is safe in this release because automation openers are not supported.
+4. Start only 0.2 web/workers, then resume support traffic. Writing-first may now be used. Add `new` to console routes and regenerate/customize views as needed.
+
+NULL-provenance cases are treated as requester-opened even before the backfill,
+so quotas, labels and reply metrics stay correct. This read compatibility does
+**not** make old assignment writers compatible with 0.2; the drain is still required.
+
+Rolling back is a host code rollback, not a Gemfile pin: 0.1 does not know the new settings, routes or predicates. Keep the columns and the provenance already written — but note that 0.1's `Assignment#release!` revalidates `reason` and rejects `opened`, so closing, releasing or handing off a case the desk opened will fail under 0.1 until a compatibility patch accepts that reason. Prefer disabling the entry point (drop `new`/`open_conversation` from your routes) over downgrading with active desk-opened cases.
+
 ## [0.1.3] - 2026-09-17
 
 ### Fixed

data/README.md

@@ -36,10 +36,12 @@ class Order < ApplicationRecord
   supportable topic: :order           # can be asked about
 end
 
-ticket = alice.ask_support!("My order never arrived", about: order)
+ticket = alice.ask_support!("My order never arrived", about: order)   # she asks
 ticket.assign!(to: lucia, by: lucia)
-ticket.reply!("We're on it", by: lucia)
+ticket.reply!("We're on it", by: lucia)                               # you answer
 ticket.close!(by: lucia)
+
+lucia.open_support_conversation_with!(alice, "We saw your refund bounced", about: order)   # you write first
 ```
 
 That's a ticket, a conversation, an assignment history, an append-only audit trail and four events your app can subscribe to.
@@ -52,7 +54,7 @@ Add the gem:
 gem "support_desk"
 ```
 
-Install it (creates the migration + an annotated initializer):
+Install it (creates the migrations + an annotated initializer):
 
 ```bash
 bundle install
@@ -60,6 +62,13 @@ rails generate support_desk:install
 rails db:migrate
 ```
 
+Already on 0.1? `rails generate support_desk:upgrade` copies only the
+migrations a version bump needs (0.2.0: who opened each case) and nothing
+you own. Migrate first, pause support traffic, drain all old web requests and
+workers, and backfill before starting 0.2 traffic. This is not a rolling
+upgrade: old assignment writers cannot handle new support-opened cases.
+See the CHANGELOG for the complete cutover and rollback procedure.
+
 Three model lines and one route line:
 
 ```ruby
@@ -103,17 +112,21 @@ Desk records are memoised for the life of the process, so anything that has to c
 
 ## The model macros
 
-### `has_support_tickets(desk: :default, as: nil)`
+### `has_support_tickets(desk: :default, as: nil, if: nil)`
 
-Adds exactly four methods to whoever asks for help:
+Adds six methods to whoever asks for help:
 
 | method | what it does |
 |---|---|
 | `support_tickets` | `has_many`, newest first. Chain the scopes: `alice.support_tickets.open.about(order)` |
 | `ask_support!(message, about:, topic:, files:, via:)` | opens the ticket, posts the first message, emits `ticket_opened`, and hands back the `Ticket` — or the open one they already have about the same thing |
+| `support_requester?` | may this person ask for help, and be written to, right now? |
+| `support_desk` | the desk record their tickets go to |
 | `awaiting_support_reply?` | is the desk holding any of their questions? |
 | `unread_support_count` | for a nav badge, counted against the chats read horizon |
 
+`if:` is a method name or a callable, and it is a **write** rule rather than a screen rule. `has_support_tickets if: :kept?` means a closed account can neither ask nor be written to, on every path — while its history stays readable, its cases stay in the queue, and agents can still take notes on them and close them.
+
 ### `supportable(topic:, candidates: nil, one_open_ticket: true)`
 
 Makes a domain record something people can ask about. Every method has a working default; override the ones that matter:
@@ -129,7 +142,7 @@ Makes a domain record something people can ask about. Every method has a working
 
 ### `acts_as_support_agent(if: nil, kind: :human)`
 
-Makes someone able to answer. Agents are never chats participants — the desk sends, the agent *authors* — so this needs no messaging setup at all. It adds `support_agent?`, `support_agent_name`, `support_agent_avatar`, `on_duty?`, `support_capacity` and `support_queue`, and **no verbs**: the ticket is the subject of every sentence.
+Makes someone able to answer. Agents are never chats participants — the desk sends, the agent *authors* — so this needs no messaging setup at all. It adds `support_agent?`, `support_agent_name`, `support_agent_avatar`, `on_duty?`, `support_capacity`, `support_queue` and exactly one verb — `open_support_conversation_with!`, the only agent action with no ticket yet (see [Writing first](#writing-first)). Everywhere else the ticket is the subject of the sentence.
 
 ## Tickets
 
@@ -280,13 +293,15 @@ One word in your routes file draws every verb an agent needs:
 ```ruby
 # config/routes.rb
 namespace :madmin do
-  resources :support_tickets, only: %i[index show], concerns: :support_console
+  resources :support_tickets, only: %i[index show new], concerns: :support_console
 end
 ```
 
 That adds member `reply take assign hand_off release close reopen note
-change_topic` and collection `next`. It has to sit inside a `resources`
-block, since that is what those routes hang off.
+change_topic` and collection `next` and `open_conversation`. It has to sit
+inside a `resources` block, since that is what those routes hang off.
+`new` stays yours: add it to `only:` when you render the form behind
+`open_conversation` ("Write to someone").
 
 The concern is seeded into every route set by a small prepend on Rails'
 routing mapper, because routing concerns live in a Hash built per `draw`
@@ -298,7 +313,7 @@ Rails.application.routes.draw do
   SupportDesk::ConsoleRoutes.register(self)
 
   namespace :madmin do
-    resources :support_tickets, only: %i[index show], concerns: :support_console
+    resources :support_tickets, only: %i[index show new], concerns: :support_console
   end
 end
 ```
@@ -396,6 +411,86 @@ route. It takes its layout and authentication from
 Generate when you have an admin to put this inside and want the files;
 mount when you don't. They render the same templates either way.
 
+## Writing first
+
+Most cases start with somebody asking. Some start with you:
+
+```ruby
+lucia.open_support_conversation_with!(alice, "We saw your refund bounced", about: withdrawal)
+```
+
+That is not a personal message from Lucía. It speaks as the desk, signs the
+message with her name, lands in Alice's inbox as "Support", and seats Lucía
+on the case from its first committed state — silently, because "Lucía is
+taking care of your request" in a thread Alice never opened answers a
+question nobody asked. It is the same seam `ask_support!` uses, so there is
+one algorithm for cardinality, topics, subjects, conversations, events and
+clocks:
+
+```ruby
+SupportDesk::Ticket.open!(requester: alice, message: "…", by: lucia)   # what the sugar calls
+```
+
+If Alice already has this conversation open, the message joins it as an
+ordinary **reply** — under your desk's reply policy, which may well leave
+the case with whoever holds it. Nothing about that is guessed from a count:
+the opener knows whether it inserted, and the console says one true thing
+either way.
+
+Every case now records who opened it:
+
+```ruby
+ticket.opened_by             # => alice · lucia — a record, like closed_by
+ticket.opened_by_requester?  # she asked
+ticket.opened_by_support?    # we wrote first
+
+SupportDesk::Ticket.opened_by_support.awaiting_requester
+```
+
+Her abuse limits stay hers: `open_rate_limit` and `max_open_tickets` count
+only the cases she opened, so five conversations you started can never stop
+her asking her first question. And `time_to_first_reply` is nil for a case
+you opened — nobody was waiting for it.
+
+### The line a thread opens with
+
+```ruby
+config.opening_line              = "You opened a conversation about “%{label}”. We usually reply within %{reply_within}."
+config.opening_line_from_support = "%{desk} started this conversation with you about “%{label}”."
+```
+
+Both are posted inside the opening transaction, one database tick above the
+message they introduce — so the line can never arrive after it, or not at
+all. A String (with `%{label}`, `%{desk}`, `%{reply_within}`), an I18n key,
+a block given the ticket, or nil. `opening_line` defaults to nil, so
+existing threads open exactly as they do today; `opening_line_from_support`
+has the gem's own copy as its default, because a message from a desk
+somebody never wrote to has to explain itself.
+
+### From the console
+
+Add `new` to your routes and the queue grows a "Write to someone" button:
+
+```ruby
+resources :support_tickets, only: %i[index show new], concerns: :support_console
+```
+
+Tell the console how to find people and it grows a search box too;
+otherwise it takes a GlobalID from one of your own pages (a user's admin
+screen, an order) and says so:
+
+```ruby
+config.find_requester { |query| User.find_by(email: query.to_s.strip.downcase) }
+```
+
+### Who can be written to
+
+`has_support_tickets if: :kept?` is the whole policy. When it turns false
+the person can neither ask nor be written to, on every path — the console,
+the model, a direct chats write — and nothing is hidden or deleted: the
+transcript stays readable, the case stays in the queue, and agents can
+still take notes and close it.
+
 ## The wizard
 
 "What do you need help with?" is a plain object, not a controller, so a host

data/Rakefile

@@ -21,6 +21,22 @@ end
 APP_RAKEFILE = File.expand_path("test/dummy/Rakefile", __dir__)
 load "rails/tasks/engine.rake"
 
+# `db:migrate:reset` — the command the README and CI give for the PostgreSQL
+# leg — is `["db:drop", "db:create", "db:schema:dump", "db:migrate"]` in
+# ActiveRecord's own databases.rake. That third step is hardwired: it ignores
+# the dummy's `config.active_record.dump_schema_after_migration = false`,
+# which is why plain `rake db:migrate` leaves no dump and this task does.
+#
+# The dump is stamped with the Rails version that wrote it
+# (`ActiveRecord::Schema[8.1]`), and every later leg's `db:test:load_schema`
+# prefers a schema.rb over the migrations — so one PostgreSQL run made the
+# 7.2 Appraisal die with "Unknown migration version 8.1" until the file was
+# deleted by hand. The dummy migrates from db/migrate and never from a dump,
+# so the artifact has no reader: throw it away where it is made.
+if Rake::Task.task_defined?("db:migrate:reset")
+  Rake::Task["db:migrate:reset"].enhance { rm_f "test/dummy/db/schema.rb" }
+end
+
 require "rake/testtask"
 
 Rake::TestTask.new(:test) do |t|

data/app/controllers/support_desk/tickets_controller.rb

@@ -55,9 +55,11 @@ module SupportDesk
       # The form was submitted from a step that isn't the composer (a stale
       # tab, a hand-rolled POST): re-render the step they are actually on.
       render :new, status: :unprocessable_entity
-    rescue SupportDesk::NotAllowed, SupportDesk::NotSupportable
-      # The subject passed the wizard's check and failed the model's. Same
-      # answer as a forged token: 404.
+    rescue SupportDesk::NotAllowed, SupportDesk::NotSupportable, SupportDesk::NotARequester
+      # The subject passed the wizard's check and failed the model's, or this
+      # account stopped being able to write between the form and the submit.
+      # Same answer as a forged token: 404. "Not yours", "not there" and "not
+      # eligible" must look the same from outside.
       raise ActiveRecord::RecordNotFound
     end
 

data/app/helpers/support_desk/engine_helper.rb

@@ -75,13 +75,19 @@ module SupportDesk
       within = SupportDesk.config.desk(desk_key).reply_within
       return nil if within.nil?
 
-      t("support_desk.thread.promise", time: SupportDesk::Wizard.humanize_duration(within))
+      t("support_desk.thread.promise", time: SupportDesk.humanize_duration(within))
     end
 
     # The status line under a case in the requester's list: who owes the next
     # word, or that it's over.
     def support_ticket_state(ticket)
       return t("support_desk.tickets.state.closed") if ticket.closed?
+      # A conversation the desk started, before they have said anything back:
+      # "we replied" would be a lie about a thread they never opened, and
+      # "we're on it" is worse — there is nothing of theirs to be on.
+      if ticket.opened_by_support? && ticket.last_requester_message_at.nil?
+        return t("support_desk.tickets.state.opened_by_support")
+      end
 
       ticket.awaiting_reply? ? t("support_desk.tickets.state.awaiting_reply") : t("support_desk.tickets.state.answered")
     end

data/app/views/support_desk/console/tickets/_context_card.html.erb

@@ -26,6 +26,11 @@
       </div>
     <% end %>
 
+    <div class="flex justify-between gap-3">
+      <dt class="text-slate-500"><%= t("support_desk.console.context.opened_by") %></dt>
+      <dd class="text-right"><%= card.opened_by_label %></dd>
+    </div>
+
     <div class="flex justify-between gap-3">
       <dt class="text-slate-500"><%= t("support_desk.console.context.topic") %></dt>
       <dd class="text-right"><%= card.topic_label %></dd>

data/app/views/support_desk/console/tickets/_new_conversation_form.html.erb

@@ -0,0 +1,91 @@
+<%# The compose form. Everything it renders is a draft the controller set
+    BEFORE it looked anything up, so a refusal comes back with the message
+    still in the box.
+
+    Three shapes for "who is this for", in order of how sure we are:
+
+      @requester          a card — the page that opened this form knew
+      find_requester      a text field — the host said how to look people up
+      neither             a hint naming the setting, and no send button,
+                          because a form that can't reach anybody is worse
+                          than one that says so
+
+    Deliberately NOT promised here: who ends up holding the case. If this
+    person already has this conversation open, the message joins it as an
+    ordinary reply and the desk's reply policy decides the seat. %>
+<%= form_with url: console_tickets_path(:open_conversation, desk: support_desk_record.key),
+      method: :post, html: { multipart: true }, class: "space-y-4" do %>
+  <section class="rounded-lg border border-slate-200 bg-white p-4">
+    <h2 class="text-sm font-semibold"><%= t("support_desk.console.new_conversation.requester") %></h2>
+
+    <% if @requester %>
+      <div class="mt-2 flex items-center justify-between gap-3">
+        <p class="text-sm font-medium"><%= Chats.display_name_for(@requester) %></p>
+        <%= hidden_field_tag :requester, @requester.to_global_id.to_s %>
+      </div>
+    <% elsif support_desk_record.config.find_requester %>
+      <%# Text, not an email field: the host's callback may look people up by
+          phone, handle or anything else they chose. %>
+      <%= text_field_tag :requester_query, @requester_query,
+            placeholder: t("support_desk.console.new_conversation.requester_query"),
+            class: "mt-2 w-full rounded-md border border-slate-300 p-2 text-sm" %>
+    <% else %>
+      <p class="mt-2 text-sm text-slate-500"><%= t("support_desk.console.new_conversation.requester_hint") %></p>
+    <% end %>
+
+    <% if @about %>
+      <p class="mt-3 text-sm text-slate-500">
+        <%= t("support_desk.console.new_conversation.about", subject: @about.support_label) %>
+      </p>
+      <%= hidden_field_tag :about, @about.to_global_id.to_s %>
+    <% end %>
+  </section>
+
+  <section class="rounded-lg border border-slate-200 bg-white p-4">
+    <%# A subject brings its own topic with it, so the picker is only for
+        cases that are about nothing in particular. The supplied topic is
+        preserved either way. %>
+    <% if @about %>
+      <%= hidden_field_tag :topic, @topic %>
+    <% else %>
+      <label class="text-sm font-semibold" for="topic"><%= t("support_desk.console.new_conversation.topic") %></label>
+      <%= select_tag :topic,
+            options_for_select(support_conversation_topics.map { |topic| [ topic.full_label, topic.path ] }, @topic),
+            class: "mt-2 w-full rounded-md border border-slate-300 p-2 text-sm" %>
+    <% end %>
+
+    <label class="mt-4 block text-sm font-semibold" for="body">
+      <%= t("support_desk.console.new_conversation.message") %>
+    </label>
+    <%= text_area_tag :body, @body, rows: 5, maxlength: Chats.config.max_message_length,
+          class: "mt-2 w-full rounded-md border border-slate-300 p-2 text-sm" %>
+
+    <p class="mt-2 text-xs text-slate-500">
+      <%= t("support_desk.console.new_conversation.signed_as", agent: current_agent.support_agent_name) %>
+    </p>
+
+    <% if Chats.config.attachments %>
+      <div class="mt-3">
+        <%= file_field_tag "files[]", multiple: true, class: "text-xs text-slate-500" %>
+        <%# Browsers can't be handed a file input back. Say so rather than
+            letting somebody assume their attachment survived the 422. %>
+        <p class="mt-1 text-xs text-slate-500"><%= t("support_desk.console.errors.attachments_again") %></p>
+      </div>
+    <% end %>
+  </section>
+
+  <div class="flex items-center justify-between gap-3">
+    <%= link_to t("support_desk.console.new_conversation.cancel"), console_tickets_path,
+          class: "text-sm text-slate-500 underline underline-offset-2" %>
+
+    <% if support_conversation_sendable? && (@requester || support_desk_record.config.find_requester) %>
+      <%= submit_tag t("support_desk.console.new_conversation.send", desk: support_desk_record.name),
+            class: "rounded-md bg-slate-900 px-3 py-2 text-sm font-medium text-white hover:bg-slate-700" %>
+    <% elsif flash[:alert].blank? %>
+      <p class="text-sm text-slate-500">
+        <%= support_conversation_available? ? t("support_desk.console.new_conversation.requester_hint") :
+              t("support_desk.console.errors.off_duty") %>
+      </p>
+    <% end %>
+  </div>
+<% end %>

data/app/views/support_desk/console/tickets/_ticket_row.html.erb

@@ -20,6 +20,14 @@
         </span>
 
         <span class="font-mono text-xs text-slate-400"><%= ticket.reference %></span>
+
+        <%# A case we started reads differently from one somebody asked for:
+            nobody is waiting on us in it until they answer. %>
+        <% if ticket.opened_by_support? %>
+          <span class="rounded-full bg-slate-100 px-2 py-0.5 text-xs font-medium text-slate-600">
+            <%= t("support_desk.console.row.opened_by_support") %>
+          </span>
+        <% end %>
       </div>
 
       <p class="mt-0.5 text-sm text-slate-500">

data/app/views/support_desk/console/tickets/index.html.erb

@@ -17,8 +17,20 @@
       <p class="text-sm text-slate-500"><%= support_desk_record.name %></p>
     </div>
 
-    <%= link_to t("support_desk.console.actions.next"), console_tickets_path(:next),
-          class: "inline-flex items-center rounded-md bg-slate-900 px-3 py-2 text-sm font-medium text-white hover:bg-slate-700" %>
+    <div class="flex items-center gap-2">
+      <%# The door to writing first. Through console_tickets_path so it
+          resolves under an isolated admin engine as well as a host
+          namespace, and carrying the desk so a multi-desk console composes
+          for the desk being worked. %>
+      <% if support_conversation_offered? %>
+        <%= link_to t("support_desk.console.actions.new_conversation"),
+              console_tickets_path(:new, desk: support_desk_record.key),
+              class: "inline-flex items-center rounded-md border border-slate-300 px-3 py-2 text-sm font-medium text-slate-900 hover:bg-slate-50" %>
+      <% end %>
+
+      <%= link_to t("support_desk.console.actions.next"), console_tickets_path(:next),
+            class: "inline-flex items-center rounded-md bg-slate-900 px-3 py-2 text-sm font-medium text-white hover:bg-slate-700" %>
+    </div>
   </header>
 
   <%= render "tabs", queue: @queue, scope: @scope %>

data/app/views/support_desk/console/tickets/new.html.erb

@@ -0,0 +1,25 @@
+<%# Writing first: the desk starting a conversation with somebody who hasn't
+    written to us.
+
+    It is a whole page rather than a modal on purpose — the 422 that a bad
+    email or a refused message comes back as has to render the form again
+    with everything still typed into it, and a stream refresh would throw
+    that away. %>
+<div class="mx-auto max-w-2xl px-4 py-6 text-slate-900">
+  <header class="mb-5">
+    <h1 class="text-xl font-semibold"><%= t("support_desk.console.new_conversation.title") %></h1>
+    <p class="text-sm text-slate-500"><%= support_desk_record.name %></p>
+  </header>
+
+  <%# The refusal is rendered HERE rather than left to your layout: this
+      screen answers 422 with itself, and an agent has to read why on the
+      page that came back. If your layout already prints flashes, delete
+      this block when you eject the views. %>
+  <% if flash[:alert] %>
+    <p class="mb-4 rounded-md border border-red-200 bg-red-50 px-3 py-2 text-sm text-red-800">
+      <%= flash[:alert] %>
+    </p>
+  <% end %>
+
+  <%= render "new_conversation_form" %>
+</div>

data/config/console_routes.rb

@@ -10,7 +10,7 @@
 # SAME `:support_console` concern a host writes in their own routes file —
 # the turnkey console gets no private API.
 SupportDesk::ConsoleEngine.routes.draw do
-  resources :tickets, path: "", only: %i[index show], concerns: :support_console
+  resources :tickets, path: "", only: %i[index show new], concerns: :support_console
 
   root to: "tickets#index"
 end

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

@@ -8,10 +8,14 @@ en:
         tabs_label: "Queue tabs"
         empty: "Nothing here right now."
       row:
+        opened_by_support: "Written by support"
         waiting: "%{duration}"
         unassigned: "Unassigned"
       context:
         title: "Context"
+        opened_by: "Opened by"
+        not_recorded: "not recorded"
+        unavailable: "account unavailable"
         requester: "Requester"
         open_tickets: "Open cases"
         member_since: "Member since"
@@ -21,6 +25,17 @@ en:
       transcript:
         title: "Conversation"
         empty: "Nothing has been said yet."
+      new_conversation:
+        title: "Write as support"
+        requester: "To"
+        requester_query: "Their email"
+        requester_hint: "Set `config.find_requester` to look people up from here"
+        about: "About %{subject}"
+        topic: "Topic"
+        message: "Message"
+        send: "Send as %{desk}"
+        cancel: "Cancel"
+        signed_as: "Signed “%{agent}”."
       composer:
         reply: "Reply"
         note: "Internal note"
@@ -53,6 +68,7 @@ en:
           note: "Internal note"
       actions:
         back: "Back to the queue"
+        new_conversation: "Write to someone"
         next: "Next case"
         reply: "Send"
         note: "Save note"
@@ -64,6 +80,7 @@ en:
         reopen: "Reopen"
         change_topic: "Refile"
       flashes:
+        message_sent: "Message sent to %{requester}."
         replied: "Answer sent."
         taken: "This case is yours."
         assigned: "Assigned to %{agent}."
@@ -90,4 +107,13 @@ en:
         take_it_first: "Take this case first — this desk only lets the assignee reply."
         held_by_somebody_else: "%{holder} is handling this case."
         unavailable_action: "You can't do that on this case right now."
+        unknown_requester: "We can't find that person."
+        not_a_requester: "That account can't receive support messages."
+        invalid_requester: "That link doesn't point at anybody we can write to."
+        invalid_subject: "That link doesn't point at anything we can open a conversation about."
+        invalid_input: "Something in the form didn't come through. Try again."
+        no_requester_lookup: "Open this form from the person's own page: there's no way to look them up from here."
+        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."
         generic: "That didn't work."

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

@@ -8,10 +8,14 @@ es:
         tabs_label: "Pestañas de la cola"
         empty: "Aquí no hay nada ahora mismo."
       row:
+        opened_by_support: "Escrita por soporte"
         waiting: "%{duration}"
         unassigned: "Sin asignar"
       context:
         title: "Contexto"
+        opened_by: "Abierta por"
+        not_recorded: "sin registrar"
+        unavailable: "cuenta no disponible"
         requester: "Cliente"
         open_tickets: "Casos abiertos"
         member_since: "Cliente desde"
@@ -21,6 +25,17 @@ es:
       transcript:
         title: "Conversación"
         empty: "Todavía no se ha dicho nada."
+      new_conversation:
+        title: "Escribir por soporte"
+        requester: "Para"
+        requester_query: "Email de la persona"
+        requester_hint: "Configura `config.find_requester` para buscar a alguien desde aquí"
+        about: "Sobre %{subject}"
+        topic: "Tema"
+        message: "Mensaje"
+        send: "Enviar como %{desk}"
+        cancel: "Cancelar"
+        signed_as: "Firmado «%{agent}»."
       composer:
         reply: "Responder"
         note: "Nota interna"
@@ -53,6 +68,7 @@ es:
           note: "Nota interna"
       actions:
         back: "Volver a la cola"
+        new_conversation: "Escribir a alguien"
         next: "Siguiente caso"
         reply: "Enviar"
         note: "Guardar nota"
@@ -64,6 +80,7 @@ es:
         reopen: "Reabrir"
         change_topic: "Cambiar tema"
       flashes:
+        message_sent: "Mensaje enviado a %{requester}."
         replied: "Respuesta enviada."
         taken: "El caso es tuyo."
         assigned: "Asignado a %{agent}."
@@ -90,4 +107,13 @@ es:
         take_it_first: "Toma el caso antes de responder: en esta mesa solo responde quien lo lleva."
         held_by_somebody_else: "Lo lleva %{holder}."
         unavailable_action: "Ahora mismo no puedes hacer eso en este caso."
+        unknown_requester: "No encontramos a esa persona."
+        not_a_requester: "Esa cuenta no puede recibir mensajes de soporte."
+        invalid_requester: "Ese enlace no apunta a nadie a quien podamos escribir."
+        invalid_subject: "Ese enlace no apunta a nada sobre lo que podamos abrir la conversación."
+        invalid_input: "Algo en el formulario no se ha enviado bien. Vuelve a intentarlo."
+        no_requester_lookup: "Abre este formulario desde la ficha de la persona: aquí no podemos buscarla."
+        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."
         generic: "No ha funcionado."

data/config/locales/support_desk.en.yml

@@ -7,6 +7,8 @@ en:
       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."
     notifications:
       title: "%{desk} · new message"
     queue:
@@ -41,6 +43,7 @@ en:
       state:
         awaiting_reply: "We're on it"
         answered: "We replied"
+        opened_by_support: "We wrote to you"
         closed: "Closed"
     doors:
       new: "Need help?"