Rework core integration: validated capability layer, docs, and session state

2026-09-11 14:09:04 +02:00
parent 2a15f057df
commit e62d3007d8
33 changed files with 1897 additions and 612 deletions
@@ -0,0 +1,86 @@
+# Communication
+
+This document describes the trigger rules, the trust model, the commands, and the trigger log.
+
+## Trigger rules
+
+A message is a trigger when one of these conditions is true:
+
+- The message is a direct message to the puppet. A direct message is a one-to-one DM, not a group.
+- The message mentions the puppet. This applies in guild channels and group DMs.
+
+All other messages are ignored.
+
+## Trust model
+
+The puppet has one owner and a trust list.
+
+- The owner is always trusted. The default owner is `177117296140091393` (zzib).
+- The trust list holds additional user IDs.
+- A trusted user gets the 100-entry log. An untrusted user gets the 30-entry log.
+
+The owner controls the trust list. Commands from other users do not change the list.
+
+## Commands
+
+The owner sends commands from Discord. In a direct message, the text is the command. In a guild or
+a group DM, mention the puppet first.
+
+| Command | Effect |
+| --- | --- |
+| `whitelist list` | Show the owner and the trusted users. |
+| `whitelist add @user` | Add one or more users to the trust list. |
+| `whitelist remove @user` | Remove one or more users from the trust list. |
+
+Notes:
+
+- The owner cannot be removed.
+- The command accepts mentions and raw user IDs.
+- The daemon replies with a confirmation. The reply uses the same pacing as all other sends.
+
+## Trigger log
+
+The log has two ring buffers.
+
+| Buffer | Limit | Content |
+| --- | --- | --- |
+| Trusted | 100 entries | Triggers from the owner and trusted users |
+| Untrusted | 30 entries | Triggers from all other users |
+
+One entry holds these fields:
+
+| Field | Meaning |
+| --- | --- |
+| `id` | The message ID |
+| `channelId` | The channel ID |
+| `guildId` | The guild ID, or absent for a DM |
+| `authorId` | The author user ID |
+| `authorName` | The author username |
+| `content` | The raw message content |
+| `timestamp` | The message timestamp |
+| `trusted` | True for a trusted author |
+| `command` | The parsed command text, when the message is a command |
+
+## Event flow
+
+1. The client receives a `MESSAGE_CREATE` gateway event.
+2. The core renderer normalizes the event.
+3. The core bridge pushes the event to the daemon.
+4. The daemon applies the trigger rules.
+5. The daemon adds a qualifying message to the log.
+6. The daemon runs a trusted command, when the message is a command.
+
+## State file
+
+The daemon stores the owner ID and the trust list in JSON.
+
+- Default path: `poc/.veskslop-state.json`.
+- Override: `VESKSLOP_STATE_FILE`.
+- The trigger log is in memory only. The log resets at restart.
+
+## How to add a trigger rule
+
+1. Add the rule in `poc/src/puppet.ts`, in `handleEvent`.
+2. Keep the rule small and testable.
+3. Add a unit test in `poc/src/test-communication.ts` when the rule is pure logic.
+4. Run `pnpm test:comm`.