feat(tools): bring Teknium's peer session messaging onto current main

[barronlroth]

What does this PR do?

Bring Teknium's peer session messaging implementation from #106423 onto current main. Two independent sessions in the same Hermes home can discover each other and send a short local update without the user copying text between them.

The first commit is a cherry-pick of Teknium's original cff14a4, preserving his authorship. Its three conflicts are resolved while retaining current compression-activity handling, connector registration, and setup/start-chat documentation. The second commit makes the bounded compatibility and documentation changes below. This is a draft continuation for maintainer review, not a request to close #106423.

Related Issue

Continues #106423. Related coordination use case: #76221. #123218 proposes a separate project-discovery/read/ACK workflow; this draft retains the original two-tool design.

Type of Change

• ✨ New feature
• 📝 Documentation update
• ✅ Tests

Changes Made

• Keep peer_sessions and peer_send in the existing opt-in peer_messaging toolset, outside the default core tools. Delivery continues through the existing activity hook and user-role steer lane.
• Pin receiving to the recipient agent's session database home so an out-of-turn callback cannot drain the ambient profile's same-ID mailbox. Discovery/send lookups explicitly use the same profile home as publication; availability requires its actual state.db.
• State the actual delivery contract in the tool response, attribution text, and references: enabling the toolset grants discovery/sending; receiving does not require it. Idle sessions wait for their next activity. A successful send means queued, not read or completed.
• Document best-effort consumption. A receiver crash between draining the mailbox into memory and transcript persistence can lose a message. This draft does not add ACKs, retries, automatic wake, or exactly-once execution.
• Identify the peer as the writer while retaining the existing user-role transport. Peer text does not grant new human permission or override the user's instructions. This is attribution guidance, not a new structural authority boundary.
• Update the inherited implementation for current lint rules, including BOM-tolerant JSON reads.

How to Test

scripts/run_tests.sh tests/tools/test_peer_messaging.py tests/tools/test_peer_messaging_delivery.py tests/tools/test_registry.py tests/tools/test_toolsets.py tests/agent/test_session_activity.py tests/agent/test_session_activity_persist.py tests/agent/test_steer.py -j 3
python scripts/check

On macOS arm64, Python 3.14.7 in an independent PM-built dev/test environment:

• 107 tests passed, 0 failed. New coverage runs the full handle_function_call path, real activity hook, real steering methods, and SQLite persistence. It checks peer attribution in the actual user row, append-only prefix preservation, reception without send tools, no replay after consumption, BOM-tolerant envelopes, and recipient-home routing.
• Profile regression: fails without the recipient-home pin, passes with it. With two homes containing the same recipient ID, the unpinned code delivers the second profile's payload to the first profile's agent.
• Separate-process smoke passed against a temporary Hermes home: the sender discovers and queues; a different receiving process drains through the activity hook, forms the user row, persists its peer attribution to SQLite, and consumes the mailbox.
• All 12 blocking checks in python scripts/check passed, including Ruff, code health, Windows footguns, and compatibility pointers. Diff whitespace checks pass.

The smoke stops at model-ready message construction and persistence; it does not call a live model. Full-suite CI, Windows execution, and live Telegram/Desktop behavior remain unverified.

Checklist

• Read the contributing guidance and searched existing PRs; this deliberately continues feat(tools): peer session messaging — one session can warn or unblock another (inspired by Muse Code) #106423 and links the separate feat(peer-messaging): project discovery, tool-data inbox, replies and ACKs #123218 workflow.
• Conventional commits; Teknium's authorship preserved.
• Changes are scoped to the peer-messaging implementation and its current-main integration.
• Focused tests and blocking lint checks pass.
• Full test suite / upstream CI pass.
• Relevant documentation and tool descriptions updated; no new configuration keys.
• Tested on macOS arm64; cross-platform source checks pass, Windows runtime validation remains pending.

[seyfal]

I ran this branch with two Hermes processes and found five ways a peer message can get lost, pass as the user's own words or land in the wrong turn, including the two blocking findings from the #106423 review. The fixes are in barronlroth#1, 11 commits on top of this branch with a test for each, so merging it there updates this PR and keeps all three authors' commits. I also re-ran the busy, idle and no-tool-call cases live on claude-haiku-4-5 with the fixes in.

The first commit fixes a /steer placement bug that also exists on main without peer messaging, and I can send it as its own PR if you'd rather land it first.