hermes - 💡(How to fix) Fix docs(google-chat): document Format 3 / Cloud Run relay envelope and sender_type contract [1 pull requests]

Summary

website/docs/user-guide/messaging/google_chat.md documents the Pub/Sub + Workspace Add-ons setup (the "Format 1" envelope path) but does not document the Cloud Run relay / "Format 3" envelope shape supported by plugins/platforms/google_chat/adapter.py:_extract_message_payload. As of #22432 (merged), Format 3 also accepts a sender_type field that operators MUST set correctly to get the BOT self-filter — but no operator-facing doc explains this.

Why it matters

#22432 (salvage of #22107) hardened Format 3 so the downstream BOT self-filter (adapter.py:1145) actually fires for relay-forwarded bot replies. The fix is gated on the relay sending envelope.sender_type for each forwarded message:

• sender_type: "BOT" → message dropped, bot-loop closed
• sender_type: "HUMAN" (or absent) → message reaches the agent loop

A relay misconfigured to forward bot replies as HUMAN (or to omit the field entirely) cannot be distinguished from genuine humans. Without docs, operators have no way to know they need to forward sender.type from the upstream Chat event.

What this issue tracks

A docs PR adding a "Format 3 / Cloud Run relay" section to website/docs/user-guide/messaging/google_chat.md covering:

1. What Format 3 is — flat-shape envelope used by self-hosted Cloud Run relays that keep GCP credentials off the Hermes host.
2. Required envelope fields — event_type, sender_email, text, space_name, message_name, thread_name (optional), and crucially sender_type ("HUMAN" or "BOT").
3. The operator contract for sender_type — relay MUST forward sender.type from the upstream Chat event so the BOT self-filter can drop bot-originated replies. Default is HUMAN for backward compatibility, but missing the field disables the bot-loop guard.
4. A minimal reference relay envelope — JSON example showing the canonical shape.
5. Trust boundary note — the relay is implicitly trusted; anyone with publish rights on its Pub/Sub topic can craft envelopes with arbitrary sender_email (allowlist passes through). This is unchanged by #22432; the fix only addresses the bot-loop case under an honest-but-misconfigured relay.

Out of scope

• Reference relay implementation (separate repo / template).
• Trust-boundary hardening beyond docs (would need cryptographic envelope signing — separate design discussion).

Pointers

• Adapter call site: plugins/platforms/google_chat/adapter.py:1013-1031 (the sender_type block + operator-contract comment block landed in #22432).
• BOT self-filter site: plugins/platforms/google_chat/adapter.py:1145.
• Tests covering the contract: tests/gateway/test_google_chat.py::TestOnPubsubMessage::test_relay_flat_bot_sender_is_filtered_end_to_end and ::TestExtractMessagePayload::test_relay_flat_* (5 tests added in #22432).
• Originating PR + its salvage: #22107 → #22432.