feat(bot-mode): bots on every Desktop connection can message each other

[teknium1]

Summary

Bots on every Desktop connection can now message each other: message_agent reaches agents on any gateway the Desktop holds a socket to (local, remote URL, SSH, Hermes Cloud, docker) — connections ARE the peer set (Teknium ruling, Aug 2026). Also fixes a gate bug where profiles with the legacy plugin-appended protocol in SOUL.md silently lost the message_agent tool.

Root cause of the reported dead end (user screenshot: cloud bot @-mentioned, agent replies "agent messaging isn't available here"): cross-connection roster rows were visible and taggable but had no delivery route — message_agent only knew local profiles and hermes peer targets, and the injection gate keyed on protocol-section non-emptiness, which the legacy-SOUL dedupe empties.

How it works

The Desktop already holds a persistent authenticated line to every connected gateway. Two plugin loops use those lines:

• Roster sync (60s): pushes each gateway the union roster of agents on the OTHER connections (bot_relay.roster.sync) → Bot Chat prompts list them ("Teammates on OTHER connected machines"), capability epoch refreshes eternal chats on change.
• Envelope relay (4s): drains queued cross-connection DMs (bot_relay.outbox.drain), delivers each on the target connection's own socket (bot_relay.deliver — same one-turn Bot Chat transport local DMs use), posts the reply back (bot_relay.reply) where a waiter wakes the sender via the standard completion-notification path.

Gateways never see each other's credentials; the Desktop is the courier. Ambiguous handles disambiguate as handle@connection (the tool's error teaches the exact forms). Older backends without the RPCs are skipped per-call.

Changes

• tools/bot_relay.py (new): roster store + validation, target resolution, atomic outbox claim, reply files, waiter command.
• tools/bot_mode_dm.py: relay route in message_agent (peer → local → relay, incl. same-name-on-other-connection); gates now key on is_bot_mode_managed() — fixes the legacy-SOUL tool loss.
• tools/bot_mode_probe.py: is_bot_mode_managed(); remote-teammates paragraph in the protocol section; relay roster in the capability fingerprint.
• tui_gateway/methods_bot_relay.py (new) + server.py: 4 RPCs, all on the RPC pool (deliver runs a full agent turn).
• apps/desktop/src/plugins/hermes-bots/plugin.js: relay worker loops (start/stop via register/onDispose, feature-detected, degrade gracefully); mention-middleware note now names the cross-connection message_agent target.
• Docs: website/docs/user-guide/bot-mode.md — new "Messaging across connected machines (the Desktop relay)" section; @mention + cross-machine sections updated.

Validation

	Before	After
Cloud/SSH/remote bot via message_agent	unreachable ("not a peer")	delivered + reply relayed
Legacy-SOUL profile Bot Chat	tool silently missing	tool injected (regression test)
Bot Chat roster	local + peers only	+ agents on every connection

Tests: 50 Python (13 relay + 5 RPC new; all bot_mode_dm/probe suites green), 368 plugin source-shape tests (5 new). E2E: real two-install round-trip — roster sync → message_agent ack → envelope claim → deliver RPC (argv contract) → reply → real waiter subprocess prints "Reply from @ops on ssh-b: … All green"; error path prints the delivery failure distinctly.

Infographic

[github-actions]

૮ >ﻌ< ა ci review

_{ran on a0c4b45 — feat(bot-mode): bots on every Desktop connection can message}

⚠️ Warnings

CI timings · View report · View job

Wall time 9m47s vs 3m14s (+202.6%). 2 job(s) slower, 10 faster, 2 unchanged.

• JS & TS checks / JS & TS checks: -30.0s
• Python lints / ruff enforcement (blocking): -14.0s
• Python lints / Windows footguns (blocking): -9.0s
• Python tests / Run tests: +8.0s
• OS-specific tests / Windows-only tests: -8.0s

---

OSV vulnerability scan · View job

7 known vulnerabilities found in pinned dependencies.

• CVE-2026-67213 in package-lock.json
• CVE-2026-67213 in website/package-lock.json
• CVE-2026-71554 in uv.lock
• CVE-2026-70608 in package-lock.json
• CVE-2026-56876 in package-lock.json
• CVE-2026-70606 in package-lock.json
• CVE-2026-71554 in uv.lock

How to fix:

Review the findings in the Security tab. Update the affected dependencies if a patched version is available.

[teknium1]

Live E2E evidence (no mocks anywhere in the chain)

Level A — relay protocol over real WebSockets. Two real hermes dashboard gateways (A :18871, B :18872, separate scratch HERMES_HOMEs, real OpenRouter key), script playing the Desktop courier over each gateway's real /api/ws:

1. bot_relay.roster.sync on A → {count: 2} (B's default + ops pushed)
2. Real sender turn on A (real AIAgent, Bot Chat, gemini-3.7-flash) — the model chose to call message_agent; envelope queued
3. bot_relay.outbox.drain on A → 1 envelope, scout → ops@machine-b
4. bot_relay.deliver on B → real one-turn hermes -p ops chat run, replied in 18.5s
5. bot_relay.reply on A → reply file written; receiver's ops state.db carries the attributed DM + assistant reply (14 messages)

Level B — the shipped plugin loops as the courier. Real Electron desktop (dev server + CDP, worktree backend via HERMES_DESKTOP_HERMES), connections registry seeded with both gateways. No script touched the relay RPCs — the hermes-bots plugin's own 60s roster loop and 4s drain loop did all carrying:

• Roster loop live on both sides: A's roster lists default@dash-b + ops@dash-b, B's lists default@local + scout@local, both refreshing on the 60s cadence
• Decisive round-trip with clean dirs + unique codeword:

[sender]   envelope 94f9c35b… queued: "Message from 🤖 scout (@scout): Codeword ZEBRA-9174: what is 17*23? …"
[relay]    reply for 94f9c35b…: error='' — "Codeword ZEBRA-9174: 391"
[receiver] B ops Bot Chat (state.db): user DM + assistant "Codeword ZEBRA-9174: 391"
LEVEL B LIVE E2E (Desktop loops as courier): PASS

PASS criteria were strict: the new envelope id's reply file (a first run matched a stale reply file from Level A — invalidated, dirs swept, rerun), correct answer + codeword in the reply, and the unique DM present in the receiving profile's state.db.

Field notes from the run: desktop resolves its local backend via PATH hermes (main-repo code) unless HERMES_DESKTOP_HERMES pins the worktree — the loops silently no-op against a backend without the RPCs, exactly the graceful-degradation path older backends will take.