@copilotkit/channels-discord 0.0.2

package/dist/discord-listener.js

@@ -0,0 +1,118 @@
+import { decodeReaction } from "./interaction.js";
+/** Wire Gateway events to normalized turns/commands. Mirrors attachSlackListener. */
+export function attachDiscordListener(cfg) {
+    const { client, botUserId, onTurn, onCommand, onReaction, commandPending } = cfg;
+    client.on("messageCreate", (msg) => {
+        const botId = typeof botUserId === "function" ? botUserId() : botUserId;
+        if (!shouldAnswer(msg, botId))
+            return;
+        const replyTarget = {
+            channelId: msg.channelId,
+            ...(msg.guildId ? { guildId: msg.guildId } : {}),
+        };
+        void Promise.resolve(onTurn({
+            conversationKey: msg.channelId,
+            replyTarget,
+            userText: stripMention(msg.content, botId),
+            senderUserId: msg.author.id,
+        })).catch((e) => console.error("[bot-discord] onTurn handler failed:", e));
+    });
+    client.on("interactionCreate", async (i) => {
+        if (typeof i?.isChatInputCommand !== "function" || !i.isChatInputCommand())
+            return;
+        // Register the live interaction with the timer-race registry, arming an
+        // auto-`deferReply` ~500ms before Discord's 3s window. This replaces the
+        // old eager `i.reply(...)` so a handler can `openModal` first; if it
+        // doesn't, `settle` acks (deferReply) and the real reply is delivered
+        // out-of-band as a channel message.
+        const triggerId = commandPending?.register(i);
+        const rawOptions = {};
+        for (const opt of i.options?.data ?? [])
+            rawOptions[opt.name] = opt.value;
+        const replyTarget = {
+            channelId: i.channelId,
+            ...(i.guildId ? { guildId: i.guildId } : {}),
+        };
+        try {
+            await onCommand({
+                command: i.commandName,
+                text: Object.values(rawOptions).map(String).join(" "),
+                rawOptions,
+                conversationKey: i.channelId,
+                replyTarget,
+                senderUserId: i.user.id,
+                triggerId,
+            });
+        }
+        catch (e) {
+            console.error("[bot-discord] onCommand handler failed:", e);
+        }
+        finally {
+            if (triggerId !== undefined)
+                await commandPending?.settle(triggerId);
+            // The deferReply(ephemeral) auto-ack only satisfies Discord's 3s window;
+            // the real response is delivered out-of-band as channel messages, so
+            // remove the dangling ephemeral "thinking…" once dispatch completes. A
+            // modal (showModal) does not defer, so `i.deferred` is false there and
+            // this is skipped; likewise if the handler itself already replied.
+            try {
+                if (i.deferred && !i.replied)
+                    await i.deleteReply?.();
+            }
+            catch {
+                /* interaction already gone / cleared */
+            }
+        }
+    });
+    if (onReaction) {
+        const handleReaction = (added) => async (reaction, user) => {
+            const botId = typeof botUserId === "function" ? botUserId() : botUserId;
+            const u = user;
+            // Skip the bot's own reaction. `u.bot` is `undefined` on a PARTIAL user
+            // (the uncached path these handlers support via Partials), so also guard
+            // by id — matching the other platforms' bot-id guard.
+            if (u?.bot || u?.id === botId)
+                return;
+            try {
+                const r = reaction;
+                if (r.partial)
+                    await r.fetch?.();
+                if (r.message?.partial)
+                    await r.message.fetch?.();
+            }
+            catch {
+                return;
+            }
+            // Keep the sink dispatch inside a try/catch so a throwing/rejecting
+            // user handler degrades-never-throws instead of escaping as an
+            // unhandled rejection — mirroring the onTurn/onCommand paths above.
+            try {
+                const evt = decodeReaction(reaction, user, added);
+                if (evt)
+                    await onReaction(evt);
+            }
+            catch (e) {
+                console.error("[bot-discord] onReaction handler failed:", e);
+            }
+        };
+        client.on("messageReactionAdd", handleReaction(true));
+        client.on("messageReactionRemove", handleReaction(false));
+    }
+}
+/** Answer @-mentions and DMs; skip our own messages and other bots. */
+function shouldAnswer(msg, botUserId) {
+    if (msg.author.id === botUserId)
+        return false;
+    if (msg.author.bot)
+        return false;
+    if (msg.channel.isDMBased())
+        return true;
+    // Only answer a DIRECT user mention. discord.js `mentions.has()` also returns
+    // true for role mentions and @everyone/@here that happen to include the bot,
+    // so narrow to the explicit user-mention set.
+    return msg.mentions.users?.has?.(botUserId) ?? false;
+}
+/** Drop a leading <@botId> / <@!botId> mention from the message text. */
+function stripMention(content, botUserId) {
+    return content.replace(new RegExp(`<@!?${botUserId}>`, "g"), "").trim();
+}

package/dist/discord-listener.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=discord-listener.test.d.ts.map

package/dist/discord-listener.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"discord-listener.test.d.ts","sourceRoot":"","sources":["../src/discord-listener.test.ts"],"names":[],"mappings":""}

package/dist/discord-listener.test.js

@@ -0,0 +1,361 @@
+import { describe, it, expect, vi } from "vitest";
+import { attachDiscordListener } from "./discord-listener.js";
+import { PendingInteractions } from "./pending-interactions.js";
+function fakeClient() {
+    const handlers = {};
+    return {
+        on(event, cb) {
+            handlers[event] = cb;
+        },
+        emit(event, ...args) {
+            handlers[event]?.(...args);
+        },
+    };
+}
+/** A complete (non-partial) reaction with the fields decodeReaction needs. */
+function reaction(over = {}) {
+    return {
+        partial: false,
+        emoji: { name: "👍", id: null },
+        message: { id: "m1", channelId: "c1", guildId: "g1", partial: false },
+        ...over,
+    };
+}
+const botId = "bot-1";
+function message(over) {
+    return {
+        author: { id: "u1", bot: false, username: "ann", globalName: "Ann" },
+        content: "hello",
+        channelId: "c1",
+        guildId: "g1",
+        mentions: { has: () => false, users: { has: () => false } },
+        channel: { isDMBased: () => false },
+        ...over,
+    };
+}
+describe("attachDiscordListener", () => {
+    it("emits a turn when the bot is mentioned", () => {
+        const client = fakeClient();
+        const onTurn = vi.fn();
+        attachDiscordListener({
+            client: client,
+            botUserId: botId,
+            onTurn,
+            onCommand: vi.fn(),
+        });
+        client.emit("messageCreate", message({
+            mentions: {
+                has: () => true,
+                users: { has: (q) => q === "bot-1" },
+            },
+            content: "<@bot-1> hi",
+        }));
+        expect(onTurn).toHaveBeenCalledWith(expect.objectContaining({
+            conversationKey: "c1",
+            replyTarget: { channelId: "c1", guildId: "g1" },
+            senderUserId: "u1",
+        }));
+    });
+    it("does not answer a role / @everyone mention that only matches via mentions.has", () => {
+        const client = fakeClient();
+        const onTurn = vi.fn();
+        attachDiscordListener({
+            client: client,
+            botUserId: botId,
+            onTurn,
+            onCommand: vi.fn(),
+        });
+        // `mentions.has` is true (e.g. a role mention the bot belongs to), but the
+        // bot is not a direct user mention, so we must NOT answer.
+        client.emit("messageCreate", message({
+            mentions: { has: () => true, users: { has: () => false } },
+            content: "<@&role-1> ping everyone",
+        }));
+        expect(onTurn).not.toHaveBeenCalled();
+    });
+    it("emits a turn for a DM even without a mention", () => {
+        const client = fakeClient();
+        const onTurn = vi.fn();
+        attachDiscordListener({
+            client: client,
+            botUserId: botId,
+            onTurn,
+            onCommand: vi.fn(),
+        });
+        client.emit("messageCreate", message({ channel: { isDMBased: () => true }, guildId: null }));
+        expect(onTurn).toHaveBeenCalledTimes(1);
+    });
+    it("ignores the bot's own messages", () => {
+        const client = fakeClient();
+        const onTurn = vi.fn();
+        attachDiscordListener({
+            client: client,
+            botUserId: botId,
+            onTurn,
+            onCommand: vi.fn(),
+        });
+        client.emit("messageCreate", message({ author: { id: "bot-1", bot: true } }));
+        expect(onTurn).not.toHaveBeenCalled();
+    });
+    it("ignores other bots", () => {
+        const client = fakeClient();
+        const onTurn = vi.fn();
+        attachDiscordListener({
+            client: client,
+            botUserId: botId,
+            onTurn,
+            onCommand: vi.fn(),
+        });
+        client.emit("messageCreate", message({ author: { id: "u2", bot: true } }));
+        expect(onTurn).not.toHaveBeenCalled();
+    });
+    it("resolves a getter-form botUserId per event", () => {
+        const client = fakeClient();
+        const onTurn = vi.fn();
+        let id = "";
+        attachDiscordListener({
+            client: client,
+            botUserId: () => id,
+            onTurn,
+            onCommand: vi.fn(),
+        });
+        // Before the id is known, the bot's own message would not match a mention,
+        // but a DM still answers regardless of id.
+        id = "bot-1";
+        client.emit("messageCreate", message({
+            mentions: {
+                has: (q) => q === "bot-1",
+                users: { has: (q) => q === "bot-1" },
+            },
+            content: "<@bot-1> hi",
+        }));
+        expect(onTurn).toHaveBeenCalledWith(expect.objectContaining({ conversationKey: "c1", senderUserId: "u1" }));
+    });
+    it("forwards a chat-input command via onCommand with a triggerId, then settles (deferReply) when no modal opens", async () => {
+        const client = fakeClient();
+        const onCommand = vi.fn();
+        const deferReply = vi.fn().mockResolvedValue(undefined);
+        const commandPending = new PendingInteractions({
+            ackBufferMs: 2500,
+            defer: (i) => i.deferReply(),
+        });
+        attachDiscordListener({
+            client: client,
+            botUserId: botId,
+            onTurn: vi.fn(),
+            onCommand,
+            commandPending,
+        });
+        client.emit("interactionCreate", {
+            isChatInputCommand: () => true,
+            id: "int-1",
+            commandName: "triage",
+            channelId: "c1",
+            guildId: "g1",
+            user: { id: "u1", username: "ann", globalName: "Ann" },
+            options: { data: [{ name: "priority", value: "high" }] },
+            deferReply,
+        });
+        // Let the async command handler (dispatch + settle) run to completion.
+        await Promise.resolve();
+        await Promise.resolve();
+        expect(onCommand).toHaveBeenCalledWith(expect.objectContaining({
+            command: "triage",
+            conversationKey: "c1",
+            rawOptions: { priority: "high" },
+            triggerId: "int-1",
+        }));
+        // No handler opened a modal, so `settle` acks via deferReply (the eager
+        // `i.reply(...)` is gone — the registry now owns the ack).
+        expect(deferReply).toHaveBeenCalledTimes(1);
+    });
+    it("clears the dangling deferred ephemeral after a non-modal command settles", async () => {
+        const client = fakeClient();
+        const deferReply = vi.fn().mockResolvedValue(undefined);
+        const deleteReply = vi.fn().mockResolvedValue(undefined);
+        const commandPending = new PendingInteractions({
+            ackBufferMs: 2500,
+            // The settle ack defers the reply, marking the interaction `deferred`.
+            defer: async (i) => {
+                await i.deferReply();
+                i.deferred = true;
+            },
+        });
+        attachDiscordListener({
+            client: client,
+            botUserId: botId,
+            onTurn: vi.fn(),
+            // No modal opened → the auto-defer ack leaves a dangling ephemeral
+            // "thinking…" spinner that must be cleared.
+            onCommand: vi.fn(),
+            commandPending,
+        });
+        const interaction = {
+            isChatInputCommand: () => true,
+            id: "int-3",
+            commandName: "triage",
+            channelId: "c1",
+            guildId: "g1",
+            user: { id: "u1" },
+            options: { data: [] },
+            deferred: false,
+            replied: false,
+            deferReply,
+            deleteReply,
+        };
+        client.emit("interactionCreate", interaction);
+        await new Promise((r) => setTimeout(r, 0));
+        expect(deferReply).toHaveBeenCalledTimes(1);
+        expect(deleteReply).toHaveBeenCalledTimes(1);
+    });
+    it("does not delete the reply when a command opened a modal (no defer)", async () => {
+        const client = fakeClient();
+        const deferReply = vi.fn().mockResolvedValue(undefined);
+        const deleteReply = vi.fn().mockResolvedValue(undefined);
+        const commandPending = new PendingInteractions({
+            ackBufferMs: 2500,
+            defer: (i) => i.deferReply(),
+        });
+        attachDiscordListener({
+            client: client,
+            botUserId: botId,
+            onTurn: vi.fn(),
+            // Simulate a handler that opened a modal: it marks the live interaction
+            // responded so `settle` never defers, and `deferred` stays false.
+            onCommand: async (cmd) => {
+                await commandPending.respondWith(cmd.triggerId, async () => { });
+            },
+            commandPending,
+        });
+        const interaction = {
+            isChatInputCommand: () => true,
+            id: "int-4",
+            commandName: "open-modal",
+            channelId: "c1",
+            guildId: "g1",
+            user: { id: "u1" },
+            options: { data: [] },
+            deferred: false,
+            replied: false,
+            deferReply,
+            deleteReply,
+        };
+        client.emit("interactionCreate", interaction);
+        await new Promise((r) => setTimeout(r, 0));
+        expect(deferReply).not.toHaveBeenCalled();
+        expect(deleteReply).not.toHaveBeenCalled();
+    });
+    it("does not ack or dispatch a non-command interaction", async () => {
+        const client = fakeClient();
+        const onCommand = vi.fn();
+        const deferReply = vi.fn().mockResolvedValue(undefined);
+        const commandPending = new PendingInteractions({
+            ackBufferMs: 2500,
+            defer: (i) => i.deferReply(),
+        });
+        attachDiscordListener({
+            client: client,
+            botUserId: botId,
+            onTurn: vi.fn(),
+            onCommand,
+            commandPending,
+        });
+        client.emit("interactionCreate", {
+            isChatInputCommand: () => false,
+            id: "int-2",
+            commandName: "triage",
+            channelId: "c1",
+            guildId: "g1",
+            user: { id: "u1" },
+            options: { data: [] },
+            deferReply,
+        });
+        await Promise.resolve();
+        await Promise.resolve();
+        expect(deferReply).not.toHaveBeenCalled();
+        expect(onCommand).not.toHaveBeenCalled();
+    });
+    it("catches a rejecting onTurn handler instead of letting it escape", async () => {
+        const client = fakeClient();
+        const errSpy = vi.spyOn(console, "error").mockImplementation(() => { });
+        const onTurn = vi.fn().mockRejectedValue(new Error("boom"));
+        attachDiscordListener({
+            client: client,
+            botUserId: botId,
+            onTurn,
+            onCommand: vi.fn(),
+        });
+        expect(() => client.emit("messageCreate", message({
+            mentions: {
+                has: () => true,
+                users: { has: (q) => q === "bot-1" },
+            },
+            content: "<@bot-1> hi",
+        }))).not.toThrow();
+        // Let the rejected promise settle so the .catch runs.
+        await Promise.resolve();
+        await Promise.resolve();
+        expect(errSpy).toHaveBeenCalledWith("[bot-discord] onTurn handler failed:", expect.any(Error));
+        errSpy.mockRestore();
+    });
+    it("catches a rejecting onReaction handler instead of letting it escape", async () => {
+        const client = fakeClient();
+        const errSpy = vi.spyOn(console, "error").mockImplementation(() => { });
+        const onReaction = vi.fn().mockRejectedValue(new Error("boom"));
+        attachDiscordListener({
+            client: client,
+            botUserId: botId,
+            onTurn: vi.fn(),
+            onCommand: vi.fn(),
+            onReaction,
+        });
+        expect(() => client.emit("messageReactionAdd", reaction(), { id: "u1", bot: false })).not.toThrow();
+        // Let the rejected promise settle so the .catch runs.
+        await Promise.resolve();
+        await Promise.resolve();
+        expect(onReaction).toHaveBeenCalledTimes(1);
+        expect(errSpy).toHaveBeenCalledWith("[bot-discord] onReaction handler failed:", expect.any(Error));
+        errSpy.mockRestore();
+    });
+    it("skips the bot's own reaction by id even when the bot flag is undefined (partial user)", () => {
+        const client = fakeClient();
+        const onReaction = vi.fn();
+        attachDiscordListener({
+            client: client,
+            botUserId: botId,
+            onTurn: vi.fn(),
+            onCommand: vi.fn(),
+            onReaction,
+        });
+        // A PARTIAL user has no `bot` flag, so the old `u?.bot` guard would let the
+        // bot's own reaction leak through and echo. Guarding by id must skip it.
+        client.emit("messageReactionAdd", reaction(), { id: botId });
+        expect(onReaction).not.toHaveBeenCalled();
+    });
+    it("dispatches a normal user's reaction add", () => {
+        const client = fakeClient();
+        const onReaction = vi.fn();
+        attachDiscordListener({
+            client: client,
+            botUserId: botId,
+            onTurn: vi.fn(),
+            onCommand: vi.fn(),
+            onReaction,
+        });
+        client.emit("messageReactionAdd", reaction(), { id: "U1", bot: false });
+        expect(onReaction).toHaveBeenCalledWith(expect.objectContaining({ added: true, conversationKey: "c1" }));
+    });
+    it("skips the bot's own reaction removal by id (partial user)", () => {
+        const client = fakeClient();
+        const onReaction = vi.fn();
+        attachDiscordListener({
+            client: client,
+            botUserId: botId,
+            onTurn: vi.fn(),
+            onCommand: vi.fn(),
+            onReaction,
+        });
+        client.emit("messageReactionRemove", reaction(), { id: botId });
+        expect(onReaction).not.toHaveBeenCalled();
+    });
+});

package/dist/download-files.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Inbound file transport. Discord messages can carry attachments; this turns
+ * them into AG-UI multimodal message content the agent's model can read —
+ * images as binary data parts and plain text/CSV/JSON/etc. as decoded `text`
+ * parts — downloading each from its public CDN URL (no auth required).
+ *
+ * The AgentContentPart union is intentionally identical to bot-slack's so the
+ * agent sees the same multimodal input shape across both adapters.
+ */
+/** The subset of a Discord attachment we use. */
+export interface DiscordAttachmentRef {
+    /** CDN URL — publicly fetchable, no auth header needed. */
+    url: string;
+    /** Original filename, used for extension-based MIME fallback. */
+    name: string;
+    /** MIME type reported by Discord (may be null/undefined for some uploads). */
+    contentType?: string | null;
+    /** Byte length reported by Discord. Used to gate the size cap pre-fetch. */
+    size: number;
+}
+/** A base64 data source, shared by every binary media part. */
+export type MediaDataSource = {
+    type: "data";
+    value: string;
+    mimeType: string;
+};
+/**
+ * AG-UI multimodal content parts — SAME shape as bot-slack emits so the agent
+ * sees identical multimodal input across both adapters.
+ *
+ * Binary media (image/audio/video/document) is passed straight through as a
+ * data part; the agent's model decides what it can actually consume. Most
+ * models read images and PDFs; far fewer accept audio or video. The bridge
+ * stays transport-only and does not gate on model capability.
+ */
+export type AgentContentPart = {
+    type: "text";
+    text: string;
+} | {
+    type: "image";
+    source: MediaDataSource;
+} | {
+    type: "audio";
+    source: MediaDataSource;
+} | {
+    type: "video";
+    source: MediaDataSource;
+} | {
+    type: "document";
+    source: MediaDataSource;
+};
+/** Tunables for inbound file handling (all optional; sane defaults). */
+export interface FileDeliveryConfig {
+    /**
+     * Skip a single file larger than this many bytes without fetching it.
+     * Default 10 MiB.
+     */
+    maxBytes?: number;
+    /**
+     * Truncate decoded text files to this many bytes before injecting them into
+     * the prompt (keeps a large text upload from blowing the token budget).
+     * Default 200 KiB.
+     */
+    maxTextBytes?: number;
+    /**
+     * Process at most this many attachments per message. Extra attachments beyond
+     * this cap are ignored without fetching, bounding the multimodal payload /
+     * token budget a single message can inject. Default 5.
+     */
+    maxFiles?: number;
+    /**
+     * Inject a custom fetch implementation (for testing or environments without
+     * the global `fetch`).
+     */
+    fetchImpl?: typeof fetch;
+}
+/**
+ * Download Discord message attachments and convert them to AG-UI content parts.
+ *
+ * Files whose reported size exceeds `maxBytes` are skipped WITHOUT fetching;
+ * the actual downloaded byte length is re-checked against the same cap after
+ * fetching. Images map to an image part; text/* MIME types and text-named
+ * files (.txt, .csv, .json, .md, .log, .tsv, .yaml) — including ones reported
+ * with a generic binary MIME like application/octet-stream — map to a text
+ * part (truncated to `maxTextBytes`); other binary content is skipped with a
+ * short text note explaining why (bot-slack parity), so the model knows a file
+ * was dropped.
+ *
+ * At most `maxFiles` attachments (default 5) are processed; any beyond that cap
+ * are ignored without fetching, bounding the multimodal payload a single
+ * message can inject.
+ */
+export declare function buildFileContentParts(attachments: readonly DiscordAttachmentRef[], cfg?: FileDeliveryConfig): Promise<AgentContentPart[]>;
+//# sourceMappingURL=download-files.d.ts.map

package/dist/download-files.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"download-files.d.ts","sourceRoot":"","sources":["../src/download-files.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,iDAAiD;AACjD,MAAM,WAAW,oBAAoB;IACnC,2DAA2D;IAC3D,GAAG,EAAE,MAAM,CAAC;IACZ,iEAAiE;IACjE,IAAI,EAAE,MAAM,CAAC;IACb,8EAA8E;IAC9E,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,4EAA4E;IAC5E,IAAI,EAAE,MAAM,CAAC;CACd;AAED,+DAA+D;AAC/D,MAAM,MAAM,eAAe,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC;AAEhF;;;;;;;;GAQG;AACH,MAAM,MAAM,gBAAgB,GACxB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAC9B;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,eAAe,CAAA;CAAE,GAC1C;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,eAAe,CAAA;CAAE,GAC1C;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,eAAe,CAAA;CAAE,GAC1C;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,MAAM,EAAE,eAAe,CAAA;CAAE,CAAC;AAElD,wEAAwE;AACxE,MAAM,WAAW,kBAAkB;IACjC;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;CAC1B;AA8BD;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,qBAAqB,CACzC,WAAW,EAAE,SAAS,oBAAoB,EAAE,EAC5C,GAAG,GAAE,kBAAuB,GAC3B,OAAO,CAAC,gBAAgB,EAAE,CAAC,CAsG7B"}