feat(gateway): add Rocket.Chat platform adapter

[cyb0rgk1tty]

Summary

Adds a Rocket.Chat adapter so Hermes can chat from self-hosted Rocket.Chat alongside the existing platforms. Full parity with the Mattermost adapter: REST (v1) for outbound writes, DDP WebSocket for inbound receive, PAT auth, threaded replies via tmid, file upload via the two-step rooms.media flow, mention gating, DM/channel/group detection, and system-message / self-message filtering.

No new Python dependency — the adapter is built on aiohttp, which is already required by the Mattermost / HomeAssistant / SMS adapters.

Motivation

Rocket.Chat is a common self-hosted choice alongside Mattermost and Matrix. Users who run both wanted a single Hermes profile model across platforms.

What's in the diff

• Adapter: gateway/platforms/rocketchat.py (~560 lines) with RocketchatAdapter(BasePlatformAdapter).
• Wiring through the full 16-point ADDING_A_PLATFORM.md checklist:
  • Platform.ROCKETCHAT enum + _apply_env_overrides() block in gateway/config.py
  • Adapter factory branch + platform_env_map / platform_allow_all_map entries in gateway/run.py
  • PLATFORM_HINTS entry in agent/prompt_builder.py (so the agent knows Markdown + threads + MEDIA: hints apply)
  • hermes-rocketchat toolset + inclusion in hermes-gateway composite (toolsets.py)
  • Cron delivery platform_map + _HOME_TARGET_ENV_VARS entry (cron/scheduler.py)
  • Standalone _send_rocketchat() + platform_map + dispatch in tools/send_message_tool.py
  • deliver schema description bump in tools/cronjob_tools.py
  • PLATFORMS registry entry in hermes_cli/platforms.py, status display row in hermes_cli/status.py, full wizard entry in hermes_cli/gateway.py
• Tests: tests/gateway/test_rocketchat.py — 46 tests mirroring test_mattermost.py coverage (config loading, format/truncate, send with mocked aiohttp, DDP frame dispatch including ping/pong + ready + stream-room-messages, dedup, mention gating, threading, media-type MIME propagation, requirements check).
• Docs: new website/docs/user-guide/messaging/rocketchat.md setup guide, plus table/diagram/next-steps updates in messaging/index.md and entries in reference/environment-variables.md.

Env var contract

ROCKETCHAT_URL                      required  — server URL (e.g. https://rc.example.com)
ROCKETCHAT_TOKEN                    required  — Personal Access Token ("Ignore Two Factor" must be checked)
ROCKETCHAT_USER_ID                  required  — bot user _id (shown next to the PAT at creation)
ROCKETCHAT_ALLOWED_USERS            optional  — comma-separated user _ids
ROCKETCHAT_ALLOW_ALL_USERS          optional  — "true" to skip allowlist
ROCKETCHAT_HOME_CHANNEL             optional  — room _id for cron delivery
ROCKETCHAT_HOME_CHANNEL_NAME        optional  — display name (default "Home")
ROCKETCHAT_REQUIRE_MENTION          optional  — default "true"; set "false" to respond to all channel msgs
ROCKETCHAT_FREE_RESPONSE_CHANNELS   optional  — comma-separated room _ids exempt from the above
ROCKETCHAT_REPLY_MODE               optional  — "thread" (uses tmid) or "off" (flat, default)

Mirrors the Mattermost env shape so existing profile tooling maps directly.

Test plan

• pytest tests/gateway/test_rocketchat.py -q → 46 passed
• pytest tests/ -q → no new failures (the existing dingtalk/matrix/agent_cache failures on main are pre-existing and unchanged)
• hermes gateway setup lists Rocket.Chat in the wizard with the correct prompts
• Live verification against a self-hosted Rocket.Chat 8.2 workspace:
  • REST /api/v1/me authentication
  • DDP WS connect + stream-room-messages:__my_messages__ subscription
  • Inbound DM parse → agent dispatch
  • Outbound chat.postMessage with tmid (threaded reply visible in client)
  • Full LLM roundtrip (glm-5.1 via ollama-cloud) — "2 + 2 = 4 👍" delivered as thread reply
• Live file upload (unit-tested; not yet exercised end-to-end)
• DDP reconnect after a server-side restart (handler exists and unit-tested)

Notes

• The adapter subscribes to the __my_messages__ virtual room id (covers every room the bot is a member of with one sub). DDP subscriptions don't resume across reconnect, so the adapter re-logs-in and re-subscribes on every reconnect.
• rooms.media + rooms.mediaConfirm is used for uploads (the older rooms.upload is deprecated in 6.x+).
• Writes go via REST; receive goes via DDP. This matches what Rocket.Chat's developer docs recommend ("DDP methods no longer actively tested — prefer REST for new work") while keeping the only viable push path for incoming messages.

🤖 Generated with Claude Code

[alt-glitch]

Likely duplicate of #4637 — both add a Rocket.Chat platform adapter. Also addresses feature request #3725.

[HearthCore]

Hey @cyb0rgk1tty, thanks a lot for your work on the Rocket.Chat adapter — your PR #14869 was the foundation we built on. 🙏

We refactored your approach into the modern plugin format (plugins/platforms/rocketchat/, kind: platform) so it requires zero core Hermes changes. It also bundles several fixes and enhancements that we developed while running it live:

Key additions:

• ✅ DDP reconnect with exponential backoff (2s–60s)
• ✅ TTS audio pipeline (ffmpeg MP3 conversion for voice messages)
• ✅ Bidirectional Hermes session title ↔ RC room topic sync
• ✅ Emoji reactions (👀✅❌) on channel messages
• ✅ Slash command position-0 fix (no false positives mid-sentence)
• ✅ is_gateway_known_command() gate to prevent unnecessary 400s
• ✅ Deferred attachments (file-only uploads merged with next text msg)
• ✅ AGENTS.md for AI assistant devs + full README
• ✅ Fixes both bugs reported on the parallel PR feat(gateway): add Rocket.Chat platform adapter #4637 (empty init.py + discover_plugins)

Our PR: #30463

Would love your thoughts on the approach! Happy to collaborate further. 🔥

Also tagging @meron1122 since your PR #4637 was a valuable reference for the plugin structure.

[teknium1]

Thanks for the substantial Rocket.Chat adapter work.

Automated hermes-sweeper review found that this change matches the standing in-tree-provider-integration policy: new third-party/vendor integrations must ship as standalone plugins, rather than add adapter, config, cron, sender, toolset, and setup branches throughout Hermes core.

• The PR adds the adapter at gateway/platforms/rocketchat.py and core wiring in gateway/config.py, gateway/run.py, cron/scheduler.py, and tools/send_message_tool.py.
• Current platform guidance explicitly recommends ~/.hermes/plugins/ for community/third-party adapters and states that route requires zero core changes: gateway/platforms/ADDING_A_PLATFORM.md:5-15.
• Current main already resolves plugin platforms through platform_registry before the legacy adapter chain: gateway/run.py:8652-8688.
• The linked discussion around feat(plugins): add Rocket.Chat platform adapter as bundled plugin #30463 is useful prior work; the appropriate next step is to publish and maintain Rocket.Chat as a standalone installable plugin repository, promoted through #plugins-skills-and-skins.

This is an automated hermes-sweeper review.

---

Closed as not-planned per standing maintainer policy (in-tree-provider-integration). This is a design-direction decision, not a code-quality judgment — see the Contribution Rubric in AGENTS.md for what the project is looking for. If you believe this policy was misapplied to your change, comment here and a maintainer will take a look.

[meron1122]

I published plugin powerup with amazing features from @HearthCore and a few more. Feel free to use and contribute
https://github.com/HalfbitStudio/hermes-plugin-rocketchat