chatwoot-router 0.3.0 → 0.5.0

package/CHANGELOG.md

@@ -7,6 +7,28 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.5.0] - 2026-10-05
+
+### Fixed
+
+- Route a resolved ticket that a customer message reopens. Chatwoot reopens it as pending in a bot inbox and keeps
+  its assignee, and the router left every pending ticket with a person assignee alone, so such a ticket stayed
+  pending: off people's open view and never handed back. Its turn is now routed with its owner kept: a kind with a
+  status still ends it (a thanks-only message can be resolved), and anything else, a greeting included, goes back
+  to the owner as open. Only another bot's pending tickets are left alone.
+
+## [0.4.0] - 2026-10-04
+
+### Changed
+
+- Route each conversation in a Durable Object of its own, named `<account>:<conversation>`; one sweeper object
+  pages the accounts and hands each conversation to its object. This replaces 0.3.0's `Coordinator` class and
+  bounded RPC machinery; a slow Jev or Chatwoot request still delays only its own conversation.
+
+### Upgrade
+
+- Declare only the `Router` Durable Object (remove `Coordinator`).
+
 ## [0.3.0] - 2026-10-03
 
 ### Fixed
@@ -90,7 +112,9 @@ 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.3.0...HEAD
+[Unreleased]: https://github.com/Phala-Network/chatwoot-workers/compare/chatwoot-router@0.5.0...HEAD
+[0.5.0]: https://github.com/Phala-Network/chatwoot-workers/compare/chatwoot-router@0.4.0...chatwoot-router@0.5.0
+[0.4.0]: https://github.com/Phala-Network/chatwoot-workers/compare/chatwoot-router@0.3.0...chatwoot-router@0.4.0
 [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

@@ -6,106 +6,26 @@ of [chatwoot-discord-relay](https://github.com/Phala-Network/chatwoot-workers/tr
 
 ## How it works
 
-Chatwoot owns the lifecycle: a conversation is the bot's while pending, and people's otherwise.
-
-System One is TypeSafe's class of decision models, and Jev is its first model. The router calls TypeSafe's
-System One API (`/v1/systemone`) with the model in `routing.model` (Jev by default). `routing.endpoint`
-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 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 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 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
-  never lowers or removes an expected boundary id. Once matched, a different transition requires an activity
-  **after that boundary id**, even when the old activity has the same status and second-level timestamp. Repeated
-  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 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
-  cannot be reconstructed. Chatwoot writes activity only for a changed status with activity content; no-op status
-  changes create none. Activities use job execution time, and customer/scheduled reopen usually creates none.
-  A late activity ordered after new text does not license reading old text across the boundary; empty input hands off.
-- 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 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 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.
-  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 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 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.
-
-After handoff, later customer messages belong to people. Resolved tickets reopen pending in an active bot inbox
-and are decided on their **new turn's** messages. Snoozed tickets reopen open and go to people. A canned reply
-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 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),
-[bot events](https://raw.githubusercontent.com/chatwoot/chatwoot/v4.18.0/app/listeners/agent_bot_listener.rb), and
-[webhook fallback](https://raw.githubusercontent.com/chatwoot/chatwoot/v4.18.0/lib/webhooks/trigger.rb).
+Chatwoot owns the lifecycle: a conversation is the bot's while it is pending, and people's otherwise. The router
+is each routed account's native agent bot, connected to the inboxes it should route.
+
+1. A new ticket in a connected inbox is pending, so Chatwoot sends its events to the router's
+   `/chatwoot/agent-bot` webhook. Each conversation is routed by a Durable Object of its own, so a slow request
+   for one conversation never delays another.
+2. The router reads the customer's first messages of this turn (redacted, at most three and 1,600 characters)
+   and asks TypeSafe's System One API (`/v1/systemone`, model `routing.model`, Jev by default; `routing.endpoint`
+   may point to another deployment) for the owner, topic, kind, and whether there is a request yet.
+3. It applies the topic and kind labels, sends the kind's canned reply if it has one (at most once per
+   conversation), and ends the turn: the kind's resolved or snoozed status, the confident owner, or a handoff to
+   people (`status=open`). A greeting with no request yet stays pending until the customer says more. A resolved
+   ticket that a customer message reopens keeps its owner: its kind may still end it (a thanks is resolved),
+   otherwise it goes back to the owner.
+4. Anything uncertain hands off to people: an unclear owner, a failed or unconfirmed reply, a human replying,
+   three failed attempts. Disconnecting an inbox's bot hands its pending tickets to people.
+5. A sweep every five minutes lists pending and open conversations, so a missed webhook is caught up and a bot
+   assignment left on an open ticket is released.
+
+[Routing behavior](https://github.com/Phala-Network/chatwoot-workers/blob/main/packages/chatwoot-router/docs/behavior.md) has the precise rules and the Chatwoot contracts they rest on.
 
 ## Deploy
 
@@ -123,7 +43,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 SQLite Durable Objects `Router` (bound as `ROUTER`) and `Coordinator` (bound as `COORDINATOR`).
+The default Worker name is `chatwoot-router`; it exports one SQLite Durable Object, `Router`, bound as `ROUTER`.
 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.
 
@@ -131,12 +51,12 @@ For a private deployment repository, depend on the public `chatwoot-router` npm
 `@cloudflare/vite-plugin`. Its Worker entry is:
 
 ```ts
-export { default, Router, Coordinator } from "chatwoot-router";
+export { default, Router } 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` 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(...)`.
+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(...)`.
 
 For a configuration larger than a Worker JSON binding, use immutable KV configuration instead:
 
@@ -221,12 +141,10 @@ fail startup; `/healthz` returns 503 without credentials in its response. All se
 
 ## Upgrade and rollback
 
-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
+the 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.
 

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

@@ -1,5 +1,4 @@
 import { z } from "zod";
-export { ConfigError } from "../../../shared/config.ts";
 export declare const configSchema: z.ZodObject<{
     chatwoot: z.ZodObject<{
         baseUrl: z.ZodURL;
@@ -39,3 +38,4 @@ export interface Settings {
 }
 export declare function parseSettings(rawConfig: unknown, rawSecrets: object): Settings;
 export declare function buildSettings(config: Config, secrets: Secrets): Settings;
+export {};

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

@@ -1,8 +1,6 @@
 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,5 +4,4 @@ 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";