Skip to content

fix(whatsapp): wire missing Baileys retry/cache hooks for group message reliability#94338

Merged
mcaxtr merged 5 commits into
openclaw:mainfrom
xialonglee:fix/issue-7433-whatsapp-baileys-retry-hooks
Jun 21, 2026
Merged

fix(whatsapp): wire missing Baileys retry/cache hooks for group message reliability#94338
mcaxtr merged 5 commits into
openclaw:mainfrom
xialonglee:fix/issue-7433-whatsapp-baileys-retry-hooks

Conversation

@xialonglee

@xialonglee xialonglee commented Jun 18, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Root Cause

WhatsApp/Baileys socket construction was missing required retry and cache hooks. When Baileys needs to decrypt a message or resolve group metadata during retry, it calls getMessage and cachedGroupMetadata respectively — both default to async () => undefined in Baileys. Without these callbacks, group message decryption can fail on retry, and group metadata is fetched on every use rather than served from cache. Additionally, four Baileys event handlers (groups.upsert, groups.update, group-participants.update, lid-mapping.update) were unregistered, leaving the metadata cache stale and group state untracked.

Summary

  • Bug: WhatsApp group message reliability degraded because Baileys retry hooks (getMessage, cachedGroupMetadata) were absent and cache-invalidation event handlers were unregistered.
  • What this PR changes:
    • session.ts: Conditional spread for getMessage/cachedGroupMetadata to avoid overriding Baileys defaults when not provided.
    • inbound/monitor.ts: Bounded message store (500 entries) for getMessage retry support; four event handlers (groups.upsert, groups.update, group-participants.update, lid-mapping.update) with proper close cleanup; initial group fetch populates the Baileys-level cache so cachedGroupMetadata works immediately for all pre-existing groups; groups.update and group-participants.update now invalidate all three cache layers (baileysGroupMetaCache, groupMetaCache, groupMetadataCache) to prevent stale data after partial group updates; sent message content also cached in recentMessageKeys so getMessage can return the original proto.IMessage after socket reconnect/cache-miss.
    • connection-controller.ts: Optional getMessage/cachedGroupMetadata parameters passed through to createWaSocket.
    • auto-reply/monitor.ts: Caches created and wired into the production openConnection call.
    • Fixes Improve WhatsApp/Baileys group message reliability #7433

Verification

  • node scripts/run-vitest.mjs extensions/whatsapp/src/monitor-inbox.behavior.test.ts — 75/75 passed
  • node scripts/run-vitest.mjs extensions/whatsapp/src/connection-controller.test.ts — 17/17 passed
  • Autoreview: clean — sent message caching fix for ClawSweeper P1 finding
  • CI: pending after re-push (sent message cache for getMessage retry)

Real behavior proof

Behavior addressed: WhatsApp group message decryption/retry reliability — missing Baileys getMessage and cachedGroupMetadata callbacks, unregistered group state event handlers, incomplete cache invalidation on group/participant updates, and unsent message content for getMessage retry after reconnect.

Real environment tested: Linux, Node 22, branch fix/issue-7433-whatsapp-baileys-retry-hooks.

Exact steps or command run after this patch:

cd /home/0668000452/codes/OPENSOURCES/openclaw
node scripts/run-vitest.mjs extensions/whatsapp/src/monitor-inbox.behavior.test.ts 2>&1 | tail -10
node scripts/run-vitest.mjs extensions/whatsapp/src/connection-controller.test.ts 2>&1 | tail -10

Evidence after fix:

$ node scripts/run-vitest.mjs extensions/whatsapp/src/monitor-inbox.behavior.test.ts 2>&1 | tail -10
 ✓ extensions/whatsapp/src/monitor-inbox.behavior.test.ts (75 tests) 27140ms
 Test Files  1 passed (1)
      Tests  75 passed (75)

$ node scripts/run-vitest.mjs extensions/whatsapp/src/connection-controller.test.ts 2>&1 | tail -10
 ✓ extensions/whatsapp/src/connection-controller.test.ts (17 tests) 8602ms
 Test Files  1 passed (1)
      Tests  17 passed (17)

Observed result after fix: All WhatsApp tests pass (75/75 monitor-inbox, 17/17 connection-controller). The sent message caching ensures getMessage returns the original proto.IMessage for outbound messages after socket reconnect, matching the existing inbound message store pattern.

What was not tested: Live WhatsApp E2E roundtrip (requires real WhatsApp credentials and a paired phone — no automated testing infrastructure available). Test coverage uses mocked Baileys socket events. The bounded message store eviction (500 entries) and sent-message caching paths are covered by unit tests.

@openclaw-barnacle openclaw-barnacle Bot added channel: whatsapp-web Channel integration: whatsapp-web size: S proof: supplied External PR includes structured after-fix real behavior proof. labels Jun 18, 2026
@clawsweeper

clawsweeper Bot commented Jun 18, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Codex review: needs maintainer review before merge. Reviewed June 21, 2026, 9:00 AM ET / 13:00 UTC.

Summary
The branch wires Baileys getMessage and cachedGroupMetadata through the WhatsApp socket path, adds bounded retry/group metadata caches with group-event invalidation, and expands WhatsApp monitor behavior coverage.

PR surface: Source +473. Total +473 across 5 files.

Reproducibility: yes. at source level: current main and v2026.6.9 omit the requested Baileys callbacks and group metadata listeners while Baileys v7.0.0-rc13 exposes and uses those hooks. I did not reproduce a live current-main decryption failure in this read-only review.

Review metrics: 3 noteworthy metrics.

  • Baileys socket callbacks: 2 added. getMessage and cachedGroupMetadata affect retry resend and group-send behavior beyond ordinary local message flow coverage.
  • Group metadata listeners: 3 added. groups.upsert, groups.update, and group-participants.update now mutate live cache state, so maintainers should review the new event-driven delivery surface.
  • Retry cache retention: 500 entries, 10-minute message TTL. Recent message content is retained in memory for Baileys retry lookup, so the bounded retention policy matters for delivery and privacy review.

Stored data model
Persistent data-model change detected: persistent cache schema: extensions/whatsapp/src/inbound/monitor.ts, serialized state: extensions/whatsapp/src/session.ts. Confirm migration or upgrade compatibility proof before merge.

Root-cause cluster
Relationship: fixed_by_candidate
Canonical: #7433
Summary: This PR is the open candidate fix for the canonical WhatsApp/Baileys retry and group-cache reliability issue; earlier reconnect recovery work is related but partial.

Members:

Proposal only: this assessment does not dispatch repair, suppress jobs, mutate sibling items, close, or merge anything.

Merge readiness
Overall: 🐚 platinum hermit
Proof: 🦞 diamond lobster
Patch quality: 🐚 platinum hermit
Result: ready for maintainer review.

Overall follows the weaker of proof and patch quality, so missing proof can cap an otherwise strong patch.

Rank-up moves:

  • Maintainers can ask for a forced Baileys retry/decryption proof if they want to remove the remaining direct getMessage observation gap.

Risk before merge

  • [P1] The patch changes live WhatsApp retry resend and group metadata lookup paths, so an incorrect cache retention or invalidation choice could affect group message delivery.
  • [P1] The real WhatsApp QA proof covers 35 scenarios but does not explicitly force a Baileys retry receipt or decryption failure where the new getMessage callback is observed.
  • [P1] The PR retains recent message content in memory for retry lookup; it is bounded and non-persistent, but maintainers should consciously accept that privacy/reliability tradeoff.

Maintainer options:

  1. Accept Current WhatsApp QA Proof
    Proceed after normal checks if maintainers consider the 35-scenario real WhatsApp QA run plus focused source and unit coverage sufficient for this retry/cache path.
  2. Require Forced Retry Proof
    Ask for a redacted run that forces a Baileys retry receipt or decryption failure so the new getMessage callback is directly observed before merge.

Next step before merge

  • [P2] No automated source repair is indicated; maintainers need to review the message-delivery risk, residual retry proof gap, and normal merge gates.

Security
Cleared: No concrete security or supply-chain regression found; the PR changes only WhatsApp plugin source/tests and adds bounded non-persistent in-memory message retention without dependency, workflow, lockfile, credential-storage, or disk-persistence changes.

Review details

Best possible solution:

Land the focused WhatsApp plugin fix after maintainers accept the bounded in-memory retention and residual retry-path proof gap, then let the linked issue close from the merged PR.

Do we have a high-confidence way to reproduce the issue?

Yes at source level: current main and v2026.6.9 omit the requested Baileys callbacks and group metadata listeners while Baileys v7.0.0-rc13 exposes and uses those hooks. I did not reproduce a live current-main decryption failure in this read-only review.

Is this the best way to solve the issue?

Yes for the code boundary: the PR keeps the fix inside the WhatsApp plugin session/controller/inbound monitor path and avoids core API or config changes. The remaining question is how much direct retry-path proof maintainers want before merge.

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning high; reviewed against 8a7906c716d2.

Label changes

Label justifications:

  • P2: This is a bounded WhatsApp channel reliability fix with real delivery impact but no emergency core-runtime outage.
  • merge-risk: 🚨 message-delivery: The patch changes WhatsApp retry resend and group metadata paths that can affect whether live group messages decrypt, resend, or route correctly.
  • rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🦞 diamond lobster and patch quality is 🐚 platinum hermit.
  • status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Sufficient (live_output): A member supplied after-fix real WhatsApp QA live output with linked accounts and 35/35 scenarios passing, though the proof does not directly force a retry receipt path.
  • proof: sufficient: Contributor real behavior proof is sufficient. A member supplied after-fix real WhatsApp QA live output with linked accounts and 35/35 scenarios passing, though the proof does not directly force a retry receipt path.
Evidence reviewed

PR surface:

Source +473. Total +473 across 5 files.

View PR surface stats
Area Files Added Removed Net
Source 5 493 20 +473
Tests 0 0 0 0
Docs 0 0 0 0
Config 0 0 0 0
Generated 0 0 0 0
Other 0 0 0 0
Total 5 493 20 +473

What I checked:

Likely related people:

  • vincentkoc: Authored and merged the earlier reconnect-time group inbound recovery work that partially overlaps this issue and has recent commits in the same WhatsApp monitor/session/controller paths. (role: recent WhatsApp reliability contributor; confidence: high; commits: 21a92ea0f636, d70e6b13d7e1, f3283a330b4c; files: extensions/whatsapp/src/inbound/monitor.ts, extensions/whatsapp/src/session.ts, extensions/whatsapp/src/connection-controller.ts)
  • mcaxtr: Recent merged history includes WhatsApp connection lifecycle and multi-account inbound work in the same files, and this login supplied the live WhatsApp QA proof for the PR. (role: recent area contributor and proof provider; confidence: high; commits: aa023e428306, 458a52610a4d, da1da6110209; files: extensions/whatsapp/src/inbound/monitor.ts, extensions/whatsapp/src/connection-controller.ts, extensions/whatsapp/src/auto-reply/monitor.ts)
  • neeravmakwana: Authored the merged change that hydrated participating WhatsApp groups on connect, which is the current main behavior this PR extends into the Baileys-level metadata cache. (role: introduced adjacent group hydration behavior; confidence: medium; commits: 763d5cea443a; files: extensions/whatsapp/src/inbound/monitor.ts, extensions/whatsapp/src/monitor-inbox.streams-inbound-messages.test-support.ts)
  • steipete: Local history shows the highest volume of recent touches across the central WhatsApp files, and prior review context on the linked issue called out the same missing Baileys hooks. (role: reviewer and adjacent contributor; confidence: medium; commits: c09031f15a38, 3b6d980c52c3, 491969efb091; files: extensions/whatsapp/src/inbound/monitor.ts, extensions/whatsapp/src/session.ts, extensions/whatsapp/src/connection-controller.ts)
What the crustacean ranks mean
  • 🦀 challenger crab: rare, exceptional readiness with strong proof, clean implementation, and convincing validation.
  • 🦞 diamond lobster: very strong readiness with only minor maintainer review expected.
  • 🐚 platinum hermit: good normal PR, likely mergeable with ordinary maintainer review.
  • 🦐 gold shrimp: useful signal, but proof or patch confidence is still limited.
  • 🦪 silver shellfish: thin signal; proof, validation, or implementation needs work.
  • 🧂 unranked krab: not merge-ready because proof is missing/unusable or there are serious correctness or safety concerns.
  • 🌊 off-meta tidepool: rating does not apply to this item.

Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

How this review workflow works
  • ClawSweeper keeps one durable marker-backed review comment per issue or PR.
  • Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
  • A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
  • PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
  • Maintainers can also comment @clawsweeper review to request a fresh review only.
  • Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
  • Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
  • Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

@clawsweeper clawsweeper Bot added rating: 🦪 silver shellfish Thin PR readiness signal; proof, validation, or implementation needs work. status: 📣 needs proof The PR needs real behavior proof before ClawSweeper can clear the contributor ask. P2 Normal backlog priority with limited blast radius. labels Jun 18, 2026
@clawsweeper clawsweeper Bot mentioned this pull request Jun 18, 2026
Closed
@xialonglee

xialonglee commented Jun 18, 2026

Copy link
Copy Markdown
Contributor Author

CI note: the failing checks-node-core-runtime-media-ui check is a pre-existing core runtime test failure unrelated to the WhatsApp extension changes in this PR (all 4 changed files are under extensions/whatsapp/).

@clawsweeper clawsweeper Bot added rating: 🧂 unranked krab Not merge-ready due to missing proof or serious correctness/safety concerns. and removed rating: 🦪 silver shellfish Thin PR readiness signal; proof, validation, or implementation needs work. labels Jun 18, 2026
@xialonglee
xialonglee force-pushed the fix/issue-7433-whatsapp-baileys-retry-hooks branch from 716b3db to 02c64d5 Compare June 19, 2026 16:02
@clawsweeper clawsweeper Bot added the merge-risk: 🚨 message-delivery 🚨 May drop, duplicate, misroute, suppress, or wrongly target messages. label Jun 19, 2026
@mcaxtr mcaxtr self-assigned this Jun 20, 2026
@mcaxtr

mcaxtr commented Jun 20, 2026

Copy link
Copy Markdown
Member

WhatsApp QA proof on local rewritten HEAD:

  • Branch/head tested: fix/issue-7433-whatsapp-baileys-retry-hooks @ 394a15f67b8764b42ae9c66255dfd3d7bf56cd84
  • Base: origin/main @ 97b0b559ad17b6f567fc195d26c610b931f52d3b
  • Command: whatsapp-qa-branch --pr 94338
  • Provider mode: mock-openai
  • Driver account: default
  • SUT account: work
  • QA group: configured/redacted
  • Result: 35 pass / 0 fail / 0 skip; discovered and ran all 35 WhatsApp QA scenarios
  • Artifacts:
    • .artifacts/qa-e2e/whatsapp-full-pr-94338-20260620-220710/whatsapp-qa-report.md
    • .artifacts/qa-e2e/whatsapp-full-pr-94338-20260620-220710/qa-evidence.json
    • .artifacts/qa-e2e/whatsapp-full-pr-94338-20260620-220710/whatsapp-qa-observed-messages.json
    • .artifacts/qa-e2e/whatsapp-full-pr-94338-20260620-220710/gateway-debug/ was not present in this passing run

Post-run state:

  • Checkout restored to clean main.
  • Installed Gateway restarted; openclaw gateway status reports runtime running and connectivity probe ok.
  • openclaw channels status --channel whatsapp reports both default and work linked, running, connected, and healthy after settle.

Focused local checks still listed by the QA script for normal pre-merge coverage:

  • pnpm test extensions/qa-lab/src/providers/mock-openai/server.test.ts extensions/qa-lab/src/live-transports/whatsapp/whatsapp-live.runtime.test.ts extensions/whatsapp/src/qa-driver.runtime.test.ts extensions/whatsapp/src/inbound/send-api.test.ts
  • pnpm tsgo:extensions
  • pnpm lint:extensions
  • git diff --check origin/main..HEAD

@clawsweeper clawsweeper Bot added proof: sufficient ClawSweeper judged the real behavior proof convincing. rating: 🐚 platinum hermit Good normal PR readiness with ordinary maintainer review expected. status: 👀 ready for maintainer look ClawSweeper has no concrete contributor-facing blocker left for this PR. and removed rating: 🧂 unranked krab Not merge-ready due to missing proof or serious correctness/safety concerns. status: 📣 needs proof The PR needs real behavior proof before ClawSweeper can clear the contributor ask. labels Jun 21, 2026
@mcaxtr
mcaxtr force-pushed the fix/issue-7433-whatsapp-baileys-retry-hooks branch from 394a15f to 5a86f4b Compare June 21, 2026 01:17
@mcaxtr
mcaxtr requested review from a team as code owners June 21, 2026 12:33
@openclaw-barnacle openclaw-barnacle Bot added docs Improvements or additions to documentation channel: discord Channel integration: discord channel: googlechat Channel integration: googlechat channel: imessage Channel integration: imessage channel: line Channel integration: line labels Jun 21, 2026
@github-actions

github-actions Bot commented Jun 21, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Dependency graph guard cleared

This PR no longer has blocked dependency graph changes. A future dependency graph change requires a fresh /allow-dependencies-change comment after the guard blocks that new head SHA.

  • Current SHA: ee6de071f728d2a56e3b186fe2ac2fa86699d787

@mcaxtr

mcaxtr commented Jun 21, 2026

Copy link
Copy Markdown
Member

Merged via squash.

Thanks @xialonglee!

@github-actions github-actions Bot mentioned this pull request Jun 21, 2026
Open
@clawsweeper clawsweeper Bot mentioned this pull request Jul 1, 2026
Merged
This was referenced Jul 1, 2026
Merged
Open
@clawsweeper clawsweeper Bot mentioned this pull request Jul 18, 2026
Closed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

@mcaxtr mcaxtr

Labels

channel: whatsapp-web Channel integration: whatsapp-web merge-risk: 🚨 message-delivery 🚨 May drop, duplicate, misroute, suppress, or wrongly target messages. P2 Normal backlog priority with limited blast radius. proof: sufficient ClawSweeper judged the real behavior proof convincing. proof: supplied External PR includes structured after-fix real behavior proof. rating: 🐚 platinum hermit Good normal PR readiness with ordinary maintainer review expected. size: L status: 👀 ready for maintainer look ClawSweeper has no concrete contributor-facing blocker left for this PR.

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

Improve WhatsApp/Baileys group message reliability

2 participants

@xialonglee @mcaxtr