134 lines
4.4 KiB
Markdown
134 lines
4.4 KiB
Markdown
# Communication
|
|
|
|
This document describes the trigger rules, the trust model, the commands, the trigger log, the
|
|
context cache, and the response policy.
|
|
|
|
## Trigger rules
|
|
|
|
A message is a trigger when both conditions are true:
|
|
|
|
- The author is trusted. The owner counts as trusted.
|
|
- One of these conditions is true:
|
|
- The message is a one-to-one DM to the puppet.
|
|
- The message mentions the puppet in a guild channel or a group DM.
|
|
|
|
All other messages are ignored. Untrusted messages do not enter the log at this time. The daemon
|
|
ignores bots and its own messages.
|
|
|
|
## 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 more user IDs.
|
|
- The owner controls the trust list. Commands from other users do not change the list.
|
|
|
|
## Commands
|
|
|
|
The owner sends commands from Discord. In a DM, 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 reply follows the response policy.
|
|
|
|
## Response policy
|
|
|
|
The policy decides where a reply goes. Sensitive replies go by DM.
|
|
|
|
| Setting | Meaning | Default |
|
|
| --- | --- | --- |
|
|
| `defaultMode` | The mode for normal replies: `channel` or `dm` | `channel` |
|
|
| `sensitiveCommands` | Commands that always reply by DM | `whitelist`, `config` |
|
|
| `overrides` | A per-command mode | empty |
|
|
|
|
Rules:
|
|
|
|
- An override wins over the sensitive list. The sensitive list wins over the default mode.
|
|
- A DM reply failure does not fall back to the origin channel. The daemon logs the error only.
|
|
- Read the policy with `get_puppet_config`. Change it with `set_puppet_config`.
|
|
|
|
## Trigger log
|
|
|
|
The log has two ring buffers.
|
|
|
|
| Buffer | Limit | Content |
|
|
| --- | --- | --- |
|
|
| Trusted | 100 entries | Triggers from the owner and trusted users |
|
|
| Untrusted | 30 entries | Reserved. No triggers enter this buffer at this time. |
|
|
|
|
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 looks like a command |
|
|
| `context` | Prior messages. Present on mention triggers. |
|
|
|
|
## Context
|
|
|
|
The daemon collects prior messages for a mention trigger. Direct messages do not need context.
|
|
|
|
- Message limit: `contextMessages`, default 15.
|
|
- Character limit: `contextChars`, default 4000.
|
|
- The lower limit stops the collection.
|
|
- The content is the message text and the attachment file names. Media bodies stay on Discord.
|
|
- The trigger message is not part of its own context.
|
|
|
|
The cache makes the fetch small.
|
|
|
|
1. The daemon reads the newest cached message ID for the channel.
|
|
2. It fetches messages after that ID. On the first run, it fetches the newest messages.
|
|
3. It merges the new messages into the cache.
|
|
4. It assembles the context from the merged list.
|
|
|
|
Cache settings:
|
|
|
|
| Setting | Default |
|
|
| --- | --- |
|
|
| `VESKSLOP_CACHE_DIR` | `<tmp>/veskslop-cache` |
|
|
| `VESKSLOP_CACHE_MAX_BYTES` | 50 MiB |
|
|
| Messages per channel | 200 |
|
|
|
|
Eviction removes the least recently written channel files until the folder fits the size limit.
|
|
|
|
## Event flow
|
|
|
|
1. The client receives a `MESSAGE_CREATE` gateway event.
|
|
2. The core normalizes the event.
|
|
3. The core bridge pushes the event to the daemon.
|
|
4. The daemon applies the trigger rules.
|
|
5. The daemon collects context for a mention trigger.
|
|
6. The daemon adds the entry to the log.
|
|
7. The daemon runs a trusted command and replies through the response policy.
|
|
|
|
## State file
|
|
|
|
The daemon stores the owner ID, the trust list, and the config 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 or a command
|
|
|
|
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` and `pnpm test:cache`.
|