feat: multiparty / per-participant read receipts for messages

[RonPalmeri]

Summary

Add first-class, per-participant read/consumption receipts so it is verifiably known which
participants (humans and agents) in a channel/DM have received — and, distinctly, have
processed — a specific message.

Problem

There is currently no attributable, auditable way to know whether a given participant has
consumed a message. For human+agent teams this is the core coordination primitive:

• A sender cannot distinguish "delivered," "seen," and "acted on" — so coordination degrades
  to re-pinging or to agents polling for changes, which is wasteful at scale.
• There is no way to know an agent has actually ingested context before depending on it.
• Accountability in multi-party threads is asserted, not verifiable.

Desired Behavior

• Two receipt classes, both first-class:
  1. Rendered — a participant's client displayed the message (the human semantic).
  2. Processed — the participant attests it has consumed the message (read into context /
     acted upon). For agents this is published by the agent or its harness at processing time,
     with no dependency on any UI or "active view" — headless and API-driven consumers are the
     primary case, not an edge case.
• Receipts are signed events attributable to the participant (or its delegated key), and
  append-only: a receipt is never deleted or mutated; corrections are superseding events.
• UI can render "Read by: Alice, Bob, Agent-X" / "Processed by 3/5" with an expandable list.
• Works in channels and DMs.
• Enables sender-side policy: because read-state is queryable, senders can implement
  escalation ("unprocessed after T → re-notify / escalate") and gating ("proceed only after
  X has processed Y") — replacing both blind re-pings and consumer-side polling loops.
• Privacy controls: participants can disable emitting receipts per-scope (channel/DM), with
  the trade-off visible to counterparties (a participant with receipts off reads as
  "unknown," never as "read").

Open Questions

• Event kind: new NIP vs. extension of existing kinds; one kind with a state tag
  (rendered|processed) vs. two kinds?
• Visibility: receipts public to the channel vs. visible only to the message author
  (+ admins)? Per-scope configurability?
• Idempotency/dedup expectations for relays when the same receipt is republished.
• Retention/expiry — and whether expiry is compatible with auditability requirements.

Motivation

Teams of humans + agents live or die on knowing what has actually been consumed. Today that
knowledge is either faked (assumed from delivery) or bought expensively (polling). Making
consumption a signed, append-only protocol citizen turns coordination from assertion into
verification — and makes multiplayer agent collaboration on Buzz practical at team scale.

[RonPalmeri]

Following up on my own open questions with a concrete design, after a close read of the codebase — and an offer at the end.

Proposed design

Two new kinds in a plain, non-replaceable range (registered in crates/buzz-core/src/kind.rs):

• KIND_MESSAGE_RECEIPT_RENDERED — a participant's client displayed the message
• KIND_MESSAGE_RECEIPT_PROCESSED — the participant (human or agent) attests the message entered its working context / was acted on

Two kinds rather than one-kind-with-a-state-tag, following CONTRIBUTING's own principle that "event kinds are the only switch" — it keeps REQ filtering kind-level (an agent gating on processed subscribes to one kind, no tag-filter dependency) and gives each class its own auth arm in required_scope_for_kind(). Happy to collapse to a single kind + state tag if maintainers prefer registry economy. Range note: this must not land in 10100–19999 (replaceable, collapses per (pubkey, kind)) or the 30000s (parameterized-replaceable) — a receipt is an append-only per-target fact. Same constraint #3091 independently identified; the right family is the plain range that kind:7 reactions live in.

Event shape: e tag = target message id · h tag = group id (NIP-29 convention) · signed by the participant's key (or its delegated agent key) · created_at = receipt time · empty content (structured JSON reserved for a future reason).

Idempotency / dedup: exactly the shipped reaction pattern — crates/buzz-db/src/reaction.rs already implements per-user-per-target dedup via ON CONFLICT (community_id, event_created_at, event_id, pubkey, emoji) DO UPDATE with soft-delete. A receipts table keys on (community_id, target_event_id, pubkey, receipt_kind) the same way: republish is a no-op upsert, corrections supersede, nothing is destroyed. The ReactionGroup { count, users } shape is a near-exact template for ReceiptGroup ("Processed by 3/5", expandable).

Visibility: receipts are plain group events visible to channel participants — the same visibility class as reactions, which is what makes them sender-queryable at all. This is deliberately complementary to, not overlapping with, KIND_READ_STATE (30078): that object is self-encrypted, per-user, replaceable — "my unread badges, synced across my devices," invisible to counterparties by design. Receipts are the multiparty half it intentionally doesn't cover. Both coexist; neither replaces the other.

Privacy: per-scope emission opt-out lives client-side (a participant with receipts off reads as unknown, never as read). Fine to defer the settings surface to a later PR — see sequencing.

Retention: receipts follow their channel's retention; no special expiry. Auditability wins, and grouped rollups keep query cost flat.

Agent emission ("processed"): published from the agent harness at turn time — the natural hook is buzz-acp's turn lifecycle, adjacent to where KIND_AGENT_TURN_METRIC already publishes — with a crisp attestation semantic: the message content entered the agent's working context this turn. No dependency on any UI or "active view"; a headless emitter is just another authenticated WS EVENT. Sender-side escalation/gating ("unprocessed after T → escalate") then needs no relay policy engine — it's client policy over a standard REQ.

Offer

We're prepared to implement this and contribute it, sliced per CONTRIBUTING's focused-PR guidance:

1. PR 1: kinds + relay ingest/scope + DB dedup + test-client coverage — processed only, WS-queryable. (S–M)
2. PR 2: sender-side query surface + desktop "Processed by N/M" UI on the MessageReactions pattern. (M)
3. PR 3: rendered class + mobile parity + per-scope opt-out settings. (M–L)

DCO-signed, conventional commits, just ci green, screenshots on the UI PRs. If maintainers have a preferred kind split, range, or want this built internally instead — say the word and we'll align. We're building human+agent teams on Buzz and this is the coordination primitive we keep reaching for.

[samiriasbeck]

There is a related but distinct receipt class needed by agent workflows: turn lifecycle receipts. I would avoid overloading rendered / processed with queue and execution state.

processed can remain the participant attestation proposed here (“this source event entered my working context”). Separately, a workflow/job run needs a correlated state machine such as:

received -> queued -> dispatched -> running -> responded | failed | timed_out | policy_denied

Those states are operational facts produced by the relay/harness, not claims that a human read content. They should reference the source event and carry only identifiers, timestamps/durations, attempt number and a bounded error code.

Suggested correlation fields:

• source e tag;
• channel h tag;
• target agent p tag;
• run, step, attempt, and optional cycle tags;
• state and reason_code;
• monotonic stage durations where available.

Invariants that matter for multi-agent orchestration:

• states are monotonic per attempt;
• retries create a new attempt but preserve the same run/step identity;
• reconnect replay is idempotent and cannot emit two terminal receipts for one attempt;
• responded means the reply/result was durably accepted, not merely generated in an ACP session;
• receipt visibility never exceeds the source channel's ACL;
• payloads contain no message body, prompt, model output, credentials or tool arguments.

This separation lets sender policy use both signals correctly: “the harness queued it” is not “the agent processed it,” and “the model generated output” is not “the result reached the channel.” It also composes with the latency work in #2408 and the missing-response correlation work in #5472 without changing the human read-receipt semantics proposed here.

[projectgreenlit]

Concrete repro from the Buzz relay:

• buzz --format compact dms list returned [] for the account that received the DM.
• The underlying DM channel still exists, and buzz --format compact messages get --channel <dm-channel> shows the messages.
• So the inbox/seen-state layer is not surfacing the DM even though the messages are present.

This matches the report that sending the same DM twice still did not produce any seen/read notification.

[RonPalmeri]

Agreed on the separation. Overloading processed with execution state would make the sender-side policy in the original issue unusable: "unprocessed after T → escalate" has to fire on a participant's claim about context, while "proceed only after X responded" has to gate on an operational fact about a run. Those want different signals, and one field can't carry both.

It also has an obvious home. The design comment above puts agent processed emission at the buzz-acp turn lifecycle, adjacent to where KIND_AGENT_TURN_METRIC already publishes — the same hook a lifecycle receipt would hang off. So this composes with the existing agent surface rather than needing a new one.

Four things I'd add:

1. The state machine has no liveness rule — which reintroduces the failure this issue exists to fix
   The invariant "reconnect replay is idempotent and cannot emit two terminal receipts for one attempt" guards duplicates. It doesn't guard the dual case: zero terminal receipts. If a harness dies between running and any terminal state, no terminal receipt is ever emitted, and a sender gating on "proceed only after X responded" waits forever — the silent-consumption problem this issue targets, moved up one layer.

A heartbeat state doesn't fix it: a process cannot emit a heartbeat announcing its own death. The only mechanism that survives the failure it's meant to detect is one declared before the failure. So:

the first non-terminal receipt for an attempt must carry a deadline (or max_duration) tag; past that deadline with no terminal receipt, any observer may locally treat the attempt as timed out with no new event, no relay-side timer. That keeps the relay dumb, costs one tag, and makes "this run went silent" a derivable fact rather than an unobservable one. Without it every consumer invents its own timeout heuristic, and they will not agree with each other.

2. There's no terminal state for cancellation or supersession responded | failed | timed_out | policy_denied has no slot for the most common non-error ending in agent orchestration: the work was obsoleted before it finished. A newer message supersedes the one that triggered the run; the revision the run was bound to moves; an operator cancels.

Encoded as failed, two things break: error-rate metrics stop meaning anything, and escalation misfires, since a superseded run should usually trigger nothing while a genuine failure should. I'd add superseded and cancelled as distinct terminal states, with superseded able to reference the event that obsoleted it. That also gives a clean chain when a rapid burst of messages collapses into one run.

3. The organizing axis is who attests, not what kind of fact it is. The framing above splits operational facts from claims about human reading. I'd argue the sharper invariant is the attestor:

processed is self-attestation with a participant asserting something about its own state. Lifecycle states are third-party attestation with a harness reporting on a run it observed. They carry different trust weight. A self-attested "I processed this" is a claim by the party with the strongest incentive to make it, and it is unfalsifiable from outside; a harness-emitted responded is checkable against a durable artifact. Three concrete consequences:

it maps onto the kind split and onto separate arms in required_scope_for_kind(), since the two classes are signed by different keys (participant vs harness/delegated); it resolves an ambiguity the state list leaves open, when does an agent emit processed versus running? They're different attestors about different things, and an agent may legitimately emit both; it lets sender policy express what it actually wants: for consequential gates, require the harness-attested responded; don't accept the self-attested processed.

4. run is a correlation channel across ACLs. "Receipt visibility never exceeds the source channel's ACL" is right but constrains the wrong thing. If a run in channel A fans out to work observable in channel B, the shared run identifier is a join key spanning both, so anyone with visibility into both streams can correlate activity they were never granted as a unit, without either ACL being violated.

The fix is the usual one: make the externally-visible run identifier channel-scoped and opaque, e.g. derived per (run, channel), so a harness keeps its internal run identity while no observer can join two channels' receipt streams. attempt and step are fine as-is; only the identity that crosses a boundary needs scoping.

Two smaller ones:

reason_code needs a registry, not just "bounded." Left to each harness it becomes free text with extra steps, and it's the field policy most wants to branch on. A small fixed set plus a namespaced escape hatch would hold.
"monotonic stage durations where available" creates optional fields policy may come to depend on. Worth stating whether durations are policy-bearing or diagnostic; if the former, they can't be optional.

Sequencing
I'd keep this out of the receipts PRs rather than widening them — the human read-receipt semantics in the original issue don't change, and the two classes can ship independently. If maintainers want the lifecycle class specified alongside rather than after, happy to fold a written spec into this thread. The implementation offer above stands either way, and I'd defer to whatever slicing maintainers prefer.

Also, policy_denied is a good state to have named this early. It pairs with the liveness point above, since a denial still has to reach the sender as a terminal fact, or the sender waits indefinitely on something that was never going to run.

@projectgreenlit — on the repro above, I think there are two separate things in it worth untangling, because they have different fixes and only one of them belongs on this issue.

The empty dms list is a real defect. A DM channel that exists, whose messages are retrievable via messages get -- channel, but which the inbox layer doesn't surface, is a bug in that layer regardless of anything proposed here. It would be better tracked as its own issue, since a feature thread that accumulates bug repros tends to get re-triaged as the bug, and the feature deferred as "addressed."

The missing seen/read notification is not a defect. Per the design comment above, KIND_READ_STATE (30078) is self-encrypted, per-user, and replaceable: it is invisible to counterparties by design. It answers "which of my devices has seen what," never "has the other party seen it." So sending the same DM twice producing no seen/read signal for the sender isn't the inbox layer failing, since there is no mechanism in Buzz today that was ever going to produce that signal.

That gap is exactly what this issue proposes to fill, and I think the repro is a useful data point for it: the expectation that a sender should be able to learn "this was seen / this was consumed" is evidently natural enough that a user hit it and read its absence as a bug.

Fixing dms list will make the inbox correct; it still won't tell a sender whether anyone read anything.

Thanks for taking the time to review this and respond.