feat(plugins): support actionable Telegram callback events

[RSapeliuk]

What does this PR do?

Adds a generic, authorized Telegram callback_query event to the existing gateway_platform_event plugin hook. Plugins receive a normalized plain-dict payload and may return a constrained action envelope to answer the callback and edit the message/inline keyboard. This lets user plugins implement Telegram inline-button workflows without monkey-patching the Telegram adapter or embedding feature-specific code in Hermes.

Related Issue

N/A — this is a reusable plugin extensibility feature motivated by Telegram inline-button plugins.

Type of Change

• 🐛 Bug fix (non-breaking change that fixes an issue)
• ✨ New feature (non-breaking change that adds functionality)
• 🔒 Security fix
• 📝 Documentation update
• 🧪 Tests (adding or improving test coverage)
• 🔨 Refactor (no behavior change)
• 🧰 New skill

Changes Made

• Return plugin results from the gateway's authorized gateway_platform_event dispatch path.
• Add Telegram callback_query normalization with stable string/dict fields only.
• Apply a constrained answer/edit action envelope in the Telegram adapter, including inline keyboard reconstruction.
• Add callback-query authorization using the existing Telegram auth boundary.
• Preserve built-in callback handling when no plugin handles the event or a plugin raises.
• Document the callback event payload and action contract.
• Add regression tests for handled callbacks and plugin-failure fallback.

How to Test

1. python -m pytest tests/gateway/test_gateway_platform_event_hook.py -q -o addopts=''
2. python -m compileall -q gateway/run.py plugins/platforms/telegram/adapter.py tests/gateway/test_gateway_platform_event_hook.py

Checklist

Code

• I've read the Contributing Guide
• My commit messages follow Conventional Commits (feat(plugins): ...)
• I've searched for existing PRs to make sure this isn't a duplicate
• My PR contains only changes related to this feature (no unrelated commits)
• I've run the targeted test suite (36 passed)
• I've tested the implementation with real imports and compile checks

Documentation & Housekeeping

• I've updated relevant documentation (website/docs/user-guide/features/hooks.md)
• I've updated cli-config.yaml.example if I added/changed config keys — N/A
• I've updated CONTRIBUTING.md or AGENTS.md if I changed architecture/workflow — N/A
• I've considered cross-platform impact (Windows, macOS) — N/A
• I've updated tool descriptions/schemas if I changed tool behavior — N/A

For New Skills

• This skill is broadly useful to most users — N/A
• SKILL.md follows the standard format — N/A
• No external dependencies that aren't already available — N/A
• I've tested the skill end-to-end — N/A

Screenshots / Logs

Targeted test output:

....................................                                     [100%]
36 passed in 9.34s

[alt-glitch]

This was generated by AI during triage.

Related competing callback-extension work: #71630 provides the earlier registered-prefix API and #21471 a pre-dispatch hook. This PR instead adds a constrained post-authorization action envelope; maintainer selection on the callback contract and precedence is needed.

[Enough1122]

AI code review — automated review for reference, author can ignore or act on any point.

feat(plugins): support actionable Telegram callback events

1. plugins/platforms/telegram/adapter.py _source_from_callback_for_auth: message_thread_id == 0 produces thread_id="0" (present but falsy), which may not match the shape _source_from_message_for_auth produces for the same chat. Normalizing 0/absent to None would keep the two auth-source builders consistent.
2. The plugin action envelope rebuilds reply_markup from buttons with callback_data=str(button["data"]) — a plugin can supply any string, including one colliding with built-in reserved prefixes (mp:, mpg:, mm:, …). Since the plugin already consumed the event this is acceptable, but documenting the reserved-prefix convention would stop future button presses from accidentally shadowing built-in picker callbacks.
3. gateway/run.py _handle_gateway_platform_event now returns invoke_hook(...) results, and the callback path does for result in results or []. If any observer hook for gateway_platform_event returns a non-iterable truthy value, the iteration raises — caught by the surrounding try/except (falls through to built-in handling), so it's safe, but a comment stating the "hooks return lists" contract would make the assumption explicit.
4. Minor: when a plugin raises after partially applying an action, query.answer is never called and the client can keep its spinner until the built-in fallback answers. Consider always answering (even with text=None) once a plugin signals handled, so the loading state is cleared deterministically.

[RSapeliuk]

Thanks for the review — addressed all four points in follow-up commit d481bce189:

• Normalize message_thread_id=0 to None consistently, including supergroup/forum classification.
• Document reserved built-in callback prefixes in the callback_query contract.
• Normalize single/tuple hook returns at the gateway boundary; callback adapters still receive a list of action envelopes.
• Acknowledge handled callbacks before applying the edit, with a regression test covering malformed edit data so Telegram's loading spinner is cleared deterministically.

Verification: 41 passed for tests/gateway/test_gateway_platform_event_hook.py; compileall and git diff --check also pass.