Serialize concurrent deliveries to one continuation token

[ruiconti]

What problem are you trying to solve?

eve does not serialize concurrent deliveries that target the same continuation token. The token is both the session resume address and an exclusive workflow hook. If two invocations race before either session is established, each tries to claim the same hook and one can fail with HookConflictError.

GitHub webhooks make this easy to hit. Creating a pull request with a label can deliver opened and labeled close together. If an application opts into both actions, the GitHub channel starts both dispatches independently with waitUntil. Both derive the same per-PR continuation token, then call send. The losing delivery is logged by sendGitHubTurn, while hook ownership rejects the conflicting run (source).

This race happens before there is a shared session. defineState cannot coordinate it because its state is scoped to one existing session. The current documentation therefore tells every channel or application to build an external per-session queue (docs).

Proposed solution

Provide framework-owned admission control for deliveries sharing a continuation token. The default policy should preserve accepted work rather than throwing or silently dropping it. A durable queue is the clearest contract, though an explicit configurable coalescing policy could also work for channels that want it.

Required behavior:

• Two verified deliveries for the same continuation token can arrive concurrently before the session exists without producing HookConflictError for normal admission contention.
• The framework creates or resumes one session and handles accepted deliveries in a documented order.
• Coordination works across processes, regions, cold starts, and retries. An in-memory mutex is insufficient.
• A crash after admission does not lose the delivery, and retrying the same delivery does not execute it twice when the caller supplies a stable delivery id or idempotency key.
• The caller receives or can observe the disposition of every delivery: started, queued, coalesced, deduplicated, or rejected. Nothing disappears behind a swallowed log.
• Different continuation tokens remain independently concurrent.
• Authentication, channel state, message context, and attachment metadata stay attached to the correct queued delivery.
• Admission contention does not become session.failed and does not post an unrecoverable error to the user.
• Tests race two GitHub webhook deliveries for one PR from a cold state and prove deterministic completion. Add a separate test showing two PRs still run concurrently.

Alternatives considered

• Use defineState as a lock. There is no session-scoped state to share during the creation race.
• Require every application to provision Redis or another external queue. That can work, but it duplicates continuation-token ownership rules and retry semantics outside eve.
• Catch and ignore HookConflictError. This avoids a crash by losing a valid delivery.

Related: #170 reported the same error class, but the author closed it after finding that their immediate reproduction came from a custom Telegram handler. The distributed creation race remains untracked.

[Lukavyi]

Another channel hits this, with a user-facing failure rather than a dropped webhook: Telegram forum topics.

Repro (eve 0.22.3, Vercel Workflow world, built-in telegramChannel()):

1. Create a new Telegram topic (or otherwise start a fresh session).
2. Send two or three messages in a row, before the agent has produced its first reply.
3. The racing deliveries fail for the same continuation token, and the user gets:

This session could not recover from an error
(HookConflictError: Hook token "telegram:<chatId>:<threadId>:" is already in use (run "wrun_01KXGRBMKYY268TRRA39PY41YS")).
Start a new message to continue.
Error id: e1b4fe57-36bf-40a9-80c8-1914c891be4a

Same shape as the GitHub opened + labeled case in the issue body — two deliveries derive the same token before either session is established — but on Telegram it is trivially reachable by a human just typing fast.

To be precise about the blast radius, since the wording of the error oversells it: the session does not actually die. The first messages fail with the HookConflictError above, and a later message (typically the third or fourth) is processed normally, after which the session keeps working. So the real damage is:

• the losing deliveries are lost — the user's first messages never reach the agent, with no indication of which ones landed;
• the user is told the session "could not recover" and to "start a new message to continue", which is false and pushes people into abandoning a topic that was fine.

So on top of serializing the deliveries, the session.failed copy for this error is misleading — a hook conflict on start is a retryable collision, not an unrecoverable session.

Two more notes for whoever picks this up:

• The initial-delivery race is only half of it. Deliveries that arrive after the session exists don't fail, but they are deferred to the next turn and can then be resolved against an input request raised in the meantime (see Steering: a message sent mid-turn is deferred to the next turn — and can be consumed as the answer to a prompt raised after it was sent #786) — so a serialization fix scoped to session start still leaves the "second message answers a question it never saw" path open.
• We filed a Telegram-flavored version of this earlier as Concurrent deliveries to one Telegram session crash the run with HookConflictError → session.failed #170 and closed it as our own bug (a custom onMessage that dispatched forum_topic_created service messages). That was a real bug on our side, but the underlying race here is separate and still reproduces with the built-in dispatch gate.

Does #644 cover the Telegram initial-delivery path, or is it scoped to the GitHub webhook dispatcher?