Skip to content

Allow specifying privileged intents in info.json - #6829

Open
Jackenmen wants to merge 15 commits into
Cog-Creators:V3/developfrom
Jackenmen:downloader-privileged-intents
Open

Jackenmen wants to merge 15 commits into
Cog-Creators:V3/developfrom
Jackenmen:downloader-privileged-intents

Conversation

@Jackenmen

@Jackenmen Jackenmen commented Nov 13, 2026 •

Copy link
Copy Markdown
Member

Description of the changes

This PR adds new optional_privileged_intents and required_privileged_intents keys to cog info.json that specify the privileged intents that the cog needs. The required ones block the cog from being installed, while optional ones serve mostly as metadata that may be presented to the user to let them know that some functionality may be unavailable.
optional_privileged_intents can only be specified, if required_privileged_intents is specified too and Downloader will ignore it, if it appears on its own.
The internal Downloader API checks required_privileged_intents in order to prevent install/update of a cog with missing required intents. Everything else (default "required" privileged intents and optional privileged intents) is handled entirely through Downloader cog's UI as it's informational-only.
[p]cog info lists optional and required privileged intents along with the statement about the reason it's needed.

Link to rendered info.json documentation:
https://red-discordbot--6829.org.readthedocs.build/en/6829/guide_publish_cogs.html#keys-specific-to-the-cog-info-json-case-sensitive

There are some things that may still need to be considered:

  • Should we let the user know when the required privileged intents changed when the bot has them enabled?
  • Should we let the user know when the optional privileged intents changed (and if so, should we do that when the bot has them enabled too?)?
  • Should we have some command for listing installed cogs grouped by the intent they use (required/optional) along with the reason to help the user grasp what uses intents in their bot?

Have the changes in this PR been tested?

No

@Jackenmen Jackenmen added this to the 3.5.25 milestone Nov 13, 2026
@Jackenmen Jackenmen changed the title Allow specifying optional/required privileged intents in info.json Allow specifying privileged intents in info.json Nov 13, 2026
@github-actions github-actions Bot added Category: Docs - For Developers This is related to developer (cog creator) documentation. Docs-only labels Nov 13, 2026
@Jackenmen
Jackenmen force-pushed the downloader-privileged-intents branch from 2f43ebf to 473d2c7 Compare November 15, 2026 07:11
@github-actions github-actions Bot added Category: Meta This is related to the repository maintenance. Category: Core - Downloader This is related to the internal Downloader APIs. and removed Docs-only labels Nov 15, 2026
@Jackenmen
Jackenmen force-pushed the downloader-privileged-intents branch from 9a943ac to c946378 Compare November 15, 2026 09:29
@github-actions github-actions Bot added the Category: Core - Command-line Interfaces This is related to Red's CLIs (redbot, redbot-launcher, redbot-setup). label Nov 15, 2026
@Jackenmen
Jackenmen force-pushed the downloader-privileged-intents branch from c946378 to 3db7cb2 Compare November 15, 2026 16:03
@github-actions github-actions Bot added the Category: Cogs - Downloader This is related to the Downloader cog. label Nov 15, 2026
@Jackenmen
Jackenmen force-pushed the downloader-privileged-intents branch 4 times, most recently from 2c368d0 to 9670279 Compare November 15, 2026 16:28
@Jackenmen Jackenmen added the Type: Feature New feature or request. label Nov 15, 2026
@Jackenmen
Jackenmen force-pushed the downloader-privileged-intents branch 2 times, most recently from 5befef8 to 72a6d57 Compare November 15, 2026 16:55
@Jackenmen
Jackenmen marked this pull request as ready for review November 15, 2026 16:56
@Jackenmen
Jackenmen force-pushed the downloader-privileged-intents branch from 72a6d57 to f1988c6 Compare November 15, 2026 17:07
@Jackenmen
Jackenmen force-pushed the downloader-privileged-intents branch from f1988c6 to f02b765 Compare November 16, 2026 16:55
@github-actions github-actions Bot added the Category: Core - Other Internals This is related to core internals that don't have a dedicated label. label Nov 16, 2026
@Jackenmen

Copy link
Copy Markdown
Member Author

Something I'm wondering is whether these two keys are really enough metadata. One common case is text-based commands - you could argue that any cog that has those can take advantage of the Message Content Intent so does that mean the cog should list that intent as optional? I don't think it would be at all helpful, if almost all cogs listed "message_content" in their optional_privileged_intents stating they can use it for their text-based commands.
I imagine we can avoid this from happening with proper documentation (the one that's currently in this PR is not enough) but, should we still have some way for cogs to indicate in their info.json that they have or don't have text-based and/or slash commands? Would that be useful?

@EternalllZM

Copy link
Copy Markdown
Contributor

Considering that commands can be issued via --mentionable (or setting prefix to bot mention) without message intent, I would say to lean towards "message_content" in info.json being used for features that are unrelated to command issuance.

Using prefix commands as justification for an intent request just leads to automatic denial, so Red should follow that guideline as well in terms of design.

should we still have some way for cogs to indicate in their info.json that they have or don't have text-based and/or slash commands?

Only if it means the entire cog can be controlled through that method. Does "has slash commands" imply you can ignore prefix commands entirely and the cog works entirely? Things to consider.

@Jackenmen
Jackenmen force-pushed the downloader-privileged-intents branch from d9be52d to e50441b Compare November 20, 2026 12:43
@Jackenmen
Jackenmen force-pushed the downloader-privileged-intents branch from e50441b to ebbe54a Compare November 20, 2026 13:15
@Jackenmen

Copy link
Copy Markdown
Member Author

I have now added a [p]cog intents command that lists all installed cogs grouped by their privileged intent and whether they're required.
Output looks like this:
image

We may want to have some recommendation on how we want the statements to look like - above it's not even a complete sentence, nor is it particularly detailed but is that still good enough as long as it mentions every feature that needs the intent? In particular, this is supposed to help the user to fill out the privileged intents request form - is it good enough for that?

@Jackenmen

Jackenmen commented Nov 20, 2026 •

Copy link
Copy Markdown
Member Author

Now that I'm thinking about it, I'm not sure whether it makes sense for missing information about required intents to mean that the cog is treated as requiring both whenever it's presented, if we ignore the text-based commands use case. Presenting such cogs as likely requiring guild members intent (but not message content intent) might make more sense but it probably would make most sense to say they likely require at least one of those two.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Category: Cogs - Downloader This is related to the Downloader cog. Category: Core - Command-line Interfaces This is related to Red's CLIs (redbot, redbot-launcher, redbot-setup). Category: Core - Downloader This is related to the internal Downloader APIs. Category: Core - Other Internals This is related to core internals that don't have a dedicated label. Category: Docs - For Developers This is related to developer (cog creator) documentation. Category: Meta This is related to the repository maintenance. Type: Feature New feature or request.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants