PR #14738: fix(tools): resolve whatsapp phone numbers to lid format

• Repository: NousResearch/hermes-agent
• Author: ysnav
• State: open | merged: False
• Link: https://github.com/NousResearch/hermes-agent/pull/14738

Description (problem / solution / changelog)

What does this PR do?

<!-- Describe the change clearly. What problem does it solve? Why is this approach the right one? -->

This PR fixes a critical bug where AI-initiated tool calls and cron reminders failed to send messages over WhatsApp because they used bare phone numbers instead of the required Linked Identity Device (LID) formats.

Context: JIDs vs. LIDs

1 JID (Jabber ID): The traditional WhatsApp routing identifier. For direct messages, it looks like [phone_number]@s.whatsapp.net. For groups, it looks like [group_id]@g.us.

2 LID (Linked Identity Device): WhatsApp's modern, privacy-focused identifier format (e.g., 77214955630717@lid). The underlying Baileys bridge now strictly enforces this format for newer accounts and multi-device setups.

Why we can't fully ditch JIDs: We must continue supporting JIDs because group chats (@g.us) still rely entirely on the JID format. Additionally, we need to maintain legacy JID fallbacks (@s.whatsapp.net) for older accounts or edge cases where an LID isn't known yet.

The Bug

Incoming messages from WhatsApp to Hermes were working perfectly. This is because the local Baileys bridge natively handles incoming LIDs and automatically maps them to phone numbers for authorization (via allowlist.js). However, the system broke on outgoing messages initiated by the AI (via tools) or by background Cron jobs. These systems only knew the user's bare phone number (e.g., +1234567890). When send_message_tool sent this bare phone number to the bridge, the bridge rejected it because it expects a fully qualified LID or JID.

The Fix

This PR implements a resolution pipeline that bridges the gap between the agent's knowledge (phone numbers) and the bridge's requirements (LIDs):

1. Resolution Pipeline: Added _resolve_whatsapp_phone_to_jid to the send_message_tool. When a bare phone number is provided, it reads the local bridge session files (~/.hermes/whatsapp/session/lid-mapping-{phone}.json) created during the bridge handshake to gracefully convert the phone number to its proper LID.
2. Smart Routing: Updated _parse_target_ref and _send_whatsapp to use this pipeline. If an already-valid JID is passed in (containing @lid, @s.whatsapp.net, or @g.us), it passes through untouched.
3. Fallback Mechanism: If no mapping file exists for a phone number, it safely falls back to the legacy @s.whatsapp.net format.

Comprehensive unit tests were added in test_send_message_tool.py to ensure legacy JIDs, LIDs, group JIDs, and fallback mechanisms are all routed correctly.

Related Issue

<!-- Link the issue this PR addresses. If no issue exists, consider creating one first. -->

Fixes #14486

Type of Change

<!-- Check the one that applies. -->

• 🐛 Bug fix (non-breaking change that fixes an issue)
• ✨ New feature (non-breaking change that adds functionality)
• 🔒 Security fix
• 📝 Documentation update
• ✅ Tests (adding or improving test coverage)
• ♻️ Refactor (no behavior change)
• 🎯 New skill (bundled or hub)

Changes Made

<!-- List the specific changes. Include file paths for code changes. -->

• tools/send_message_tool.py: Added _resolve_whatsapp_phone_to_jid and _ensure_whatsapp_jid helpers. Updated _parse_target_ref and _send_whatsapp routing to automatically resolve bare phone numbers and respect valid WhatsApp JIDs.
• tests/tools/test_send_message_tool.py: Added test class TestWhatsAppPhoneToLidResolution and TestEnsureWhatsAppJid to cover mapping file lookups, legacy fallbacks, and standard JID passthrough.

How to Test

<!-- Steps to verify this change works. For bugs: reproduction steps + proof that the fix works. -->

1. Ensure your WhatsApp bridge session is active and mapping files exist in ~/.hermes/whatsapp/session/.
2. Schedule a cron reminder using Hermes over WhatsApp with your bare phone number (e.g. "Remind me to wake up my friend at 6:39 PM").
3. Wait for the cron job to trigger and observe that the delivery executes successfully instead of throwing a validation error.

Checklist

<!-- Complete these before requesting review. -->

Code

• I've read the Contributing Guide
• My commit messages follow Conventional Commits (fix(scope):, feat(scope):, etc.)
• I searched for existing PRs to make sure this isn't a duplicate
• My PR contains only changes related to this fix/feature (no unrelated commits)
• I've run pytest tests/ -q and all tests pass
• I've added tests for my changes (required for bug fixes, strongly encouraged for features)
• I've tested on my platform: macOS 14/15

Documentation & Housekeeping

<!-- Check all that apply. It's OK to check "N/A" if a category doesn't apply to your change. -->

• I've updated relevant documentation (README, docs/, docstrings) — or N/A
• I've updated cli-config.yaml.example if I added/changed config keys — or N/A
• I've updated CONTRIBUTING.md or AGENTS.md if I changed architecture or workflows — or N/A
• I've considered cross-platform impact (Windows, macOS) per the compatibility guide — or N/A
• I've updated tool descriptions/schemas if I changed tool behavior — or N/A

For New Skills

<!-- Only fill this out if you're adding a skill. Delete this section otherwise. -->

• This skill is broadly useful to most users (if bundled) — see Contributing Guide
• SKILL.md follows the standard format (frontmatter, trigger conditions, steps, pitfalls)
• No external dependencies that aren't already available (prefer stdlib, curl, existing Hermes tools)
• I've tested the skill end-to-end: hermes --toolsets skills -q "Use the X skill to do Y"

Screenshots / Logs

<!-- If applicable, add screenshots or log output showing the fix/feature in action. -->

Tested manually as well, by asking the agent to remind me at 18:39 via whatsapp, and it did remind me

Changed files

• tests/tools/test_send_message_tool.py (modified, +106/-2)
• tools/send_message_tool.py (modified, +81/-4)