# discord

The `discord` extension gives a session its own Discord bot. Messages the bot may see reach the session through the daemon's event inbox (the same durable `mail` table and dispatcher webhooks use), and the session answers through the `discord` binding in its kernel. The extension is installed but **disabled by default**; enable it globally in `/extensions` to run bots and mount its HTTP service. A bot whose extension is off globally does not connect and reports state `disabled`.

The table initialiser only creates storage. Its `StartupPlugin` starts the bot manager after the extension schema transaction commits, before runtime readiness.

## Setup

1. In the Discord developer portal, create an application, open **Bot**, press **Reset Token** and copy the token. On the same page enable the **Message Content** intent; without it the gateway closes with 4014 and the bot fails with that reason.
2. Open the Discord page (`/discord`), press `ctrl+o`, and give the bot a name (1–64 characters), the session it belongs to (one bot per session), the token, and your own Discord user ID. To copy your ID, turn on Settings → Advanced → Developer Mode, then right-click yourself → Copy User ID. You, the owner, can always DM the bot.
3. Invite the bot with the page's invite URL (`ctrl+l` copies it): `https://discord.com/oauth2/authorize?client_id=<application_id>&scope=bot&permissions=274878024768`, which grants View Channel, Send Messages, Embed Links, Attach Files, Read Message History, Add Reactions and Send Messages in Threads. Before the bot's first READY, the application id is read from the token's first segment.
4. On the bot's Channels pane, choose what each channel delivers. Channels start **off**.

The token never leaves the daemon except into the bot process's environment. Listings and the kernel never include it.

## Channels and delivery

A `discord_channels` row means the bot sees that channel; no row means off. Each row sets a delivery:

- `turn` (end of turn): a message waits for a running turn to end, then everything that waited starts the next turn together. An idle session starts a turn at once.
- `tool` (after tool call): a message steers a running turn after its current tool call, or starts a turn when idle.

`mentions_only` delivers only messages that mention the bot user (`@everyone` does not count). Threads follow their parent channel's row. DMs are always delivered after the current tool call.

Other bots' messages are delivered like anyone's: other people's albedos live in these channels. There are no cooldowns. The bot's own messages are never delivered.

## DM whitelist

The owner and the people on the bot's allowed list may DM it. A DM from anyone else stores no letter; it creates or updates a **request** (username, a 200-character preview, last time, count; at most 50 per bot, oldest dropped). The DMs pane lists the owner, the allowed people, and the requests; allowing a request (`PUT .../dms/{user_id}`) removes it, and when no name is given and the bot is online the daemon looks the person's display name up. The owner cannot be removed.

## Ingest rules

For every message the bot process reports, in one store transaction:

1. The channel's cursor (newest message id seen, compared as integers) moves forward, for configured guild channels and their threads and for whitelisted DM channels.
2. A message from the bot user is ignored.
3. A DM from the owner or an allowed person becomes an `Event(AfterTool)` letter; any other DM becomes a request.
4. A guild message uses the row for its channel, else for its parent channel. Without one it is ignored. With `mentions_only` and no mention of the bot it is ignored. Otherwise it becomes `Event(AfterTool)` for `tool` and `Event(AfterTurn)` for `turn`.
5. The channel and the message are numbered (below). The letter id is `discord-<bot id>-<message id>`; a message whose letter exists already (a catch-up replay) stores nothing. Sender name is `discord`.

The letter body, which mail wraps as `<event id="…" from="discord">`:

```
[discord #<channel> in <server> · c<N>] @<username> (<nick or global name>, bot) · message <number>[ · reply to <number>] · <time>
<content, or "(no text)">
attachment: <filename> <url>
```

DMs start with `[discord dm · c<N>] @<username> (<global name>)`. The parenthesis is left out when there is no display name and says `bot` only for bots. A channel whose name is not known is `a channel`. Content past 16,384 characters is cut. Attachment URLs are the CDN links; no jump link or snowflake appears anywhere in the body. `<time>` is when Discord says the message was sent, in the daemon machine's local time with its UTC offset (`10:37am UTC-4`, `UTC+5:30`, `UTC`), with the date in front (`Oct 22 9:05pm UTC-4`) when that was not today there (`albedo_discord:local_stamp`); a reaction is stamped when it arrived.

## Handles and numbers

The session never handles a snowflake. A channel the bot sees is numbered `c1`, `c2`, … in the order the daemon first met it (`discord_channel_refs`, per bot), and every message the daemon delivers, sends, reads with `history`, or sees reacted to is numbered 1, 2, … within its channel, in the order it was first met (`discord_message_refs`, per bot, with the author, their name and the first 80 characters of the text, for reactions to quote). Both tables belong to the bot and go with it; a number means the same after a restart. Numbers follow first sight, not time: older messages read later with `history` get larger numbers than newer ones already met.

Wherever the binding takes a channel it accepts the handle (`c3`), the name (`general`, `#general`, `Server/general` when two servers share one), or a snowflake; `Server/general` and the name are matched against channels the daemon has numbered, which includes every configured channel. A name two channels share fails and lists their handles. Wherever it takes a message it accepts the number (`413`, `#413`) or a snowflake. A number the channel does not have fails with `not_found`. `send`, `history` and `react` still work only where the bot sees (below).

## Incoming reactions

Reaction additions arrive as inbox events naming who reacted, the emoji, and the message:

```
[discord reaction #<channel> in <server> · c<N>] @<username> (<nick or global name>) reacted <emoji> to your message <number>: "<start of its text>" · <time>
```

`your message` is a message the bot wrote; for another author it is `<name>'s message`, and when the daemon never recorded the author it is `message`. The quoted text is what the daemon recorded when it met the message (delivered, sent or read through `history`); a message it never met has no quote. DMs are `[discord dm reaction · c<N>]`. The bot's own reactions are ignored. In DMs, only the owner and allowed users reach the session; refused reactions do not create DM requests. Configured channels and their threads use the same delivery setting as messages. In a mentions-only channel, a reaction reaches the session only when its target was written by the bot or was already delivered to this session.

Reactions do not advance message cursors. Their letter IDs include the Gateway session ID and dispatch sequence, so a replay during RESUME does not deliver twice. No message text is fetched for a reaction; the session uses the recorded quote, its conversation, or `discord.history()` for context. Reaction removals and additions missed while the bot process was stopped are not backfilled.

## Kernel binding

`discord` acts only through the session's own bot; failures raise `DiscordError`.

- `await discord.send(channel, text, reply_to=None)` → `Record(messages, channel)`: the numbers of the messages posted and the channel's handle. Text over 2,000 characters is split on lines; only the first part replies, and a later reaction quotes the start of the first part. Mentions never ping `@everyone` or roles.
- `await discord.dm(user, text)` → `Record(messages, channel)`, only to the owner or an allowed person.
- `await discord.history(channel, limit=20, before=None)` → `Record(number, author, username, bot, content, timestamp, reply_to, attachments)` per message, oldest first; `author` is the name they go by there, `reply_to` a number.
- `await discord.react(channel, message, emoji)`.
- `await discord.channels()` → `Record(handle, name, guild, delivery, mentions_only)` per configured channel.
- `await discord.status()` → `Record(name, state, detail, user, owner, invite_url)`.

`send`, `history` and `react` work in configured channels and in channels the bot has delivered or sent a message in (threads under configured channels, whitelisted DMs). Channel messages are conversation, not instructions from the user.

## Bot process

`src/albedo/harness/extensions/discord/manager.gleam` owns the bot processes. The extension's initialiser starts it once per daemon, under its own supervisor; every two seconds, and at once after an HTTP change, it rereads the bots and the global selection. Each enabled bot runs `python3 -u priv/python/albedo_discord.py` as an Erlang port (`albedo_discord.erl` owns the port, line framing and request ids) with `ALBEDO_DISCORD_TOKEN` in its environment; `ALBEDO_DISCORD_API` (default `https://discord.com/api/v10`) passes through from the daemon's environment, which tests point at a fake Discord. The process connects with intents 46593 (guilds, guild messages and reactions, direct messages and reactions, message content), heartbeats, resumes after socket loss with 1–60 s backoff, and exits on stdin EOF.

A DM reaction event names no one, so the process asks Discord who it was once and remembers the answer. Every line is one JSON object. The process sends `status` (`connecting`, `online`, `reconnecting`, with the bot `user` and `application_id`), `fatal` (then exits 2), `message` (every MESSAGE_CREATE, normalized), `reaction` (MESSAGE_REACTION_ADD with actor, their server nickname, emoji and target message IDs), and `reply`. The daemon sends requests with an integer `id`: `send`, `dm`, `history`, `react`, `guilds` (from the process's cache), `user`, and `catch_up`. A request waits at most 15 s; a process that exits fails its pending requests. After each `online` the daemon sends `catch_up` with its stored cursors, and the process replays up to 50 newer messages per channel as `backfill` messages.

## States and failures

The page and `discord.status()` show one state with a detail:

- `disabled`: the bot is disabled, or the extension is off globally.
- `connecting` / `online` / `reconnecting`: as the process reports.
- `reconnecting` with "the bot process exited …; restarting in Ns": the process died; the daemon restarts it after a doubling pause (1 s up to 60 s), reset by the next `online`.
- `failed`: a fatal close (4004 bad token, 4010–4013, 4014 Message Content intent not enabled). The daemon does not restart it until the bot's token or enabled flag changes.

READY records the bot's user id, username and application id. Deleting the bot, or its session, stops the process and removes its rows.

## HTTP

The page uses `/extensions/discord/` with the daemon token, while the extension is enabled globally: `GET`/`POST /bots`, `GET`/`PATCH`/`DELETE /bots/{id}` (PATCH carries `revision`; a stale one answers 412; DELETE takes `?revision=N`), `GET /bots/{id}/guilds` (live; 503 `bot_offline` unless online), `PUT /bots/{id}/channels/{channel_id}`, `GET /bots/{id}/dms`, `PUT`/`DELETE /bots/{id}/dms/{user_id}`, and `DELETE /bots/{id}/requests/{user_id}`. Times are unix milliseconds. [OpenAPI](../docs/openapi.yaml) has the schemas.