feat(hooks): add message:sent and message:received internal hook events by heybeaux · Pull Request #6384 · openclaw/openclaw

heybeaux · 2026-02-01T16:11:55Z

Summary

Implements the internal hook events documented as "Future Events" in the hooks documentation. These events enable extensions to observe the complete message lifecycle.

Related Issue

This PR addresses the functionality requested in #5354, which was closed as NOT_PLANNED due to maintainer bandwidth. As suggested, submitting a PR instead.

Changes

New Events

message:received - Triggered when an inbound message is processed

Context includes: text, channel, chatType, from, to, senderId, senderName, senderUsername, messageId, threadId, timestamp, accountId, mediaUrls, mediaTypes
Triggered in dispatch-from-config.ts after duplicate check, alongside the existing plugin hook

message:sent - Triggered when an outbound message is successfully delivered

Context includes: text, channel, chatType, kind (tool/block/final), mediaUrl, mediaUrls, timestamp
Triggered in reply-dispatcher.ts after successful delivery

Implementation Details

Added "message" to InternalHookEventType in src/hooks/internal-hooks.ts
Trigger message:received in dispatchReplyFromConfig() for inbound messages
Trigger message:sent in the reply dispatcher after delivery success
Added sessionKey, channel, and chatType options to ReplyDispatcherOptions for hook context
Updated dispatchInboundMessageWithDispatcher and dispatchInboundMessageWithBufferedDispatcher to inject session context into dispatcher options

Use Cases

Agent memory systems (e.g., Engram) that need to persist conversations for context retrieval
Analytics and logging plugins for conversation insights
Message archival and search indexing
Conversation export features

Example Usage

import { registerInternalHook } from './hooks/internal-hooks.js';

// Track all received messages
registerInternalHook('message:received', async (event) => {
  await saveToMemory({
    sessionKey: event.sessionKey,
    text: event.context.text,
    from: event.context.from,
    timestamp: event.timestamp,
  });
});

// Track all sent messages
registerInternalHook('message:sent', async (event) => {
  await logOutbound({
    sessionKey: event.sessionKey,
    text: event.context.text,
    kind: event.context.kind,
    timestamp: event.context.timestamp,
  });
});

Testing

TypeScript compilation passes ✅
Existing internal hook tests pass ✅
The hooks are fire-and-forget with error handling to prevent disrupting message flow

Checklist

Code compiles without errors
Follows existing hook patterns (createInternalHookEvent, triggerInternalHook)
Non-blocking (uses void promises with catch)
Includes context useful for memory/analytics use cases

Greptile Overview

Greptile Summary

Adds two new internal hook events to the existing internal hook registry: message:received is emitted during inbound message processing (after duplicate-check) with message/metadata context, and message:sent is emitted after successful outbound delivery from the reply dispatcher. To support outbound context, dispatcher options are extended to carry sessionKey, channel, and chatType, and the inbound dispatch entrypoints now inject those values from the finalized inbound context.

Confidence Score: 4/5

This PR is generally safe to merge, with a couple of hook-contract consistency issues worth addressing.
Changes are localized to hook emission points and dispatcher option plumbing, and the new hooks are fire-and-forget. Main concerns are consistency/contract details (timestamp representation and asymmetric gating on sessionKey) and observability (silent error swallowing) rather than core message delivery correctness.
src/auto-reply/reply/reply-dispatcher.ts and src/auto-reply/reply/dispatch-from-config.ts

_{(3/5) Reply to the agent's comments like "Can you suggest a fix for this @greptileai?" or ask follow-up questions!}

greptile-apps

_{1 file reviewed, 3 comments}

_{Edit Code Review Agent Settings | Greptile}

src/auto-reply/reply/reply-dispatcher.ts

heybeaux · 2026-02-02T14:27:27Z

Hi maintainers,

Just following up on this PR. Greptile bot feedback has been addressed:

Removed duplicate timestamp (now uses event.timestamp only)
Made sessionKey handling consistent (both events fire even with empty sessionKey)
Added error logging at verbose level (matching existing patterns)

The CI failures appear to be unrelated to this PR — they're in Swift lint and Windows build, while this change only touches TypeScript hook dispatch code. Happy to rebase if there are conflicts, but wanted to check if a maintainer could re-run CI or confirm these failures are pre-existing.

This feature would enable automatic memory capture for AI agents via the hook system. Appreciate any guidance on getting it over the line.

f2daz · 2026-02-04T10:02:15Z

👍 This feature would be very valuable for our Mission Control dashboard integration. We're building a real-time agent activity tracker that needs to sync tool calls and messages to an external dashboard. Looking forward to this landing!

Use case: Automatic status updates in a custom dashboard showing what the agent is currently doing, token usage, and activity history.

heybeaux · 2026-02-04T16:37:59Z

@f2daz It sounds like a lot of projects, both existing and in development, would benefit from this feature. I'm hopeful that we'll see movement in the next week or so. It's incredible to see such a busy open source project.

Glucksberg · 2026-02-08T12:05:00Z

📋 Duplicate triage note: PR #6797 appears to implement the same fix. Consider consolidating or closing one in favor of the other.

heybeaux · 2026-02-09T19:07:49Z

Hey @Glucksberg, thanks for flagging the overlap with #6797.

I've taken a look at both implementations and they're solving the same problem with very similar approaches — dedicated message:received and message:sent hook events using the existing internal hook system.

A few observations:

This PR (feat(hooks): add message:sent and message:received internal hook events #6384) was opened on Feb 1st and addresses the same feature request from Feature Request: message:received and message:sent hook events #5354
feat(hooks): add message:received and message:sent hook events #6797 takes a similar approach but adds a dedicated message-hooks.ts module with typed context interfaces and tests, which is a nice structural pattern
feat(hooks): add message:received and message:sent hook events #6797 also bundles some dispatcher refactoring (return type changes, removed functions) that goes beyond the hook feature itself

I'm very open to consolidating — the goal is getting this feature landed, not who gets credit. A few paths forward:

If the maintainers prefer feat(hooks): add message:received and message:sent hook events #6797's module structure, I'm happy to adopt that pattern here and rebase
If feat(hooks): add message:received and message:sent hook events #6797 is closer to what the team wants, I can close this PR — just want to make sure the context fields from both are considered (this PR includes chatType, from, to, mediaUrls which are useful for memory/analytics use cases)
Happy to collaborate directly with @NOVA-Openclaw if that's helpful

Whatever gets the feature across the finish line works for me. 🤝

Implements the message lifecycle hooks documented as 'Future Events' in the hooks documentation. These events enable extensions to observe inbound and outbound messages for logging, analytics, memory systems, and archival. New events: - message:received: triggered when an inbound message is processed - message:sent: triggered after an outbound message is successfully delivered Both events include rich context (text, channel, chatType, sender info, media URLs) and are fired asynchronously so they never block message processing. Includes: - 6 test cases covering event triggering, general/specific handler routing, media fields, error isolation, and type validation - Documentation update moving these from 'Future Events' to documented events Combines approaches from prior community PRs openclaw#6384, openclaw#6797, and openclaw#9859. Resolves openclaw#12775, openclaw#8807, openclaw#13004 Related: openclaw#5354, openclaw#12867, openclaw#12914

matskevich · 2026-02-12T08:21:50Z

hey @heybeaux — running message hooks in production (via backport of #6797, same concept as yours) for a week now. 550+ events, 3 hooks built on top (memory, DLP, multi-bot sync).

found a real gap and opened a discussion with a proposal to extend the lifecycle: #14539

short version: message:received fires before media understanding, so voice messages arrive as <media:audio> with no transcript. proposing message:preprocessed as a third event after applyMediaUnderstanding().

both PRs solve the same core problem. would be great to coordinate — happy to contribute groupId fix and preprocessed to whichever PR the maintainers prefer.

beaux-riel · 2026-02-12T20:24:04Z

Hey @matskevich — love that you've been battle-testing this in production. 550+ events with zero crashes is exactly the validation this feature needs.

The message:preprocessed gap is real and I've hit it too — building a memory system (Engram) on top of OpenClaw, and voice messages arriving as <media:audio> tags are useless for semantic search. Having the transcript available at hook time is critical.

I'm happy to add message:preprocessed to this PR. The three-event lifecycle makes sense:

received → media/link understanding → preprocessed → agent → sent

Your proposed MessagePreprocessedContext type looks clean. I'd suggest we also carry forward the context fields from this PR (chatType, from, to, mediaUrls) across all three events for consistency.

Plan:

I'll rebase this PR and add the message:preprocessed event following the pattern in your discussion
Include groupId fix
Keep it minimal — ~40 lines, no breaking changes, same hook system

If you want to co-author or review, happy to coordinate. Let's get this landed. 🤝

Implements the internal hook events documented as 'Future Events' in the hooks documentation. These events enable extensions to observe message lifecycle: - message:received: Triggered when an inbound message is processed - Includes: text, channel, chatType, from/to, senderId, senderName, messageId, threadId, timestamp, mediaUrls, mediaTypes - Triggered in dispatch-from-config.ts after duplicate check - message:sent: Triggered when an outbound message is successfully delivered - Includes: text, channel, chatType, kind (tool/block/final), mediaUrl, mediaUrls, timestamp - Triggered in reply-dispatcher.ts after successful delivery Use cases: - Agent memory systems (e.g., Engram) that need to persist conversations - Analytics and logging plugins - Message archival and search indexing - Conversation export features API example: registerInternalHook('message:received', async (event) => { await saveToMemory(event.context.text, event.sessionKey); }); registerInternalHook('message:sent', async (event) => { await logOutbound(event.context.text, event.context.kind); }); Closes openclaw#5354 (NOT_PLANNED - now implemented via PR)

- Remove duplicate timestamp from hook context (use event.timestamp) - Make sessionKey handling consistent (fire even with empty key, fall back to "") - Add debug logging for hook errors (match dispatch-from-config pattern)

…ding Fires after applyMediaUnderstanding() and applyLinkUnderstanding(), before agent processing. Voice messages now have transcripts, images have descriptions, and links have summaries when this hook fires. Also adds groupId to message:received internal hook context. Addresses discussion openclaw#14539 (three-event lifecycle proposal).

beaux-riel · 2026-02-12T22:42:09Z

Updated — PR now implements the full three-event lifecycle from discussion #14539:

message:received → applyMediaUnderstanding + applyLinkUnderstanding → message:preprocessed → agent → message:sent

What's new in the latest push:

message:preprocessed hook — fires after media/link understanding, before agent processing. Voice messages arrive with transcripts, images with descriptions, links with summaries. Both plugin hook and internal hook variants.
groupId added to message:received internal hook context
All CI checks passing ✅

This addresses @matskevich's production finding that message:received fires too early for hooks that need enriched content (memory, search, moderation). The preprocessed event fills that gap with ~40 lines of new code, no breaking changes.

4 commits, 7 files, +172 lines. Ready for review.

sebslight · 2026-02-13T03:43:54Z

Closing as duplicate of #14196. If this is incorrect, comment and we can reopen.

greptile-apps bot reviewed Feb 1, 2026

View reviewed changes

src/auto-reply/reply/reply-dispatcher.ts Outdated Show resolved Hide resolved

src/auto-reply/reply/reply-dispatcher.ts Outdated Show resolved Hide resolved

src/auto-reply/reply/reply-dispatcher.ts Outdated Show resolved Hide resolved

VACInc mentioned this pull request Feb 1, 2026

[Feature]: Hooks/Webhooks (Egress) #3990

Closed

heybeaux force-pushed the feat/message-lifecycle-hooks branch from fdd23a7 to bd107e2 Compare February 2, 2026 14:41

Glucksberg mentioned this pull request Feb 8, 2026

feat(hooks): add message:received and message:sent hook events #6797

Closed

grunt3714-lgtm mentioned this pull request Feb 11, 2026

feat(hooks): add message:received and message:sent internal hook events #14196

Closed

heybeaux force-pushed the feat/message-lifecycle-hooks branch from b516878 to 6b6762d Compare February 12, 2026 20:43

openclaw-barnacle bot added size: XL and removed size: M labels Feb 12, 2026

Clawdbot added 3 commits February 12, 2026 12:44

fix: address code review feedback on message lifecycle hooks

6195b81

- Remove duplicate timestamp from hook context (use event.timestamp) - Make sessionKey handling consistent (fire even with empty key, fall back to "") - Add debug logging for hook errors (match dispatch-from-config pattern)

style: fix import ordering in reply-dispatcher

66de12c

heybeaux force-pushed the feat/message-lifecycle-hooks branch from 6b6762d to a15c032 Compare February 12, 2026 20:46

openclaw-barnacle bot added size: S and removed size: XL labels Feb 12, 2026

heybeaux force-pushed the feat/message-lifecycle-hooks branch from a15c032 to 16c9d44 Compare February 12, 2026 20:49

Merge branch 'main' into feat/message-lifecycle-hooks

c08f820

sebslight closed this Feb 13, 2026

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Comments

feat(hooks): add message:sent and message:received internal hook events#6384

feat(hooks): add message:sent and message:received internal hook events#6384
heybeaux wants to merge 5 commits intoopenclaw:mainfrom
heybeaux:feat/message-lifecycle-hooks

heybeaux commented Feb 1, 2026 •

edited by greptile-apps bot

Loading

Uh oh!

greptile-apps bot left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

heybeaux commented Feb 2, 2026

Uh oh!

f2daz commented Feb 4, 2026

Uh oh!

heybeaux commented Feb 4, 2026

Uh oh!

Glucksberg commented Feb 8, 2026

Uh oh!

heybeaux commented Feb 9, 2026

Uh oh!

matskevich commented Feb 12, 2026

Uh oh!

beaux-riel commented Feb 12, 2026

Uh oh!

beaux-riel commented Feb 12, 2026

Uh oh!

sebslight commented Feb 13, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

Uh oh!

Comments

Conversation

heybeaux commented Feb 1, 2026 • edited by greptile-apps bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Related Issue

Changes

New Events

Implementation Details

Use Cases

Example Usage

Testing

Checklist

Greptile Overview

Greptile Summary

Confidence Score: 4/5

Uh oh!

greptile-apps bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

heybeaux commented Feb 2, 2026

Uh oh!

f2daz commented Feb 4, 2026

Uh oh!

heybeaux commented Feb 4, 2026

Uh oh!

Glucksberg commented Feb 8, 2026

Uh oh!

heybeaux commented Feb 9, 2026

Uh oh!

matskevich commented Feb 12, 2026

Uh oh!

beaux-riel commented Feb 12, 2026

Uh oh!

beaux-riel commented Feb 12, 2026

Uh oh!

sebslight commented Feb 13, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

heybeaux commented Feb 1, 2026 •

edited by greptile-apps bot

Loading