chatwoot-router 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -7,6 +7,50 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.3.0] - 2026-10-03
+
+### Fixed
+
+- End a kind's turn with resolved/snoozed only after its canned reply is confirmed to exist in Chatwoot. Failed,
+  unknown or malformed creation outcomes, incomplete history, and attempts without visible replies hand off to
+  people without sending again. A reply seen as failed/deleted in the final fresh read also hands off.
+- Recognize historical public outgoing messages from the account's exact brand bot, including the former relay's
+  replies, without moving reply ledgers. Preserve the durable attempt/observed guard across turns and upgrades.
+- Disconnecting an inbox hands its pending brand-bot leftovers to people with native bot `status=open`. The sweep
+  reads pending/open account conversations, including old disconnected inboxes, and retries failed handoffs.
+- Release the brand bot immediately after a kind's resolved/snoozed status using its standard unassignment API;
+  durable retries finish failed releases. Preserve status, turn boundaries and other owners. The open sweep heals
+  Chatwoot webhook-failure fallbacks without scanning resolved/snoozed history.
+
+### Changed
+
+- Partition routing by account and conversation, with a separate paged `Coordinator`. Each conversation owns its
+  queue, decisions and reply/turn guards; slow conversations no longer occupy another conversation's executor.
+- Bound webhook admission and sweep child RPC waits. Persist scan progress independently of failed child
+  deliveries, so retries retain unavailable targets while later pages and healthy conversations continue.
+- Reuse message pages only within one fresh phase, combine independent read-only preparation, and scope cached
+  decisions to actual redacted input and routing configuration/model. Preserve fresh side-effect checks and the
+  existing bounded history reads and 45-request budget; inbox-bot ownership is read fresh instead of cached.
+
+### Upgrade
+
+- This minor release changes deployment bindings. Export and declare SQLite `Router` and `Coordinator`, bound as
+  `ROUTER` and `COORDINATOR`, and keep the five-minute reconciliation trigger. Conversation Router identities are
+  now `<account>:<conversation>`; account for any existing global Router guards before enabling
+  new owners. Keep Worker identities, namespaces/storage and immutable configuration keys.
+- Deploy chatwoot-discord-relay 0.31.0 first, completing its separately authorized
+  [partition adoption](https://github.com/Phala-Network/chatwoot-workers/blob/main/packages/chatwoot-discord-relay/docs/adoption.md)
+  when upgrading an existing Hub. Verify the sole routing owner before connecting bots one account at a time;
+  health checks and webhook acknowledgements do not establish successful routing or channel delivery.
+- To stop routing, disconnect bots but retain credentials and keep this router running until pending/open account
+  passes and durable ending retries clear all brand-bot ownership. Verify resolved/snoozed endings too, preserving
+  human and other-bot owners. Only then stop ingress, cron, queued alarms and in-flight work.
+- Preserve permanent reply attempts, observed/deleted-reply records, unknown guards and turn boundaries. Empty
+  history cannot reconstruct lost guards or justify another send. The legacy relay's reply ledger is independent;
+  restoring old code/configuration does not transfer Router-only replies or unknown attempts. Once new effects
+  exist, use forward repair in the current namespaces; direct version rollback to relay 0.27 is not a safe handover
+  and Cloudflare rollback cannot cross Durable Object class/lifecycle changes.
+
 ## [0.2.0] - 2026-10-03
 
 ### Changed
@@ -46,6 +90,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   `routing_kind`.
 - The `chatwoot-router-store-config` command and `chatwoot-router/stored-config`, for a configuration in KV.
 
-[Unreleased]: https://github.com/Phala-Network/chatwoot-workers/compare/chatwoot-router@0.2.0...HEAD
+[Unreleased]: https://github.com/Phala-Network/chatwoot-workers/compare/chatwoot-router@0.3.0...HEAD
+[0.3.0]: https://github.com/Phala-Network/chatwoot-workers/compare/chatwoot-router@0.2.0...chatwoot-router@0.3.0
 [0.2.0]: https://github.com/Phala-Network/chatwoot-workers/compare/chatwoot-router@0.1.0...chatwoot-router@0.2.0
 [0.1.0]: https://github.com/Phala-Network/chatwoot-workers/releases/tag/chatwoot-router@0.1.0

package/README.md

@@ -15,18 +15,24 @@ may point to another deployment of that API, for example a proxy or gateway.
 - Each routed account has a configured brand bot. Routing is limited to inboxes linked to that exact account's
   bot, discovered through `GET inboxes/{id}/agent_bot`. The wrapped `agent_bot.id` and `account_id` must match;
   `agent_bot: null` or `agent_bot: {}` means unlinked. Foreign-account and system bots are rejected. The user token
-  must see every routed inbox. Disconnecting an inbox stops routing. The API does not expose whether the
+  must see every routed inbox. Disconnecting an inbox stops classification/replies and hands any pending ticket still assigned to this bot to people. The API does not expose whether the
   association is inactive; disconnect to disable it. `routing.botIds` and both bot credential maps require
   exactly the routed account keys (see [Configuration reference](#configuration-reference)).
+- Each account+conversation has its own SQLite `Router` Durable Object: its queue, memo, reply records and turn
+  guards have one writer. A slow conversation cannot occupy another conversation’s alarm. A separate `Coordinator`
+  Durable Object pages the account lists and durably enqueues each conversation in its own object.
 - Signed bot webhooks at `/chatwoot/agent-bot` enqueue a deduplicated conversation job. The five-minute sweep
-  lists **pending** conversations without an age cutoff. Inbox discovery and page cursors persist across alarms
-  within the request budget. Failed pages retry. An empty page ends a pass; the next starts at page 1 and catches
+  lists only **pending and open conversations in the account**, including disconnected inboxes, without an age
+  cutoff. Pending tickets route or hand off; open tickets still assigned to the brand bot release that assignment
+  with `POST assignments {assignee_id: null}`, preserving status after a fresh ownership read. Resolved/snoozed
+  history is not scanned. Each status has its own persistent page cursor within the request budget. Failed pages
+  retry. An empty page ends that status's pass; the next starts at page 1 and catches
   conversations skipped by changing pages. Neither event payloads nor sweep rows are decision inputs.
 - Read messages newest-first, unfiltered (including activities), with `before` paging, at most five pages of 20.
   The latest `conversation_status_changed` activity begins the turn; without one or evidence it is missing, use
   the conversation's start. Take the first three usable customer texts after the boundary, oldest first. Include
   email subjects and reply text without quoted history; omit automatic email, deleted messages and private notes.
-  Redact identifiers and contact names, then cap the input at 1,600 characters. Memoize Jev's decision by input ids.
+  Redact identifiers and contact names, then cap the input at 1,600 characters. Memoize Jev's decision by account, conversation, input ids, actual redacted input and routing configuration/model.
 - Status activity is asynchronous. The queue's boundary guard remembers an observed/expected transition and the
   last boundary needed to reject stale handoff work. An activity read before its first status webhook can match
   that webhook's status and time only if no existing expectation requires a newer activity. Merging a webhook
@@ -35,7 +41,7 @@ may point to another deployment of that API, for example a proxy or gateway.
   delivery of the same transition timestamp does not start another expectation. Only a status webhook supplies a transition time;
   a read observing pending end requires a newer activity without inferring a time from `updated_at`. The last
   pending observation survives retries, so a retry confirming resolution after a lost response retains that boundary.
-  Other non-pending snapshots exit: metadata updates change `updated_at` without creating a status activity.
+  Other non-pending snapshots only release a remaining brand-bot assignment: metadata updates change `updated_at` without creating a status activity.
   An expected activity not yet present retries normally; an incomplete read or a deleted known boundary hands off.
   Permanently missing activity uses the same three-attempt limit. A new boundary clears the previous turn's failure
   count and handoff. Chatwoot exposes no turn API: a lost webhook plus permanently removed, never-observed activity
@@ -45,23 +51,37 @@ may point to another deployment of that API, for example a proxy or gateway.
 - Jev chooses owner, topic, kind and whether there is a request. A confident kind takes precedence; otherwise a
   confident greeting/no-request stays pending while fewer than three texts exist. Empty or identifier-only input,
   three greetings, an unclear owner with an actual request, or a public human reply hands off. Blocked contacts
-  and person-assigned conversations are untouched. Bot and user assignees are distinguished by `assignee_type`.
+  and person-assigned conversations are untouched during routing; disconnect handoff also clears blocked bot leftovers.
+  Bot and user assignees are distinguished by `assignee_type`.
 - Before **each** action, re-read the inbox link, pending status, assignee, turn boundary, inputs and public human
   replies. A changed input defers the job to decide again. Apply topic/kind labels, then the kind's canned reply,
-  then exactly one ending action: the kind's resolved/snoozed status, a confident owner's assignment, or explicit
-  bot `status=open` handoff. Preserve human topic labels and validate that an owner still belongs to the account.
+  then end the turn: set the kind's resolved/snoozed status and immediately release the bot, assign a confident
+  owner, or use explicit bot `status=open` handoff. Chatwoot keeps the bot on resolve/snooze, so release is part of
+  that same ending, with a fresh ownership/status read. A failed release keeps the durable job for retry, even
+  though the sweep excludes closed history. Clearing only the bot creates no assignment/status activity and does
+  not move the turn boundary; Chatwoot still dispatches assignment/update events. Preserve human topic labels and
+  validate that an owner still belongs to the account.
   Successful person assignment ends the turn without a bot-handoff reporting event; nothing follows it.
   Reopened resolved conversations can lack a bot assignee, in which case assignment would not open
   pending: use native handoff instead. Chatwoot has no atomic compare-and-write API for a change racing a mutation.
 - Only canned replies have an action record, `reply:<account>:<conversation>`, kept across turns and upgrades.
-  Record it **before sending**: a failure or unknown outcome is never resent. Labels, assignment and status use
+  Before sending, read up to five unfiltered history pages (100 messages), past turn boundaries, for a public outgoing
+  message (`message_type=1`, `private=false`, `sender.type=agent_bot`) from this account's exact configured bot id.
+  A confirmed, non-deleted, non-failed reply counts as replied, including replies the old relay sent; preserve an
+  observed record so later removal cannot permit a resend. A complete read to the beginning with none permits the
+  first attempt; an incomplete/failed/ambiguous read or an existing attempt without a visible reply hands off.
+  Record the attempt **before sending**. A failed POST, lost response, malformed receipt or failed/deleted reply
+  persists handoff and never resolves/snoozes or resends. Only a valid creation receipt for this conversation or
+  confirmed history permits the kind's ending status. This confirms creation in Chatwoot, not channel delivery;
+  a delivery failure seen in the final fresh read also hands off. Labels, assignment and status use
   current Chatwoot state, without an effects ledger or custom coordination attributes. A missing canned response
   hands off immediately. After three processing failures (initial, +5s, +10s), persist handoff mode. Further retries
   only revalidate the turn and hand off, with backoff capped at 30 minutes. Handoff failures keep the job; deleted
-  conversations and disconnected inboxes end it. Credentials/service failures need repair before handoff can succeed.
+  conversations end it. Disconnected brand-bot pending tickets use native bot `status=open` handoff without Jev
+  or a turn-history read; failures retry until the handoff succeeds. Other bots and people are untouched. Credentials/service failures need repair before handoff can succeed.
 - A Worker 2xx means the job is durable, not that routing succeeded. Chatwoot's own webhook failure fallback cannot
   cover later alarm failures. Its fallback opens pending on failed `message_created`/`message_updated` delivery unless
-  `keep_pending_on_bot_failure` is enabled; it may leave a bot assignee on open. The relay shows that as unassigned.
+  `keep_pending_on_bot_failure` is enabled; it may leave a bot assignee on open. The router releases that assignment on its next job or sweep.
   Chatwoot makes three delivery attempts for 429/500 responses. Irrelevant valid bot events are acknowledged.
   There is no router account-webhook endpoint.
 
@@ -70,11 +90,17 @@ and are decided on their **new turn's** messages. Snoozed tickets reopen open an
 following a customer message counts as answering it in the relay, even if that message was outside Jev's window.
 
 The API contracts were checked against Chatwoot v4.18.0:
-[assignment](https://raw.githubusercontent.com/chatwoot/chatwoot/v4.18.0/app/services/conversations/assignment_service.rb),
+[assignment service](https://raw.githubusercontent.com/chatwoot/chatwoot/v4.18.0/app/services/conversations/assignment_service.rb)
+and [controller](https://raw.githubusercontent.com/chatwoot/chatwoot/v4.18.0/app/controllers/api/v1/accounts/conversations/assignments_controller.rb),
 [status changes](https://raw.githubusercontent.com/chatwoot/chatwoot/v4.18.0/app/controllers/api/v1/accounts/conversations_controller.rb),
 [activity creation](https://raw.githubusercontent.com/chatwoot/chatwoot/v4.18.0/app/models/concerns/activity_message_handler.rb)
 and its [job](https://raw.githubusercontent.com/chatwoot/chatwoot/v4.18.0/app/jobs/conversations/activity_message_job.rb),
 [message paging](https://raw.githubusercontent.com/chatwoot/chatwoot/v4.18.0/app/finders/message_finder.rb),
+[message creation](https://raw.githubusercontent.com/chatwoot/chatwoot/v4.18.0/app/builders/messages/message_builder.rb),
+[message JSON](https://raw.githubusercontent.com/chatwoot/chatwoot/v4.18.0/app/views/api/v1/models/_message.json.jbuilder),
+[bot sender](https://raw.githubusercontent.com/chatwoot/chatwoot/v4.18.0/app/models/agent_bot.rb),
+[account access](https://raw.githubusercontent.com/chatwoot/chatwoot/v4.18.0/app/controllers/concerns/ensure_current_account_helper.rb),
+[conversation access](https://raw.githubusercontent.com/chatwoot/chatwoot/v4.18.0/app/policies/conversation_policy.rb),
 [inbox bot response](https://raw.githubusercontent.com/chatwoot/chatwoot/v4.18.0/app/views/api/v1/accounts/inboxes/agent_bot.json.jbuilder),
 [assignees/timestamps](https://raw.githubusercontent.com/chatwoot/chatwoot/v4.18.0/app/presenters/conversations/event_data_presenter.rb),
 [token permissions](https://raw.githubusercontent.com/chatwoot/chatwoot/v4.18.0/app/controllers/concerns/access_token_auth_helper.rb),
@@ -97,7 +123,7 @@ npx cf deploy --prebuilt --dry-run
 Edit `cloudflare.config.ts` with your non-secret settings. Keep required secrets out of source control;
 `.dev.vars.example` lists placeholders. For local development copy it to `.dev.vars` and use `npm run dev`.
 A maintainer deploys with `npx cf deploy --secrets-file <private-file>`.
-The default Worker name is `chatwoot-router`; it exports one SQLite Durable Object, `Router`, bound as `ROUTER`.
+The default Worker name is `chatwoot-router`; it exports SQLite Durable Objects `Router` (bound as `ROUTER`) and `Coordinator` (bound as `COORDINATOR`).
 Keep the `*/5 * * * *` cron trigger for reconciliation. `GET /healthz` returns 200 for a valid, readable
 configuration and 503 otherwise; it does not test upstream credentials or connectivity.
 
@@ -105,12 +131,12 @@ For a private deployment repository, depend on the public `chatwoot-router` npm
 `@cloudflare/vite-plugin`. Its Worker entry is:
 
 ```ts
-export { default, Router } from "chatwoot-router";
+export { default, Router, Coordinator } from "chatwoot-router";
 ```
 
 Use the same `cloudflare.config.ts` and `vite.config.ts` structure as this package. Pin compatible tooling versions
-from the workspace and root manifests. Declare `Router` with `exports.durableObject({ storage: "sqlite" })`, bind it as
-`ROUTER`, declare required secrets with `bindings.secret()`, and put `CONFIG` in `bindings.json(...)`.
+from the workspace and root manifests. Declare `Router` and `Coordinator` with `exports.durableObject({ storage: "sqlite" })`, bind it as
+`ROUTER` and `COORDINATOR` respectively, declare required secrets with `bindings.secret()`, and put `CONFIG` in `bindings.json(...)`.
 
 For a configuration larger than a Worker JSON binding, use immutable KV configuration instead:
 
@@ -195,21 +221,45 @@ fail startup; `/healthz` returns 503 without credentials in its response. All se
 
 ## Upgrade and rollback
 
-1. Verify user-token inbox visibility and count existing pending tickets. Keep both existing Worker names,
-   Durable Object namespaces and reply records. Existing pending tickets will be routed; open tickets stay human-owned.
-2. Deploy the new relay first. Remove its `router.accounts` and `router.waitSeconds`; keep every kind name in
-   `router.keepLabels`. During the transition existing open tickets can go directly to triage.
-3. Stop the old router's account webhook and cron; replace it in place. Never run both routers. Remove
-   `startAfterConversationId`, `reconcile`, `routing.snoozeUnclear`, `CHATWOOT_WEBHOOK_SECRETS` and
-   `CHATWOOT_BOT_TOKENS` from its configuration. Add `routing.botIds` and the two new required bot secrets.
-   The one-time storage migration removes old jobs/checkpoints/non-reply effects and decision memos. Reply records
-   survive; the pending sweep reconstructs jobs. The Worker never deletes Chatwoot attributes.
-4. Connect the bots one account at a time after both Workers are ready. Keep existing `routing_*` attributes and
-   definitions until the owner's rollback window ends, then remove them manually.
-5. To roll back, **disconnect bots first**, stop the new router/cron, then restore old code, config and account
-   webhook if needed. Do not run old and new routing together. Choose old cutover ids deliberately; retained
-   reply records prevent resends, but lifecycle changes already made are not reversible automatically.
-   Relay sweeps wake held jobs after disconnect; people can open ordinary pending conversations.
+0.2.x was never deployed, so the conversation partition and coordinator require no state migration.
+
+Keep Worker names, Durable Object namespaces/storage and old KV configuration keys. The Router DO holds
+permanent reply attempts/observed records and turn guards as well as jobs and decisions. Message history cannot
+rebuild an unknown attempt, an observed reply since deleted, or a missing turn boundary. Do not delete or recreate
+any conversation’s Router DO during rollback. If its state is lost or restored to an older recovery point, keep bots disconnected
+and isolate conversations with uncertain attempts/turns for owner review; a currently empty history does not
+prove another send is safe. Existing pending conversations are reconciled; non-pending conversations stay with people. The user token must see all relevant inboxes.
+
+For the first move from the relay's built-in routing (production baseline 0.27.0):
+
+1. Record the live relay deployment/version id and CONFIG_KEY before rollout; retain its Hub and old secrets.
+   Disconnect all brand bots and prevent competing old deployments. Verify bot identities, owner membership,
+   labels, canned responses and inbox visibility. Historical confirmed brand-bot replies need no ledger migration.
+2. Deploy and verify relay 0.30 first. Remove `routing`, `router.accounts` and `router.waitSeconds`; keep every kind
+   in `router.keepLabels`. Verify the actual version and that built-in routing/in-flight old work stopped.
+3. Bootstrap this Worker by hand with all four secrets in a protected secrets file while bots remain disconnected.
+   Verify KV/domain, upstream permissions and test tickets; health/2xx alone do not prove routing success.
+   If using an infra PR whose push deploys both Workers independently, merge only after both hand deployments pass.
+4. Connect bots one account at a time and verify real routing, handoff, failed/unknown reply handling, historical
+   reply deduplication and Discord/triage behavior, including at least a complete sweep.
+5. To roll back, disconnect bots first and **keep this router running until no pending ticket remains assigned to
+   a disconnected brand bot and no non-pending ticket remains assigned to that bot**. Complete pending/open
+   account passes and let failed ending releases finish through their durable retries: pending uses native bot
+   handoff, open leftovers use explicit unassignment, and kind endings release resolved/snoozed tickets in the
+   same turn. Confirm cleared bot ownership across statuses; preserve human/other-bot owners. Then stop
+   webhook entry, cron and queued/in-flight router work; stopping cron alone does not cancel DO alarms. Preserve DO
+   namespace and storage, including reply and turn guards. Restore the recorded live 0.27 version **and its
+   CONFIG_KEY**, without overlapping old/new routing. Relay 0.27 uses its original Hub's
+   `kind-reply:<account>:<conversation>` records; the Router uses separate `reply:<account>:<conversation>`
+   records. Restoring code/config does not copy Router attempts into the Hub or reset either ledger. Only replies
+   already recorded by 0.27 retain its own reply-once protection; Router-only replies/unknown attempts can be
+   attempted again by 0.27. Keep both DOs and review/isolate those tickets before restoring old routing. Rollback
+   does not guarantee reply-once across this switch or undo sent messages or other mutations.
+
+Current router upgrades need no custom coordination attributes, compatibility effects or one-time lifecycle
+cleanup. Older unreadable job payloads are dropped; live snapshots and the account sweep reconstruct queued work, not durable reply/turn guards.
+If handoff credentials fail, repair them or let a real owner take the tickets; do not bulk-open with the integration
+user token, which can assign every ticket to that user. Keep old attributes through the owner's rollback window.
 
 Redaction is best effort, not anonymization: other personal information can still reach TypeSafe. Logs contain
 ids and outcomes, never message bodies or credentials. See [SECURITY.md](https://github.com/Phala-Network/chatwoot-workers/blob/main/SECURITY.md),

package/lib/packages/chatwoot-router/src/coordinator.d.ts

@@ -0,0 +1,10 @@
+import { DurableObject } from "cloudflare:workers";
+import type { Env } from "./env.ts";
+export declare const COORDINATOR_NAME = "global";
+/** Lists one page per alarm. Conversation state belongs exclusively to the conversation's Router. */
+export declare class Coordinator extends DurableObject<Env> {
+    private readonly store;
+    constructor(ctx: DurableObjectState, env: Env);
+    requestSweep(): Promise<void>;
+    alarm(): Promise<void>;
+}

package/lib/packages/chatwoot-router/src/env.d.ts

@@ -1,6 +1,8 @@
 import type { ConfigEnv } from "../../../shared/settings.ts";
+import type { Coordinator } from "./coordinator.ts";
 import type { Router } from "./router.ts";
 export interface Env extends ConfigEnv {
+    COORDINATOR: DurableObjectNamespace<Coordinator>;
     ROUTER: DurableObjectNamespace<Router>;
     CHATWOOT_TOKEN: string;
     CHATWOOT_AGENT_BOT_SECRETS: string;

package/lib/packages/chatwoot-router/src/index.d.ts

@@ -4,4 +4,5 @@ declare const _default: {
     scheduled(_controller: ScheduledController, env: Env, context: ExecutionContext<unknown>): Promise<void>;
 };
 export default _default;
+export { Coordinator } from "./coordinator.ts";
 export { Router } from "./router.ts";