openclaw - 💡(How to fix) Fix [PRD] Deepen WhatsApp target resolution into canonical target facts [1 comments, 2 participants]

Problem Statement

WhatsApp target handling is currently correct but scattered. A maintainer or agent working on the WhatsApp plugin has to understand several separate modules to answer one basic question: what does this target mean?

The same raw target can be parsed for explicit message commands, normalized again for outbound authorization, interpreted again for session routing, and converted again for wire delivery. Those paths also carry adjacent facts such as chat type, allowlist behavior, newsletter presence behavior, group bypass behavior, and LID-aware send JIDs. This makes the WhatsApp target modules shallow: deleting any one helper mostly moves the same normalization and policy knowledge into another caller.

From the user's perspective, the desired behavior is boring consistency: WhatsApp direct numbers, group JIDs, newsletter JIDs, prefixed targets, allowlist entries, and LID mappings should behave the same no matter whether the user sends through a message tool, a channel send path, a reply path, an action path, or routing metadata.

Solution

Create a deeper WhatsApp target facts module with a small, stable interface. It should turn a raw WhatsApp target plus the relevant policy inputs into canonical target facts that callers can reuse instead of rediscovering.

The module should preserve current shipped behavior while concentrating the rules in one place:

• Normalize direct numbers, WhatsApp-prefixed targets, group JIDs, and newsletter JIDs consistently.
• Classify the target as direct, group, or channel once.
• Produce route peer facts from the canonical target.
• Produce outbound authorization facts using the current allowFrom behavior.
• Produce wire delivery facts, including LID-aware direct JID selection when an auth mapping is available.
• Preserve the current behavior that group and newsletter targets bypass direct allowFrom checks.
• Preserve the current behavior that newsletter targets skip composing presence.
• Expose enough information that existing callers can stop doing local target interpretation.

The implementation should be done in its own worktree and branch, not directly on main. Use conventional commit style for both the branch name and commit messages. Example branch names: refactor/whatsapp-target-facts or feat/whatsapp-canonical-target-facts. Example commit message shape: refactor(whatsapp): add canonical target facts module.

User Stories

1. As an OpenClaw user sending a WhatsApp direct message, I want phone number normalization to be consistent, so that the same recipient is reached from every send path.
2. As an OpenClaw user sending to a WhatsApp group, I want group JIDs to be recognized consistently, so that group sends and group routing do not drift.
3. As an OpenClaw user sending to a WhatsApp newsletter, I want newsletter JIDs to be recognized consistently, so that newsletter delivery keeps its special behavior.
4. As an OpenClaw user using whatsapp: prefixed targets, I want the prefix stripped once in a canonical way, so that prefixed and unprefixed inputs behave identically.
5. As an OpenClaw user with allowFrom configured, I want direct target authorization to behave the same across sends and actions, so that policy is predictable.
6. As an OpenClaw user with an empty direct allowFrom list, I want the existing direct outbound behavior preserved, so that this refactor does not silently tighten policy.
7. As an OpenClaw user sending to a group while allowFrom is configured for direct messages, I want the existing group behavior preserved, so that group sends do not start failing unexpectedly.
8. As an OpenClaw user sending to a newsletter while allowFrom is configured, I want the existing newsletter behavior preserved, so that newsletter sends do not start failing unexpectedly.
9. As an OpenClaw user with LID-addressed WhatsApp contacts, I want outbound direct sends to keep using available LID mappings, so that messages do not land in sender-only ghost chats.
10. As an OpenClaw user sending to a newsletter, I want composing presence to stay disabled, so that OpenClaw does not attempt unsupported presence updates.
11. As an OpenClaw user sending to a normal direct chat or group, I want composing presence behavior to stay unchanged, so that delivery still feels responsive.
12. As an OpenClaw agent using the WhatsApp message tool, I want target parsing and session routing to share canonical facts, so that messages continue the right conversation.
13. As an OpenClaw agent reacting to a WhatsApp message, I want action authorization to reuse the same target facts as outbound sends, so that reactions respect the same target rules.
14. As an OpenClaw maintainer, I want target classification to live in one module, so that changing target behavior has strong locality.
15. As an OpenClaw maintainer, I want route peer facts to come from canonical target facts, so that routing bugs are not fixed separately in multiple places.
16. As an OpenClaw maintainer, I want wire JID conversion to be represented as an explicit derived fact, so that callers do not need to know whether the target is a phone number, group JID, newsletter JID, or LID.
17. As an OpenClaw maintainer, I want allowlist decisions to be inspectable as data, so that blocked-target errors can stay clear and consistent.
18. As an OpenClaw maintainer, I want invalid-target errors to stay user-facing and actionable, so that users still learn the expected WhatsApp target formats.
19. As an OpenClaw maintainer, I want current target tests to collapse around the new target facts interface where practical, so that the interface is the test surface.
20. As an OpenClaw maintainer, I want the implementation to avoid new core dependencies, so that WhatsApp-specific behavior remains plugin-owned.
21. As a third-party plugin author, I want bundled plugin refactors to respect plugin boundaries, so that private WhatsApp internals are not turned into accidental SDK contracts.
22. As a reviewer, I want the PR to show behavior preservation through focused tests, so that the change is recognizable as a refactor rather than a behavior change.
23. As a reviewer, I want the work done on a dedicated worktree and branch, so that main stays clean while the design is being implemented.
24. As a reviewer, I want conventional branch and commit naming, so that history and automation remain easy to scan.
25. As a future agent, I want the PRD to name the intended deep module, so that I do not repeat the shallow-helper pattern.

Implementation Decisions

• Build or deepen a WhatsApp target facts module with one small interface that accepts raw target input plus the relevant policy and optional LID mapping context, then returns canonical target facts.
• Keep the module local to the WhatsApp plugin. Do not move WhatsApp-specific target behavior into core.
• The canonical target facts should include at least: normalized target, chat type, route peer facts, outbound authorization decision, wire delivery JID, and whether composing presence is appropriate.
• Preserve current target formats: direct E.164-ish numbers, WhatsApp user JIDs, legacy user JIDs, LID JIDs where already supported, group JIDs, newsletter JIDs, and whatsapp: prefixes.
• Preserve current direct allowFrom semantics, including wildcard, empty-list behavior, and normalized matching.
• Preserve current group and newsletter behavior that bypasses the direct allowFrom check.
• Preserve current LID-aware send behavior where auth mappings can convert a direct phone target into a LID wire JID.
• Preserve current newsletter behavior that skips composing presence.
• Replace local target parsing in message command parsing, outbound session routing, outbound authorization, channel sends, and send adapter setup with calls into the canonical target facts module where it reduces duplication.
• Avoid introducing a seam unless it has more than one real adapter. The target facts module should be a deep module, not a speculative adapter layer.
• Keep plugin production code importing only from public plugin SDK subpaths and local WhatsApp barrels or modules.
• Do not promote this target facts interface to a public SDK contract unless implementation proves a real third-party plugin need.
• Do the implementation in a dedicated worktree and branch, not on main.
• Use conventional commit style for the branch name and each commit. Prefer a refactor-prefixed branch unless the implementation intentionally changes user-visible behavior.
• Use conventional commit messages, scoped to whatsapp where possible.
• If implementation discovers a necessary behavior change, split that decision into a separate issue or explicitly call it out before proceeding.

Testing Decisions

• Good tests should exercise external behavior through the target facts interface and the existing caller behavior. Avoid tests that lock in internal helper ordering or file layout.
• Add or update tests for direct target normalization, prefixed targets, group JIDs, newsletter JIDs, invalid targets, wildcard allowFrom, empty allowFrom, blocked direct targets, and allowed direct targets.
• Add or update tests for route peer facts so direct, group, and channel targets continue to produce the expected routing shape.
• Add or update tests for wire delivery facts, especially direct phone-to-JID conversion, direct phone-to-LID conversion when a mapping is present, group JID pass-through, and newsletter JID pass-through.
• Add or update tests that prove newsletter targets still skip composing presence.
• Add or update tests that prove groups and newsletters still bypass direct allowFrom checks.
• Keep existing outbound target, session route, action authorization, and send adapter tests as prior art, migrating assertions toward the deeper target facts interface where it improves locality.
• Run focused WhatsApp plugin tests for the touched target, routing, action, and outbound send surfaces.
• Run the repository's changed check before handoff if the touched surface remains narrow. Use remote or broader proof if the implementation expands into shared plugin SDK or gateway behavior.

Out of Scope

• Changing WhatsApp allowFrom policy semantics.
• Changing group policy, group allowlist, or mention gating semantics.
• Changing pairing, login, auth storage, or credential repair behavior.
• Changing inbound access control.
• Changing message delivery retry behavior.
• Changing LID mapping persistence or discovery beyond preserving current send behavior.
• Creating a public Plugin SDK target facts contract.
• Refactoring the entire outbound send module or inbound turn orchestration.
• Adding a prototype to the repository.
• Implementing directly on main.

Further Notes

This PRD comes from the first architecture improvement candidate for the WhatsApp plugin: Canonical Target Facts.

The goal is depth and locality, not novelty. The best implementation should make existing behavior easier to see and test while leaving user-visible behavior unchanged.

The prior prototype was removed and should not be recreated as part of this issue unless the implementer uses a separate throwaway worktree and deletes the prototype before opening a PR.