docs(eve): research - event consumers plan

[ruiconti]

Research plan for #1170. Design only — no runtime changes, no new public API.

What this proposes

Normalize event consumption. Today the flow an event takes depends on who consumes it: followers (TUI, web clients, evals) read the durable session stream at their own pace, while channels and the remote-callback forwarder run inline in the producer's emit path, alive only while the producer's compute is awake.

The proposal inverts that split. The harness funnels every event a single way, and every consumer — channels included — consumes from a durable delivery step. An accepted delivery survives crashes and redelivers until consumed (queue retry, journaled side effects). The price is one extra hop per event; v1 is scoped so that hop replaces a wake the caller already pays.

"Notification" appears in the design only as wire vocabulary: the status: "notification" class on #1167's callback envelope, one of the event classes a lane can carry. The unit this plan normalizes is the event.

Why

The first events to need this — a child's authorization.* surfaced on the caller's stream (#1167) — show the inline weld failing concretely. Receipts pinned to #1167's head 413ce48d and main 0a8b63c5:

• The delivery hook rotates; producers hold a stale token. The engine buffers deliveries on hooks: resumeHook durably appends a hook_received event to the owning run's log and re-queues the run — no one needs to be awaiting the hook yet — and it throws only for a missing or disposed hook or a terminal run (@workflow/core@5.0.0-beta.36, dist/runtime/resume-hook.js). But a session exposes no long-lived hook. Its delivery hook is keyed by the current turn's continuation token: the callee's callback URL captures that token at dispatch (remote-agent-dispatch.ts:30), the entry workflow rekeys the hook to a fresh token every time a turn parks (workflow-entry.ts:251), and the retired hook is disposed immediately, so a delivery to its token gets HookNotFoundError (session-delivery-hook.ts:37). The route surfaces that as a 404 (session-callback-route.ts:67) and the callee logs and moves on. Why it matters: these events are how a person gets unblocked. Expected path: a remote child suspends on sign-in, the forwarded authorization.required becomes the sign-in prompt in the caller's channel, the person clicks, the child resumes. Divergence: the caller's turn also holds a pending approval — the feat(eve): propagate remote-callee authorization events to the caller #1167 hitl-collision shape — and that approval rekeyed the delivery hook, disposing the one whose token the child's callback URL still carries; the prompt 404s, and the only person who can unblock the child is never asked. Same failure on the way out: after the terminal callback resolves the call and the session rekeys for its next turn, the racing authorization.completed hits the disposed hook, and a card that did render stays frozen on "waiting". One curl verifies it: POST a well-formed notification to a retired callback token and read back {"error":"Session callback not pending."}.
• Nothing redelivers. Producers do emit from journaled steps, but a delivery failure never reaches the journal — deliberately, so an unreachable caller cannot fail the producing step: the remote POST failure is swallowed in the forwarder, and a throwing local forward is swallowed by callAdapterEventHandler. A producer-side retry couldn't fix it anyway: the POST is addressed to a retired token and rotation is one-way, so the address never becomes valid again — while the retry re-runs the step's other side effects. The child's own stream write is durable; the delivery isn't.
• Delivery is heavyweight. A rendering-only event — one whose entire effect is presentation, e.g. a child's authorization.required becoming the channel's sign-in prompt, never touching model history or session state — costs a queue wake of the parked turn workflow (turn-workflow.ts:297) plus a journaled step that re-reads the durable session and deserializes the full context to run one adapter handler and one stream write.
• The same forwarding is implemented twice. Local children forward through the subagent adapter's journaled hook step, remote callees through the callback POST plus route projection (self-described as "the callback-URL analog" of the former). Two transports, two implementations, divergent failure semantics (the local step rethrows, the remote swallows), converging only at the caller's inbox. Note: an earlier draft claimed channels render twice — the trace shows rendering converges on one proxy step; the duplication is producer-side forwarding.
• Channels are locked to the workflow. Adapter state rides the workflow step's serialized context, so nothing outside the session workflow can safely invoke a channel.

Comparison artifacts

• feat(eve): propagate remote-callee authorization events to the caller #1167 (reopened) — the baseline: child authorization events piped through today's continuation entry point, resumeHook into the session workflow's turn inbox. It works end to end and hits every failure above. To keep it a clean baseline for the delivery path alone, it sheds its eve/tools authorization API exposure.
• A prototype of this design — the per-session consumer run below, exercised against the same fixture evals.

v1 shape

Scoped by per-lane wake accounting so v1 adds zero new queue wakes:

• Caller side: one consumer run per session (workflow//eve//eventConsumer, same compiled bundle and deployment as the session's other runs), awaiting <sessionId>:events — a hook whose token is stable for the session's lifetime, so producers stop chasing the rotating turn token and the engine's own hook buffering applies — holding the stream writable. It replaces the queue wake the caller already pays today — but hydrates only channel context. Each delivery is one journaled write step (event-consumer-write-step): invoke the channel's existing adapter event handler (channels change nothing) and append the wrapped subagent.event for followers. Adapter state persists in the consumer's own run state, which buys Slack edit-in-place on authorization.completed.
• Callee side: no consumer run. Forwarding keeps its direct POST — the only lane where a consumer would add a new wake — just deferred off the emitting step's critical path.
• Frequency admission rule: higher-frequency event types (working, proxied HITL) enter only with cursor-based coalescing.

Why this shape

Three drafts died on the way: route-side streams.write-by-id + per-consumer enqueue (replaced by resumeHook against a companion run — the hook queue already provides ordering, at-least-once, exactly-once side effects, duplicate-run safety); consumers on both sides (wake accounting moved the callee's behind the admission rule); a new channel notification member (unnecessary — adapters already implement the handler these events arrive through).

Relation to #1167: the consumer replaces its caller-side resumeHook-into-the-session-workflow arm; the callee-side forwarding gets deferred; the wire envelope and termination lane stay.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
eve-docs	Ready	Preview, Comment, Open in v0	Jul 24, 2026 10:48pm
eve-docs-1644	Ready	Preview, Comment, Open in v0	Jul 24, 2026 10:48pm
eve-docs-4759	Ready	Preview, Comment, Open in v0	Jul 24, 2026 10:48pm