@copilotkit/channels-discord 0.0.2

package/LICENSE

@@ -0,0 +1,21 @@
+The MIT License
+
+Copyright (c) Atai Barkai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/README.md

@@ -0,0 +1,308 @@
+# @copilotkit/channels-discord
+
+The **Discord `PlatformAdapter`** for [`@copilotkit/channels`](../channels). It connects a
+Discord application to any AG-UI agent: ingress via discord.js (Gateway), egress
+as Components V2 rendered from the `@copilotkit/channels-ui` JSX vocabulary, plus text
+streaming, opaque-id interactions, and HITL.
+
+You write your UI as JSX once (`@copilotkit/channels-ui`) and drive the bot with
+`@copilotkit/channels`; this package is the only one that talks to Discord.
+
+## Install
+
+```sh
+pnpm add @copilotkit/channels-discord @copilotkit/channels @copilotkit/channels-ui
+```
+
+## Quickstart
+
+```ts
+import { createBot } from "@copilotkit/channels";
+import {
+  discord,
+  defaultDiscordTools,
+  defaultDiscordContext,
+} from "@copilotkit/channels-discord";
+
+const bot = createBot({
+  adapters: [
+    discord({
+      botToken: process.env.DISCORD_BOT_TOKEN!, // Bot token — Gateway + REST
+      appId: process.env.DISCORD_APP_ID!, // Application ID for command registration
+      guildId: process.env.DISCORD_GUILD_ID, // Optional: instant guild-scoped dev commands
+    }),
+  ],
+  agent: (threadId) => makeAgent(threadId),
+  tools: [...defaultDiscordTools, ...appTools], // lookup_discord_user + your tools
+  context: [...defaultDiscordContext, ...appContext], // tagging/formatting/thread guidance
+  commands: [
+    {
+      name: "triage",
+      description: "Summarize the thread and propose issues.",
+      async handler({ thread, text }) {
+        await thread.runAgent({ prompt: `Triage: ${text}` });
+      },
+    },
+  ],
+});
+
+bot.onMention(({ thread }) => thread.runAgent());
+
+await bot.start();
+```
+
+`discord(opts)` returns a `DiscordAdapter`. The adapter connects via the
+Discord Gateway (WebSocket) — no public URL required. The listener pre-filters
+ingress to the turns the bot should answer (@-mentions in guild channels and
+DMs), so a single `onMention` handler covers most use cases.
+
+### Required env
+
+| Var                 | Purpose                                                                  |
+| ------------------- | ------------------------------------------------------------------------ |
+| `DISCORD_BOT_TOKEN` | Bot token for Gateway login and REST calls.                              |
+| `DISCORD_APP_ID`    | Application ID used when registering slash commands.                     |
+| `DISCORD_GUILD_ID`  | _(Optional)_ Guild ID for instant per-guild command registration in dev. |
+
+> **Global commands** (no `guildId`) propagate across Discord in ~1 hour.
+> **Guild-scoped commands** (with `guildId`) register instantly — use them
+> during development and switch to global for production.
+
+### Privileged intents
+
+The adapter requests **two** privileged gateway intents — `MessageContent` and
+`GuildMembers`. Both must be enabled in the
+[Discord Developer Portal](https://discord.com/developers/applications)
+(your application → Bot → Privileged Gateway Intents) or Gateway login is
+rejected.
+
+> - **Message Content Intent** — without it the Gateway delivers messages with
+>   an empty `content` string and the bot cannot read what users write.
+> - **Server Members Intent** (`GuildMembers`) — backs member search, which
+>   powers `lookup_discord_user` / `thread.lookupUser`. Without it those
+>   lookups fail and login is rejected.
+
+### Reaction intent and partials
+
+The adapter also requests `GuildMessageReactions` and enables the
+`Partials.Message` and `Partials.Reaction` partials:
+
+> - **`GuildMessageReactions`** — a **non-privileged** gateway intent; no
+>   toggle is needed in the Discord Developer Portal (unlike `MessageContent`
+>   and `GuildMembers`). Required to receive reaction events in guild channels.
+> - **`DirectMessageReactions`** — also non-privileged; required to receive
+>   reaction events in DMs. Discord.js v14 treats guild and DM reactions as
+>   separate intents — both are needed if the bot operates in DMs.
+> - **`Partials.Message` + `Partials.Reaction`** — Discord only includes full
+>   message objects in the reaction event payload when the message is already
+>   in the client's in-memory cache. For any message that was sent before the
+>   bot started (or was evicted from cache), the payload arrives as a _partial_.
+>   Enabling these two partials lets the listener fetch the full object on
+>   demand via `reaction.fetch()` / `reaction.message.fetch()`, so reactions
+>   on older messages are not silently dropped.
+
+## What it provides
+
+### JSX → Components V2 rendering
+
+`renderDiscordMessage(ir)` translates the `@copilotkit/channels-ui` vocabulary to a
+ready-to-send Discord Components V2 payload (`{ components, flags }`) with the
+`IS_COMPONENTS_V2` flag (`MessageFlags.IsComponentsV2`) set. It builds on
+`renderComponents(ir)`, the lower-level building block, which returns a bare
+`ContainerBuilder` with no flag. The entire message is wrapped in a single
+`Container`; child nodes map as follows:
+
+| bot-ui element         | Discord output                                          |
+| ---------------------- | ------------------------------------------------------- |
+| `Message`              | `Container` (accent color → `setAccentColor`)           |
+| `Header`               | `TextDisplay` with `# ` prefix                          |
+| `Section` / `Markdown` | `TextDisplay`                                           |
+| `Fields`               | `TextDisplay` — each field as a **bold-label** line     |
+| `Context`              | `TextDisplay` — each part as a `-# subtext` line        |
+| `Actions`              | One or more `ActionRow`s                                |
+| `Button`               | `Button` (custom_id = minted opaque `ck:` id)           |
+| `Select`               | `StringSelect` (custom_id = minted opaque `ck:` id)     |
+| `Image`                | `MediaGallery` with a single item                       |
+| `Divider`              | `Separator`                                             |
+| `Table`                | `TextDisplay` — fenced code block via `discordMarkdown` |
+
+### Per-element budget
+
+Discord caps every element. The renderer degrades by truncate-with-overflow /
+clamp — it never silently drops content. Limits live in `DISCORD_LIMITS`:
+
+| Limit                  | Value | Element                               |
+| ---------------------- | ----- | ------------------------------------- |
+| `componentsPerMessage` | 40    | total (nested) components per message |
+| `actionRows`           | 5     | action rows per message               |
+| `buttonsPerRow`        | 5     | buttons per action row                |
+| `selectOptions`        | 25    | options per string select             |
+| `textDisplayChars`     | 2000  | chars per TextDisplay                 |
+| `buttonLabel`          | 80    | button label chars                    |
+| `customId`             | 100   | `custom_id` chars                     |
+| `headerText`           | 256   | header line chars (`# ` TextDisplay)  |
+
+### Streaming
+
+`thread.stream(...)` posts a plain-text placeholder and edits it in place via
+`ChunkedMessageStream`: throttled `message.edit` calls at ~1100 ms intervals,
+2000-char chunking, mid-stream bracket auto-close, and Markdown →
+Discord-flavored Markdown translation so the in-flight message always renders.
+
+### Interactions (ack-first)
+
+Every `interactionCreate` event (button click, string select) is immediately
+acknowledged with `deferUpdate` (within the **≤3s** deadline,
+`ackDeadlineMs = 3000`). `decodeInteraction` then extracts the opaque minted
+id (`ck:…`) from the `custom_id`, and hands an `InteractionEvent` to the
+engine. The token carries only the opaque id — no props or secrets. Unrelated
+clicks decode to events the bot harmlessly ignores.
+
+### Human-in-the-loop
+
+Use `thread.awaitChoice(<Picker .../>)` to post an interactive message and
+block until a click resolves it; the resolved value is the clicked control's
+value. Agent interrupts (`on_interrupt`) are captured by the run renderer and
+dispatched to your `onInterrupt` handler, which posts a picker; the click
+resumes the agent via `thread.resume(value)`.
+
+### Modals
+
+`openModal(view)` opens a Discord modal in response to a button click or slash
+command. The call must happen **before any other response** (within Discord's
+3-second acknowledgement window) — open the modal first, then do long-running
+work in a follow-up message.
+
+> **Validation re-open is not supported on Discord.** When a user submits a
+> modal, a `bot.onModalSubmit` handler may return `{ errors }`, but Discord has
+> no API to re-open the same modal with per-field validation errors (unlike
+> Slack's `response_action: "errors"` mechanic). The `{ errors }` result is
+> ignored by the adapter — the modal is acknowledged with `deferUpdate`
+> regardless. Validate inputs before calling `openModal`, or post a follow-up
+> message to report any submission errors.
+>
+> Only `TextInput` fields are supported in Discord modals. `ModalSelect` and
+> `RadioButtons` elements are rejected at render time with a `ModalRenderError`
+> (which `openModal` surfaces as `{ ok: false, error }`).
+
+### Ephemeral messages
+
+Discord ephemeral messages are interaction-scoped — Discord only supports them
+as the initial response to a button click or slash command, and they cannot be
+sent outside that 3-second window. For this reason `supportsEphemeral` is
+advertised as `false`.
+
+`thread.postEphemeral(user, ui, { fallbackToDM: true })` works around this by
+sending the message as a **DM** to the target user when native ephemeral is
+unavailable. The result carries `{ ok: true, usedFallback: true }` so callers
+can detect that a DM was used instead of an in-channel ephemeral.
+
+With `{ fallbackToDM: false }` and no live interaction, `postEphemeral` returns
+`null` (the documented no-fallback sentinel).
+
+> **Future enhancement:** native interaction-ephemeral follow-up (calling
+> `interaction.followUp({ ephemeral: true, … })` within the ack window) is a
+> planned addition. Once plumbed, `supportsEphemeral` will be upgraded to `true`
+> for interaction contexts and `usedFallback` will return `false`.
+
+### Typing indicator and reactions
+
+The adapter supports both Discord-native capabilities:
+
+- **Typing indicator** — `channel.sendTyping()` is called at the start of each
+  run, giving users immediate feedback.
+- **Reactions** — `supportsReactions: true` is advertised; the engine can add
+  emoji reactions during processing.
+
+### Sender-profile resolution
+
+The adapter resolves each turn's Discord user id to a `PlatformUser`
+(`{ id, name?, handle? }`), cached per id. Note that Discord bots cannot read
+user email addresses — `PlatformUser.email` is always `undefined` on this
+platform. Inbound file attachments can be downloaded and delivered to the agent
+as multimodal content parts (`buildFileContentParts`); a tool can post a file
+back out via `thread.postFile(...)`.
+
+### Built-ins
+
+- `defaultDiscordTools` — ships `lookup_discord_user` so the agent can resolve
+  a name/handle to a `<@USERID>` mention. Spread into `tools`.
+- `defaultDiscordContext` — tagging procedure, Discord Markdown formatting
+  guidance, and the Discord channel/thread conversation model. Spread into
+  `context`.
+
+## Tool context
+
+Tools receive the single shared `BotToolContext` from `@copilotkit/channels`
+(`{ thread, message?, user?, signal?, platform }`) and reach Discord power
+only through capability-gated `thread` methods, which this adapter backs:
+
+- `thread.getMessages()` — the current channel's recent messages (via
+  `channel.messages.fetch`), each a `ThreadMessage` (`{ user?, text, ts?,
+isBot? }`).
+- `thread.lookupUser(query)` — resolve a name/handle to a `PlatformUser` by
+  searching guild members.
+- `thread.postFile({ bytes, filename, title?, altText? })` — upload a file
+  into the channel as an attachment.
+
+This keeps tools portable: define them with `defineBotTool({...})` and they
+work against any adapter that advertises the same capabilities.
+
+## Slash commands
+
+Slash commands are registered up front on `bot.start()` via `registerCommands`.
+When `guildId` is set they register to that guild instantly; without it they
+register globally and take ~1 hour to propagate. Register handlers with
+`bot.onCommand`:
+
+```ts
+bot.onCommand({
+  name: "triage",
+  description: "Summarize the thread and propose issues.",
+  options: {
+    // Optional JSON Schema for native Discord slash-command options.
+    // Generates typed Discord option descriptors via jsonSchemaToDiscordOptions.
+  },
+  async handler({ thread, text, user, rawOptions }) {
+    await thread.runAgent({ prompt: `Triage: ${text}` });
+  },
+});
+```
+
+Unlike Slack, commands are registered programmatically — there is no manifest
+file. Discord delivers native structured option values via `rawOptions` when the
+command's `options` schema is provided; args also arrive flattened as free text
+in `ctx.text`.
+
+> **App setup** (OAuth scopes, bot permissions, invite URL) is done via the
+> Discord Developer Portal and the OAuth2 invite flow. A complete wiring example
+> lives in [`examples/slack`](../../examples/slack) — one bot app that runs
+> Slack and/or Discord depending on which secrets you set.
+
+## What's NOT in v1
+
+- **Modal limitations** — text-input modals are supported (up to 5 fields).
+  `ModalSelect` and `RadioButtons` elements are rejected at render time.
+  Validation re-open (`response_action: "errors"`) is not supported — Discord
+  has no API for it; submit errors should be posted as a follow-up message
+  instead.
+- OAuth / multi-guild install (single bot token only)
+- Durable (Redis/DB) `ActionStore` — in-memory only; actions expire on restart
+- Proactive posting (bot replies only to turns it's part of)
+- Auto-sharding (single `Client` instance)
+- Native interaction-ephemeral (`supportsEphemeral` is `false`; use
+  `thread.postEphemeral(user, ui, { fallbackToDM: true })` for a DM-based
+  workaround)
+
+## Exports
+
+`discord`, `DiscordAdapter`, `DiscordAdapterOptions`; `DiscordConversationStore`;
+`attachDiscordListener`, `ListenerConfig`, `ClientLike`, `IncomingCommandRaw`;
+`createRunRenderer`, `ChannelLike`; `decodeInteraction`; `conversationKeyOf`,
+`ReplyTarget`, `IncomingTurn`; `renderComponents`, `renderDiscordMessage`,
+`DISCORD_LIMITS`; `discordMarkdown`; `MessageStream`, `MessageStreamConfig`;
+`ChunkedMessageStream`, `ChunkedMessageStreamConfig`; `autoCloseOpenMarkdown`;
+`registerCommands`, `jsonSchemaToDiscordOptions`; `buildFileContentParts`,
+`DiscordAttachmentRef`, `AgentContentPart`, `FileDeliveryConfig`;
+`defaultDiscordContext`, `discordTaggingContext`, `discordFormattingContext`,
+`discordConversationModelContext`; `lookupDiscordUserTool`, `defaultDiscordTools`.

package/dist/__tests__/ephemeral.test.d.ts

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

package/dist/__tests__/ephemeral.test.d.ts.map

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

package/dist/__tests__/ephemeral.test.js

@@ -0,0 +1,26 @@
+// packages/channels-discord/src/__tests__/ephemeral.test.ts
+import { it, expect, vi } from "vitest";
+import { DiscordAdapter } from "../adapter.js";
+function makeAdapter() {
+    const send = vi.fn().mockResolvedValue({ id: "dm1" });
+    const client = {
+        users: {
+            fetch: vi.fn().mockResolvedValue({
+                createDM: vi.fn().mockResolvedValue({ id: "dm-channel-1", send }),
+            }),
+        },
+    };
+    const adapter = new DiscordAdapter({ botToken: "t", appId: "app" }, { client: client });
+    return { adapter, send, client };
+}
+it("DM-falls-back when fallbackToDM=true (usedFallback=true)", async () => {
+    const { adapter, send } = makeAdapter();
+    const res = await adapter.postEphemeral({ channelId: "C1" }, { id: "U1" }, [{ type: "text", props: { value: "hi" } }], { fallbackToDM: true });
+    expect(res).toMatchObject({ ok: true, usedFallback: true });
+    expect(send).toHaveBeenCalled();
+});
+it("returns null when fallbackToDM=false and no live interaction", async () => {
+    const { adapter } = makeAdapter();
+    const res = await adapter.postEphemeral({ channelId: "C1" }, { id: "U1" }, [{ type: "text", props: { value: "hi" } }], { fallbackToDM: false });
+    expect(res).toBeNull();
+});

package/dist/__tests__/intents.test.d.ts

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

package/dist/__tests__/intents.test.d.ts.map

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

package/dist/__tests__/intents.test.js

@@ -0,0 +1,8 @@
+import { it, expect } from "vitest";
+import { GatewayIntentBits, Partials } from "discord.js";
+import { DISCORD_DEFAULT_INTENTS, DISCORD_DEFAULT_PARTIALS, } from "../adapter.js";
+it("requests the reaction intent and partials", () => {
+    expect(DISCORD_DEFAULT_INTENTS).toContain(GatewayIntentBits.GuildMessageReactions);
+    expect(DISCORD_DEFAULT_PARTIALS).toContain(Partials.Message);
+    expect(DISCORD_DEFAULT_PARTIALS).toContain(Partials.Reaction);
+});

package/dist/__tests__/modal-submit.test.d.ts

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

package/dist/__tests__/modal-submit.test.d.ts.map

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

package/dist/__tests__/modal-submit.test.js

@@ -0,0 +1,26 @@
+// packages/channels-discord/src/__tests__/modal-submit.test.ts
+import { it, expect } from "vitest";
+import { decodeModalSubmit } from "../interaction.js";
+it("decodes a modal submission's text fields by custom_id", () => {
+    const interaction = {
+        customId: "triage",
+        channelId: "C1",
+        guildId: "G1",
+        user: { id: "U1", username: "ada" },
+        fields: {
+            fields: new Map([
+                ["summary", { customId: "summary", value: "boom" }],
+                ["detail", { customId: "detail", value: "ctx" }],
+            ]),
+        },
+    };
+    const evt = decodeModalSubmit(interaction);
+    expect(evt).toMatchObject({
+        callbackId: "triage",
+        values: { summary: "boom", detail: "ctx" },
+        user: { id: "U1", name: "ada" },
+        conversationKey: "C1",
+        replyTarget: { channelId: "C1", guildId: "G1" },
+        platform: "discord",
+    });
+});

package/dist/__tests__/reactions.test.d.ts

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

package/dist/__tests__/reactions.test.d.ts.map

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

package/dist/__tests__/reactions.test.js

@@ -0,0 +1,87 @@
+import { describe, it, expect, vi } from "vitest";
+import { emoji } from "@copilotkit/channels-ui";
+import { decodeReaction } from "../interaction.js";
+import { DiscordAdapter } from "../adapter.js";
+it("decodes a unicode reaction add", () => {
+    const evt = decodeReaction({
+        emoji: { name: "👍", id: null },
+        message: { id: "m1", channelId: "C1", guildId: "G1" },
+    }, { id: "U1", username: "ada", bot: false }, true);
+    expect(evt).toMatchObject({
+        rawEmoji: "👍",
+        added: true,
+        user: { id: "U1", name: "ada" },
+        conversationKey: "C1",
+        messageId: "m1",
+        replyTarget: { channelId: "C1", guildId: "G1" },
+    });
+});
+it("encodes a custom emoji as name:id passthrough", () => {
+    const evt = decodeReaction({
+        emoji: { name: "blob", id: "999" },
+        message: { id: "m2", channelId: "C2" },
+    }, { id: "U2", bot: false }, false);
+    expect(evt.rawEmoji).toBe("blob:999");
+    expect(evt.added).toBe(false);
+});
+describe("addReaction / removeReaction egress", () => {
+    function makeAdapter() {
+        const botId = "BOT1";
+        const react = vi.fn().mockResolvedValue(undefined);
+        const removeUser = vi.fn().mockResolvedValue(undefined);
+        const msg = {
+            react,
+            reactions: {
+                cache: new Map([
+                    ["👍", { users: { remove: removeUser } }],
+                    ["custom", { users: { remove: removeUser } }],
+                    // Discord keys hearts by the BARE codepoint (no trailing U+FE0F).
+                    ["❤", { users: { remove: removeUser } }],
+                ]),
+            },
+        };
+        const client = {
+            user: { id: botId },
+            channels: {
+                fetch: vi.fn().mockResolvedValue({
+                    id: "C1",
+                    send: vi.fn(),
+                    messages: {
+                        fetch: vi.fn().mockResolvedValue(msg),
+                    },
+                }),
+            },
+        };
+        const adapter = new DiscordAdapter({ botToken: "t", appId: "app" }, { client: client });
+        return { adapter, react, removeUser, botId, msg };
+    }
+    const target = { channelId: "C1" };
+    const messageRef = { id: "M1", channelId: "C1" };
+    it("addReaction resolves thumbs_up to 👍 and calls msg.react", async () => {
+        const { adapter, react } = makeAdapter();
+        const res = await adapter.addReaction(target, messageRef, "thumbs_up");
+        expect(res).toEqual({ ok: true });
+        expect(react).toHaveBeenCalledWith("👍");
+    });
+    it("addReaction passes unknown emoji through raw", async () => {
+        const { adapter, react } = makeAdapter();
+        const res = await adapter.addReaction(target, messageRef, "some_custom_emoji");
+        expect(res).toEqual({ ok: true });
+        expect(react).toHaveBeenCalledWith("some_custom_emoji");
+    });
+    it("removeReaction removes the bot's own id via reactions.cache.get(token)?.users.remove", async () => {
+        const { adapter, removeUser, botId } = makeAdapter();
+        const res = await adapter.removeReaction(target, messageRef, "thumbs_up");
+        expect(res).toEqual({ ok: true });
+        expect(removeUser).toHaveBeenCalledWith(botId);
+    });
+    it("removeReaction finds a reaction cached under the bare (VS16-stripped) codepoint", async () => {
+        // `emoji.heart` resolves to the qualified "❤️" (U+2764 U+FE0F), but Discord
+        // keys the cache by the bare "❤" (U+2764). A VS16-tolerant lookup must still
+        // find the reaction and remove the bot's own id.
+        const { adapter, removeUser, botId } = makeAdapter();
+        const res = await adapter.removeReaction(target, messageRef, emoji.heart);
+        expect(res).toEqual({ ok: true });
+        expect(removeUser).toHaveBeenCalledWith(botId);
+    });
+});

package/dist/adapter.d.ts

@@ -0,0 +1,118 @@
+import { Client, GatewayIntentBits, Partials } from "discord.js";
+import type { PlatformAdapter, SurfaceCapabilities, IngressSink, InteractionEvent, RunRenderer, ReplyTarget as BotReplyTarget, ConversationStore, MessageRef, PlatformUser, UserQuery, CommandSpec, NativePayload } from "@copilotkit/channels";
+import type { BotNode, ThreadMessage, EmojiValue, EphemeralResult } from "@copilotkit/channels-ui";
+import type { RestLike } from "./commands.js";
+export interface DiscordAdapterOptions {
+    botToken: string;
+    appId: string;
+    /** When set, slash commands register to this guild instantly (dev); else global. */
+    guildId?: string;
+    interruptEventNames?: ReadonlySet<string>;
+}
+/**
+ * Default Gateway intents for the bot.
+ *
+ * - `Guilds`, `GuildMessages`, `MessageContent`, `DirectMessages` — message ingress.
+ * - `GuildMembers` — privileged; backs `lookup_discord_user` / `thread.lookupUser`.
+ *   Must be toggled on in the Discord Developer Portal (Bot → Privileged Gateway Intents).
+ * - `GuildMessageReactions` — non-privileged; no portal toggle needed.
+ *   Required to receive reaction add/remove events in guild channels.
+ * - `DirectMessageReactions` — non-privileged; required to receive reaction
+ *   add/remove events in DMs. Distinct from `GuildMessageReactions` in discord.js v14.
+ */
+export declare const DISCORD_DEFAULT_INTENTS: readonly [GatewayIntentBits.Guilds, GatewayIntentBits.GuildMessages, GatewayIntentBits.MessageContent, GatewayIntentBits.DirectMessages, GatewayIntentBits.GuildMembers, GatewayIntentBits.GuildMessageReactions, GatewayIntentBits.DirectMessageReactions];
+/**
+ * Default partials for the bot.
+ *
+ * - `Channel` — needed to receive DMs.
+ * - `Message` + `Reaction` — required to receive reactions on uncached messages.
+ *   Discord only delivers partial reaction events when the reacted-to message is not
+ *   in the client's cache; without these partials those events are silently dropped.
+ */
+export declare const DISCORD_DEFAULT_PARTIALS: readonly [Partials.Channel, Partials.Message, Partials.Reaction];
+export declare class DiscordAdapter implements PlatformAdapter {
+    private readonly opts;
+    readonly platform = "discord";
+    readonly capabilities: SurfaceCapabilities;
+    readonly ackDeadlineMs = 3000;
+    private readonly client;
+    private readonly rest;
+    private readonly store;
+    private botUserId;
+    private isReady;
+    private pendingCommands;
+    private readonly userCache;
+    /**
+     * Tracks live component interactions so a handler can open a modal (which
+     * must be the interaction's INITIAL response, within ~3s) before the adapter
+     * auto-defers. Constructed in `start()`. Used by `openModal` (Task D4).
+     */
+    private pending;
+    /**
+     * Tracks live slash-command interactions (a command's initial response is a
+     * reply, not a component update, so it needs its own registry). `openModal`
+     * consults this too, so a command handler can `showModal` before the adapter
+     * auto-defers. Constructed in `start()`.
+     */
+    private commandPending;
+    constructor(opts: DiscordAdapterOptions, injected?: {
+        client?: Client;
+        rest?: RestLike;
+    });
+    registerCommands(commands: readonly CommandSpec[]): void;
+    /**
+     * Publish the registered commands. Guards against an empty list: an empty
+     * `setMyCommands`/`PUT` CLEARS all of the bot's commands, so a race where
+     * `ready` fires before commands are stashed must not wipe them.
+     */
+    private publishCommands;
+    start(sink: IngressSink): Promise<void>;
+    stop(): Promise<void>;
+    render(ir: BotNode[]): import("discord.js").ContainerBuilder;
+    post(target: BotReplyTarget, ir: BotNode[]): Promise<MessageRef>;
+    update(ref: MessageRef, ir: BotNode[]): Promise<void>;
+    stream(target: BotReplyTarget, chunks: AsyncIterable<string>): Promise<MessageRef>;
+    delete(ref: MessageRef): Promise<void>;
+    createRunRenderer(target: BotReplyTarget): RunRenderer;
+    decodeInteraction(raw: unknown): InteractionEvent | undefined;
+    lookupUser(q: UserQuery): Promise<PlatformUser | undefined>;
+    get conversationStore(): ConversationStore;
+    getMessages(target: BotReplyTarget): Promise<ThreadMessage[]>;
+    postFile(target: BotReplyTarget, args: {
+        bytes: Uint8Array;
+        filename: string;
+        title?: string;
+        altText?: string;
+    }): Promise<{
+        ok: boolean;
+        fileId?: string;
+        error?: string;
+    }>;
+    addReaction(target: BotReplyTarget, messageRef: MessageRef, emoji: EmojiValue): Promise<{
+        ok: boolean;
+        error?: string;
+    }>;
+    removeReaction(target: BotReplyTarget, messageRef: MessageRef, emoji: EmojiValue): Promise<{
+        ok: boolean;
+        error?: string;
+    }>;
+    postEphemeral(_target: BotReplyTarget, user: PlatformUser | string, ir: BotNode[], opts: {
+        fallbackToDM: boolean;
+    }): Promise<EphemeralResult | null>;
+    renderModal(ir: BotNode[]): NativePayload;
+    openModal(_target: BotReplyTarget, triggerId: string, ir: BotNode[]): Promise<{
+        ok: boolean;
+        error?: string;
+    }>;
+    resolveUser(userId: string): Promise<PlatformUser>;
+    private channelIdOf;
+    private fetchSendable;
+    /**
+     * Fetch the channel's recent messages OLDEST→NEWEST, normalized for the
+     * conversation store's history reconstruction. Best-effort: on any fetch
+     * error returns [] (bot-slack's fetchHistory does the same).
+     */
+    private fetchHistory;
+}
+export declare function discord(opts: DiscordAdapterOptions): DiscordAdapter;
+//# sourceMappingURL=adapter.d.ts.map

package/dist/adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../src/adapter.ts"],"names":[],"mappings":"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"}