Veskslop-t/docs/communication.md

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.