hermes-agent/website/docs/user-guide/messaging
Siddharth Balyan d38b73fa57
fix(matrix): E2EE and migration bugfixes (#10860)
* - make buffered streaming
- fix path naming to expand `~` for agent.
- fix stripping of matrix ID to not remove other mentions / localports.

* fix(matrix): register MembershipEventDispatcher for invite auto-join

The mautrix migration (#7518) broke auto-join because InternalEventType.INVITE
events are only dispatched when MembershipEventDispatcher is registered on the
client. Without it, _on_invite is dead code and the bot silently ignores all
room invites.

Closes #10094
Closes #10725
Refs: PR #10135 (digging-airfare-4u), PR #10732 (fxfitz)

* fix(matrix): preserve _joined_rooms reference for CryptoStateStore

connect() reassigned self._joined_rooms = set(...) after initial sync,
orphaning the reference captured by _CryptoStateStore at init time.
find_shared_rooms() returned [] forever, breaking Megolm session rotation
on membership changes.

Mutate in place with clear() + update() so the CryptoStateStore reference
stays valid.

Refs #8174, PR #8215

* fix(matrix): remove dual ROOM_ENCRYPTED handler to fix dedup race

mautrix auto-registers DecryptionDispatcher when client.crypto is set.
The adapter also registered _on_encrypted_event for the same event type.
_on_encrypted_event had zero awaits and won the race to mark event IDs
in the dedup set, causing _on_room_message to drop successfully decrypted
events from DecryptionDispatcher. The retry loop masked this by re-decrypting
every message ~4 seconds later.

Remove _on_encrypted_event entirely. DecryptionDispatcher handles decryption;
genuinely undecryptable events are logged by mautrix and retried on next
key exchange.

Refs #8174, PR #8215

* fix(matrix): re-verify device keys after share_keys() upload

Matrix homeservers treat ed25519 identity keys as immutable per device.
share_keys() can return 200 but silently ignore new keys if the device
already exists with different identity keys. The bot would proceed with
shared=True while peers encrypt to the old (unreachable) keys.

Now re-queries the server after share_keys() and fails closed if keys
don't match, with an actionable error message.

Refs #8174, PR #8215

* fix(matrix): encrypt outbound attachments in E2EE rooms

_upload_and_send() uploaded raw bytes and used the 'url' key for all
rooms. In E2EE rooms, media must be encrypted client-side with
encrypt_attachment(), the ciphertext uploaded, and the 'file' key
(with key/iv/hashes) used instead of 'url'.

Now detects encrypted rooms via state_store.is_encrypted() and
branches to the encrypted upload path.

Refs: PR #9822 (charles-brooks)

* fix(matrix): add stop_typing to clear typing indicator after response

The adapter set a 30-second typing timeout but never cleared it.
The base class stop_typing() is a no-op, so the typing indicator
lingered for up to 30 seconds after each response.

Closes #6016
Refs: PR #6020 (r266-tech)

* fix(matrix): cache all media types locally, not just photos/voice

should_cache_locally only covered PHOTO, VOICE, and encrypted media.
Unencrypted audio/video/documents in plaintext rooms were passed as MXC
URLs that require authentication the agent doesn't have, resulting
in 401 errors.

Refs #3487, #3806

* fix(matrix): detect stale OTK conflict on startup and fail closed

When crypto state is wiped but the same device ID is reused, the
homeserver may still hold one-time keys signed with the previous
identity key. Identity key re-upload succeeds but OTK uploads fail
with "already exists" and a signature mismatch. Peers cannot
establish new Olm sessions, so all new messages are undecryptable.

Now proactively flushes OTKs via share_keys() during connect() and
catches the "already exists" error with an actionable log message
telling the operator to purge the device from the homeserver or
generate a fresh device ID.

Also documents the crypto store recovery procedure in the Matrix
setup guide.

Refs #8174

* docs(matrix): improve crypto recovery docs per review

- Put easy path (fresh access token) first, manual purge second
- URL-encode user ID in Synapse admin API example
- Note that device deletion may invalidate the access token
- Add "stop Synapse first" caveat for direct SQLite approach
- Mention the fail-closed startup detection behavior
- Add back-reference from upgrade section to OTK warning

* refactor(matrix): cleanup from code review

- Extract _extract_server_ed25519() and _reverify_keys_after_upload()
  to deduplicate the re-verification block (was copy-pasted in two
  places, three copies of ed25519 key extraction total)
- Remove dead code: _pending_megolm, _retry_pending_decryptions,
  _MAX_PENDING_EVENTS, _PENDING_EVENT_TTL — all orphaned after
  removing _on_encrypted_event
- Remove tautological TestMediaCacheGate (tested its own predicate,
  not production code)
- Remove dead TestMatrixMegolmEventHandling and
  TestMatrixRetryPendingDecryptions (tested removed methods)
- Merge duplicate TestMatrixStopTyping into TestMatrixTypingIndicator
- Trim comment to just the "why"
2026-04-17 04:03:02 +05:30
..
_category_.json feat: add documentation website (Docusaurus) 2026-03-05 05:24:55 -08:00
bluebubbles.md fix(bluebubbles): auto-register webhook with BlueBubbles server on connect 2026-04-10 03:21:45 -07:00
dingtalk.md docs: comprehensive documentation update for recent features 2026-03-17 03:42:02 -07:00
discord.md feat(discord): add channel_prompts config 2026-04-15 16:31:28 -07:00
email.md docs: comprehensive docs audit — fix 12 stale/missing items across 10 pages (#3618) 2026-03-28 15:26:35 -07:00
feishu.md feat(feishu): add scan-to-create onboarding for Feishu / Lark 2026-04-12 13:05:56 -07:00
homeassistant.md docs: fix 40+ discrepancies between documentation and codebase (#5818) 2026-04-07 10:17:44 -07:00
index.md feat(gateway): unify QQBot branding, add PLATFORM_HINTS, fix streaming, restore missing setup functions 2026-04-14 00:11:49 -07:00
matrix.md fix(matrix): E2EE and migration bugfixes (#10860) 2026-04-17 04:03:02 +05:30
mattermost.md feat: extend channel_prompts to Telegram, Slack, and Mattermost 2026-04-15 16:31:28 -07:00
open-webui.md feat(api-server): stream /v1/responses SSE tool events 2026-04-14 20:51:52 -07:00
qqbot.md feat(gateway): unify QQBot branding, add PLATFORM_HINTS, fix streaming, restore missing setup functions 2026-04-14 00:11:49 -07:00
signal.md docs: comprehensive docs audit — cover 13 features from last week's PRs (#5815) 2026-04-07 10:21:03 -07:00
slack.md feat: extend channel_prompts to Telegram, Slack, and Mattermost 2026-04-15 16:31:28 -07:00
sms.md update docks with changes made 2026-04-11 14:05:38 -07:00
telegram.md feat(telegram): add dedicated TELEGRAM_PROXY env var and config.yaml proxy_url support 2026-04-15 22:13:11 -07:00
webhooks.md docs: add QQBot to all 14 docs pages (full platform parity) 2026-04-14 00:11:49 -07:00
wecom-callback.md docs: comprehensive update for recent merged PRs (#9019) 2026-04-13 10:50:59 -07:00
wecom.md docs: fix 40+ discrepancies between documentation and codebase (#5818) 2026-04-07 10:17:44 -07:00
weixin.md fix(weixin): keep multi-line messages in single bubble by default (#7903) 2026-04-11 12:00:05 -07:00
whatsapp.md docs: comprehensive update for recent merged PRs (#9019) 2026-04-13 10:50:59 -07:00