From b7b7a94e0ffa23267422bc90948c5cbbba930e5b Mon Sep 17 00:00:00 2001 From: gnuxie Date: Tue, 2 Sep 2025 15:14:39 +0100 Subject: [PATCH 1/3] In room command prompts. --- proposals/0000-in-room-command-prompts.md | 131 ++++++++++++++++++++++ 1 file changed, 131 insertions(+) create mode 100644 proposals/0000-in-room-command-prompts.md diff --git a/proposals/0000-in-room-command-prompts.md b/proposals/0000-in-room-command-prompts.md new file mode 100644 index 00000000000..7432627a9b8 --- /dev/null +++ b/proposals/0000-in-room-command-prompts.md @@ -0,0 +1,131 @@ +# MSC0000: Prompts and partial commands for in room commands. + +When composing a command, a user may not know what to provide for as an argument to a command. In +this situation, it is desirable for the client to be able to prompt the user with suggestions for +the argument. + +## Proposal + +### The promptable property on parameters + +Within the parameter description for a command argument, we specify a new property `promptable` +which when given the value `true` signals to clients that they may send a _partial commmand_ to the +bot to receive suggestions for the argument. + +### The `m.bot.command_prompt` event + +Consider the following command description under the context of MSC4332 and MSC4333. + +```jsonc +{ + "sigil": "!", + "commands": [ + { + "syntax": "draupnir takedown {entity} {list} {reason}", + "arguments": { + "entity": { + "m.text": [{"body": "The entity to ban"}], + }, + "reason": { + "m.text": [{"body": "The reason for the ban"}], + }, + "list": { + "m.text": [{"body": "The policy list to ban the user on"}], + "promptable": true, + }, + }, + "description": { + "m.text": [{"body": "Ban a user in all protected rooms"}], + }, + }, + ] +} +``` + +When a client is composing the argument for `list`, if the user is unable to make a decision for the +policy list, the client can send the following `m.bot.command`: + +```jsonc +{ + "m.bot.command": { + "syntax": "draupnir takedown {entity} {list} {reason}", + "arguments": { + "entity": { + "id": "!room:example.org", + "via": ["second.example.org"] + }, + } + } +} +``` + +The bot will then respond with an event containing an `m.bot.command_prompt` mixin: + + +```jsonc +{ + "body": "Please select a policy room", + "m.bot.command_prompt": { + "syntax": "draupnir takedown {entity} {list} {reason}", + "arguments": { + "entity": { + "id": "!room:example.org", + "via": ["second.example.org"] + }, + }, + "suggested_arguments": { + "list": { + "suggested": [ + { + "id": "!policyroom:example.com", + "via": ["second.example.com"] + }, + { + "id": "!fTjMjIzNKEsFlUIiru:neko.dev", + "via": ["neko.dev"] + } + ], + "default": { + "id": "!policyroom:example.com", + "via": ["second.example.com"] + } + } + } + } +} +``` + +It is desirable that a bot can send a prompt without any prior command, so that it is possible to +create notices which prompt action. + +### Client considerations + +Clients should allow prompts to be cancellable. + +## Potential issues + +None considered. + +## Alternatives + +### Reaction based prompts + +[Draupnir](https://github.com/the-draupnir-project/Draupnir) currently manages prompts manually by +embedding a mixin in a reply to a command event with suggestsions that can be selected by sending +a reaction that references the event. + +## Security considerations + +### Unsolicited prompt + +Clients need to take care to make sure that the sender of the prompt matches the bot for which the +command is intended to be sent to. Otherwise clients could be tricked into sending commands by other +users. + +## Unstable prefix + +`m.bot.command_prompt` -> `org.matrix.msc0000.command_prompt` + +## Dependencies + +This MSC builds on MSC4332 (which at the time of writing have not yet been accepted into the spec). From 42623749afa24f4d0f67c2c60b611fc0a2b1a780 Mon Sep 17 00:00:00 2001 From: gnuxie Date: Tue, 2 Sep 2025 15:19:19 +0100 Subject: [PATCH 2/3] 4340 --- ...oom-command-prompts.md => 4340-in-room-command-prompts.md} | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) rename proposals/{0000-in-room-command-prompts.md => 4340-in-room-command-prompts.md} (96%) diff --git a/proposals/0000-in-room-command-prompts.md b/proposals/4340-in-room-command-prompts.md similarity index 96% rename from proposals/0000-in-room-command-prompts.md rename to proposals/4340-in-room-command-prompts.md index 7432627a9b8..36d9a101c06 100644 --- a/proposals/0000-in-room-command-prompts.md +++ b/proposals/4340-in-room-command-prompts.md @@ -1,4 +1,4 @@ -# MSC0000: Prompts and partial commands for in room commands. +# MSC4340: Prompts and partial commands for in room commands. When composing a command, a user may not know what to provide for as an argument to a command. In this situation, it is desirable for the client to be able to prompt the user with suggestions for @@ -124,7 +124,7 @@ users. ## Unstable prefix -`m.bot.command_prompt` -> `org.matrix.msc0000.command_prompt` +`m.bot.command_prompt` -> `org.matrix.msc4340.command_prompt` ## Dependencies From f9781971d0ca24e3bf1850928219488d46aa462f Mon Sep 17 00:00:00 2001 From: gnuxie Date: Tue, 2 Sep 2025 15:21:03 +0100 Subject: [PATCH 3/3] typo in command. --- proposals/4340-in-room-command-prompts.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/4340-in-room-command-prompts.md b/proposals/4340-in-room-command-prompts.md index 36d9a101c06..3568a19b287 100644 --- a/proposals/4340-in-room-command-prompts.md +++ b/proposals/4340-in-room-command-prompts.md @@ -9,7 +9,7 @@ the argument. ### The promptable property on parameters Within the parameter description for a command argument, we specify a new property `promptable` -which when given the value `true` signals to clients that they may send a _partial commmand_ to the +which when given the value `true` signals to clients that they may send a _partial command_ to the bot to receive suggestions for the argument. ### The `m.bot.command_prompt` event