@spinabot/brigade 1.5.0 → 1.6.1

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

@@ -0,0 +1,786 @@
+/**
+ * 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 { buildDiscordSenderName, discordChannelType, discordThreadId, extractDiscordMemberRoleIds, extractDiscordMentions, extractDiscordReplyContext, extractDiscordText, hasInboundMedia, isThreadChannel, resolveInboundAttachments, } from "./inbound-extras.js";
+import { buildDiscordAttachment, downloadDiscordAttachment } from "./media.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;
+/**
+ * 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 };
+}
+/* ───────────────────────── 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));
+}
+/** 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;
+}
+/* ───────────────────────── 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 })),
+        };
+    }
+    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) => {
+                    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;
+                });
+            },
+        };
+    }
+    // `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;
+    // 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) };
+    };
+    /** 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;
+        const resolve = resolveLookups(message);
+        const text = extractDiscordText(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;
+    };
+    /** Handle a messageCreate / messageUpdate event. */
+    const handleMessage = (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
+            const normalized = normalize(message, opts);
+            if (!normalized)
+                return;
+            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;
+        return {
+            conversationId: channel,
+            from: fromId,
+            ...(fromName ? { fromName } : {}),
+            text: "",
+            chatType: msg?.guildId ? "group" : "direct",
+            ...(guildId ? { guildId } : {}),
+            reaction: { emojis: [emoji], targetMessageId: target },
+            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 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,
+        };
+    };
+    /** Handle an interactionCreate event (button press OR slash command). */
+    const handleInteraction = (interaction) => {
+        try {
+            stampInboundEvent();
+            if (typeof interaction.isButton === "function" && interaction.isButton()) {
+                // 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;
+            }
+            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) });
+        }
+    };
+    /* ── event wiring ── */
+    const wireClient = (c) => {
+        c.on("messageCreate", ((message) => 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")
+                handleMessage(updated, { edited: true });
+        }));
+        c.on("messageDelete", (() => {
+            // A deleted message carries no routable content — just stamp liveness.
+            stampInboundEvent();
+        }));
+        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. */
+    const startOnce = async () => {
+        const c = buildClient(args.botToken);
+        client = c;
+        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;
+        }));
+        // 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);
+    };
+    /**
+     * 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;
+        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`);
+        if (typeof ch.isTextBased === "function" && !ch.isTextBased()) {
+            throw new Error(`Discord: channel ${targetId} is not text-based`);
+        }
+        return ch;
+    };
+    const sendText = async (channel, text, opts) => {
+        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() };
+        // 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 };
+        }
+        const sent = await ch.send(options);
+        return { messageId: typeof sent.id === "string" ? sent.id : "" };
+    };
+    const sendInteractive = async (channel, text, rows, opts) => {
+        const ch = await resolveSendChannel(channel, opts?.threadId);
+        const components = resolvedBuilders.buildComponentRows(rows);
+        const options = { content: text, components, allowedMentions: safeDiscordAllowedMentions() };
+        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 : "" };
+    };
+    const sendMedia = async (channel, media, opts) => {
+        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 (att.caption)
+            options.content = att.caption;
+        await ch.send(options);
+    };
+    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 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 */
+        }
+    };
+    const close = async () => {
+        closed = true;
+        connected = false;
+        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,
+        isConnected: () => connected,
+        isTokenInvalid: () => tokenInvalid,
+        sendText,
+        sendInteractive,
+        sendMedia,
+        react,
+        removeOwnReactions,
+        editMessageText,
+        deleteMessage,
+        registerCommands,
+        setComposing,
+        markRead: async () => { },
+        close,
+    };
+}
+export { DISCORD_MESSAGE_LIMIT };
+//# sourceMappingURL=connection.js.map