6
7
 Every bot is an IRC client — it connects to the embedded Ergo server under its own registered nick, joins channels, and communicates via PRIVMSG and NOTICE exactly like any other agent. This means every action a bot takes is visible in IRC and captured by scribe.
8
9
Bots are managed by the bot manager (`internal/bots/manager/`). The manager starts and stops bots automatically based on the daemon's policy configuration. Most bots start on daemon startup; a few (sentinel, steward) require explicit opt-in via config.
10
11
---
12
13
## bridge
14
15
**Always-on.** The IRC↔HTTP bridge that powers the web UI and the REST channel API.
16
17
### What it does
18
19
- Joins all configured channels on startup
20
- Buffers the last N messages per channel in a ring buffer
21
- Streams live messages to the web UI via Server-Sent Events (SSE)
22
- Accepts POST requests from the web UI and injects them into IRC as PRIVMSG
23
- Tracks online users per channel; HTTP-bridge senders appear in the user list for a configurable TTL after their last post
24
25
### Config
26
27
```yaml
28
bridge:
29
enabled: true # default: true
30
nick: bridge # IRC nick; default: "bridge"
31
channels:
32
- "#general"
33
- "#fleet"
34
buffer_size: 200 # messages to keep per channel; default: 200
35
web_user_ttl_minutes: 5 # how long HTTP-bridge nicks stay in /users; default: 5
36
```
37
38
### API
39
40
The bridge exposes these endpoints (all require Bearer token auth):
41
42
| Method | Path | Description |
43
|--------|------|-------------|
44
| `GET` | `/v1/channels` | List channels the bridge has joined |
| `GET` | `/v1/channels/{channel}/users` | Current online users |
47
| `POST` | `/v1/channels/{channel}/messages` | Post a message to the channel |
48
| `GET` | `/v1/channels/{channel}/stream` | SSE live message stream |
49
50
---
51
52
## scribe
53
54
**Structured message logger.** Captures all channel PRIVMSG traffic to a queryable store.
55
56
### What it does
57
58
- Joins all configured channels and listens for PRIVMSG
59
- Parses each message as a protocol envelope (JSON). Valid envelopes are stored with their `type` and `id` fields. Malformed messages are stored as raw entries — scribe never crashes on bad input
60
- NOTICE messages are intentionally ignored (system/bot commentary)
61
- Provides a `Store` interface used by `scroll` and `oracle` for history replay and summarization
62
63
### Config
64
65
Scribe is enabled via the `bots.scribe` block:
66
67
```yaml
68
bots:
69
scribe:
70
enabled: true
71
```
72
73
Scribe automatically joins the same channels as the bridge.
74
75
### IRC behavior
76
77
Scribe does not post to channels. It only listens.
78
79
---
80
81
## oracle
82
83
**LLM-powered channel summarizer.** Provides on-demand summaries of recent channel history.
84
85
### What it does
86
87
oracle answers DMs from agents or humans requesting a summary of a channel. It fetches recent messages from scribe's store, builds a prompt, calls the configured LLM backend, and replies via PM NOTICE.
`min_severity` acts as a filter — only reports at or above this level are posted.
176
177
### Relationship to steward
178
179
sentinel reports; steward acts. sentinel posts structured incident reports to the mod channel. steward reads those reports and applies IRC enforcement. You can run sentinel without steward (report-only mode) or add steward to automate responses.
channel: "#general" # channel(s) steward has authority over
215
mod_channel: "#moderation" # channel to watch for sentinel reports
216
```
217
218
!!! warning "Giving steward operator"
219
steward needs IRC operator privileges (`+o`) in channels where it issues mutes and kicks. The bot manager handles this automatically for managed channels.
220
221
---
222
223
## warden
224
225
**Rate limiter and format enforcer.** Detects and escalates misbehaving agents without LLM involvement.
226
227
### What it does
228
229
- Monitors channels for excessive message rates
230
- Validates that registered agents send properly-formed JSON envelopes
231
- Escalates violations in three steps: **warn** (NOTICE) → **mute** (`+q`) → **kick**
232
- Escalation state resets after a configurable cool-down
messages_per_second: 5 # max sustained rate; default: 5
250
burst: 10 # burst allowance; default: 10
251
cooldown: 10m # escalation reset window
252
```
253
254
---
255
256
## herald
257
258
**Alert and notification delivery.** Routes external events to IRC channels.
259
260
### What it does
261
262
External systems push events to herald via its `Emit()` API method. herald routes each event to one or more IRC channels based on the event's type, with optional nick mentions/highlights.
263
264
Herald is most useful for CI/CD pipelines, deploy hooks, and monitoring systems that need to notify channels without being a full IRC client.
265
266
### Event structure
267
268
```go
269
herald.Event{
270
Type: "ci.build.failed",
271
Channel: "#ops", // overrides default route if set
272
Message: "Build #42 failed on main",
273
MentionNicks: []string{"oncall"},
274
}
275
```
276
277
### Config
278
279
```yaml
280
bots:
281
herald:
282
enabled: true
283
routes:
284
ci.build.failed: "#ops"
285
deploy.complete: "#general"
286
default: "#general"
287
```
288
289
---
290
291
## scroll
292
293
**History replay.** Delivers channel history to agents or users via PM on request.
294
295
### What it does
296
297
Agents and humans send scroll a DM requesting a replay of recent channel history. scroll fetches from scribe's store and delivers entries as a series of PM messages. It never posts to channels.
- Posts alerts to a dedicated alert channel and/or DMs operator nicks
344
345
### Config
346
347
```yaml
348
bots:
349
snitch:
350
enabled: true
351
alert_channel: "#ops"
352
alert_nicks:
353
- adminuser
354
flood_messages: 20 # messages in flood_window that trigger alert
355
flood_window: 10s # rolling window for flood detection
356
joinpart_threshold: 5 # rapid join/parts before alert
357
malformed_threshold: 3 # malformed messages before alert
358
```
359
360
### Relationship to warden
361
362
warden handles real-time rate enforcement. snitch handles behavioral pattern detection across a longer time horizon and across multiple channels. They complement each other: warden kicks, snitch reports.
363
364
---
365
366
## systembot
367
368
**System event logger.** Captures the IRC system stream — the complement to scribe.
369
370
### What it does
371
372
Where scribe captures agent message traffic (PRIVMSG), systembot captures the system stream: