feat(whatsapp): durably observe approved group history

[NehoraiHadad]

Summary

• Durably persist unmentioned messages from explicitly approved, mention-gated WhatsApp groups without dispatching the agent.
• Give addressed turns one bounded, context-only window of the latest 50 observed messages.
• Key WhatsApp text debounce by the raw chat and sender so simultaneous messages from different group members can never merge.
• Route ambient and addressed non-command messages to one shared group session while retaining the real sender for slash-command authorization.
• Preserve the original WhatsApp timestamp, message id, sender/chat provenance, and structured display metadata.

Problem

With require_mention: true, WhatsApp drops ambient group messages before a MessageEvent reaches the session store. The next addressed turn therefore has neither durable searchable history nor the nearby conversation that made a follow-up meaningful.

The initial implementation also exposed three edge cases:

1. shared group routing made the debounce key identical for every sender, so concurrent addressed messages could coalesce;
2. observed=True rows were withheld from ordinary user replay only when an adapter prompt marker was present;
3. durable observed history and the RAM backfill could inject the same ambient messages twice.

Behavior

Both observation and legacy RAM backfill remain opt-in:

whatsapp:
  require_mention: true
  group_policy: allowlist
  group_allow_from:
    - 120363001234567890@g.us
  observe_unmentioned_group_messages: true
  observe_allowed_chats:
    - 120363001234567890@g.us
  history_backfill: true
  history_backfill_limit: 50

For an approved ambient message, the adapter:

1. verifies that it was rejected only by the mention gate;
2. writes one observed=True user row to the existing SessionStore / state.db;
3. deduplicates by platform message id;
4. stops before agent dispatch, typing, read receipt, or outbound delivery.

The gateway removes observed rows from replay regardless of adapter prompt markers. Only an observer-marked addressed group turn may render them, and it receives at most the latest 50 as a separate context-only block. Markerless cron, send_message, and non-adapter dispatches receive no observed chatter. When durable observation is active for that chat, the duplicate RAM channel_context is suppressed. When durable observation is inactive, the existing RAM backfill behavior is preserved.

WhatsApp text batching uses raw (profile, chatId, senderId) identity, while the eventual agent session remains shared at the group level. Commands deliberately retain their sender-scoped source and original text so existing slash authorization remains fail-closed.

Scope and privacy

• Observation never inherits an unrestricted group_policy: open.
• observe_allowed_chats must resolve to an explicit non-empty group allowlist; it can narrow group_allow_from.
• Disallowed groups and broadcasts are neither buffered nor persisted.
• A persistence failure logs and drops the observation; it never turns ambient chatter into an agent request.
• No new database, worker, or inference path is introduced.

Tests

• allowed ambient message: one durable observed row, zero dispatch;
• disallowed group: zero buffer and zero persistence;
• addressed turn: shared session and one non-duplicated durable context block;
• without a prompt marker, observed rows are neither replayed nor rendered;
• observed replay is bounded to the latest 50 messages;
• simultaneous addressed messages from different senders use separate debounce slots;
• RAM backfill remains available when durable observation is inactive;
• slash command sender identity remains intact;
• duplicate platform message id: one row;
• original timestamp, display metadata, FTS visibility, and restart persistence;
• YAML-to-platform configuration bridging;
• existing WhatsApp, Telegram, replay, timestamp, and auto-continue regressions.

Validation on current main:

174 passed, 2 skipped
ruff: clean
git diff --check: clean

This supersedes the PR's original backfill-only implementation while preserving its immediate 50-message context goal exactly once.

[NehoraiHadad]

Live deployment datapoint. We ran this branch (merged together with the botIds device-suffix fix) against a real WhatsApp group: Baileys linked-device session, WHATSAPP_MODE=bot, require_mention: true with a custom wake pattern, history_backfill: true, history_backfill_limit: 50.

Observed over a multi-activation session:

• Unmentioned group chatter produced no responses and no agent invocations (mention gating intact).
• The next gated activation arrived with the [Recent group messages] block carrying the interim chatter, and the model correctly answered a question whose answer existed only in that unmentioned chatter — the injection does real work end-to-end, not just prompt decoration.
• The very first activation after connect already carried backfill of a message sent before the wake word.
• No duplicate injection or ordering issues across the session; prompt-cache hit rates stayed high (79–95%) with the injected block present.

Happy to share redacted logs if useful.

[Enough1122]

AI code review — automated review for reference, author can ignore or act on any point.

feat(whatsapp): durably observe approved group history

Well-structured feature with thorough tests: per-(chat, sender) watermarks, ring-buffer bound, per-chat isolation, and prompt-injection care (neutralized names, [unverified] tags, preamble) are all covered.

1. gateway/platforms/whatsapp_common.py:528 — only sender names are neutralized; message bodies are injected verbatim into channel_context. A multi-line body (WhatsApp messages can contain newlines) is only defended by the [unverified] preamble for unauthorized senders; a verified/allowlisted sender's body is treated as trusted and its markdown/newlines can blur the [Recent group messages] block boundary. Consider collapsing body newlines (like the name handling) or otherwise bounding each line so the block stays a flat list of [name] text lines.
2. The feature is wired only into the native bridge adapter's _build_message_event (plugins/platforms/whatsapp/adapter.py:1474); the Cloud API adapter shares WhatsAppBehaviorMixin but never calls _maybe_record_group_history, so history_backfill silently does nothing there. Either wire it or document the limitation.
3. Minor: the title says "durably observe" but the buffer is explicitly in-memory and reset on restart (documented in the docs). Also, _build_group_channel_context advances the watermark before the event is fully built — if _build_message_event fails after context construction (e.g., image download error), that sender's buffered context is consumed and lost for the current batch. Consider advancing the watermark only once the event is actually delivered.
4. The _enqueue_text_event merge copies channel_context only when existing lacks one; in the rare case both events carry context, the later one is dropped. Given the watermark advances per build, a follow-up merge could double-inject — acceptable, but the interaction is subtle enough to warrant a comment.

[NehoraiHadad]

Full live E2E validation (2026-08-16). Ran this branch (as community-engine-v0.2.2: this PR + the LID authz work) on a production-shaped single-home deployment: real Baileys linked-device session, gateway.multiplex_profiles: true with the observed group routed to its own profile, require_mention: true + custom wake pattern, observe_unmentioned_group_messages: true, observe_allowed_chats pinned to exactly one group.

Verified end-to-end on a live group:

• Unmentioned message → zero outbound, durably recorded under the routed profile (shared-transcript source, NO_REPLY marker, sender attribution preserved in-content).
• Wake-word message → normal routed turn and reply.
• A later "what was written here?" turn retrieved the silently observed message with full provenance (group id/name, sender id/name) — the observe → store → retrieve chain closes.
• A group deliberately left OFF every allowlist received real traffic (fresh sender-keys on disk) and produced zero sessions and zero stored rows.

Two deployment findings from the same session, filed separately since they're pre-existing and not caused by this PR: #87830 (routed-turn authorization never consults whatsapp.group_allow_from from config — env var only, silent drop) and #87833 (restart can orphan the bridge and silently kill inbound delivery).

On the review points above: (1) agreed — collapsing body newlines like the name handling is cheap hardening, will fold into this branch; (2) correct, native-bridge only for now — will state that explicitly in the docs section; (3) fair point on the watermark advancing before the event is fully built, and on "durably" — the durable half is the store, the backfill window is in-memory as documented; (4) will add the comment on the merge interaction.

[NehoraiHadad]

Review follow-ups pushed (d691f3b, 74bf411, 09a80c8).

1. Body newlines (d691f3b) — message bodies now go through the same neutralize_untrusted_inline_text the sender names already used, with max_chars=0 so the body is not truncated (the size bound stays the ring buffer, not the line). The block is a flat list of [name] text lines again for every sender, allowlisted or not. New test test_observed_body_newlines_collapse_into_one_context_line feeds a body containing a forged [Recent group messages] header and asserts one buffered message renders as exactly one line.

2. Cloud API limitation (74bf411) — documented rather than wired. Confirmed the read: WhatsAppCloudAdapter inherits WhatsAppBehaviorMixin but never calls _maybe_record_group_history / _build_group_channel_context / the observe path, so both history_backfill and observe_unmentioned_group_messages are no-ops there. Stated in the WhatsApp guide, in both env-var reference rows, and at the mixin section comment so the next person editing the helpers sees it.

3. Watermark ordering (d691f3b) — comment at the update site. The trade is deliberate: advancing at render time costs one lost window if the event is dropped afterwards, while advancing on delivery would replay the entire window on every failed build. One correction to the review's example — the media download runs before _build_group_channel_context, not after, so an image-download error cannot consume the window.

4. Batch merge (09a80c8) — comment at the merge site explaining why only the first channel_context in a batch survives: the watermark advances once per build, so batched events carry disjoint windows; concatenating would splice a second block header into the prompt, and keeping the later one would drop the older window. The cost is bounded by the batch quiet period, and the durable observe path still records those messages.

Also from the review: "durably observe" refers to the store (one row per message, survives restart), not the backfill window, which the docs already describe as bounded and in memory.

Tests: uv run pytest tests/gateway/test_whatsapp_group_observer.py (14 passed) and uv run pytest tests/gateway -k whatsapp (194 passed, 3 skipped).

[NehoraiHadad]

Rebased onto current NousResearch/hermes-agent/main and force-pushed with lease.

New head: 723d02d4.

Conflict resolved in plugins/platforms/whatsapp/adapter.py: kept batching isolated by profile + raw chat + sender so distinct group authors cannot coalesce into one text batch.

Validation:

• uv run --with pytest pytest tests/gateway/test_whatsapp_group_observer.py — 14 passed
• uv run --with pytest --with pytest-asyncio --with aiohttp pytest tests/gateway -k whatsapp — 195 passed, 5 skipped