**Migrated from GitHub issue icub3d/decentcom#77** **Original Author:** @icub3d **Original Date:** 2026-04-17T21:42:41Z --- # Feature: Reference Bots (modbot, welcomebot, auditbot) ## Overview Ship three reference bots under \`tools/bots/\` that demonstrate correct use of the bot SDK, provide working tooling for common server needs, and set the pattern third-party developers can follow. ## Background Per #68 and the bot-framework discussion: bots are the right tool for moderation beyond simple rate limits, onboarding, and audit/observability. Reference bots give open-server admins day-one tooling, validate the SDK against real use cases, and raise the quality bar for the third-party ecosystem. ## Requirements - [x] \`decentcom-modbot\`: detects obvious spam patterns (duplicate messages, link floods); takes configurable actions (warn / kick / ban). - [x] \`decentcom-welcomebot\`: greets new members in a configured channel, posts configurable rules. - [x] \`decentcom-auditbot\`: streams moderation events (kicks, bans, deletes) to a configurable external sink (file, webhook). - [x] Each bot is a separate binary under \`tools/bots/<name>/\`. - [x] Each bot reads config from a TOML file + env vars (12-factor). - [x] Each bot has a README explaining install and configuration. ## Design Each bot is an independent crate that uses the SDK (#76). Bots share no state; each is deployable on its own. ### Component Changes - New workspace members: \`tools/bots/modbot/\`, \`tools/bots/welcomebot/\`, \`tools/bots/auditbot/\`. ## Task List ### Phase 1: welcomebot (simplest, validates the SDK end-to-end) - [x] Scaffold crate. - [x] Config: channel ID, welcome template, optional rules message. - [x] Handler for \`on_member_join\`. - [x] README. ### Phase 2: modbot - [x] Scaffold crate. - [x] Config: detection rules (duplicate threshold, links-per-minute threshold) and action policy (warn / kick / ban). - [x] Handlers: \`on_message\`. - [x] Action execution via SDK helpers. - [x] README. ### Phase 3: auditbot - [x] Scaffold crate. - [x] Config: sink type (file | webhook), endpoint, event filter. - [x] Handler for moderation events (kick, ban, message delete, join, leave). - [x] README. ## Test List - [x] welcomebot: unit test for template interpolation. - [x] modbot: unit tests — duplicate detection, link flood detection, varied messages, link counting. - [x] auditbot: unit test — file sink appends JSON lines correctly. - [ ] welcomebot: integration test — member joins, welcome message appears in the configured channel. - [ ] modbot: integration test — user sends 10 duplicate messages, modbot issues a kick/ban. - [ ] auditbot: integration test — admin kicks a user, event appears in the sink. ## Open Questions - modbot detection logic: pluggable rule modules from v1 or monolithic first? (Recommendation: monolithic first, pluggable once we see real usage patterns.) - auditbot webhook format: generic JSON, Slack-compatible, or Matrix-compatible? (Recommendation: generic JSON; Slack/Matrix adapters can ship as separate bots.) ## Dependencies - Blocked by #75 (Bot Account Type). - Blocked by #76 (Bot SDK). - Related: #68 (modbot builds on velocity / timeout primitives).

icub3d commented

2026-04-26 16:46:12 +00:00

Owner

Migrated from GitHub issue icub3d/decentcom#77
Original Author: @icub3d
Original Date: 2026-04-17T21:42:41Z

Feature: Reference Bots (modbot, welcomebot, auditbot)

Overview

Ship three reference bots under `tools/bots/` that demonstrate correct use of the bot SDK, provide working tooling for common server needs, and set the pattern third-party developers can follow.

Background

Per #68 and the bot-framework discussion: bots are the right tool for moderation beyond simple rate limits, onboarding, and audit/observability. Reference bots give open-server admins day-one tooling, validate the SDK against real use cases, and raise the quality bar for the third-party ecosystem.

Requirements

`decentcom-modbot`: detects obvious spam patterns (duplicate messages, link floods); takes configurable actions (warn / kick / ban).
`decentcom-welcomebot`: greets new members in a configured channel, posts configurable rules.
`decentcom-auditbot`: streams moderation events (kicks, bans, deletes) to a configurable external sink (file, webhook).
Each bot is a separate binary under `tools/bots//`.
Each bot reads config from a TOML file + env vars (12-factor).
Each bot has a README explaining install and configuration.

Design

Each bot is an independent crate that uses the SDK (#76). Bots share no state; each is deployable on its own.

Component Changes

New workspace members: `tools/bots/modbot/`, `tools/bots/welcomebot/`, `tools/bots/auditbot/`.

Task List

Phase 1: welcomebot (simplest, validates the SDK end-to-end)

Scaffold crate.
Config: channel ID, welcome template, optional rules message.
Handler for `on_member_join`.
README.

Phase 2: modbot

Scaffold crate.
Config: detection rules (duplicate threshold, links-per-minute threshold) and action policy (warn / kick / ban).
Handlers: `on_message`.
Action execution via SDK helpers.
README.

Phase 3: auditbot

Scaffold crate.
Config: sink type (file | webhook), endpoint, event filter.
Handler for moderation events (kick, ban, message delete, join, leave).
README.

Test List

welcomebot: unit test for template interpolation.
modbot: unit tests — duplicate detection, link flood detection, varied messages, link counting.
auditbot: unit test — file sink appends JSON lines correctly.
welcomebot: integration test — member joins, welcome message appears in the configured channel.
modbot: integration test — user sends 10 duplicate messages, modbot issues a kick/ban.
auditbot: integration test — admin kicks a user, event appears in the sink.

Open Questions

modbot detection logic: pluggable rule modules from v1 or monolithic first? (Recommendation: monolithic first, pluggable once we see real usage patterns.)
auditbot webhook format: generic JSON, Slack-compatible, or Matrix-compatible? (Recommendation: generic JSON; Slack/Matrix adapters can ship as separate bots.)

Dependencies

Blocked by #75 (Bot Account Type).
Blocked by #76 (Bot SDK).
Related: #68 (modbot builds on velocity / timeout primitives).

icub3d

closed this issue
added the
type:feature

area:core

area:infra

status:complete
labels

Rows
Columns

Feature: Reference Bots (modbot, welcomebot, auditbot) #55