PR #64559: fix(plugins): emit message_received hook for queued inbound messages (#64525)

• Repository: openclaw/openclaw
• Author: qualiobra
• State: open | merged: False
• Link: https://github.com/openclaw/openclaw/pull/64559

Description (problem / solution / changelog)

Summary

• Problem: The message_received plugin hook silently misses most inbound messages since v2026.4.2 — plugins relying on it for chat history logging, analytics, or content moderation observe near-zero inbound events while message_sent continues to fire reliably.
• Why it matters: Plugins relying on message_received to observe ALL inbound messages are broken without any error signal.
• What changed: Extracted hook emission into a standalone emitMessageReceivedHooks() function (following the emitPreAgentMessageHooks() pattern) and call it at the message ingestion layer in dispatchReplyFromConfig(), before the dispatch-vs-enqueue decision. Removed the old emission block that was deeper in the dispatch pipeline.
• What did NOT change (scope boundary): The queue/drain mechanism (kickFollowupDrainIfIdle, enqueueFollowupRun, followup-runner) is not modified. The message_sent hook is untouched.

Change Type (select all)

• Bug fix
• Feature
• Refactor required for the fix
• Docs
• Security hardening
• Chore/infra

Scope (select all touched areas)

• Gateway / orchestration
• Skills / tool execution
• Auth / tokens
• Memory / storage
• Integrations
• API / contracts
• UI / DX
• CI/CD / infra

Linked Issue/PR

• Closes #64525
• This PR fixes a bug or regression

Root Cause (if applicable)

• Root cause: The kickFollowupDrainIfIdle() mechanism (added in v2026.3.2 to fix stranded messages) creates a fast drain path through followup-runner.ts → runEmbeddedPiAgent that bypasses dispatchReplyFromConfig() — the only place where message_received was emitted. The regression became observable in v2026.4.2 when commit 622b91d04e changed queue timing, routing significantly more messages through the fast-path.
• Missing detection / guardrail: No test asserted that message_received fires before the dispatch-vs-enqueue decision point.
• Contributing context (if known): The original kickFollowupDrainIfIdle fix was correct — it solved a real race condition. The bug is that hook emission was architecturally coupled to the dispatch layer instead of the ingestion layer.

Regression Test Plan (if applicable)

• Coverage level that should have caught this:
  • Unit test
  • Seam / integration test
  • End-to-end test
  • Existing coverage already sufficient
• Target test or file: src/auto-reply/reply/dispatch-from-config.test.ts — "emits message_received hook before dispatch logic (regression #64525)"
• Scenario the test should lock in: message_received hook fires before the reply resolver runs, ensuring it fires regardless of whether the message will be dispatched or enqueued.
• Why this is the smallest reliable guardrail: The test verifies call ordering (hook before reply resolver) which breaks if the hook emission is moved back below the dispatch decision.
• Existing test that already covers this (if any): The existing "emits message_received hook with originating channel metadata" test verified the hook fires but did not assert ordering relative to dispatch logic.

User-visible / Behavior Changes

• message_received plugin hook now fires for ALL inbound messages, including those queued while a session is active. Previously these were silently missed.
• Hook now fires slightly earlier in the pipeline (at ingestion, before routing/claim checks) — this is the correct semantic for "message received".

Diagram (if applicable)

Before:
Channel → dispatchReplyFromConfig() → [routing] → [claim checks] → message_received → session busy? → enqueue (no hook on drain)

After:
Channel → dispatchReplyFromConfig() → message_received → [routing] → [claim checks] → session busy? → enqueue (hook already fired)

Security Impact (required)

• New permissions/capabilities? No
• Secrets/tokens handling changed? No
• New/changed network calls? No
• Command/tool execution surface changed? No
• Data access scope changed? No

Repro + Verification

Environment

• OS: macOS
• Runtime/container: Node 22+
• Model/provider: N/A (hook infrastructure)
• Integration/channel (if any): All channels affected

Steps

1. Register a plugin with a message_received hook
2. Send two messages in quick succession to a session
3. Observe that the second message (queued while session is active) does not trigger the hook

Expected

• message_received fires for both messages

Actual

• message_received fires only for the first message; the second is silently missed

Evidence

• Failing test/log before + passing after
• Trace/log snippets
• Screenshot/recording
• Perf numbers (if relevant)

New regression test "emits message_received hook before dispatch logic (regression #64525)" in dispatch-from-config.test.ts asserts hook fires before reply resolver. 7 unit tests for emitMessageReceivedHooks() in message-received-hooks.test.ts.

Human Verification (required)

• Verified scenarios: Hook fires for normal messages, hook fires before dispatch logic, hook skipped for duplicates, internal hook fires with session key, plugin hook uses correct event shape
• Edge cases checked: Missing session key (internal hook skipped), missing message ID (fallback chain), missing timestamp (omitted), no registered hooks (plugin hook skipped)
• What you did not verify: Live testing on a running OpenClaw instance with real channel adapter

Review Conversations

• I replied to or resolved every bot review conversation I addressed in this PR.
• I left unresolved only the conversations that still need reviewer or maintainer judgment.

Compatibility / Migration

• Backward compatible? Yes
• Config/env changes? No
• Migration needed? No

Risks and Mitigations

• Risk: Hook now fires for plugin-bound messages that previously returned early before reaching the emission point (handled/declined/error claim outcomes).
  • Mitigation: This is the correct semantic — message_received means "a message was received by the system", not "a message entered the dispatch pipeline". The hook is documented as fire-and-forget (observer).
• Risk: Hook timing changed (slightly earlier in pipeline).
  • Mitigation: The PluginMessageReceivedEvent shape and PluginMessageContext are identical. FinalizedMsgContext fields are fully populated at the call site.

AI-assisted: Yes (Claude Code — research, root cause analysis, implementation, testing) Testing: Fully tested locally (pnpm build && pnpm check && pnpm test — all pass; pre-existing upstream failures unrelated)

Changed files

• src/auto-reply/reply/dispatch-from-config.test.ts (modified, +42/-0)
• src/auto-reply/reply/dispatch-from-config.ts (modified, +8/-33)
• src/auto-reply/reply/message-received-hooks.test.ts (added, +174/-0)
• src/auto-reply/reply/message-received-hooks.ts (added, +46/-0)