feat(gateway,skills): unified skill trigger framework with Discord components

[0xarkstar]

Unified skill trigger framework — resolver + reactions + mentions + Feishu

Status update (2026-05-19)

Rebased onto current upstream/main HEAD 16abb74ea (post-Atropos-removal + post-clarify-buttons-salvage). 20 commits, 132/132 trigger framework tests green.

Discord button wiring deferred to PR #19413 (TerminalSausage, "interactive components — buttons, select menus, REST + WebSocket paths"), which the maintainer is salvaging onto current main. To avoid an on_interaction handler conflict (discord.py allows only one registered handler per event) and reduce review surface, this PR's button-specific wiring was removed in the "refactor: defer Discord button wiring to PR #19413" commit.

The metadata.hermes.triggers.button schema and the resolver's button matcher are retained as framework extension points so a follow-up PR can connect PR #19413's component dispatch into resolve_event_skills('button', payload, skills) — completing the round-trip skill declaration → component emission → click → skill dispatch.

Adjacent upstream landing — clarify-as-buttons: PR #19249 (LeonSGP43) was salvage-merged into main on 2026-05-13 as commit 1dca6a696 (also tracked as PR #25485). That work is complementary to this PR — it adds a Discord-specific ClarifyChoiceView for the existing clarify tool; this PR provides the cross-adapter resolver substrate that lets any skill declare button/reaction/mention triggers via frontmatter. No code overlap (verified during rebase).

TL;DR

opt-in metadata.hermes.triggers schema in skill frontmatter + adapter-agnostic event resolver + Discord composition handler that routes inbound reactions and mentions to skills declaring matching triggers + 2 outbound reaction tools. Feishu reaction routing uplifted to the same resolver with broadcast fallback for skills without explicit triggers. Matrix is left for follow-up.

Closes: #3879 (skill trigger keywords RFC) · #19111 (Discord clarify-as-buttons — partial; button emission via #19413)
Closes (partial): #22365 (Discord reaction emoji customization — outbound lifecycle config separately tracked in #22100)
Supersedes: #8379 (Discord inbound reaction routing — generalized in this PR)
Defers to #19413: button emission + interaction dispatch (this PR retains the resolver-side button trigger as a bridge hook point)
Issue: #503 Platform-Native Rich Interactions RFC — Discord reaction/mention lanes addressed; button lane addressed by #19413; Telegram/Slack/Matrix lanes remain open as follow-ups.

Production deployment

This branch is currently the production runtime for BlueNode (Hermes profile on OCI ARM64 Graviton) — operations Discord bot for Inha University's blockchain club. Continuously deployed since 2026-04-27 (~22 days at time of writing).

Multiple commits emerged directly from operating that bot:

• cache-first reaction author lookup — added after observing fetch_message round-trips dominating reaction event latency
• reactions config bridge fix — added after dict-form yaml discord.reactions: {inbound_routing: true} was silently disabling routing in production
• event counters for filter decisions — production observability
• mention routing wiring — production use case of skill resolution on @mentions

Architecture (in one diagram)

graph LR
  A[skill frontmatter<br/>metadata.hermes.triggers] -->|skill_utils.py<br/>parser| B[skill_resolver.py<br/>resolve_event_skills]
  D[on_raw_reaction_*<br/>discord.py] -->|reaction| H[discord_interactions.py<br/>handler]
  E[_handle_message<br/>discord.py] -->|mention| H
  F[_handle_reaction_event<br/>feishu.py] -->|reaction| B
  H --> B
  B --> G[adapter.handle_message<br/>auto_skill=&lt;matched&gt;]
  P[PR #19413<br/>component dispatch] -.->|future bridge| B

Loading

The resolver is gateway/skill_resolver.py (pure function, no self, no platform imports). Adapters call resolve_event_skills(event_type, payload, skills) and dispatch on the result. Adding a new adapter = wire its event handler to the same resolver call — no resolver changes needed.

Defensive note (mirrors review feedback on PR #19413)

This PR's reacted-message cache lookup (_connection._messages) is a discord.py internal — wrapped in try/except (AttributeError, KeyError, TypeError) so a minor-version rename falls through to fetch_message silently rather than breaking reaction routing. Pattern preemptively applied per maintainer's #19413 review #2 (which flagged _view_store._views for the same defensive treatment).

Concrete changes

Frontmatter parser (agent/skill_utils.py)

• New: extract_skill_triggers, derive_implicit_triggers, get_skill_triggers (pure functions).
• Schema α: type-keyed dict — mention, slash, button, reaction, cron each with their own field shape. Button trigger type retained as extension point for the future bridge to PR feat(discord): interactive components — buttons, select menus, REST + WebSocket paths #19413.

Adapter-agnostic resolver (gateway/skill_resolver.py, new)

• resolve_event_skills(event_type, payload, skills) -> List[str] — pure function.
• Matchers per event_type: button (custom_id fnmatch, ready for feat(discord): interactive components — buttons, select menus, REST + WebSocket paths #19413 bridge), reaction (emoji exact + optional channel_filter + age_limit), mention (regex match), slash (name exact).
• has_explicit_triggers(skills) — cached helper used by Feishu BC fork.

Discord interactions handler (gateway/platforms/discord_interactions.py, new)

• DiscordInteractionsHandler — composition handler. Receives on_raw_reaction_add/remove and handle_inbound_mention calls from the Discord adapter.
• handle_inbound_reaction(payload, action): cache-first author lookup (with defensive try/except on discord.py internals) → resolver dispatch.
• handle_inbound_mention(message, normalized_text): routes mentions through the resolver; caller can early-return when no match.
• make_skill_custom_id / is_skill_custom_id: canonical skill_<name>_<action> helpers retained as the bridge's hook points for the future PR connecting feat(discord): interactive components — buttons, select menus, REST + WebSocket paths #19413's component dispatch to this resolver.

Discord adapter wiring (gateway/platforms/discord.py)

• __init__: instantiate DiscordInteractionsHandler with _build_skill_provider().
• Intents: conditional intents.reactions = True opt-in via config.extra.reactions.inbound_routing (default false).
• connect(): register on_raw_reaction_add/remove ONLY if inbound_routing flag is True. Mention routing fires from _handle_message (already in the normal message path).
• Button on_interaction registration removed in this PR — that surface is owned by PR feat(discord): interactive components — buttons, select menus, REST + WebSocket paths #19413.
• Existing slash commands, ExecApprovalView, UpdatePromptView, ModelPickerView all UNTOUCHED.

Feishu BC (gateway/platforms/feishu.py)

• _handle_reaction_event calls resolve_event_skills('reaction', payload, skills) BEFORE building the synthetic text event.
• BC fork: matched → matched dispatch · empty + no triggers exist anywhere → broadcast (preserves existing behavior) · empty + triggers exist → skip.

Outbound reaction tools

• tools/discord_reaction_tool.py — discord_add_reaction + discord_remove_reaction. Async, lazy import discord, structured error returns. _remove_reaction passes client.user so it removes the bot's own reaction (not other users'). Wraps discord.NotFound / Forbidden / HTTPException / generic Exception structurally.

Note: discord_send_button_message was removed; outbound button emission is provided by PR #19413's send_message tool extension.

Latent bug fix: dict-form discord.reactions config bridge

The yaml form discord.reactions: {enabled: true, inbound_routing: true} was previously stringified by gateway/config.py (str(reactions).lower() → garbage env var) and never bridged to PlatformConfig.extra, silently disabling both outbound 👀✅❌ emoji feedback AND the new inbound routing. Fix splits cleanly:

• bool form → legacy DISCORD_REACTIONS env var
• dict form → extra.reactions (Track 1 routing)

Backward-compat preserved for both.

Testing

pytest tests/agent/test_skill_utils_triggers.py \
       tests/gateway/test_skill_resolver.py \
       tests/gateway/test_discord_interactions.py \
       tests/gateway/test_discord_inbound_reactions.py \
       tests/gateway/test_feishu_reactions_bc.py \
       tests/tools/test_discord_reaction_tool.py \
       tests/tools/test_registry.py \
       tests/gateway/test_discord_event_counters.py \
       tests/gateway/test_reaction_cache_first.py \
       tests/gateway/test_mention_routing.py \
       -n auto
# 132/132 passed

Both -n auto (parallel) and -n 0 (serial) modes pass.

Broader regression check: pytest tests/gateway/ tests/tools/ — env-only failures (missing optional psutil, faster_whisper, kittentts deps), confirmed identical on plain upstream/main.

Backward compatibility

• Skills WITHOUT triggers: frontmatter are parsed unchanged.
• Feishu broadcast fallback preserved for the no-explicit-triggers corpus.
• intents.reactions = True is opt-in via config.extra.reactions.inbound_routing (default false).
• No new slash commands registered.
• Existing internal Views (ExecApprovalView, UpdatePromptView, ModelPickerView) keep their own dispatch.

Salvage-friendly + split offer

This PR is structured for salvage: each commit is independently revertable, the resolver is decoupled from adapters, and I'm happy to rewrite/rescope on maintainer feedback within 24h.

If preferred, I can split this PR further into 2 smaller PRs:

• Core foundation (~600 LoC): skill_utils.py parser + skill_resolver.py + their tests
• Discord + Feishu integration (~900 LoC): handler + adapter wiring + reaction tools + Feishu BC + config bridge fix + docs

Let me know which approach is easier to land.

Status

• 20 commits (1 became no-op after rebase — upstream replaced the manual builtin-tool set in test_registry.py with dynamic discovery, so our hardcoded-list edit auto-dropped)
• 132 tests pass parallel + serial · zero regressions in adjacent gateway/agent suites
• Rebased onto upstream/main HEAD 16abb74ea (2026-05-19) — post-Atropos-removal (chore: remove Atropos RL environments and tinker-atropos integration #26106) + post-clarify-buttons salvage (feat(discord): render clarify choices as buttons #25485)
• mergeable=MERGEABLE
• Production-deployed since 2026-04-27 on BlueNode (~22 days)

🤖 Generated with Claude Code

[0xarkstar]

Friendly nudge — this PR has been open for a few days without review. Happy to address any maintainer feedback or rebase if upstream has moved.

For context, I've also opened a complementary PR #18255 (cron token-leak mitigation) which is independent of this one — it does not touch the unified trigger framework files and can be reviewed/merged in either order.

Thanks for the maintenance work on this project!

[0xarkstar]

Closing this PR. Upstream has since shipped native equivalents of what this PR set out to do, and the code it patches has been replatformed:

1. Discord was replatformed to a plugin architecture (plugins/platforms/discord/), removing gateway/platforms/discord.py / discord_interactions.py that this PR builds on — the diff can no longer be rebased onto current main (same situation that closed feat: add Gemma 4 tool call parser #7449).
2. Channel→skill routing now exists natively: resolve_channel_skills() in gateway/platforms/base.py with channel_skill_bindings config (see tests/gateway/test_discord_channel_skills.py), covering the auto-skill dispatch use case this PR's mention/reaction trigger routing targeted.
3. Discord components (buttons / clarify flows) also landed natively (tests/gateway/test_discord_clarify_buttons.py, tools/slash_confirm.py).

The remaining piece not covered upstream — cron token-leak mitigation — lives in #18255, which I've rebased onto current main and keeps standing on its own.

Thanks for the earlier triage; happy to re-open a focused follow-up if a gap in the native trigger handling turns up.