Veskslop/docs/communication.md

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.