Durable message work belongs around agent-server

1The decision

Agent-server remains the source of truth for conversations: durable events, execution, state and event streaming. The coordinator remains the source of truth for external work: whether a platform message has been integrated and whether an agent event has been delivered.

Edge availability: Cloudflare Queue is a spool, not the coordinator

1. The Worker authenticates the platform request and writes one envelope with a stable platform source identity.
2. The local pull adapter computes the canonical lane and calls resolveLane plus acceptIntake.
3. Only after the SQLite intake transaction commits does the adapter acknowledge the Cloudflare message. If acknowledgment is lost, redelivery hits the coordinator’s unique source key and returns the existing work row.
4. The coordinator—not Cloudflare Queue—owns lane order, claims, retries after local acceptance, projection, delivery outcomes and audit history.

This is intentionally two durable layers with different facts: Cloudflare Queue records that an edge message has not yet reached the host; the SQLite coordinator records that accepted external work has or has not been integrated and delivered. Neither store impersonates the other.

2One fact, one owner

The deletion test is useful here: deleting the coordinator would force deduplication, claims, retries, crash recovery and ordering back into every adapter. That is enough complexity behind one small interface to earn a module.

3Compare the three real systems

What the Hermes lessons mean here

4Two work kinds, one durable mechanism

A single agent execution can consume several incoming messages and produce several deliverable events. One end-to-end row would force unrelated failure domains together, so the store has two work kinds behind the same claim/retry mechanism.

Canonical record

Adapter-computed lane key

Borrow Hermes’s deterministic session-key idea, but let each channel adapter compute the canonical key because it owns that platform’s chat, thread and alias semantics:

channel:{platform}:{account}:{chat}:{thread-or-root}

WhatsApp → channel:whatsapp:smolpaws:120363426327189600@g.us:root
Slack    → channel:slack:T06P212QSEA:C06P5NCGSFP:1783869407.798

DMs isolate by stable chat identity; a Slack or Discord thread gets its own lane. Platform aliases—especially WhatsApp JID/LID forms—are canonicalized by the adapter before it returns the key.

Persisted lane directory

The coordinator resolves the adapter’s key to an agent-server conversation and saves the correspondence even though the key is deterministic. That row is both routing state and debugging evidence:

lane_key         TEXT PRIMARY KEY
conversation_id  TEXT NOT NULL
platform         TEXT NOT NULL
account_id       TEXT
chat_id          TEXT NOT NULL
thread_id        TEXT
display_name     TEXT
created_at       TEXT NOT NULL
last_seen_at     TEXT NOT NULL

Repeated resolution of the same lane returns the same conversation_id. Operators can query either side to explain which platform chat created a conversation, why messages split, or whether alias normalization produced an unexpected lane; no version field is introduced yet.

Small coordinator interface

adapter.computeLane(input)        → lane descriptor
resolveLane(lane)                 → lane binding + conversation_id
acceptIntake(binding, input)      → existing-or-new work
projectDeliveries(conversation)   → number created
claimReady(worker, now)           → claimed work | null
settle(claim, outcome)            → done | retry_wait | delivery_unknown | failed
reconcile(now)                    → expired/reconciled count

The storage adapter hides the lane directory, SQLite transactions, lane-head selection, backoff and stale-claim fencing. Channel adapters compute canonical lane identity, normalize input, deliver output and optionally reconcile external effects; they do not persist the mapping themselves.

5Worked trace: two messages arrive during execution

6Crash matrix

7ADR: considered options

Consequences

• The coordinator is a new local module and process responsibility, but not a new network service requirement; it can run in the SmolPaws host process initially.
• Every adapter migrates to the same accept/claim/settle interface. Platform code stops polling agent execution directly.
• SQLite is the first storage adapter. PostgreSQL may implement the same interface later with FOR UPDATE SKIP LOCKED, matching Automation’s multi-worker shape.
• The current agent-server needs one narrow compatibility extension for deterministic message append. Without it, intake remains vulnerable to the append-response-loss window.
• Delivery uncertainty becomes explicit product state. This is less comforting than “exactly once,” and more truthful.

8One required agent-server contract delta

The current message request contains role, content and run; agent-server creates a fresh event identity internally and returns only success. A coordinator that crashes after a successful append cannot safely distinguish “append happened” from “append never happened.”

POST /api/conversations/{id}/events
{
  "event_id": "uuid-v5(platform + source_message_id)",
  "role": "user",
  "content": [...],
  "run": true
}
→ { "success": true, "event_id": "...", "created": false }

This is a compatible reliability extension at the existing event seam. It does not add external work states, claims, delivery acknowledgments or platform concepts to agent-server.

9Implementation order

1. Specify the store through tests. Concurrent lane resolution, persisted lane-to-conversation lookup, duplicate accept, per-lane order, claim fencing, expiry, backoff, projector replay and delivery_unknown outcomes all get deterministic SQLite tests.
2. Add idempotent event append to agent-server. Prove append-response loss by retrying the same event identity across restart.
3. Implement intake only. Run a shadow path that accepts and appends one non-critical channel while current delivery remains unchanged.
4. Add event projection and delivery work. Start with terminal agent responses and a recording adapter; prove projector crash cases before real sends.
5. Canary WhatsApp. It exercises media, aliases, restart recovery and the most visible duplicate/loss cases. Preserve a rollback switch.
6. Migrate Discord, Slack, GitHub and email. They become platform adapters around the same coordinator interface rather than new orchestration implementations.
7. Remove superseded orchestration paths. Only after a soak period shows no unresolved delivery_unknown states, ordering violations or duplicate intake.

No estimates are attached. Each step stops on an executable invariant, not on elapsed time.

10Source map and validation