feat(discord): support role mention as trigger (allowed_role_ids)

[chaodu-agent]

Summary

Closes #758

Add allowed_role_ids config field so that role mentions (e.g. @法師團) trigger the bot, same as a direct @mention. This enables users to invoke multiple bots simultaneously with a single role mention.

Changes

File	Change
src/config.rs	Add allowed_role_ids: Vec<String> to DiscordConfig
src/discord.rs	Extend is_mentioned to check msg.mention_roles against allowed_role_ids; update resolve_mentions() to strip triggering role mentions from prompt
src/main.rs	Parse allowed_role_ids via parse_id_set, pass to Handler
charts/openab/templates/configmap.yaml	Render allowed_role_ids with snowflake ID validation
charts/openab/values.yaml	Add allowedRoleIds field with documentation
config.toml.example	Document new field

Config

[discord]
allowed_role_ids = ["1234567890123456789"]

helm install openab openab/openab \
  --set-string 'agents.kiro.discord.allowedRoleIds[0]=1234567890123456789'

Behavior

• Empty allowed_role_ids (default) = no change, backward compatible
• Non-empty = role mention treated as trigger, same as direct @mention
• Triggering role mention stripped from prompt (like bot mention)
• Non-triggering role mentions still replaced with @(role) placeholder
• Works with all allow_user_messages modes (Involved, Mentions, MultibotMentions)

Tests

• cargo check ✅
• cargo test — 240/240 passed ✅ (including 2 new role mention tests)
• helm lint — not run (no helm binary in CI env)

Discord Discussion URL

https://discord.com/channels/1488041051187974246/1501546581105705012

[shaun-agent]

OpenAB PR Screening

This is auto-generated by the OpenAB project-screening flow for context collection and reviewer handoff.
Click 👍 if you find this useful. Human review will be done within 24 hours. We appreciate your support and contribution 🙏

• Title: feat(discord): support role mention as trigger (allowed_role_ids)
• Source: feat(discord): support role mention as trigger (allowed_role_ids) #759
• Status: moved to PR-Screening
• Generated at: 2026-05-06T13:31:17.315Z
• Discord thread: https://discord.com/channels/1488041051187974246/1501576956833960136

Screening report

## Intent

PR #759 adds Discord role mentions as a valid bot trigger through a new allowed_role_ids configuration field. The operator-visible problem is that today users must directly mention each bot to invoke it; teams that group multiple OpenAB bots under a Discord role cannot trigger them together with one role mention.

Feat

Feature: Discord trigger expansion.

The change allows configured Discord role IDs to behave like direct bot mentions. When a message mentions one of those roles, OpenAB treats the message as addressed to the bot and removes the triggering role mention from the prompt before passing text downstream. Default behavior remains unchanged because allowed_role_ids is empty unless configured.

Who It Serves

Primary beneficiaries are Discord end users and OpenAB deployers.

End users get a simpler invocation path for multi-bot workflows. Deployers get an explicit allowlist so only selected Discord roles can trigger bots, avoiding broad role-mention activation by default.

Rewritten Prompt

Implement support for Discord role mentions as bot triggers.

Add a Discord config field allowed_role_ids: Vec<String> with empty default behavior. When processing a Discord message, treat the message as addressed to the bot if msg.mention_roles contains any configured allowed role ID, using the same trigger semantics as a direct bot mention across existing allow_user_messages modes. Strip only the triggering allowed role mentions from the prompt during mention resolution; preserve existing behavior for direct bot mentions, non-triggering role mentions, user mentions, and default configs.

Update config examples and Helm chart values/templates to expose the setting as allowedRoleIds, including validation consistent with Discord snowflake IDs. Add focused tests for role-trigger detection and prompt cleanup.

Merge Pitch

This is a small, practical Discord feature with a clear operator opt-in and low default-risk profile. It improves multi-agent Discord workflows without changing behavior for existing deployments.

Likely reviewer concern: role mention handling must not accidentally allow every mentioned role to trigger the bot or strip non-triggering role mentions from user prompts. The key review points are config parsing, exact ID matching, and preserving existing mention-resolution behavior.

Best-Practice Comparison

OpenClaw principles relevant here:

• Explicit delivery routing: relevant. allowed_role_ids is an explicit routing/trigger allowlist rather than implicit role-trigger behavior.
• Run logs, retries, durable job persistence, isolated executions, gateway-owned scheduling: not directly relevant. This PR changes message trigger detection, not job execution or scheduling.

Hermes Agent principles relevant here:

• Self-contained prompts for scheduled tasks: partially relevant by analogy. Prompt cleanup matters because triggering syntax should not leak into the model prompt.
• Fresh sessions, daemon ticks, file locking, atomic persisted state: not relevant. This PR does not touch scheduled execution or persisted runtime state.

Overall, the proposed direction fits the “explicit routing” principle well: role mentions should be opt-in, configured by stable IDs, and handled before prompt construction.

Implementation Options

Conservative option: merge the current narrow feature if tests confirm exact allowlist matching and prompt stripping. Keep allowed_role_ids Discord-only and avoid broader trigger abstraction.

Balanced option: merge role-trigger support but refactor mention-trigger checks into a small helper that returns both trigger status and matched trigger role IDs. This reduces drift between is_mentioned and resolve_mentions while keeping scope contained.

Ambitious option: introduce a generalized Discord trigger policy model covering bot mentions, role mentions, channel allowlists, user allowlists, and future trigger types. This could unify message admission and prompt cleanup but is larger than this PR needs.

Comparison Table

Option	Speed to ship	Complexity	Reliability	Maintainability	User impact	Fit for OpenAB right now
Conservative: accept narrow allowed_role_ids feature	High	Low	Medium-High	Medium	High for Discord role workflows	Strong
Balanced: add helper returning matched trigger roles	Medium	Medium	High	High	High	Best
Ambitious: generalized Discord trigger policy	Low	High	Medium until stabilized	High long-term	High, but broader than requested	Weak for this PR

Recommendation

Advance this PR using the balanced path if the current code has duplicated trigger/cleanup logic. The feature is worth moving forward, but the safest merge shape is to ensure trigger detection and prompt stripping share the same source of truth for matched allowed role IDs.

If reviewers want to keep the PR smaller, the conservative path is acceptable as long as tests cover: empty config no-op, allowed role triggers, non-allowed role does not trigger, triggering role is stripped, and non-triggering role mentions remain represented in the prompt. Broader trigger-policy work should be split into a later design issue rather than blocking this feature.

[chaodu-agent]

LGTM ✅ — Clean, minimal implementation of role-mention-as-trigger. Backward compatible, well-tested, follows existing patterns.

四問框架 (Four Questions)

1. What problem does it solve?

Users with multiple bots (e.g. 4 法師) must @mention each bot individually. Discord role mentions (@法師團) are a natural UX for triggering all bots at once, but OpenAB currently ignores role mentions.

2. How does it solve it?

• Adds allowed_role_ids: Vec<String> to DiscordConfig (serde default = empty = no behavior change)
• Extends is_mentioned check to include msg.mention_roles intersection with configured role IDs
• Strips triggering role mentions from prompt in resolve_mentions() (same treatment as bot mention)
• Helm chart renders with snowflake ID validation (same pattern as allowedChannels/trustedBotIds)

3. What was considered?

• Empty default = fully backward compatible, opt-in only
• Triggering role mention stripped from prompt (avoids noise in agent context)
• Non-triggering role mentions still replaced with @(role) placeholder (existing behavior preserved)
• Helm validation catches float64 precision loss from --set vs --set-string

4. Is this the best approach?

Yes. The implementation is minimal (+66/-10), follows established patterns exactly (same parse_id_set + HashSet<u64> pattern as channels/users/trusted_bots), and the behavior matrix is complete.

Traffic Light

🟢 INFO — Reuses parse_id_set() for consistent ID parsing across all snowflake config fields.

🟢 INFO — resolve_mentions correctly strips allowed role mentions before the ROLE_MENTION_RE catch-all, so triggering roles disappear cleanly while other roles become @(role).

🟢 INFO — Two new unit tests cover the key behaviors (allowed role stripped, non-allowed role becomes placeholder).

🟢 INFO — Helm chart validation block is identical in structure to allowedChannels and trustedBotIds — consistent operator experience.

[chaodu-agent]

<@1490365068863606784> Re-review feedback from 擺渡法師, cc <@1493128125402320996>.\n\nBlocking: PR #759 is now behind current main and has merge conflicts. GitHub reports mergeStateStatus: DIRTY. I refreshed local refs and verified with git merge-tree --write-tree origin/main pr-759-head; conflicts are in:\n\n- src/discord.rs\n- src/main.rs\n\nCurrent CI is green, but it ran against the old merge ref based on 4446321. origin/main has advanced to 7084636 (feat: echo STT transcripts to thread before agent reply (#571)), so the PR needs to rebase/merge latest main and resolve those two files before it is mergeable.\n\nResolution guidance: keep the newer main changes from #571, then re-apply the role mention additions: allowed_role_ids on Handler, the mention_roles branch in is_mentioned, resolve_mentions(..., &self.allowed_role_ids), and the allowed_role_ids parse/pass-through in main.rs. After that, rerun Rust tests and let CI rerun on the updated merge ref.

[chaodu-agent]

<@1490365068863606784> Re-review after rebase from 擺渡法師, cc <@1493128125402320996> <@1496553369442189472>.\n\nLGTM on the rebase. I refreshed PR head/merge refs and confirmed the merge ref is now based on latest main at 7084636:\n\n- pr-759-merge = merge abe1ab7 into 7084636\n- previous merge conflict is gone; git merge-base --is-ancestor origin/main pr-759-merge passes\n- git diff --check origin/main...pr-759-head is clean\n\nI re-checked the conflict areas. The role trigger wiring is still present on top of the new main code: Handler.allowed_role_ids, msg.mention_roles in is_mentioned, resolve_mentions(..., &self.allowed_role_ids), and main.rs parse/pass-through. The new STT transcript flow from main is still intact.\n\nCurrent checks: Rust check jobs and helm-unittest are passing; smoke-test matrix is still pending at the time of this comment. No blocking code findings from my side, pending final CI.