sugarcraft / candy-discord
Discord channel bundle for candy-code serve: dialogs from Discord into a served session through the serve's in-process host - pairing gates, guild allowlists, threaded sessions, queue modes, chunked redacted replies, approval buttons, native slash commands. Policy in the user-tier channels.discord s
Requires
- php: ^8.3
- psr/http-message: ^1.1 || ^2.0
- ratchet/pawl: ^0.4
- ratchet/rfc6455: ^0.4
- react/event-loop: ^1.6
- react/http: ^1.11
- react/promise: ^3.3
- react/socket: ^1.16
- react/stream: ^1.4
- sugarcraft/sugar-mcp-client: dev-master
- sugarcraft/sugar-plugins: dev-master
Requires (Dev)
- phpunit/phpunit: ^10.5
Suggests
None
Provides
None
Conflicts
None
Replaces
None
This package is auto-updated.
Last update: 2026-11-20 01:03:58 UTC
README
Discord channel bundle for candy-code serve. A Discord bot receives direct
messages and guild messages, forwards them into a served candy-code session
through the serve's in-process host, and posts the replies back in chunks.
Pairing gates, guild allowlists, approval buttons and native slash commands
are all handled inside the bundle.
Package: sugarcraft/candy-discord (bundle namespace CandyCode\Bundles\Discord\).
Original work: this bundle has no upstream port, so it carries no Mirrors charmbracelet/...
citation. It is a channel plugin for candy-code serve and sits outside the 42 + 22 package matrix
in docs/MATCHUPS.md.
Contents
- Requirements
- Create the Discord application and bot
- Credentials store and env fallback
- Enable the channel
- Access, guilds and mentions
- Pairing
- Approvers and approvals
- Commands
- Replies and streaming
- Settings reference
- Log events
- Troubleshooting
Requirements
- PHP 8.3+ and a candy-code build that ships the
channels.discordsettings reader. The bundle refuses to start (with a log line) on an older host. - A Discord account that can create an application in the Developer Portal, and a server (guild) where you can invite the bot.
- A
candy-code serveprocess that loads the bundle. The bundle calls the serve in process: it dials no socket, and it does not accept inbound connections from Discord. - Outbound HTTPS and WebSocket access to Discord's API and gateway.
ext-pdo_sqlite: the session and pairing stores are sqlite. Without the extension the channel refuses to start withchannels.discord.missing_extension. ReactPHP and Ratchet classes come from the host install; the bundle needs no other extensions of its own.
Create the Discord application and bot
Discord's portal changes over time; the steps below describe what the bundle needs, not a screen-by-screen walkthrough. Verify the labels in your portal.
- In the Developer Portal, create a new application. Its Application ID is the id the bundle registers slash commands under. Verify in your portal.
- Under Bot, add a bot user and copy the bot token. The token is a secret: it goes into the credentials store (below), never into settings.
- Under Bot, enable the Message Content privileged intent. The bundle
requests it when
intents.messageContentis true (the default). Without it Discord withholds message text, and the bundle falls back to mention-only handling; the gateway's disallowed-intents close (4013/4014) triggers the same degrade. Verify the privileged-intent toggle in your portal. Whenever the ladder lands on mention-only, the bundle logsdiscord_intents_degraded— that row names the posture you are actually running. - The bundle identifies to the gateway with these intents: guilds, guild messages, direct messages, and (when enabled) message content. No other intents are requested.
- Invite the bot to your server with an OAuth2 URL. The bundle relies on the
botscope for messaging and theapplications.commandsscope for slash commands (it deploys them under the application id). The bundle does not request explicit permissions in code, so the permissions you grant the bot (at minimum: view channels, send messages, read message history, and use application commands in the channels it should answer in) are whatever you set on the invite. Verify the permission set in your server.
Global slash commands can take a while to appear in Discord after the first
deploy. Verify in your server; the bundle deploys them on startup when
slash.deploy is true.
Credentials store and env fallback
The bot token lives in the 0600 channels store at ~/.candy-code/channels.json
— the same file the other channel credentials use — under
platforms.discord.accounts.<name>.token. The bundle never
reads it from settings, and it never writes it to logs: the token and the
pairing codes are registered as redaction secrets.
Canonical store shape (v1, byte-for-byte the layout CredentialStore fixes —
the Teams bundle rides the same file):
{
"version": 1,
"platforms": {
"discord": { "accounts": { "default": { "token": "<bot token>" } } }
}
}
How credential mistakes surface — two families, one loud:
| Mistake | Behaviour |
|---|---|
No token anywhere (no store, no DISCORD_BOT_TOKEN) |
start warns channels.discord.account_without_credentials for the default account, then channels.discord.no_usable_accounts; nothing starts |
| A named account without its token | channels.discord.account_without_credentials skips it; channels.discord.no_usable_accounts when nothing remains |
| Store file group/world-readable, not a regular file, or owned by another user | start refuses with a RuntimeException naming the path — a half-trusted credential file is worse than none |
For the default account only, DISCORD_BOT_TOKEN is honored when the
store has no token for it. The store wins when both are set. Named accounts
(accounts.<name>) read only from the store.
DISCORD_API_URL and DISCORD_GATEWAY_URL override the Discord endpoints, and
so do transport.apiBaseUrl and transport.gatewayUrl (the env var wins). An
override must be https/wss. Plain http/ws is accepted only for a loopback host,
and only when transport.insecureLoopbackProxy is true. A refused override
fails at startup, naming the setting that would authorize it, because the bot
token rides every request.
The bundle reads no discovery record and no CANDY_CODE_SERVER_DIR: the
serve's own state directory is that variable's business, not the bundle's. The
precedence law for the endpoint overrides is fixed in DiscordChannel::start():
the environment wins over the settings tree. To
front Discord through a local mirror or test proxy, run it on loopback and
set transport.insecureLoopbackProxy — in Endpoint's own words, "a
plain-HTTP override must never silently point at a remote host", because a bot
token rides every request. These env names live in the bundle, not in
candy-code/src, so the host's generated env roster does not list them: this
section is their documentation.
Enable the channel
The channel stays dark until channels.discord says otherwise. The user-tier
settings map carries the policy; enabled is the switch:
{
"channels.discord": {
"enabled": true,
"access": { "dmPolicy": "pairing" },
"approvals": { "enabled": true, "approvers": ["<your Discord user id>"] }
}
}
Installation: the bundle is loaded from
~/.candy-code/bundles/candy-discord — place the directory there, or run
candy-code bundles install <path> (and bundles install <name>@<marketplace>
once it is published to an added marketplace). The candy-discord/ directory
in this repository is the source tree, not the install path.
Then launch candy-code once to list the bundle, add candy-discord to
trustedBundleChannels, and launch again so it loads. This follows the same
first-launch-lists, second-launch-loads rule as every bundle. The keys are
documented in the settings reference.
Access, guilds and mentions
Direct messages follow access.dmPolicy:
pairing(default): an unpaired sender gets a pairing code and nothing is answered until an approver approves it (see Pairing).allowlist: only the users inaccess.allowFromand the pairing store's approved roster are served. An empty list serves nobody.
access.dmScope decides how DM sessions are keyed: per-peer (default), main,
per-channel-peer, or per-account-channel-peer.
Guild messages follow guilds.groupPolicy (default allowlist) and the
per-guild rows under guilds.rows. A guild with a row whose policy is
disabled is refused. Guilds without a row are not served under allowlist.
access.allowBots (default mentions) and access.ignoreOtherMentions
(default true) control messages from other bots and messages that mention
someone else. access.respondWithoutMention (default false) lets the bot answer
plain messages in a served guild without a mention. Keep it false unless you
want every message in the guild to reach the model.
Threads: when threads.enabled is true, each thread is its own session
and goes idle after threads.idleHours (default 24).
Pairing
A stranger who DMs the bot under pairing receives an 8-character code from
the unambiguous alphabet, valid for one hour, with at most three pending codes
at a time. Codes are shown only in that notice and to approvers in a direct
message, and they are redacted everywhere else.
An approver answers with either spelling:
- the slash command
/pair action:grant code:<code>(ephemeral by default throughslash.ephemeral), or - the text spelling
/pair grant <code>in a channel or DM (/pair approve <code>is a deprecated alias that still works and answers with a one-line notice).
Approval writes the sender into the 0600 store's allowlist. /pair list shows
pending codes only in a direct message; asked in a guild it answers without
listing anything. Pending codes are never listed in a channel, even to an
approver.
If approvals.approvers is empty, no one can run /pair grant, so no
stranger is ever admitted by pairing. Configure at least one approver before
you expect pairing to work.
Approvers and approvals
approvals.approvers is the Discord user-id roster allowed to answer
permission prompts and to approve pairing codes.
- Empty roster: any user in the conversation where the ask was presented
may answer
onceordeny.alwaysis refused ("needs a configured approver") and the ask stays open. The refusal is posted in the ask's own conversation. - Configured roster: only the listed users can answer. Anyone else is
refused on the wire with
is not an approver.
Every answer, from a button or from a text command, must carry the per-ask nonce minted at presentation and must arrive in the conversation the ask was presented in. A forged, stale or cross-conversation answer is refused and logged; the permission request is not touched.
Approval prompts render as buttons (Approve once, Always allow, Deny) when
approvals.enabled is true (the default). The buttons are a courtesy filter;
the roster and nonce checks run server-side in the bundle. With approvals
disabled, or where buttons cannot render, the ask falls back to a same-chat
line: /approve <askId> once|always|deny. approvals.ttlMinutes (default 30,
floor one minute, clamped to the pending-ask ceiling) bounds how long a presented
ask waits. Verify the button layout in your client.
Commands
The bundle registers these slash commands when slash.deploy is true, and
accepts the same words as text in a served conversation:
| Command | What it does |
|---|---|
/new [name] |
Start a fresh session for this conversation. |
/stop |
Stop the running turn. |
/approve <askId> [once|always|deny] |
Answer an open approval by id. |
/queue <text> |
Queue a message behind the running turn (see queue). |
/model [name] |
Show or change the model for this session. |
/pair action:grant|list [code] |
Approver pairing commands (list is DM-only). |
A channel bundle's approval contract carries the three universal verdicts — allow-once, allow-always, deny. Rule-saving and deny-with-reason are TUI-only today: the wire from a bundle has no remember member, and its note field carries actor attribution, not a user-authored reason.
Unknown slash commands are refused. Slash replies are ephemeral by default
(slash.ephemeral).
Worked pairing-and-approval exchange (a DM, text spellings):
stranger DM> hello -> bot: "pairing code k7m2q9x4 …"
approver DM> /pair grant k7m2q9x4
-> admitted; the sender id is written to
the allowlist in the 0600 store
bot DM> [ask] run composer install?
approver /approve ask_17 once -> the pending permission is answered
Replies and streaming
Replies are posted as normal Discord messages, split by the outbound chunker
to fit outbound limits and with secrets redacted. The bundle does not
stream partial output; each reply arrives as finished message chunks.
outbound.typing (default true) shows the typing indicator while a turn runs.
outbound.suppressEmbeds (default true) stops link previews from cluttering
replies. Verify how your client shows typing.
Media limits are set under media.*; see DiscordChannel for the keys the
bundle reads.
Language
The bundle owns its catalog: every delivered string goes through
Lang::t() over the channels.discord.* key family in lang/, a
plugin-owned catalog loaded through SugarCraft\Plugins\Lang. It is
mirrored across all twelve locales and checked by tests/I18n/LangParityTest;
tests/I18n/UserFacingLiteralGuardTest fails on a new bare literal in a
user-facing slot. A key missing from any locale fails the bundle suite.
Log rows stay content-free English by the bundle's log law: event names and
scalars, never message bodies.
Settings reference
All keys live under channels.discord. Defaults are the values the code uses
when a key is absent.
| Key | Default | Meaning |
|---|---|---|
enabled |
false |
Turns the channel on. |
transport.apiBaseUrl / transport.gatewayUrl |
Discord's | Endpoint overrides; https/wss, or loopback http/ws with the flag below. |
transport.insecureLoopbackProxy |
false |
Allows the loopback override above. |
intents.messageContent |
true |
Requests the Message Content intent. |
access.dmPolicy |
pairing |
pairing, allowlist, or disabled. |
access.dmScope |
per-peer |
DM session keying (see above). |
access.allowFrom |
[] |
Discord user ids (strings) allowed under allowlist. |
access.allowBots |
mentions |
How other bots' messages are treated. |
access.ignoreOtherMentions |
true |
Ignore messages that mention someone else. |
access.respondWithoutMention |
false |
Answer plain guild messages without a mention. |
guilds.groupPolicy |
allowlist |
Default for guilds without a row. |
guilds.rows |
{} |
Per-guild rows keyed by guild id; policy: "disabled" refuses. |
threads.enabled / threads.idleHours |
false / 24 |
Threaded sessions and idle timeout. |
queue.debounceMs / queue.maxPending |
500 / 20 |
Queue timing and depth. |
outbound.typing / outbound.suppressEmbeds |
true / true |
Typing indicator and link embeds. |
media.* |
maxMb 100, maxTotalMb 50 |
Attachment caps: per file, and per batch (shared across concurrent messages; rows past it are skipped with a disclosed note). |
approvals.enabled |
true |
Buttons on; false uses the text fallback. |
approvals.approvers |
[] |
Approver user ids (empty roster: no always, no pairing approvals). |
approvals.ttlMinutes |
30 |
How long a presented ask waits. |
slash.deploy |
true |
Register slash commands on startup. |
slash.ephemeral |
true |
Make slash replies ephemeral. |
accounts |
{} |
Per-account overrides, keyed by account name. |
The full default tree (the shape the bundle sees when settings say nothing — see the table above for every key's meaning):
{
"enabled": false,
"intents": { "messageContent": true },
"transport": {},
"access": { "dmPolicy": "pairing", "dmScope": "per-peer", "allowFrom": [],
"allowBots": "mentions", "ignoreOtherMentions": true,
"respondWithoutMention": false },
"guilds": { "groupPolicy": "allowlist", "rows": {} },
"threads": { "enabled": false, "idleHours": 24 },
"queue": { "mode": "steer", "debounceMs": 500, "maxPending": 20 },
"outbound": { "typing": true, "suppressEmbeds": true },
"media": { "maxMb": 100 },
"approvals": { "enabled": true, "approvers": [], "ttlMinutes": 30 },
"slash": { "deploy": true, "ephemeral": true },
"accounts": {}
}
Log events
Every row is one structured line in the channel log.
| Event | Meaning | First remedy |
|---|---|---|
channels.discord.missing_extension |
ext-pdo_sqlite is not loaded, so the session/pairing store cannot open. |
Enable the extension and restart — nothing else starts. |
channels.discord.account_without_credentials |
One named account booted without a token and was skipped (the account field names it). |
Fill that account's token row in channels.json. |
channels.discord.no_usable_accounts |
No token survived the account scan — including the plain no-credential boot (each skipped account first logs account_without_credentials). |
Add the token(s); or leave enabled: false to stay dark on purpose. |
channels.discord.serve_dial_failed |
The in-process hello to the serve was refused (the error field says why). |
The bundle redials on a ladder: 0.25 s doubling, capped at 30 s. Check the serve's own log if it persists. |
channels.discord.serve_giveup |
60 hellos in a row were refused, so the bundle stopped redialling. | Fix the serve side, then restart candy-code serve: the channel dials again only at boot. |
channels.discord.serve_connected |
The serve leg is up and bindings were adopted. | — (success row) |
discord_intents_degraded |
The gateway closed 4013/4014 or text was withheld; this process is mention-only now — one-way. | Enable the portal intent and restart. |
Other gateway/rest rows are named for their step (discord_reconnect,
discord_slash_deploy_failed, discord_rest_error, …); pairing codes never
appear in any of them — they are redaction secrets.
Troubleshooting
- The bot is online but never answers in a guild: the guild has no row
under
guilds.rows(withgroupPolicyat itsallowlistdefault), or the message did not mention the bot. Add the guild row, or mention the bot. - The bot sees messages without text: the Message Content intent is off in
the portal, or the gateway closed with 4013/4014 and the bundle degraded to
mention-only (
discord_intents_degradednames the landing in the channel log; it is one-way for the process). Enable the intent and restart. - DMs get a pairing code but nothing happens after approval: check the
approver roster.
/pair grantby a user not onapprovals.approversis refused, and an empty roster admits no one. /approvesays the answer was refused: the answer came from another conversation, carried a stale nonce (the card is from before a restart or after the ask was already answered), or came from a user not on the roster. Re-ask, or answer from the conversation the ask was presented in.alwayssays it needs a configured approver: the roster is empty. Add your user id underapprovals.approvers.- Slash commands do not appear: the bot was invited without
applications.commands, or the global deploy has not propagated yet. Verify in your server. DISCORD_BOT_TOKENis ignored: the store already has a token for the default account, and the store wins. Remove the store token to use the env.