PR #66910: fix(hooks): expose inbound media on early receive hooks

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

Description (problem / solution / changelog)

Summary

• Problem: Telegram inbound media reached the finalized inbound context, but message:received hooks dropped the media fields before managed hooks could inspect them.
• Why it matters: repo-level hook code could not claim or preprocess inbound Telegram media early, even though the downloaded media paths already existed.
• What changed: message:received now carries inbound media fields, and enriched internal message hook contexts now preserve media arrays alongside the first media item.
• What did NOT change (scope boundary): this does not add raw Telegram-native ids like file_id or media_group_id; it only exposes the finalized inbound media data already available in the runtime.

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 #
• Related #66827
• This PR fixes a bug or regression

Root Cause (if applicable)

• Root cause: the hook mapper dropped mediaPath/mediaType entirely for message:received, and it dropped mediaPaths/mediaTypes for enriched internal hook contexts.
• Missing detection / guardrail: the nearest mapper regression test covered inbound-claim media metadata, but not the early receive/preprocessed hook surfaces.
• Contributing context (if known): Telegram resolves inbound media into finalized context before the hook bridge runs, so the missing data was a mapper-contract bug rather than a Telegram download-timing bug.

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/hooks/message-hook-mappers.test.ts
• Scenario the test should lock in: canonical inbound media arrays survive into plugin/internal message:received payloads and internal message:preprocessed payloads.
• Why this is the smallest reliable guardrail: the regression happens in the shared hook mapper contract after inbound context is finalized, so a focused mapper test directly exercises the bug surface without depending on Telegram runtime setup.
• Existing test that already covers this (if any): extensions/telegram/src/bot.media.downloads-media-file-path-no-file-download.e2e.test.ts proves Telegram inbound media paths are created before the mapper stage.
• If no new test is added, why not: N/A

User-visible / Behavior Changes

Telegram/media-aware managed hooks can now read finalized inbound media paths earlier:

• internal message:received hooks now include mediaPath, mediaType, mediaPaths, and mediaTypes
• internal enriched hooks like message:preprocessed now preserve mediaPaths and mediaTypes
• plugin message_received hooks now include the same media fields in event.metadata

Diagram (if applicable)

Before:
[telegram inbound media] -> [finalized context has MediaPath/MediaPaths] -> [message:received mapper drops media] -> [hook cannot claim media early]

After:
[telegram inbound media] -> [finalized context has MediaPath/MediaPaths] -> [message:received/preprocessed mapper preserves media] -> [hook can inspect media early]

Security Impact (required)

• New permissions/capabilities? (Yes/No) No
• Secrets/tokens handling changed? (Yes/No) No
• New/changed network calls? (Yes/No) No
• Command/tool execution surface changed? (Yes/No) No
• Data access scope changed? (Yes/No) No
• If any Yes, explain risk + mitigation:

Repro + Verification

Environment

• OS: macOS 15.3.0
• Runtime/container: local Node/pnpm workspace
• Model/provider: N/A
• Integration/channel (if any): Telegram managed hook surface
• Relevant config (redacted): N/A

Steps

1. Build a canonical inbound context with multiple media paths/types.
2. Map it into plugin/internal message:received payloads and internal message:preprocessed payloads.
3. Verify the resulting hook payloads still expose the finalized media fields.

Expected

• Early message hook payloads preserve the inbound media metadata already present on the finalized context.

Actual

• Before this change, message:received dropped media entirely and enriched internal hooks dropped media arrays.

Evidence

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

Human Verification (required)

• Verified scenarios:
  • pnpm test src/hooks/message-hook-mappers.test.ts src/hooks/message-hooks.test.ts
  • pnpm test extensions/telegram/src/bot.media.downloads-media-file-path-no-file-download.e2e.test.ts -t "keeps Telegram inbound media paths with triple-dash ids"
  • pnpm check
  • pnpm build
• Edge cases checked:
  • multi-attachment inbound media arrays remain aligned with the first media item
  • existing hook fixtures still pass without requiring new fields
• What you did not verify:
  • live Telegram manual end-to-end verification against a real bot account

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/No) Yes
• Config/env changes? (Yes/No) No
• Migration needed? (Yes/No) No
• If yes, exact upgrade steps:

Risks and Mitigations

• Risk: hook consumers may start depending on the newly surfaced media fields before raw Telegram-native ids are available.
  • Mitigation: the PR keeps scope explicit and only surfaces finalized runtime media data that already exists today.

AI Assistance

Prepared with coding assistance and manually verified with the checks listed above.

Made with Cursor

Changed files

• src/hooks/internal-hooks.ts (modified, +12/-0)
• src/hooks/message-hook-mappers.test.ts (modified, +102/-2)
• src/hooks/message-hook-mappers.ts (modified, +59/-12)
• src/plugins/hook-message.types.ts (modified, +4/-0)