support_desk 0.2.0 → 0.3.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 74ee479ece9f12d0c47800369c872e8d15f7535a40665592618dc95fc88b7f10
-  data.tar.gz: 66cba52c0c8ffdba13d921d831a804b170887cbc25e3048d9b748404a80573db
+  metadata.gz: 66ba1a32f86acca1b4068bbca4091fcb16c4e6840a9d57ae5dc44bea25572ea2
+  data.tar.gz: 2433e492636e42eeffde1652a2c7d21915267c6f0a9180bea8bb010d902cdfad
 SHA512:
-  metadata.gz: 305686f2b7f606e94fdb78230991992407408d4603677935d44b7e366792692d99f79f74ddb8e631bed6633a678bb35241d9955cd73c0c52fd7fdaf6985da687
-  data.tar.gz: 6d4e3a9e84e9e14979bea658e686b29f6df00064bf1f18f80f14a1c75911f9c2a9f86ab2b6be90aa005040b6503acf485e3bc6beae5add62447918621f8fe285
+  metadata.gz: ac1246120f4c2aa2763f81866006f054e0dfd14901d42120ddc25d754b08dad350b1627552faaa9e4fd62d37a50d785eeae9abe6dab1c5dc9adbb9f9bb44acd1
+  data.tar.gz: 66fca7c4ddad8c9b41358448ec24beda2a3dcd9bade8bd373fe7433a565700d500c212f863c1755048faa7dd803c79c1fa92d3fb0b029a072322d1eff6672994

data/CHANGELOG.md

@@ -4,6 +4,203 @@ 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.3.2] - Unreleased
+
+### Fixed
+
+- Persist message-registration receipts atomically with clocks and turn revisions.
+  A new message with an earlier timestamp or smaller UUID is no longer dropped
+  as a replay. It invalidates the turn and triggers requester notifications and
+  handoff detection once, without rewinding clocks. This also fixes human-only
+  desks; no assistant configuration is needed to encounter the old defect.
+- Recovery discovers unregistered replies on closed cases and honors the desk's
+  reopen/locked policy. Repair also runs when the assistant is disabled; only
+  actual assistant dispatch requires one to be configured.
+- Public assistant assignment, release and reply refuse `turn: :current`.
+  Internal outreach and seat-taking use private paths and actual tokens.
+- Default Chats signatures render assistant messages using per-message
+  disclosure snapshots, including old 0.3.0 messages with provenance but no
+  assistant-row snapshot. Rename, mode change and flag-off do not erase old
+  disclosure. Human replies and approved drafts keep human signatures, and host
+  signature overrides remain authoritative. Transcript names are snapshotted
+  for new messages; older ones use their stored display name.
+- Correct the README signature override to preserve the human fallback.
+
+### Upgrade
+
+Run `rails generate support_desk:upgrade` and migrate **with support writes paused
+and all old web/jobs drained**. The new receipt table follows the existing ticket
+and message ID types and seeds historical messages up to the old role clocks.
+Old clocks cannot reveal lost callbacks behind that baseline: review suspect
+historical cases before resuming. Only 0.3.2 processes may write after cutover.
+See README for recovery, rollback limitations and the unchanged SQLite caveat.
+No gem publication or deployment is performed by this change.
+
+## [0.3.1] - 2026-09-19
+
+**Hardening the assistant, after an adversarial review of 0.3.0.** Nine
+defects, every one of them in the concurrency, recovery and kill-switch
+guarantees the release advertised rather than in what a green suite
+covered. Nothing here changes what an assistant may do; it changes what
+can happen to a case while she is doing it. `assign!` and `release!` take
+a `turn:` when `by:` is an assistant — the one API change — and a host
+with no assistant is untouched.
+
+### Fixed
+
+- **A customer's next question can no longer be answered around (R1).**
+  Reconciliation is a `SELECT`, and a requester never takes the case's row
+  lock, so a question could commit between the answer reading the case and
+  the answer writing to it: she replied to the previous one, and a human
+  approved a proposal from a page that predated the new one — `seen_turn`
+  was not evidence that the reviewer had seen the last committed message.
+  Every speaking path now takes the ticket's row lock and then the
+  conversation row chats updates inside every message insert, before
+  reconciling. The lock order is ticket → conversation everywhere, and it
+  is written down. **The guarantee is a row lock, so it holds on PostgreSQL
+  and MySQL and not on SQLite**, which has no row locks and whose WAL
+  snapshot reads straight through an open write transaction: a desk with an
+  assistant belongs on PostgreSQL or MySQL, and `doctor` now warns when it
+  is not.
+- **A seat is decided under the lock (R2).** `assign!` asked whether
+  anybody held the case, and whether she could hold it, *before* the
+  transition acquired the row. No threads were needed to break it: load an
+  unassigned case into one instance, give it to a person through another,
+  and the first instance took the seat from them. A topic cap or a pause
+  committed while a take waited for the lock was read too late in the same
+  way.
+- **A lost registration is repairable (R3).** A requester message that
+  committed while the process that should have registered it died left a
+  turn nothing could ever consume: reconciliation happened inside the
+  candidate answer's savepoint, the bumped revision made that very answer
+  stale, and the `StaleTurn` rolled the repair back with it — for ever,
+  while the clocks said `awaiting_requester` so no idle query could see the
+  case. The fold is now its own committed step, and
+  `redispatch_assistant_turns!` looks for unregistered messages before it
+  looks at clocks.
+- **Messages that share an instant no longer deadlock the turn (R4).** The
+  unseen-message test was "its id is not the one the clock was set from",
+  so every other message on that timestamp read as new: reconciliation
+  folded an already-registered one in again, bumped the revision, and made
+  the answer that discovered it stale. The retry did the same thing. "Seen"
+  is now the pair `(created_at, id)` compared in chats' own transcript
+  order, by the same rule in Ruby and in SQL.
+- **The silent sweep rechecks before it escalates (R5).** Its predicates
+  were true when it SELECTED its candidates. A person who answered, took
+  the case or reset the clock in between lost anyway: the case was marked
+  human-required, its priority went up, and the customer was told a person
+  was coming — on a case that already had one.
+- **Stranded seats come back (R6).** `deactivate!` promised the sweep would
+  release her cases; the sweep only ever visited configured assistants with
+  a `responds_within`, and only cases already overdue. An assistant with no
+  promise kept her seat for ever, and one removed by the documented kill
+  switch — which takes her configuration away — was not visited at all,
+  while the doctor's assistant checks returned early on exactly that state.
+  `SupportDesk.reclaim_assistant_seats!` (and `rake
+  support_desk:reclaim_assistant_seats`) reads the seats that exist.
+- **Running out of turns tells the host (R7).** The budget branch wrote the
+  `escalated` event, released her seat and posted the public hand-off line,
+  but only the outer `escalate!` published `:ticket_escalated` — so a
+  host's "a person is needed here" notifier never heard about a
+  conversation that ran out of turns. One private method now publishes it
+  for every hand-off.
+- **Disclosure on old messages stops moving (R8).** The requester-facing
+  signature resolved live configuration, so taking her out of the
+  initializer rewrote "— Rose · asistente virtual" into "— Rose" on
+  messages nobody had touched. Her name and mode are snapshotted onto her
+  own row and read back from it when nothing declares her any more. A
+  rename still renames history, deliberately; the README shows the
+  `Chats.config.message_signature` lambda for hosts that want each bubble
+  frozen.
+- **The kill switch is read after the wait (R9).** Eligibility was checked
+  before the case's row lock, and the policy then read `active?` off that
+  same stale copy, so an already-seated assistant whose job queued behind a
+  busy case could still speak after `deactivate!` had committed. Every verb
+  resolves her under the lock now, from the row. The ordinary in-flight
+  window — a switch that commits after that read — is documented rather
+  than claimed away.
+
+### Changed
+
+- `Ticket#assign!` and `Ticket#release!` take `turn:`. It is REQUIRED when
+  `by:` is an assistant (`ArgumentError` when omitted, `StaleTurn` when
+  stale) and ignored for a person, whose calls are unchanged.
+- `SupportDesk.release_silent_assistants!` runs
+  `reclaim_assistant_seats!` first, and its count includes what that
+  reclaimed.
+- The doctor's assistant invariants run whenever an assistant ROW exists,
+  not only while one is configured.
+- `Ticket.with_unregistered_requester_messages` — the scope behind the
+  repair half of redispatch.
+
+## [0.3.0] - 2026-09-19
+
+**A machine can answer, and a person still owns every word it sends.** An
+assistant is an agent with a policy: she has a seat, a name, a turn budget
+and a level that says what she may produce here — and at the default level
+that is a proposal a human reads and sends. Nothing in this release turns
+itself on. Without `config.assistant` the gem behaves exactly as 0.2 did.
+
+### Added
+
+- `config.assistant :rose do |rose| … end` — one block per assistant, with `name`, `avatar`, `autonomy`, `disclosure`, `max_turns`, `responds_within`, `may_open_conversations`, the three system lines (`hand_off_line`, `human_requested_line`, `disclosure_line`) and the two hooks (`hand_off_when`, `cap`). `config.assistants`, `config.assistant?(key)`, `config.default_assistant`, and `desk.assistant = :rose` (an explicit `nil` disables one desk rather than inheriting).
+- **`disclosure` is required and has no default.** Four modes — `:signature_and_notice`, `:signature`, `:notice`, `:none` — and boot fails until one is chosen. Whether a customer is told they are talking to a machine is a legal decision in a jurisdiction the gem knows nothing about.
+- `SupportDesk::AssistantPolicy` — what she may do on ONE case, right now, and why. `LEVELS` (`off observe draft reply resolve`), `VERBS_BY_LEVEL`, `level` / `because` / `ceilings` / `floors`, `may?` / `may_observe?` / `may_draft?` / `may_reply?` / `may_hold?` / `may_close?`, `allowed_verbs` / `forbidden_verbs` / `to_h`. Ceilings lower what she may ever produce (her autonomy, the topic's cap, the host's `cap` block, the case's cap, a pause); floors lower it because of the case's state. `because` names the one rule that decided it.
+- `topic :payments, assistant: :draft` — a topic cap, and it only ever tightens: `Topic#assistant_cap` is the minimum over the node and every ancestor.
+- `SupportDesk::Assistant` — the record a message can be authored by, an assignment can point at and an audit log can name. `SupportDesk.assistant(key = nil)`, `SupportDesk.reset_assistants!`, `SupportDesk.ai_actor?(record)`; `deactivate!(by:)` / `activate!(by:)` is the cross-process kill switch, read fresh from the row before every write.
+- `Ticket#respond!(body, by:, turn:, …)` — the one verb a harness needs. Policy decides whether it is sent, proposed as a draft, or withheld with the reason on the record; the answer is a `SupportDesk::Outcome` (`sent?` / `drafted?` / `withheld?` / `escalated?` / `turn`).
+- `Ticket#draft!`, `Ticket#escalate!(reason:, summary:)`, `Ticket#request_human!(by: requester)`, `Ticket#pause_assistant!` / `#resume_assistant!`.
+- **The turn.** `assistant_revision` is an integer bumped by every registered message and every transition; `ticket.assistant_turn` spells it, and EVERY assistant action requires it and consumes it. A late, retried or redelivered action raises `SupportDesk::StaleTurn` and writes nothing — which is why this gem has no idempotency keys, claim rows or leases.
+- `SupportDesk::Draft` — a reply she proposes and a person sends. `send!(by:, seen_turn:, body:)` posts it as the HUMAN's message (they read it, they own it, the requester sees their signature) and keeps the original; `reject!(by:, reason:)` records why, which is the number that tells you whether she is ready for a higher level. `stale?`, `edited?`, `final_body`, `confidence_percent`, and the `reviewed` / `verbatim` / `edited` scopes.
+- `SupportDesk::Transcript` — the conversation as ordered turns (`role`, `name`, `body`, `at`, `attachments`, `assisted`), with four roles rather than the clocks' three. `to_a` / `to_h` / `to_text` / `last(n)` / `since(message)` / `size`, and `ticket.transcript(limit:)`.
+- `SupportDesk::Brief` — everything a machine needs to answer one case, as versioned data. `ticket.brief(include_internal: false, transcript_limit: 50)`, `to_h` / `to_text` / `policy`. Facts only: `may` / `may_not` are the authorization, and there is not one imperative sentence in it.
+- `Requester#support_context` — key/value pairs about the PERSON, the way `Supportable#support_context` is pairs about the thing they are asking about. Empty by default; rendered by `ContextCard#requester_pairs` and included in the brief.
+- Readers and scopes for the new state: `Ticket#assistant`, `#assistant_policy`, `#assistant_turn`, `#assistant_in_play?`, `#held_by_assistant?`, `#human_required?`, `#assistant_paused?`, `#assistant_turns_left`, `#assistant_message?(message)`, `#drafts` / `#pending_draft`; and `held_by_assistants`, `held_by_humans`, `needs_human`, `assistant_paused`, `assistant_capped`, `resolved_by_assistant`, `with_pending_draft`, `assistant_idle_since(time)`. `Desk#assistant` / `#assistant?` name the one that works a desk.
+- Console: `send_draft`, `reject_draft`, `pause_assistant`, `resume_assistant`, the proposal card (Enviar / Editar / Descartar) with the confidence pill, the sources and a staleness warning, the helpers `support_pending_draft` and `support_assistant`, `"no_pending_draft"` as an `unavailable_reason`, and the `needs_human` queue tab (`Queue#needs_human`, `#visible_tabs`).
+- Requester engine: `POST /tickets/:id/request_human`, the `support_desk/tickets/_human_door` partial and the `support_human_door(ticket)` helper. The door is offered whenever an assistant is or has been in play on the case — history counts, so it can never vanish because somebody edited an initializer after she answered.
+- Events: `assistant_turn` (the only one a harness subscribes to; it carries the turn), `draft_proposed`, `draft_sent`, `draft_rejected`, `assistant_withheld`, `ticket_escalated`, `human_requested`, `assistant_paused`, `assistant_resumed`. The matching `Event::KINDS` are new too; the five internal ones join `note` and `drop_in` in `Event::INTERNAL_KINDS`, which is what `Event.requester_visible` excludes, and `Event#summary` reads the paragraph an escalation left.
+- Spanish and English copy for all of it — the system lines, the console's proposal card and flashes, the queue's new tab and the requester's door — with the suite asserting both files carry the same keys.
+- Errors: `SupportDesk::NotAnAssistant`, `SupportDesk::AssistantNotAllowed` (carrying the `policy` and the `verb`), `SupportDesk::StaleTurn`.
+- `rake support_desk:release_silent_assistants` (every minute) and `rake support_desk:redispatch_assistant_turns` (every five) — the net under a dead harness and the at-least-once retry of a dropped turn. `rake support_desk:assistant_status` reads and writes nothing.
+- Doctor: `assistants (config)`, `assistant turn subscriber`, `assistant authorship`, `assistant silence`, `assistant seats`, `assistant idle turns`, `drafts`, `ai agents without policy`.
+- `SupportDesk::TestHelpers`: `support_assistant`, `respond_as`, `draft_as`, `assert_pending_draft` / `refute_pending_draft`, `assert_needs_human` / `refute_needs_human`, `assert_held_by_assistant`, `refute_assistant_spoke`, `assert_assistant_policy`, `with_assistant_config`, `with_topic_assistant_cap`.
+- Generators: `rails g support_desk:assistant Rose --disclosure MODE [--desk KEY] [--autonomy LEVEL]` writes the turn job, the service and a job test, and PRINTS the initializer stanza, the subscription and the two scheduler lines. It never edits an initializer, never overwrites a file and copies no locales. `install` and `upgrade` both copy the additive assistants migration.
+
+### Changed — regardless of configuration
+
+These land whether or not you declare an assistant:
+
+- **A host model declared `acts_as_support_agent kind: :ai` is now refused for every support write, by it or to it** (`NotAnAssistant`). It used to be treated as a human. `kind:` is validated at declaration (`:human` or `:ai`), and `SupportDesk.doctor` warns about such classes. Only the desk's own `SupportDesk::Assistant` has machine authority.
+- **Console picker values are `SupportDesk.actor_key(agent)`**, not bare ids — an assistant and a user can share an integer id. A bare id is still accepted for one release, and only when exactly one pool member matches it.
+- `Queue::TABS` gains `:needs_human`. It is hidden unless the desk has an assistant or the count is non-zero, so no existing queue grows a tab it has no use for.
+- Every registration and every transition writes `assistant_revision`. Additive; a 0.2 process reading those rows is unaffected.
+- The schema adds `support_desk_assistants` and `support_desk_drafts`, and nine columns on `support_desk_tickets` — two defaulted integers (`assistant_revision`, `assistant_turns_count`), the rest nullable.
+
+### Changed — only when an assistant is configured
+
+- `Desk#agents` is now an **Array** (humans plus her), and `Desk#humans` is the human-only pool. Page people with `ticket.agents_to_notify` or `desk.humans`: notifying a machine is notifying nobody.
+- `announce_assignments` never announces her — "Rose is taking care of your request" is not a thing to say.
+- **A human reply on a case she holds takes it over under every `reply_policy`**, and supersedes the pending proposal. `:assignee_only` exists so two people don't answer at once, and she is not one.
+- `close!` expires pending proposals; reopening a case she closed leaves it unassigned and caps her at `:draft` for the rest of its life.
+- `Ticket#reply!` and `post_agent_message!` accept `metadata:` (provenance) and `turn:`.
+
+### Upgrading from 0.2
+
+Additive and rolling-safe — unlike the 0.2 cutover, no drain is needed.
+
+1. `bundle update support_desk` (0.3.0).
+2. `rails generate support_desk:upgrade` then `rails db:migrate`. The migration only adds tables and nullable columns.
+3. **Deploy every process to 0.3.0 before adding `config.assistant`.** A 0.2 worker cannot honour a turn it does not know about.
+4. `rails g support_desk:assistant Rose --disclosure …`, paste the printed stanza, wire the job to `:assistant_turn`, schedule the two rake tasks, and subscribe your notifiers to `draft_proposed`, `ticket_escalated` and `human_requested`.
+5. Render `support_desk/tickets/_human_door` in your thread.
+6. `SupportDesk.doctor` green.
+7. **Start at `:draft`.** Every word goes through a person until the acceptance rate on reviewed proposals says otherwise, and keep topic caps on money and identity when you raise it.
+
+Rolling back: `rose.deactivate!` is the kill switch and needs no deploy. A
+code rollback to 0.2 keeps the schema — the columns are nullable and the two
+tables are ignored — but loses the provenance rendering of her messages, so
+do it only if 0.3 itself is broken.
+
 ## [0.2.0] - 2026-09-17
 
 **The desk can write first.** Until now a case could only start with somebody