@spinabot/brigade 1.6.0 → 1.7.0

package/dist/agents/channels/discord/connection.js

@@ -0,0 +1,1600 @@
+/**
+ * Discord connection (Gateway WebSocket inbound + REST outbound).
+ *
+ * The Brigade analogue of `slack/connection.ts`, on top of discord.js v14. A
+ * single `Client` owns BOTH halves: the Gateway websocket delivers INBOUND
+ * events (no public URL needed — the local-first default, analogous to Slack
+ * Socket Mode / Telegram long-polling), and the same Client's REST drives every
+ * OUTBOUND call (send / edit / delete / react / upload / typing). `discord.js`
+ * is lazy-imported here (`await import("discord.js")` inside `connectDiscord`)
+ * so a non-Discord boot never pays for it; types are `type`-only on the static
+ * import so the static import never pulls the runtime in.
+ *
+ * Lifecycle:
+ *   - `client.login(botToken)` BOOTSTRAPS the connection. An invalid token
+ *     rejects login → TERMINAL (the only fix is a fresh token, mirroring Slack's
+ *     `tokenInvalid`). The bot's own user id is cached on `ClientReady` (the
+ *     group ACL needs it to detect `<@bot>` mentions + to filter the bot's own
+ *     echoes; without it group messages never reach the agent and the bot could
+ *     reply to itself).
+ *   - Event handlers subscribe messageCreate / messageUpdate (edit) /
+ *     messageDelete / messageReactionAdd / messageReactionRemove /
+ *     interactionCreate (button presses = approval + general callbacks, and
+ *     slash commands). Each normalizes the payload into a `DiscordInboundMessage`
+ *     and routes it via `onMessage` / `onCallbackQuery` / `onReaction`.
+ *     Attachment bytes are downloaded via a DEFERRED `resolveMedia` thunk — only
+ *     after the central access gate admits the sender (mirrors Slack/Telegram).
+ *   - discord.js auto-reconnects the Gateway internally; we SUPERVISE the initial
+ *     `.login()` with the SAME backoff curve as Slack (2s → 30s, ×1.8, ±25%) and
+ *     go terminal on an auth error.
+ *   - Events are de-duplicated by message id (a redelivered event after a
+ *     reconnect must not double-run the agent).
+ */
+import { createDedupeCache, nextBackoffDelay, } from "../sdk.js";
+import { maskProxyUrl } from "./account-config.js";
+import { isDiscordSelectSpec, } from "./components.js";
+import { DISCORD_FLAG_IS_COMPONENTS_V2, DISCORD_BUTTON_STYLE_LINK, isDiscordLinkButton, isDiscordV2MessageSpec, } from "./component-blocks.js";
+import { buildDiscordModal, decodeDiscordModalCustomId, extractModalFieldValues, formatModalSubmissionText, isDiscordModalCustomId, } from "./modals.js";
+import { consumeDiscordModal, getDiscordModal } from "./modal-registry.js";
+import { rememberDiscordUser } from "./directory-cache.js";
+import { assembleDiscordText, buildDiscordSenderName, discordChannelType, discordThreadId, extractDiscordMemberRoleIds, extractDiscordMentions, extractDiscordReplyContext, hasInboundMedia, isThreadChannel, resolveInboundAttachments, } from "./inbound-extras.js";
+import { buildDiscordAttachment, downloadDiscordAttachment } from "./media.js";
+import { isDiscordUserMessageType, resolveDiscordSystemEvent } from "./system-events.js";
+import { forgetDiscordSubagentThreadBindingByThreadId } from "./subagent-thread-binding-store.js";
+/* ───────────────────────── reconnect backoff ───────────────────────── */
+// Shares the neutral `nextBackoffDelay` curve with every other channel (see
+// `channels/backoff.ts`), tuned to the SAME schedule WhatsApp + Telegram + Slack
+// use (2s → 30s, ×1.8, ±25%). The constants live here so Discord owns its own
+// knobs; the arithmetic is the shared helper's.
+const RECONNECT_INITIAL_MS = 2_000;
+const RECONNECT_MAX_MS = 30_000;
+const RECONNECT_FACTOR = 1.8;
+const RECONNECT_JITTER = 0.25;
+const RECONNECT_MAX_ATTEMPTS = 12;
+/**
+ * Jittered exponential backoff for reconnect attempt `attempt` (0-based). Thin
+ * wrapper over the neutral `nextBackoffDelay` helper — kept as a named export so
+ * `index.ts` + the connection tests have a stable entry point.
+ */
+export function discordBackoffDelay(attempt) {
+    return nextBackoffDelay({
+        attempt,
+        initialMs: RECONNECT_INITIAL_MS,
+        maxMs: RECONNECT_MAX_MS,
+        factor: RECONNECT_FACTOR,
+        jitter: RECONNECT_JITTER,
+    });
+}
+/** Discord's hard per-message content limit (chars). Sends chunk under this. */
+const DISCORD_MESSAGE_LIMIT = 2_000;
+/* ───────────────────────── channel-type + flag constants ───────────────────────── */
+/**
+ * discord.js `ChannelType` values for forum/media channels (Fix 2b). A plain
+ * `.send()` to these is REJECTED — the connection opens a thread (forum post)
+ * instead. Hardcoded so the connection never has to import the discord.js enum on
+ * the (injected-fake) test path; the values are stable wire constants.
+ */
+const CHANNEL_TYPE_GUILD_FORUM = 15;
+const CHANNEL_TYPE_GUILD_MEDIA = 16;
+const CHANNEL_TYPE_GUILD_VOICE = 2;
+const CHANNEL_TYPE_GUILD_STAGE_VOICE = 13;
+/**
+ * Channel types where a message-thread can't be started (Fix 6). Forum/Media
+ * channels only host posts (their own threads), and Voice/Stage channels have no
+ * message-thread surface — `message.startThread(...)` 400s on all of them. The
+ * auto-thread path guards on these to avoid a wasteful failed REST call + a noisy
+ * error log (it already falls back to an un-threaded reply).
+ */
+const THREAD_UNSUPPORTED_CHANNEL_TYPES = new Set([
+    CHANNEL_TYPE_GUILD_FORUM,
+    CHANNEL_TYPE_GUILD_MEDIA,
+    CHANNEL_TYPE_GUILD_VOICE,
+    CHANNEL_TYPE_GUILD_STAGE_VOICE,
+]);
+/** `MessageFlags.SuppressNotifications` (1 << 12) — a silent send (Fix 2c). */
+const MESSAGE_FLAG_SUPPRESS_NOTIFICATIONS = 1 << 12;
+/** Discord thread titles are capped at 100 chars. */
+const DISCORD_THREAD_NAME_LIMIT = 100;
+/** True for a forum / media channel (which rejects a plain `.send()`). */
+function isForumLikeChannel(channel) {
+    return channel.type === CHANNEL_TYPE_GUILD_FORUM || channel.type === CHANNEL_TYPE_GUILD_MEDIA;
+}
+/**
+ * Derive a forum-post thread name from the first non-empty line of the body,
+ * trimmed to {@link DISCORD_THREAD_NAME_LIMIT}. Falls back to a timestamp stub
+ * when the body is empty so the post always has a title.
+ */
+function deriveForumThreadName(text) {
+    const firstLine = (text ?? "").split("\n").map((l) => l.trim()).find((l) => l.length > 0) ?? "";
+    const name = firstLine.slice(0, DISCORD_THREAD_NAME_LIMIT).trim();
+    return name || new Date().toISOString().slice(0, 16);
+}
+/**
+ * The SAFE default `allowedMentions` applied to every outbound Discord send.
+ * `parse: ["users", "roles"]` lets explicit `<@id>` / `<@&roleid>` mentions ping
+ * as intended, while the absence of `"everyone"` means an `@everyone` / `@here`
+ * that slipped into the content (agent text or a prompt injection) renders as
+ * text and notifies no one. `repliedUser: false` keeps a native reply from
+ * pinging the author it answers. A fresh object is returned per call so a send
+ * can't mutate the shared default.
+ */
+export function safeDiscordAllowedMentions() {
+    return { parse: ["users", "roles"], repliedUser: false };
+}
+/**
+ * Sanitize a string into a Discord thread name (Phase 5 autoThread): take the
+ * first non-empty line, strip user/role/channel mention markup, collapse
+ * whitespace, and truncate to Discord's 100-char limit. Falls back to
+ * `"Thread <id>"` when nothing usable remains.
+ */
+export function sanitizeThreadName(raw, fallbackId) {
+    const firstLine = (raw ?? "")
+        .split(/\r?\n/)
+        .map((l) => l.trim())
+        .find((l) => l.length > 0);
+    const cleaned = (firstLine ?? "")
+        .replace(/<@!?\d+>/g, "") // user mentions
+        .replace(/<@&\d+>/g, "") // role mentions
+        .replace(/<#\d+>/g, "") // channel mentions
+        .replace(/\s+/g, " ")
+        .trim();
+    const base = cleaned || `Thread ${fallbackId}`;
+    // Truncate to 100 UTF-16 code units (Discord's hard cap).
+    const truncated = base.length > 100 ? base.slice(0, 100).trim() : base;
+    return truncated || `Thread ${fallbackId}`;
+}
+/* ───────────────────────── error classification ───────────────────────── */
+/** Pull a message string off any thrown shape. */
+function errorText(err) {
+    if (!err)
+        return "";
+    if (typeof err === "string")
+        return err;
+    const e = err;
+    return e.message ?? String(err);
+}
+/**
+ * A Discord auth failure → the token is wrong / revoked / reset. Re-tokening is
+ * the only fix; reconnecting with the same token loops forever. discord.js
+ * surfaces a bad token on login as a `TokenInvalid` error / a message containing
+ * "invalid token" / an "disallowed intents" privileged-intents rejection (which
+ * is also terminal until the operator fixes the bot's intent settings).
+ */
+export function isDiscordUnauthorized(err) {
+    const name = err?.name ?? "";
+    if (/TokenInvalid|DisallowedIntents/i.test(name))
+        return true;
+    const code = err?.code;
+    if (code === "TokenInvalid" || code === "DisallowedIntents")
+        return true;
+    return /invalid token|incorrect login|disallowed intents|used disallowed intents/i.test(errorText(err));
+}
+/* ───────────────────────── structured send-error decode (Fix 2d) ───────────────────────── */
+/** Discord JSON error code: the bot lacks permission to act in the channel. */
+const DISCORD_ERR_MISSING_PERMISSIONS = 50013;
+/** Discord JSON error code: cannot send messages to this user (DM blocked / disabled). */
+const DISCORD_ERR_CANNOT_SEND_TO_USER = 50007;
+/** Pull the numeric Discord error `code` off a thrown discord.js error, if any. */
+function discordErrorCode(err) {
+    if (!err || typeof err !== "object")
+        return undefined;
+    const e = err;
+    const candidate = e.code !== undefined ? e.code : e.rawError?.code;
+    if (typeof candidate === "number")
+        return candidate;
+    if (typeof candidate === "string" && /^\d+$/.test(candidate))
+        return Number(candidate);
+    return undefined;
+}
+/**
+ * Turn a raw discord.js send error into an operator-readable one for the two
+ * actionable cases (Fix 2d). A 50013 (Missing Permissions) and a 50007
+ * (cannot-send-to-user / DM blocked) each map to a specific remediation hint;
+ * every other error is rethrown VERBATIM so nothing is masked. Wrapped around the
+ * three send fns so `adapter.handleAction`'s catch surfaces the decoded message.
+ */
+function decodeDiscordSendError(err) {
+    const code = discordErrorCode(err);
+    if (code === DISCORD_ERR_MISSING_PERMISSIONS) {
+        return new Error("Missing permission to post in this channel (need View Channel + Send Messages).");
+    }
+    if (code === DISCORD_ERR_CANNOT_SEND_TO_USER) {
+        return new Error("Can't DM this user — they've blocked the bot or disabled DMs.");
+    }
+    return err instanceof Error ? err : new Error(typeof err === "string" ? err : String(err));
+}
+/** Strip a Discord token out of a string before it logs. */
+export function redactDiscordToken(text, ...tokens) {
+    if (!text)
+        return text;
+    let out = text;
+    for (const token of tokens) {
+        if (token)
+            out = out.split(token).join("<redacted>");
+    }
+    // Discord bot tokens look like `<base64 id>.<base64 ts>.<secret>`; mask a
+    // plausible token fragment even if the exact token differs.
+    out = out.replace(/[A-Za-z0-9_-]{20,}\.[A-Za-z0-9_-]{4,}\.[A-Za-z0-9_-]{20,}/g, "<redacted>");
+    return out;
+}
+/**
+ * Build the discord.js `ActionRowBuilder` wrapping ONE select menu (Fix 3a). The
+ * `kind` picks the builder; a STRING select adds its options, an entity select
+ * (user/role/channel/mentionable) carries none. Placeholder + min/max are set
+ * when present.
+ */
+function buildSelectActionRow(discord, spec) {
+    const applyCommon = (menu) => {
+        menu.setCustomId(spec.customId);
+        if (spec.placeholder && typeof menu.setPlaceholder === "function")
+            menu.setPlaceholder(spec.placeholder);
+        if (typeof spec.minValues === "number" && typeof menu.setMinValues === "function")
+            menu.setMinValues(spec.minValues);
+        if (typeof spec.maxValues === "number" && typeof menu.setMaxValues === "function")
+            menu.setMaxValues(spec.maxValues);
+    };
+    let menu;
+    switch (spec.kind) {
+        case "user": {
+            const m = new discord.UserSelectMenuBuilder();
+            applyCommon(m);
+            menu = m;
+            break;
+        }
+        case "role": {
+            const m = new discord.RoleSelectMenuBuilder();
+            applyCommon(m);
+            menu = m;
+            break;
+        }
+        case "channel": {
+            const m = new discord.ChannelSelectMenuBuilder();
+            applyCommon(m);
+            menu = m;
+            break;
+        }
+        case "mentionable": {
+            const m = new discord.MentionableSelectMenuBuilder();
+            applyCommon(m);
+            menu = m;
+            break;
+        }
+        case "string":
+        default: {
+            const s = new discord.StringSelectMenuBuilder();
+            applyCommon(s);
+            const options = (spec.options ?? []).map((o) => {
+                const opt = new discord.StringSelectMenuOptionBuilder().setLabel(o.label).setValue(o.value);
+                if (o.description)
+                    opt.setDescription(o.description);
+                return opt;
+            });
+            if (options.length > 0)
+                s.addOptions(...options);
+            menu = s;
+            break;
+        }
+    }
+    const row = new discord.ActionRowBuilder();
+    row.addComponents(menu);
+    return row;
+}
+/** Map ONE V2 block spec to its discord.js builder (Fix 3c). */
+function buildV2Block(discord, block) {
+    switch (block.type) {
+        case "text":
+            return new discord.TextDisplayBuilder().setContent(block.text);
+        case "section": {
+            const section = new discord.SectionBuilder();
+            section.addTextDisplayComponents(...block.texts.map((t) => new discord.TextDisplayBuilder().setContent(t)));
+            if (block.accessory?.kind === "thumbnail") {
+                section.setThumbnailAccessory(new discord.ThumbnailBuilder().setURL(block.accessory.url));
+            }
+            else if (block.accessory?.kind === "button") {
+                section.setButtonAccessory(buildV2Button(discord, block.accessory.button));
+            }
+            return section;
+        }
+        case "separator": {
+            const sep = new discord.SeparatorBuilder();
+            if (typeof block.divider === "boolean")
+                sep.setDivider(block.divider);
+            if (block.spacing) {
+                const spacing = block.spacing === "large" ? 2 : 1;
+                sep.setSpacing(spacing);
+            }
+            return sep;
+        }
+        case "actions": {
+            const row = new discord.ActionRowBuilder();
+            row.addComponents(...block.buttons.map((b) => buildV2Button(discord, b)));
+            return row;
+        }
+        case "media-gallery": {
+            const gallery = new discord.MediaGalleryBuilder();
+            gallery.addItems(...block.items.map((it) => {
+                const item = new discord.MediaGalleryItemBuilder().setURL(it.url);
+                if (it.description)
+                    item.setDescription(it.description);
+                if (typeof it.spoiler === "boolean")
+                    item.setSpoiler(it.spoiler);
+                return item;
+            }));
+            return gallery;
+        }
+        case "file": {
+            const file = new discord.FileBuilder().setURL(block.url);
+            if (typeof block.spoiler === "boolean")
+                file.setSpoiler(block.spoiler);
+            return file;
+        }
+        default:
+            return new discord.TextDisplayBuilder().setContent("");
+    }
+}
+/** Build a V2 button (a link button when it has a url, else an interactive button). */
+function buildV2Button(discord, b) {
+    if (isDiscordLinkButton(b)) {
+        return new discord.ButtonBuilder().setLabel(b.label).setStyle(DISCORD_BUTTON_STYLE_LINK).setURL(b.url);
+    }
+    return new discord.ButtonBuilder().setLabel(b.label).setCustomId(b.customId).setStyle((b.style ?? 2));
+}
+/** Build the discord.js `ContainerBuilder` for a Components-V2 message (Fix 3c). */
+function buildV2Container(discord, spec) {
+    const container = new discord.ContainerBuilder();
+    if (typeof spec.accentColor === "number")
+        container.setAccentColor(spec.accentColor);
+    for (const block of spec.blocks) {
+        const built = buildV2Block(discord, block);
+        if (block.type === "section")
+            container.addSectionComponents(built);
+        else if (block.type === "separator")
+            container.addSeparatorComponents(built);
+        else if (block.type === "actions")
+            container.addActionRowComponents(built);
+        else if (block.type === "media-gallery")
+            container.addMediaGalleryComponents(built);
+        else if (block.type === "file")
+            container.addFileComponents(built);
+        else
+            container.addTextDisplayComponents(built);
+    }
+    return container;
+}
+/* ───────────────────────── the connection ───────────────────────── */
+export async function connectDiscord(args) {
+    const accountId = args.accountId ?? "default";
+    const sleep = args.sleepImpl ?? ((ms) => new Promise((r) => setTimeout(r, ms).unref?.()));
+    const safeLog = (msg, meta) => {
+        const redactedMsg = redactDiscordToken(msg, args.botToken);
+        if (!meta)
+            return args.log(redactedMsg);
+        const redactedMeta = {};
+        for (const [k, v] of Object.entries(meta)) {
+            redactedMeta[k] = typeof v === "string" ? redactDiscordToken(v, args.botToken) : v;
+        }
+        args.log(redactedMsg, redactedMeta);
+    };
+    const proxyUrl = (args.proxyUrl ?? "").trim();
+    // ── lazy-load discord.js (production path only) ──
+    // `builders` resolves in this precedence: an injected `buildersFactory` wins
+    // (tests / a custom build); else the production path builds real discord.js
+    // builders; else (a `clientFactory` with no builders supplied) a pass-through
+    // fake that emits plain JSON. So a test injecting just a `clientFactory` gets
+    // the pass-through, and a real boot gets real discord.js builders.
+    let buildClient;
+    let builders = args.buildersFactory ? args.buildersFactory() : undefined;
+    if (args.clientFactory) {
+        const factory = args.clientFactory;
+        buildClient = (botToken) => factory(botToken, proxyUrl || undefined);
+        builders ??= {
+            buildAttachment: (p, name) => ({ attachment: p, name }),
+            buildComponentRows: (rows) => rows.map((row) => ({ components: row })),
+            buildModal: (params) => ({ modal: params }),
+        };
+    }
+    else {
+        const discord = await import("discord.js");
+        const { Client, GatewayIntentBits, Partials } = discord;
+        // Optional proxy → a custom REST `makeRequest` via undici's ProxyAgent. A
+        // missing/malformed proxy must not wedge the channel (logged, ignored).
+        let rest;
+        if (proxyUrl) {
+            try {
+                const { ProxyAgent, fetch: undiciFetch } = await import("undici");
+                const dispatcher = new ProxyAgent(proxyUrl);
+                rest = {
+                    makeRequest: ((url, init) => undiciFetch(url, { ...init, dispatcher })),
+                };
+                safeLog("discord routing through proxy", { account: accountId, proxy: maskProxyUrl(proxyUrl) });
+            }
+            catch (err) {
+                safeLog("discord proxy setup failed — connecting directly", {
+                    account: accountId,
+                    proxy: maskProxyUrl(proxyUrl),
+                    error: err instanceof Error ? err.message : String(err),
+                });
+            }
+        }
+        buildClient = (_botToken) => new Client({
+            intents: [
+                GatewayIntentBits.Guilds,
+                GatewayIntentBits.GuildMessages,
+                GatewayIntentBits.MessageContent,
+                GatewayIntentBits.GuildMessageReactions,
+                GatewayIntentBits.DirectMessages,
+                GatewayIntentBits.DirectMessageReactions,
+            ],
+            // Partials so DM channels + uncached reactions/messages still fire events.
+            partials: [Partials.Channel, Partials.Message, Partials.Reaction],
+            ...(rest ? { rest: rest } : {}),
+        });
+        builders ??= {
+            buildAttachment(p, name) {
+                return new discord.AttachmentBuilder(p, { name });
+            },
+            buildComponentRows(rows) {
+                return rows.map((row) => {
+                    // SELECT row (Fix 3a) — alone in its ActionRow; the kind picks the builder.
+                    if (isDiscordSelectSpec(row)) {
+                        return buildSelectActionRow(discord, row);
+                    }
+                    // Components-V2 container (Fix 3c) — a single ContainerBuilder of blocks.
+                    if (isDiscordV2MessageSpec(row)) {
+                        return buildV2Container(discord, row);
+                    }
+                    // Classic BUTTON row (unchanged byte-for-byte behavior).
+                    const r = new discord.ActionRowBuilder();
+                    for (const b of row) {
+                        r.addComponents(new discord.ButtonBuilder().setCustomId(b.customId).setLabel(b.label).setStyle(b.style));
+                    }
+                    return r;
+                });
+            },
+            buildModal(params) {
+                return buildDiscordModal({
+                    ModalBuilder: discord.ModalBuilder,
+                    ActionRowBuilder: discord.ActionRowBuilder,
+                    TextInputBuilder: discord.TextInputBuilder,
+                }, params);
+            },
+        };
+    }
+    // `builders` is always assigned by here (every branch sets it); the non-null
+    // assertion documents that for the closures below.
+    const resolvedBuilders = builders;
+    // ── connection state ──
+    let selfId = null;
+    let selfName = null;
+    let connectedAtMs = null;
+    let lastEventAtMs = null;
+    const stampInboundEvent = () => {
+        lastEventAtMs = Date.now();
+    };
+    let connected = false;
+    let tokenInvalid = false;
+    let closed = false;
+    let reconnectAttempts = 0;
+    let client = null;
+    let loopPromise = null;
+    // READY-gating (Phase 5): a socket can `login()` (open) yet never reach the
+    // `clientReady` handshake. `ready` is the trustworthy "fully up" flag the
+    // presence apply + the watchdog gate on.
+    let ready = false;
+    // Resolved presence to (re)apply on every READY (Phase 5). `null` → leave
+    // Discord's default presence untouched.
+    const presencePayload = args.presence ?? null;
+    const setPresenceImpl = args.setPresenceImpl ??
+        ((c, payload) => {
+            c.user?.setPresence?.(payload);
+        });
+    /** Apply (or re-apply) a presence payload to the live client. Best-effort. */
+    const applyPresence = (payload) => {
+        const c = client;
+        const p = payload === undefined ? presencePayload : payload;
+        if (!c || !p)
+            return;
+        try {
+            setPresenceImpl(c, p);
+        }
+        catch (err) {
+            safeLog("discord presence apply failed", { error: err instanceof Error ? err.message : String(err) });
+        }
+    };
+    // READY watchdog (Phase 5): default ~20s deadline; ≤0 disables it.
+    const readyTimeoutMs = typeof args.readyTimeoutMs === "number" ? args.readyTimeoutMs : 20_000;
+    // Dedupe inbound events by id — a redelivered event after a reconnect must not
+    // double-run the agent. Per-connection lifetime.
+    const eventDedupe = createDedupeCache({ maxEntries: 10_000, ttlMs: 60 * 60 * 1_000 });
+    // Last inbound message id per channel — the target setComposing targets (Discord
+    // shows typing per-channel, so we just need the channel; the map is kept for
+    // parity / future per-message affordances).
+    const lastInboundChannel = new Set();
+    /** Token-resolver lookups primed from the cached client (best-effort, sync). */
+    const resolveLookups = (message) => {
+        // On a live message discord.js resolves mention display via the resolved
+        // collections; expandDiscordTokens falls back to the bare id when a name
+        // isn't cached. We pass resolvers that read the message's own resolved
+        // mention caches when present.
+        const users = new Map();
+        const mentionUsers = message.mentions?.users;
+        if (mentionUsers) {
+            const iter = mentionUsers instanceof Map ? mentionUsers.values() : mentionUsers;
+            for (const u of iter) {
+                if (typeof u?.id === "string")
+                    users.set(u.id, (u.globalName || u.username || u.id));
+            }
+        }
+        return { user: (id) => users.get(id) };
+    };
+    /**
+     * Prime the account's handle→id directory cache (Fix 2a) from an inbound: the
+     * message author plus every resolved `<@…>` mention. This is what later lets
+     * the outbound path rewrite a plain `@handle` the agent typed into a real
+     * `<@id>` ping. Best-effort + side-effect-only — never throws into normalize.
+     */
+    const primeDirectoryFromMessage = (message) => {
+        try {
+            const author = message.author;
+            if (author && typeof author.id === "string") {
+                rememberDiscordUser(accountId, {
+                    id: author.id,
+                    username: author.username ?? undefined,
+                    displayName: (author.globalName ?? author.displayName ?? undefined),
+                });
+            }
+            const mentionUsers = message.mentions?.users;
+            if (mentionUsers) {
+                const iter = mentionUsers instanceof Map ? mentionUsers.values() : mentionUsers;
+                for (const u of iter) {
+                    if (typeof u?.id !== "string")
+                        continue;
+                    rememberDiscordUser(accountId, {
+                        id: u.id,
+                        username: u.username ?? undefined,
+                        displayName: (u.globalName ?? u.displayName ?? undefined),
+                    });
+                }
+            }
+        }
+        catch {
+            /* directory priming is best-effort */
+        }
+    };
+    /** Normalize a discord.js message into the deferred-media inbound shape. */
+    const normalize = (message, opts) => {
+        const channelId = typeof message.channelId === "string" ? message.channelId : typeof message.channel?.id === "string" ? message.channel.id : "";
+        if (!channelId)
+            return null;
+        primeDirectoryFromMessage(message);
+        const resolve = resolveLookups(message);
+        // Assembled text: content leads, with an embed-title/description fallback when
+        // content is empty, plus appended `<sticker: …>` + `[Forwarded from …]` blocks
+        // so an embed-only / sticker-only / forwarded message isn't dropped as empty.
+        const text = assembleDiscordText(message, resolve);
+        const chatType = discordChannelType(message);
+        const threadId = discordThreadId(message);
+        const mentions = extractDiscordMentions(message, selfId ?? undefined);
+        const replyTo = extractDiscordReplyContext(message);
+        const fromName = buildDiscordSenderName(message);
+        const fromId = typeof message.author?.id === "string" ? message.author.id : channelId;
+        // Discord routes on guildId + member role ids (NOT teamId — that's Slack's
+        // workspace tier). A DM carries no guildId and no roles.
+        const guildId = typeof message.guildId === "string" ? message.guildId : undefined;
+        const memberRoleIds = guildId ? extractDiscordMemberRoleIds(message) : [];
+        const messageId = typeof message.id === "string" ? message.id : undefined;
+        const timestampMs = typeof message.createdTimestamp === "number" ? message.createdTimestamp : undefined;
+        // DEFERRED media — captured by reference, not downloaded. The thunk is only
+        // invoked by the pipeline after the access gate admits the sender.
+        const carriesMedia = hasInboundMedia(message);
+        const resolveMedia = carriesMedia
+            ? async () => {
+                const atts = resolveInboundAttachments(message);
+                if (atts.length === 0)
+                    return [];
+                const out = [];
+                for (const att of atts) {
+                    const dl = await downloadDiscordAttachment({ attachment: att, log: safeLog });
+                    if (dl)
+                        out.push(dl);
+                }
+                return out;
+            }
+            : undefined;
+        return {
+            conversationId: channelId,
+            ...(messageId ? { messageId } : {}),
+            ...(timestampMs !== undefined ? { messageTimestampMs: timestampMs } : {}),
+            from: fromId,
+            ...(fromName ? { fromName } : {}),
+            text,
+            chatType,
+            ...(guildId ? { guildId } : {}),
+            ...(memberRoleIds.length > 0 ? { memberRoleIds } : {}),
+            ...(threadId ? { threadId } : {}),
+            ...(mentions.length > 0 ? { mentions } : {}),
+            ...(replyTo ? { replyTo } : {}),
+            ...(opts?.edited ? { edited: true } : {}),
+            ...(resolveMedia ? { resolveMedia } : {}),
+            raw: message,
+        };
+    };
+    /** Is this message one the bot itself authored (its own echo)? */
+    const isSelfAuthored = (message) => {
+        if (selfId && message.author?.id === selfId)
+            return true;
+        // A webhook / bot author with no resolvable user shouldn't loop us either,
+        // but only OUR own id is a definite echo; other bots are allowed through.
+        return false;
+    };
+    /**
+     * Best-effort resolve the parent of a reply into `replyTo.body` (+ `from`).
+     * Discord doesn't inline the replied-to text, so we fetch it: `fetchReference()`
+     * first (discord.js resolves the reference directly), then `channel.messages.fetch(id)`
+     * as a fallback. The body is the parent's assembled text (token-expanded), hard-capped.
+     * Mutates `normalized.replyTo` in place. Fully guarded — any error leaves the
+     * `{ messageId }`-only context untouched so delivery never blocks/fails.
+     */
+    const backfillReplyBody = async (message, normalized) => {
+        const refId = message.reference?.messageId;
+        if (!normalized.replyTo || normalized.replyTo.body || typeof refId !== "string" || !refId)
+            return;
+        try {
+            let parent = null;
+            if (typeof message.fetchReference === "function") {
+                parent = await message.fetchReference();
+            }
+            if (!parent && typeof message.channel?.messages?.fetch === "function") {
+                parent = await message.channel.messages.fetch(refId);
+            }
+            if (!parent)
+                return;
+            const body = assembleDiscordText(parent, resolveLookups(parent)).replace(/\n/g, " ").slice(0, 300);
+            const from = typeof parent.author?.id === "string" ? parent.author.id : undefined;
+            if (body || from) {
+                normalized.replyTo = {
+                    ...normalized.replyTo,
+                    ...(body ? { body } : {}),
+                    ...(from ? { from } : {}),
+                };
+            }
+        }
+        catch (err) {
+            safeLog("discord reply-parent backfill failed", { error: err instanceof Error ? err.message : String(err) });
+        }
+    };
+    /**
+     * Handle a messageCreate / messageUpdate event.
+     *
+     * ASYNC because of three best-effort REST hydrations (all guarded, all
+     * post-`normalize`, mirroring the Slack thread-backfill pattern):
+     *   - reply-parent backfill → fills `replyTo.body` so the agent sees what was
+     *     replied to (Fix 1b);
+     *   - system events (joins / pins / boosts / thread-created …) → synthesize a
+     *     concise note as the inbound text so the agent learns the event (Fix 1c);
+     *   - empty-payload hydration → re-pull a late / proxied empty-content message
+     *     once and re-assemble before bailing (Fix 1d).
+     */
+    const handleMessage = async (message, opts) => {
+        try {
+            stampInboundEvent();
+            // Skip the bot's own messages (echoes) — a bot must never reply to itself.
+            if (isSelfAuthored(message))
+                return;
+            // Skip a message authored by ANY bot/webhook to avoid bot-loops (parity with
+            // the conservative default; a human-only channel is the norm for Brigade).
+            if (message.author?.bot === true)
+                return;
+            const id = typeof message.id === "string" ? message.id : "";
+            if (!id)
+                return;
+            // Edits fold the edit timestamp into the key so a second edit still routes.
+            const editStamp = opts?.edited && typeof message.editedTimestamp === "number" ? message.editedTimestamp : "";
+            const key = opts?.edited ? `edit:${id}:${editStamp}` : id;
+            if (!eventDedupe.claim(key))
+                return; // already seen
+            // SYSTEM event (join / pin / boost / thread-created …): no user content, so
+            // synthesize a concise note as the inbound text and route it (no debounce).
+            // An UNMAPPED system type yields null → drop it. Checked BEFORE normalize so
+            // a content-less system message isn't treated as an empty user message.
+            if (!isDiscordUserMessageType(message.type)) {
+                const channelId = typeof message.channelId === "string" ? message.channelId : typeof message.channel?.id === "string" ? message.channel.id : "";
+                const note = resolveDiscordSystemEvent(message, channelId);
+                if (!note)
+                    return; // unmapped system type — drop
+                const normalized = normalize(message, opts);
+                if (!normalized)
+                    return;
+                normalized.text = note;
+                args.onMessage(normalized);
+                lastInboundChannel.add(normalized.conversationId);
+                return;
+            }
+            let normalized = normalize(message, opts);
+            if (!normalized)
+                return;
+            // Does this message need any async REST hydration? (Empty-payload re-pull OR
+            // reply-parent backfill.) When NOTHING async applies — the common case — we
+            // deliver SYNCHRONOUSLY so callers see the inbound on the same tick.
+            const needsHydration = !normalized.text.trim() && !hasInboundMedia(message) && typeof message.fetch === "function";
+            const refId = message.reference?.messageId;
+            const needsReplyBackfill = !!normalized.replyTo &&
+                !normalized.replyTo.body &&
+                typeof refId === "string" &&
+                !!refId &&
+                (typeof message.fetchReference === "function" || typeof message.channel?.messages?.fetch === "function");
+            if (!needsHydration && !needsReplyBackfill) {
+                args.onMessage(normalized);
+                lastInboundChannel.add(normalized.conversationId);
+                return;
+            }
+            // Empty-payload hydration (Fix 1d): the MESSAGE CONTENT intent can deliver a
+            // late / proxied payload with empty content + no media. Best-effort re-pull
+            // the message once, re-assemble, and only bail if STILL empty.
+            if (needsHydration) {
+                try {
+                    const refetched = await message.fetch();
+                    if (refetched && typeof refetched === "object") {
+                        const renorm = normalize(refetched, opts);
+                        if (renorm && (renorm.text.trim() || renorm.resolveMedia)) {
+                            normalized = renorm;
+                            message = refetched;
+                        }
+                    }
+                }
+                catch (err) {
+                    safeLog("discord empty-payload hydration failed", { error: err instanceof Error ? err.message : String(err) });
+                }
+            }
+            // Reply-parent backfill (Fix 1b): fill `replyTo.body` from the parent message.
+            await backfillReplyBody(message, normalized);
+            args.onMessage(normalized);
+            lastInboundChannel.add(normalized.conversationId);
+        }
+        catch (err) {
+            safeLog("discord inbound handler error", { error: err instanceof Error ? err.message : String(err) });
+        }
+    };
+    /**
+     * Normalize a reaction-add into the inbound shape. Surfaces the single added
+     * emoji, the actor, and the target message id. Reactions carry no text.
+     */
+    const normalizeReaction = (reaction, user) => {
+        const msg = reaction.message;
+        const channel = typeof msg?.channelId === "string" ? msg.channelId : typeof msg?.channel?.id === "string" ? msg.channel.id : "";
+        const target = typeof msg?.id === "string" ? msg.id : "";
+        // A custom emoji surfaces as `name:id`; a unicode emoji as its char.
+        const emojiName = reaction.emoji?.name ?? "";
+        const emoji = reaction.emoji?.id ? `${emojiName}:${reaction.emoji.id}` : emojiName;
+        if (!channel || !target || !emoji)
+            return null;
+        const fromId = typeof user?.id === "string" ? user.id : channel;
+        if (selfId && fromId === selfId)
+            return null; // the bot's own reaction
+        if (user?.bot === true)
+            return null; // ignore other bots' reactions
+        const fromName = user?.username;
+        const guildId = typeof msg?.guildId === "string" ? msg.guildId : undefined;
+        // Author of the REACTED message — lets the adapter gate `reactionNotifications: "own"`.
+        const targetAuthorId = typeof msg?.author?.id === "string" ? msg.author.id : undefined;
+        return {
+            conversationId: channel,
+            from: fromId,
+            ...(fromName ? { fromName } : {}),
+            text: "",
+            chatType: msg?.guildId ? "group" : "direct",
+            ...(guildId ? { guildId } : {}),
+            reaction: { emojis: [emoji], targetMessageId: target, ...(targetAuthorId ? { targetAuthorId } : {}) },
+            raw: { reaction, user },
+        };
+    };
+    /** Handle a messageReactionAdd event. */
+    const handleReactionAdd = (reaction, user) => {
+        try {
+            stampInboundEvent();
+            const key = `react:${user?.id}:${reaction.emoji?.name ?? reaction.emoji?.id}:${reaction.message?.id}`;
+            if (!eventDedupe.claim(key))
+                return;
+            const normalized = normalizeReaction(reaction, user);
+            if (!normalized)
+                return;
+            args.onReaction?.(normalized);
+        }
+        catch (err) {
+            safeLog("discord reaction handler error", { error: err instanceof Error ? err.message : String(err) });
+        }
+    };
+    /** Handle a messageReactionRemove event — release the add-dedupe key so a re-add re-routes. */
+    const handleReactionRemove = (reaction, user) => {
+        stampInboundEvent(); // liveness: a removal is still inbound traffic
+        eventDedupe.release(`react:${user?.id}:${reaction.emoji?.name ?? reaction.emoji?.id}:${reaction.message?.id}`);
+    };
+    /** Normalize a button-press interaction into the approval-callback inbound shape. */
+    const normalizeButton = (interaction) => {
+        const value = typeof interaction.customId === "string" ? interaction.customId : "";
+        if (!value)
+            return null;
+        const channel = typeof interaction.channelId === "string" ? interaction.channelId : typeof interaction.channel?.id === "string" ? interaction.channel.id : "";
+        const fromId = typeof interaction.user?.id === "string" ? interaction.user.id : channel;
+        if (!channel && !fromId)
+            return null;
+        const threadId = interaction.channel && isThreadChannel(interaction.channel) ? channel : undefined;
+        const fromName = interaction.user?.username;
+        return {
+            conversationId: channel || fromId,
+            from: fromId,
+            ...(fromName ? { fromName } : {}),
+            text: "",
+            chatType: interaction.guildId ? "group" : "direct",
+            ...(typeof interaction.guildId === "string" ? { guildId: interaction.guildId } : {}),
+            ...(threadId ? { threadId } : {}),
+            callbackQuery: { data: value, callbackId: interaction.id ?? "" },
+            raw: interaction,
+        };
+    };
+    /**
+     * Normalize a SELECT-menu press into the same callback-inbound shape a button
+     * press uses (Fix 3a), but carrying the chosen `values`. The select's custom_id
+     * IS a general token (the central pipeline surfaces the values in the turn
+     * text). For an ENTITY select the raw values are Discord ids — they're prefixed
+     * with the select's kind (`user:` / `role:` / `channel:` / `mentionable:`) so
+     * the agent can tell what kind of id it received; a STRING select's values are
+     * the option values verbatim.
+     */
+    const normalizeSelect = (interaction, kind) => {
+        const value = typeof interaction.customId === "string" ? interaction.customId : "";
+        if (!value)
+            return null;
+        const channel = typeof interaction.channelId === "string" ? interaction.channelId : typeof interaction.channel?.id === "string" ? interaction.channel.id : "";
+        const fromId = typeof interaction.user?.id === "string" ? interaction.user.id : channel;
+        if (!channel && !fromId)
+            return null;
+        const threadId = interaction.channel && isThreadChannel(interaction.channel) ? channel : undefined;
+        const fromName = interaction.user?.username;
+        const rawValues = Array.isArray(interaction.values) ? interaction.values.filter((v) => typeof v === "string") : [];
+        const prefix = kind === "string" ? "" : `${kind}:`;
+        const values = rawValues.map((v) => `${prefix}${v}`);
+        return {
+            conversationId: channel || fromId,
+            from: fromId,
+            ...(fromName ? { fromName } : {}),
+            text: "",
+            chatType: interaction.guildId ? "group" : "direct",
+            ...(typeof interaction.guildId === "string" ? { guildId: interaction.guildId } : {}),
+            ...(threadId ? { threadId } : {}),
+            callbackQuery: { data: value, callbackId: interaction.id ?? "", values },
+            raw: interaction,
+        };
+    };
+    /**
+     * Normalize a MODAL SUBMIT into an ordinary inbound MESSAGE (Fix 3b). A filled
+     * form is a typed turn, not a button tap, so it routes via `onMessage` carrying
+     * the formatted `Label: value` body — the agent sees what was entered exactly as
+     * if the person typed it. The modal entry is consumed (single-use); a missing /
+     * expired entry yields null so the submit degrades gracefully.
+     */
+    const normalizeModalSubmit = (interaction) => {
+        const customId = typeof interaction.customId === "string" ? interaction.customId : "";
+        const modalId = decodeDiscordModalCustomId(customId);
+        if (!modalId)
+            return null;
+        const entry = consumeDiscordModal(modalId);
+        if (!entry) {
+            safeLog("discord modal submit for an unknown/expired form — dropped", { modalId });
+            return null;
+        }
+        const channel = typeof interaction.channelId === "string" ? interaction.channelId : typeof interaction.channel?.id === "string" ? interaction.channel.id : "";
+        const fromId = typeof interaction.user?.id === "string" ? interaction.user.id : channel;
+        if (!channel && !fromId)
+            return null;
+        const threadId = interaction.channel && isThreadChannel(interaction.channel) ? channel : undefined;
+        const fromName = interaction.user?.username;
+        const values = extractModalFieldValues(interaction, entry.fields);
+        const text = formatModalSubmissionText(entry, values);
+        return {
+            conversationId: channel || fromId,
+            from: fromId,
+            ...(fromName ? { fromName } : {}),
+            text,
+            chatType: interaction.guildId ? "group" : "direct",
+            ...(typeof interaction.guildId === "string" ? { guildId: interaction.guildId } : {}),
+            ...(threadId ? { threadId } : {}),
+            raw: interaction,
+        };
+    };
+    /**
+     * Normalize a slash-command interaction into an ordinary inbound message so the
+     * central command map (`/help`, `/status`, …) handles it. The command name is
+     * mapped to `/command` text.
+     */
+    const normalizeSlash = (interaction) => {
+        const command = typeof interaction.commandName === "string" ? interaction.commandName : "";
+        const channel = typeof interaction.channelId === "string" ? interaction.channelId : "";
+        const fromId = typeof interaction.user?.id === "string" ? interaction.user.id : channel;
+        if (!command || !channel)
+            return null;
+        const fromName = interaction.user?.username;
+        return {
+            conversationId: channel,
+            from: fromId,
+            ...(fromName ? { fromName } : {}),
+            text: `/${command}`,
+            chatType: interaction.guildId ? "group" : "direct",
+            ...(typeof interaction.guildId === "string" ? { guildId: interaction.guildId } : {}),
+            raw: interaction,
+        };
+    };
+    /**
+     * The five select-menu type guards mapped to their kind. The first that fires
+     * wins (exactly one is true for a given select press).
+     */
+    const selectKindOf = (interaction) => {
+        if (typeof interaction.isStringSelectMenu === "function" && interaction.isStringSelectMenu())
+            return "string";
+        if (typeof interaction.isUserSelectMenu === "function" && interaction.isUserSelectMenu())
+            return "user";
+        if (typeof interaction.isRoleSelectMenu === "function" && interaction.isRoleSelectMenu())
+            return "role";
+        if (typeof interaction.isChannelSelectMenu === "function" && interaction.isChannelSelectMenu())
+            return "channel";
+        if (typeof interaction.isMentionableSelectMenu === "function" && interaction.isMentionableSelectMenu())
+            return "mentionable";
+        return null;
+    };
+    /** Handle an interactionCreate event (button / select / modal-submit / slash). */
+    const handleInteraction = (interaction) => {
+        try {
+            stampInboundEvent();
+            if (typeof interaction.isButton === "function" && interaction.isButton()) {
+                // A button whose custom_id is a `modal:<id>` marker OPENS a modal instead
+                // of routing a turn (Fix 3b). Otherwise ack silently + route the press.
+                const customId = typeof interaction.customId === "string" ? interaction.customId : "";
+                if (isDiscordModalCustomId(customId)) {
+                    void openModalForTrigger(interaction, customId);
+                    return;
+                }
+                // Ack the press silently first so Discord doesn't show "interaction
+                // failed"; then route the normalized inbound.
+                void interaction.deferUpdate?.().catch(() => { });
+                const normalized = normalizeButton(interaction);
+                if (normalized)
+                    args.onCallbackQuery?.(normalized);
+                return;
+            }
+            const selectKind = selectKindOf(interaction);
+            if (selectKind) {
+                // A select press is acked silently (no visible change) then routed like a
+                // button press, carrying the chosen values (Fix 3a).
+                void interaction.deferUpdate?.().catch(() => { });
+                const normalized = normalizeSelect(interaction, selectKind);
+                if (normalized)
+                    args.onCallbackQuery?.(normalized);
+                return;
+            }
+            if (typeof interaction.isModalSubmit === "function" && interaction.isModalSubmit()) {
+                // Ack the submit so the form closes; route the filled form as a turn (Fix 3b).
+                void interaction.deferUpdate?.().catch(() => { });
+                const normalized = normalizeModalSubmit(interaction);
+                if (normalized)
+                    args.onMessage(normalized);
+                return;
+            }
+            if (typeof interaction.isChatInputCommand === "function" && interaction.isChatInputCommand()) {
+                // Ack the command ephemerally so the client spinner clears; the real
+                // reply is delivered by the pipeline as a normal channel message.
+                void interaction.reply?.({ content: "On it.", ephemeral: true }).catch(() => { });
+                const normalized = normalizeSlash(interaction);
+                if (normalized)
+                    args.onMessage(normalized);
+                return;
+            }
+        }
+        catch (err) {
+            safeLog("discord interaction handler error", { error: err instanceof Error ? err.message : String(err) });
+        }
+    };
+    /**
+     * Open the modal a modal-trigger button references (Fix 3b). Looks up the
+     * (non-consuming) registry entry, builds the discord.js modal via the injected
+     * builders, and calls `interaction.showModal`. A missing entry / absent builder
+     * is acked-silently so the client doesn't hang. The entry is NOT consumed here —
+     * consumption happens on submit so the modal stays openable until then.
+     */
+    const openModalForTrigger = async (interaction, customId) => {
+        try {
+            const modalId = decodeDiscordModalCustomId(customId);
+            const entry = modalId ? getDiscordModal(modalId) : undefined;
+            if (!entry || typeof interaction.showModal !== "function" || typeof resolvedBuilders.buildModal !== "function") {
+                // Nothing to show — ack silently so the press doesn't read as failed.
+                void interaction.deferUpdate?.().catch(() => { });
+                if (modalId && !entry)
+                    safeLog("discord modal trigger for an unknown/expired form", { modalId });
+                return;
+            }
+            const modal = resolvedBuilders.buildModal({ modalId, title: entry.title, entry });
+            await interaction.showModal(modal);
+        }
+        catch (err) {
+            safeLog("discord showModal failed", { error: err instanceof Error ? err.message : String(err) });
+            void interaction.deferUpdate?.().catch(() => { });
+        }
+    };
+    /**
+     * Handle a THREAD_UPDATE (Fix 6). When a thread transitions INTO the archived
+     * state (was not archived, now is), drop any sub-agent thread binding pointing
+     * at it so an archived thread doesn't leak a binding. discord.js hands the old +
+     * new `ThreadChannel`; we read `.archived` off each (a partial may omit `old`,
+     * in which case we act on the new archived state alone). No-op for any other
+     * thread update (rename, lock, slow-mode, …).
+     */
+    const handleThreadArchive = (oldThread, newThread) => {
+        const next = newThread;
+        const prev = oldThread;
+        const threadId = typeof next?.id === "string" ? next.id : "";
+        if (!threadId)
+            return;
+        const nowArchived = next?.archived === true;
+        const wasArchived = prev?.archived === true;
+        // Only act on the not-archived → archived transition (or when we have no prior
+        // state to compare and it's archived now).
+        if (!nowArchived || wasArchived)
+            return;
+        const dropped = forgetDiscordSubagentThreadBindingByThreadId(threadId);
+        if (dropped > 0) {
+            safeLog("discord thread archived — dropped sub-agent thread binding", { threadId, dropped });
+        }
+    };
+    /* ── event wiring ── */
+    const wireClient = (c) => {
+        // handleMessage is async (it does best-effort REST hydration for reply bodies /
+        // empty payloads); it self-guards every path, so the promise is voided here.
+        c.on("messageCreate", ((message) => void handleMessage(message)));
+        c.on("messageUpdate", ((_old, updated) => {
+            // messageUpdate fires for non-content edits too (embeds resolving, pins);
+            // only route when there's content to act on.
+            if (updated && typeof updated === "object")
+                void handleMessage(updated, { edited: true });
+        }));
+        c.on("messageDelete", (() => {
+            // A deleted message carries no routable content — just stamp liveness.
+            stampInboundEvent();
+        }));
+        // THREAD_UPDATE (Fix 6): when a thread transitions to archived, best-effort
+        // drop any sub-agent thread binding for it so an archived thread doesn't leak
+        // a binding. Fully guarded — a malformed/partial payload is a no-op.
+        c.on("threadUpdate", ((oldThread, newThread) => {
+            stampInboundEvent(); // thread state change is still gateway traffic (liveness)
+            try {
+                handleThreadArchive(oldThread, newThread);
+            }
+            catch {
+                /* never let a thread-update payload break the listener */
+            }
+        }));
+        c.on("messageReactionAdd", ((reaction, user) => handleReactionAdd(reaction, user)));
+        c.on("messageReactionRemove", ((reaction, user) => handleReactionRemove(reaction, user)));
+        c.on("interactionCreate", ((interaction) => handleInteraction(interaction)));
+        // A privileged-intents (4014) or auth-failed (4004) Gateway CLOSE is terminal:
+        // discord.js would otherwise loop reconnect attempts forever while health
+        // stayed "connected". Flip the token-invalid flag so health goes "logged-out"
+        // and the operator is told to fix intents / re-token. Any other close code
+        // (e.g. 1006) is a normal transient drop discord.js recovers from on its own.
+        c.on("shardDisconnect", ((closeEvent) => {
+            stampInboundEvent(); // a disconnect is still gateway traffic (liveness)
+            const code = closeEvent?.code;
+            if (code !== 4014 && code !== 4004)
+                return;
+            if (tokenInvalid)
+                return;
+            tokenInvalid = true;
+            connected = false;
+            safeLog("discord gateway closed with a terminal code — re-token / fix intents required", { code });
+            args.onTokenInvalid?.();
+        }));
+        // A token revoked / Gateway error mid-session surfaces on `error`; mark the
+        // token invalid on an auth-class error so health flips to "logged-out".
+        c.on("error", ((err) => {
+            if (!isDiscordUnauthorized(err)) {
+                safeLog("discord client error", { error: err instanceof Error ? err.message : String(err) });
+                return;
+            }
+            if (tokenInvalid)
+                return;
+            tokenInvalid = true;
+            connected = false;
+            safeLog("discord token rejected mid-session — re-token required");
+            args.onTokenInvalid?.();
+        }));
+    };
+    /* ── bootstrap + supervise ── */
+    /**
+     * Build the client, wire events, login, cache identity, and WAIT for the
+     * Gateway to reach READY (Phase 5). A socket can `login()` (open) yet never
+     * fire `clientReady`; we don't trust such a socket. When `readyTimeoutMs > 0`
+     * and READY hasn't fired by the deadline we destroy the client and throw so the
+     * supervise loop reconnects. On READY we apply the configured presence.
+     */
+    const startOnce = async () => {
+        const c = buildClient(args.botToken);
+        client = c;
+        ready = false;
+        wireClient(c);
+        // `clientReady` fires once the Gateway handshake + initial guild sync settle.
+        c.once("clientReady", (() => {
+            selfId = typeof c.user?.id === "string" ? c.user.id : null;
+            selfName = typeof c.user?.username === "string" ? c.user.username : null;
+            ready = true;
+            cancelReadyWatchdog();
+            // Apply the configured presence once the client is fully ready.
+            applyPresence();
+        }));
+        // login() rejects on an invalid token (terminal); resolves once the Gateway
+        // is identifying. We treat a resolved login as connected and read the cached
+        // user id (clientReady may fire just after login resolves).
+        await c.login(args.botToken);
+        selfId = selfId ?? (typeof c.user?.id === "string" ? c.user.id : null);
+        selfName = selfName ?? (typeof c.user?.username === "string" ? c.user.username : null);
+        // Arm the READY watchdog (Phase 5, NON-blocking): a socket can open
+        // (`login()` resolved) yet never fire `clientReady`. If that's still the case
+        // after the deadline, destroy the client + re-enter the supervise loop so we
+        // don't trust a half-open socket. `clientReady` cancels it. `startOnce`
+        // returns immediately so the adapter's start() never blocks on READY.
+        armReadyWatchdog(c);
+    };
+    /* ── READY watchdog (Phase 5) ── */
+    let readyTimer;
+    const cancelReadyWatchdog = () => {
+        if (readyTimer) {
+            clearTimeout(readyTimer);
+            readyTimer = undefined;
+        }
+    };
+    const armReadyWatchdog = (c) => {
+        cancelReadyWatchdog();
+        if (readyTimeoutMs <= 0 || ready || closed)
+            return;
+        readyTimer = setTimeout(() => {
+            readyTimer = undefined;
+            // READY arrived in the meantime / we tore down / the token died — nothing to do.
+            if (ready || closed || tokenInvalid || client !== c)
+                return;
+            safeLog("discord gateway opened but did not reach READY within deadline — destroying + reconnecting", {
+                account: accountId,
+                deadlineMs: readyTimeoutMs,
+            });
+            connected = false;
+            // Re-enter the supervise loop on a fresh tick (destroy + reconnect with backoff).
+            void (async () => {
+                await teardownClient();
+                if (closed || tokenInvalid)
+                    return;
+                reconnectAttempts += 1;
+                const delay = discordBackoffDelay(reconnectAttempts);
+                await sleep(delay);
+                if (closed || tokenInvalid)
+                    return;
+                loopPromise = superviseLoop().catch((err) => {
+                    safeLog("discord supervise loop crashed", { error: err instanceof Error ? err.message : String(err) });
+                });
+            })();
+        }, readyTimeoutMs);
+        if (typeof readyTimer.unref === "function")
+            readyTimer.unref();
+    };
+    /**
+     * The supervise loop — login, and on a transient setup failure reconnect with
+     * backoff. discord.js auto-reconnects the Gateway internally once logged in, so
+     * this loop mainly guards the initial login. A terminal auth error stops it.
+     */
+    const superviseLoop = async () => {
+        while (!closed && !tokenInvalid) {
+            try {
+                await startOnce();
+            }
+            catch (err) {
+                if (isDiscordUnauthorized(err)) {
+                    tokenInvalid = true;
+                    connected = false;
+                    safeLog("discord token rejected — re-token required; not connecting");
+                    args.onTokenInvalid?.();
+                    return;
+                }
+                if (closed)
+                    return;
+                const delay = discordBackoffDelay(reconnectAttempts);
+                reconnectAttempts += 1;
+                if (reconnectAttempts > RECONNECT_MAX_ATTEMPTS) {
+                    safeLog("discord setup attempts exhausted — giving up until restart", { attempts: reconnectAttempts });
+                    return;
+                }
+                safeLog("discord setup failed — retrying", {
+                    attempt: reconnectAttempts,
+                    delayMs: delay,
+                    error: err instanceof Error ? err.message : String(err),
+                });
+                // Tear down the half-built client before retrying.
+                await teardownClient();
+                await sleep(delay);
+                continue;
+            }
+            if (closed) {
+                await teardownClient();
+                return;
+            }
+            connected = true;
+            connectedAtMs = Date.now();
+            reconnectAttempts = 0;
+            safeLog("discord connected", { account: accountId, self: selfName ? `@${selfName}` : selfId });
+            args.onConnected?.();
+            return;
+        }
+    };
+    const teardownClient = async () => {
+        const c = client;
+        client = null;
+        ready = false;
+        if (c) {
+            try {
+                await c.destroy();
+            }
+            catch {
+                /* already destroyed */
+            }
+        }
+    };
+    // Kick startup. `connectDiscord` resolves as soon as the FIRST connect (or
+    // terminal failure) settles so the adapter's start() doesn't hang.
+    let resolveInitial;
+    const initial = new Promise((resolve) => {
+        resolveInitial = resolve;
+    });
+    const origOnConnected = args.onConnected;
+    const origOnTokenInvalid = args.onTokenInvalid;
+    args.onConnected = () => {
+        origOnConnected?.();
+        resolveInitial();
+    };
+    args.onTokenInvalid = () => {
+        origOnTokenInvalid?.();
+        resolveInitial();
+    };
+    loopPromise = superviseLoop().catch((err) => {
+        safeLog("discord supervise loop crashed", { error: err instanceof Error ? err.message : String(err) });
+    });
+    await Promise.race([initial, loopPromise.then(() => undefined)]);
+    /* ── outbound + control surface ── */
+    const requireLive = () => {
+        if (tokenInvalid)
+            throw new Error("Discord token is invalid — set a new bot token and restart.");
+        if (!client)
+            throw new Error("Discord channel is not started");
+        return client;
+    };
+    /**
+     * Resolve the channel to send into. For a thread send the threadId IS the
+     * target channel (Discord threads are channels), so it wins over the base
+     * channel; otherwise the conversation channel is fetched. Returns the
+     * text-capable send channel or throws a clear error.
+     */
+    const resolveSendChannel = async (channel, threadId) => {
+        const c = requireLive();
+        const targetId = threadId || channel;
+        const ch = await c.channels.fetch(targetId);
+        if (!ch)
+            throw new Error(`Discord: channel ${targetId} not found`);
+        // A forum / media channel reports `isTextBased() === false` but IS a valid
+        // send target — the post is created as a thread (Fix 2b). So we only reject
+        // genuinely non-text channels (voice/category/…) that aren't forum-like.
+        if (typeof ch.isTextBased === "function" && !ch.isTextBased() && !isForumLikeChannel(ch)) {
+            throw new Error(`Discord: channel ${targetId} is not text-based`);
+        }
+        return ch;
+    };
+    /**
+     * Post a message to a resolved channel, auto-creating a forum/media thread when
+     * the target is a `GuildForum`/`GuildMedia` channel (Fix 2b) — those reject a
+     * plain `.send()`. The thread name is derived from the first non-empty content
+     * line. Returns the created message's id. Used by every text-ish send path.
+     */
+    const postToChannel = async (ch, options) => {
+        if (isForumLikeChannel(ch)) {
+            if (typeof ch.threads?.create !== "function") {
+                throw new Error("Discord: forum/media channel cannot create a thread (missing threads.create)");
+            }
+            const name = deriveForumThreadName(options.content ?? "");
+            const message = {};
+            if (options.content !== undefined)
+                message.content = options.content;
+            if (options.flags !== undefined)
+                message.flags = options.flags;
+            const created = await ch.threads.create({ name, message });
+            const messageId = typeof created.lastMessage?.id === "string" ? created.lastMessage.id : typeof created.id === "string" ? created.id : "";
+            return { messageId };
+        }
+        const sent = await ch.send(options);
+        return { messageId: typeof sent.id === "string" ? sent.id : "" };
+    };
+    const sendText = async (channel, text, opts) => {
+        try {
+            const ch = await resolveSendChannel(channel, opts?.threadId);
+            // SAFE allowed-mentions on EVERY send: explicit user/role pings still notify,
+            // but a stray `@everyone`/`@here` (agent text or prompt injection) can't
+            // mass-ping, and a reply won't ping the author it answers.
+            const options = { content: text, allowedMentions: safeDiscordAllowedMentions() };
+            // Silent send — suppress the recipient's notification (Fix 2c).
+            if (opts?.silent)
+                options.flags = MESSAGE_FLAG_SUPPRESS_NOTIFICATIONS;
+            // Native reply target — reply under the message being answered (only when not
+            // threading, since a thread send is already scoped).
+            if (opts?.replyToMessageId && !opts?.threadId) {
+                options.reply = { messageReference: opts.replyToMessageId, failIfNotExists: false };
+            }
+            return await postToChannel(ch, options);
+        }
+        catch (err) {
+            throw decodeDiscordSendError(err);
+        }
+    };
+    const sendInteractive = async (channel, text, rows, opts) => {
+        try {
+            const ch = await resolveSendChannel(channel, opts?.threadId);
+            // Components V2 (Fix 3c): when any row is a V2 container, the WHOLE message
+            // is V2 — the IsComponentsV2 flag is set and plain `content` is forbidden
+            // (text must live inside a V2 text block). When no V2 row is present the
+            // classic button/select path is byte-identical to before (plain content +
+            // no flag).
+            const hasV2 = rows.some((row) => isDiscordV2MessageSpec(row));
+            let effectiveRows = rows;
+            if (hasV2 && text && text.trim()) {
+                // Prepend the message text as a leading TextDisplay block inside the FIRST
+                // V2 container so the V2 message still shows the body (it can't use content).
+                effectiveRows = rows.map((row) => {
+                    if (isDiscordV2MessageSpec(row)) {
+                        return { ...row, blocks: [{ type: "text", text }, ...row.blocks] };
+                    }
+                    return row;
+                });
+            }
+            const components = resolvedBuilders.buildComponentRows(effectiveRows);
+            const options = { components, allowedMentions: safeDiscordAllowedMentions() };
+            if (hasV2) {
+                // A V2 message carries no plain content; the flag tells Discord to render
+                // the component tree. SuppressNotifications (silent) ORs in alongside it.
+                options.flags = DISCORD_FLAG_IS_COMPONENTS_V2 | (opts?.silent ? MESSAGE_FLAG_SUPPRESS_NOTIFICATIONS : 0);
+            }
+            else {
+                options.content = text;
+                if (opts?.silent)
+                    options.flags = MESSAGE_FLAG_SUPPRESS_NOTIFICATIONS;
+            }
+            if (opts?.replyToMessageId && !opts?.threadId) {
+                options.reply = { messageReference: opts.replyToMessageId, failIfNotExists: false };
+            }
+            const sent = await ch.send(options);
+            return { messageId: typeof sent.id === "string" ? sent.id : "" };
+        }
+        catch (err) {
+            throw decodeDiscordSendError(err);
+        }
+    };
+    const sendMedia = async (channel, media, opts) => {
+        try {
+            const ch = await resolveSendChannel(channel, opts?.threadId);
+            // validateOutboundMediaPath runs inside buildDiscordAttachment (throws on a
+            // refused path).
+            const att = buildDiscordAttachment(media);
+            const file = resolvedBuilders.buildAttachment(att.path, att.name);
+            const options = { files: [file], allowedMentions: safeDiscordAllowedMentions() };
+            if (opts?.silent)
+                options.flags = MESSAGE_FLAG_SUPPRESS_NOTIFICATIONS;
+            if (att.caption)
+                options.content = att.caption;
+            await ch.send(options);
+        }
+        catch (err) {
+            throw decodeDiscordSendError(err);
+        }
+    };
+    const fetchMessage = async (channel, messageId) => {
+        const ch = await resolveSendChannel(channel);
+        const fetchFn = ch.messages?.fetch;
+        if (typeof fetchFn !== "function")
+            throw new Error("Discord: channel cannot fetch messages");
+        const msg = await fetchFn.call(ch.messages, messageId);
+        if (!msg)
+            throw new Error(`Discord: message ${messageId} not found`);
+        return msg;
+    };
+    const editMessageText = async (channel, messageId, text) => {
+        const msg = await fetchMessage(channel, messageId);
+        await msg.edit({ content: text });
+    };
+    const deleteMessage = async (channel, messageId) => {
+        const msg = await fetchMessage(channel, messageId);
+        await msg.delete();
+    };
+    const pinMessage = async (channel, messageId) => {
+        const msg = await fetchMessage(channel, messageId);
+        if (typeof msg.pin !== "function")
+            throw new Error("Discord: message cannot be pinned");
+        await msg.pin();
+    };
+    const unpinMessage = async (channel, messageId) => {
+        const msg = await fetchMessage(channel, messageId);
+        if (typeof msg.unpin !== "function")
+            throw new Error("Discord: message cannot be unpinned");
+        await msg.unpin();
+    };
+    const react = async (channel, messageId, emoji) => {
+        const name = emoji.trim();
+        if (!name)
+            return;
+        try {
+            const msg = await fetchMessage(channel, messageId);
+            await msg.react(name);
+        }
+        catch (err) {
+            // Reactions are cosmetic — a missing emoji / permission never blocks.
+            safeLog("discord react failed (cosmetic)", { error: err instanceof Error ? err.message : String(err) });
+        }
+    };
+    const removeOwnReactions = async (channel, messageId) => {
+        try {
+            const msg = await fetchMessage(channel, messageId);
+            const cache = msg.reactions?.cache;
+            const list = cache
+                ? cache instanceof Map
+                    ? [...cache.values()]
+                    : [...cache]
+                : [];
+            const mine = list.filter((r) => r.me === true);
+            // Nothing cached as ours → fall back to removeAll only if no other users'
+            // reactions would be clobbered (we can't tell, so we DON'T removeAll here).
+            for (const r of mine) {
+                try {
+                    if (r.users?.remove)
+                        await r.users.remove(selfId ?? undefined);
+                    else if (r.remove)
+                        await r.remove();
+                }
+                catch (err) {
+                    safeLog("discord remove own reaction failed (cosmetic)", { error: err instanceof Error ? err.message : String(err) });
+                }
+            }
+        }
+        catch (err) {
+            safeLog("discord removeOwnReactions failed (cosmetic)", { error: err instanceof Error ? err.message : String(err) });
+        }
+    };
+    const registerCommands = async (commands) => {
+        if (!commands || commands.length === 0)
+            return;
+        const c = client;
+        const appId = selfId;
+        const rest = c?.rest;
+        if (!c || !appId || !rest || typeof rest.put !== "function")
+            return;
+        try {
+            // Lazy-import Routes only on the production path; a test fake doesn't reach
+            // here (no rest.put). The application-commands route is global.
+            const discord = await import("discord.js");
+            await rest.put(discord.Routes.applicationCommands(appId), { body: commands });
+            safeLog("discord application commands registered", { count: commands.length });
+        }
+        catch (err) {
+            safeLog("discord command registration failed (best-effort)", { error: err instanceof Error ? err.message : String(err) });
+        }
+    };
+    const setComposing = async (channel, state) => {
+        // Discord shows typing for ~10s or until the next message; we only fire it on
+        // "composing" (there's no "stop typing" call). Best-effort + cosmetic.
+        if (state !== "composing")
+            return;
+        try {
+            const ch = await resolveSendChannel(channel);
+            if (typeof ch.sendTyping === "function")
+                await ch.sendTyping();
+        }
+        catch {
+            /* cosmetic — missing permission / not live: ignore */
+        }
+    };
+    /**
+     * Create a thread off an existing message (Phase 5 autoThread). Fetches the
+     * channel + message, calls `message.startThread(...)`, and returns the new
+     * thread id. On a create-race (the message already has a thread — Discord
+     * rejects a second `startThread`) it returns the existing thread id. Returns
+     * `null` on any failure so the caller falls back to an un-threaded reply.
+     */
+    const createThreadFromMessage = async (channelId, messageId, opts) => {
+        try {
+            const c = requireLive();
+            const ch = await c.channels.fetch(channelId);
+            if (!ch || typeof ch.messages?.fetch !== "function")
+                return null;
+            // Forum/Media/Voice channels reject `startThread` (they have no
+            // message-thread surface). Skip SILENTLY (Fix 6) — the caller falls back
+            // to an un-threaded reply, and we suppress the noisy known-unsupported error.
+            const channelType = ch.type;
+            if (typeof channelType === "number" && THREAD_UNSUPPORTED_CHANNEL_TYPES.has(channelType)) {
+                return null;
+            }
+            const message = await ch.messages.fetch(messageId);
+            if (!message)
+                return null;
+            // Already threaded → reuse (avoids the "already has a thread" reject).
+            if (message.hasThread && message.thread?.id)
+                return message.thread.id;
+            if (typeof message.startThread !== "function")
+                return null;
+            const created = await message.startThread({
+                name: opts.name,
+                ...(typeof opts.autoArchiveMinutes === "number" ? { autoArchiveDuration: opts.autoArchiveMinutes } : {}),
+            });
+            const id = typeof created?.id === "string" ? created.id : "";
+            return id || null;
+        }
+        catch (err) {
+            safeLog("discord createThreadFromMessage failed", {
+                channelId,
+                error: err instanceof Error ? err.message : String(err),
+            });
+            // Create-race: another actor may have threaded the message already.
+            try {
+                const c = client;
+                const ch = c ? await c.channels.fetch(channelId) : null;
+                const message = ch && typeof ch.messages?.fetch === "function" ? await ch.messages.fetch(messageId) : null;
+                if (message?.thread?.id)
+                    return message.thread.id;
+            }
+            catch {
+                /* refetch also failed — give up */
+            }
+            return null;
+        }
+    };
+    const close = async () => {
+        closed = true;
+        connected = false;
+        ready = false;
+        cancelReadyWatchdog();
+        await teardownClient();
+        try {
+            await Promise.race([
+                loopPromise ?? Promise.resolve(),
+                new Promise((resolve) => setTimeout(resolve, 5_000).unref?.()),
+            ]);
+        }
+        catch {
+            /* loop already settled */
+        }
+    };
+    return {
+        selfId: () => selfId,
+        selfName: () => selfName,
+        connectedAt: () => connectedAtMs,
+        lastEventAt: () => lastEventAtMs,
+        // `connected` is only set after startOnce resolves, which (when the watchdog
+        // is enabled) requires READY — so connected already implies the Gateway is
+        // fully up. The `|| ready` keeps the flag honest if the watchdog is disabled.
+        isConnected: () => connected && (ready || readyTimeoutMs <= 0),
+        isTokenInvalid: () => tokenInvalid,
+        sendText,
+        sendInteractive,
+        sendMedia,
+        react,
+        removeOwnReactions,
+        editMessageText,
+        deleteMessage,
+        pinMessage,
+        unpinMessage,
+        registerCommands,
+        setComposing,
+        markRead: async () => { },
+        applyPresence,
+        createThreadFromMessage,
+        close,
+    };
+}
+export { DISCORD_MESSAGE_LIMIT };
+//# sourceMappingURL=connection.js.map