@mulmobridge/discord 1.2.1 → 1.3.0

package/README.md

@@ -12,6 +12,67 @@ Files posted with a message are downloaded from Discord's CDN and forwarded to M
 - Images and PDFs reach Claude directly; text, DOCX, XLSX and PPTX are converted server-side. Other types are skipped with a log line.
 - Attachments arrive over the **Message Content Intent**, the same privileged intent the bot already needs to read text.
 
+## Threads
+
+A Discord thread is a **channel of its own** — it has its own id, separate from the channel it hangs off. That single fact drives both settings below.
+
+> **Check the bot's permissions first.** Posting inside a thread needs `Send Messages in Threads`, which Discord treats as separate from `Send Messages`. Without it the bot receives thread messages and silently fails to reply. See [Setup](#3-invite-the-bot-to-your-server).
+
+### The allowlist judges a thread by its parent channel
+
+`DISCORD_ALLOWED_CHANNELS` used to compare a thread against its own id, and a thread's id is minted fresh every time someone opens one. So the allowlist and threads could not be used together: you had to paste each new thread's id into `.env` and restart, or leave the list empty and let the bot answer in every channel it can see.
+
+Now a message in a thread is admitted when the **parent channel** is listed. Allow `#ai-help` once and every thread under it works, with the permitted area still closed at that channel. Listing a thread's own id also still works, so an existing `.env` keeps behaving as it did.
+
+### `DISCORD_SESSION_GRANULARITY` — one session per thread, or per channel
+
+> **What's a "session"?** In MulmoClaude a *session* is one continuous conversation — it remembers what you said earlier and builds on it. This setting decides how many sessions one Discord channel maps to.
+
+#### 🧵 `thread` (default) — a thread is its own conversation
+
+```text
+#ai-help
+├── Alice: "Summarize yesterday's standup"        → session: #ai-help
+│
+├── 🧵 Deploy question
+│   ├── Bob: "What's the rollback procedure?"     ┐
+│   └── Bob: "And who approves it?"               ┘ → its own session
+│
+└── 🧵 Translation task
+    ├── Alice: "Translate the release notes"      ┐
+    └── Alice: "Now make it shorter"              ┘ → its own session
+```
+
+Open a thread for each topic and the AI keeps them apart — Bob's deploy question never mixes into Alice's translation. Because a thread carries its own id, this is what the bridge has always done for threads that reached it; the default keeps that.
+
+#### 🗂 `channel` — every thread joins its parent channel's conversation
+
+```text
+#ai-help
+├── Alice: "Summarize yesterday's standup"        ┐
+├── 🧵 Deploy question                            │
+│   └── Bob: "What's the rollback procedure?"     ├ one session, keyed by #ai-help
+└── 🧵 Translation task                           │
+    └── Alice: "Translate the release notes"      ┘
+```
+
+Use this when threads are just a tidier way to lay out **one** running conversation and you want the AI to carry context across all of them. Watch out: a long-lived channel session accumulates context, so answers get slower and pull in stale details.
+
+| | `thread` *(default)* | `channel` |
+|---|---|---|
+| Message in a channel | channel session | channel session |
+| Message in a thread | **thread session** | **parent channel session** |
+| Post in a **forum** channel | thread session | thread session |
+| DM | one session per DM | one session per DM |
+
+Notes:
+
+- **A forum post never folds**, in either mode. Discord does not allow posting into a forum channel itself — you open a post — so a session keyed by the forum id would have nowhere to deliver a server-initiated message. A forum post is its own conversation anyway; there is no channel-level talk to fold it into. The forum id still works in `DISCORD_ALLOWED_CHANNELS`.
+- **A thread never folds onto a parent your allowlist does not cover.** If you allow a thread by its own id — the older workaround — its parent channel is not thereby allowed, so `channel` mode keeps that thread's own session rather than aiming replies at a channel you chose to leave out. Both rules are the same invariant: a session is only ever keyed to a channel the bot may actually talk in.
+- The value is case-insensitive. Anything other than `thread` or `channel` makes the bridge exit at startup rather than guess — including Slack's `auto`, which has no separate meaning here.
+- The default differs from [`@mulmobridge/slack`](https://www.npmjs.com/package/@mulmobridge/slack), where `SLACK_SESSION_GRANULARITY` defaults to `channel`. A Slack thread is a facet of a channel; a Discord thread is a channel. Set both explicitly if you run the two bridges and want them to match.
+- Switching modes does not delete anything. It only changes how *new* messages map to sessions — old conversations stay in the MulmoClaude UI, and the AI does not port their context into the new ones.
+
 ## Setup
 
 ### 1. Create a Discord Application
@@ -29,7 +90,9 @@ Files posted with a message are downloaded from Discord's CDN and forwarded to M
 
 **OAuth2** → **URL Generator**:
 - Scopes: `bot`
-- Permissions: `Send Messages`, `Read Message History`
+- Permissions: `Send Messages`, `Send Messages in Threads`, `Read Message History`
+
+`Send Messages in Threads` is a **separate** Discord permission from `Send Messages` — a bot granted only the latter receives messages posted in a thread and then fails to reply to them. Grant both, or the bot will look silent inside every thread. Already-invited bots do not pick up a new permission from a fresh invite URL alone; add it to the bot's role, or to the channel's permission overwrites.
 
 Copy the generated URL and open it in your browser to invite the bot.
 
@@ -52,7 +115,8 @@ npx @mulmobridge/discord
 | Variable | Required | Description |
 |---|---|---|
 | `DISCORD_BOT_TOKEN` | Yes | Bot token from Developer Portal |
-| `DISCORD_ALLOWED_CHANNELS` | No | CSV of channel IDs to restrict (empty = all) |
+| `DISCORD_ALLOWED_CHANNELS` | No | CSV of channel IDs to restrict (empty = all). A thread is admitted by its **parent** channel, or by its own id — see [Threads](#threads) |
+| `DISCORD_SESSION_GRANULARITY` | No | `thread` *(default)* \| `channel`. Whether a thread is its own session or joins its parent channel's. `channel` folds only onto a parent that is postable and allow-listed. See [Threads](#threads) |
 | `MULMOCLAUDE_API_URL` | No | Default: auto (`.server-port`; waits if nothing is published) |
 | `MULMOCLAUDE_AUTH_TOKEN` | No | Bearer token (auto-read from workspace) |
 | `DISCORD_BRIDGE_DEFAULT_ROLE` | No | Role id to seed new bridge sessions with (e.g. `coder`, `general`). Applied ONLY when a discord session first appears — once the user switches role via `/role <id>` the session's own role wins. Unknown role ids silently fall back to the server's default with a warn log. |

package/dist/index.js

@@ -5,7 +5,11 @@
 //   DISCORD_BOT_TOKEN      — Bot token from Discord Developer Portal
 //
 // Optional:
-//   DISCORD_ALLOWED_CHANNELS — CSV of channel IDs (empty = allow all)
+//   DISCORD_ALLOWED_CHANNELS — CSV of channel IDs (empty = allow all).
+//                              A thread is admitted by its PARENT channel.
+//   DISCORD_SESSION_GRANULARITY — "thread" (default) | "channel"
+//                              Whether a thread is its own session or joins
+//                              its parent channel's. See README.md.
 //   MULMOCLAUDE_API_URL      — default: the port in <workspace>/.server-port.
 //                              With none published the client waits (#3078)
 //   MULMOCLAUDE_AUTH_TOKEN   — bearer token (or read from workspace)
@@ -14,6 +18,7 @@ import { Client, GatewayIntentBits, Partials } from "discord.js";
 import { createBridgeClient, installProcessGuards } from "@mulmobridge/client";
 import { parseCsvSet } from "@mulmoclaude/common";
 import { collectAttachments, resolveMessageText } from "./attachments.js";
+import { buildExternalChatId, isChannelAllowed, parseGranularity, readChannelRef } from "./sessionId.js";
 const TRANSPORT_ID = "discord";
 installProcessGuards({ name: TRANSPORT_ID });
 const MAX_DISCORD_LENGTH = 2000;
@@ -24,6 +29,18 @@ if (!token) {
 }
 const allowedChannels = parseCsvSet(process.env.DISCORD_ALLOWED_CHANNELS);
 const allowAll = allowedChannels.size === 0;
+// The explicit `T` return annotation is what lets TS see `process.exit`'s
+// `never` and accept the catch branch as non-returning.
+function parseEnvOrExit(parse) {
+    try {
+        return parse();
+    }
+    catch (err) {
+        console.error(`[discord] ${err instanceof Error ? err.message : String(err)}`);
+    }
+    return process.exit(1);
+}
+const granularity = parseEnvOrExit(() => parseGranularity(process.env.DISCORD_SESSION_GRANULARITY));
 const discord = new Client({
     intents: [GatewayIntentBits.Guilds, GatewayIntentBits.GuildMessages, GatewayIntentBits.DirectMessages, GatewayIntentBits.MessageContent],
     // Partials.Channel is required to receive DM messageCreate events —
@@ -54,24 +71,25 @@ discord.on("messageCreate", (msg) => {
 async function onMessageCreate(msg) {
     if (msg.author.bot)
         return;
-    const { channelId } = msg;
+    const channelRef = readChannelRef(msg.channelId, msg.channel);
     // Checked before the attachment downloads so a denied channel never
     // makes the bridge fetch anything.
-    if (!allowAll && !allowedChannels.has(channelId))
+    if (!isChannelAllowed(channelRef, allowedChannels))
         return;
     const text = msg.content.trim();
     const files = [...msg.attachments.values()];
     if (text.length === 0 && files.length === 0)
         return;
-    console.log(`[discord] message channel=${channelId} user=${msg.author.tag} len=${text.length} attachments=${files.length}`);
+    const externalChatId = buildExternalChatId(channelRef, granularity, allowedChannels);
+    console.log(`[discord] message channel=${channelRef.channelId} parent=${channelRef.parentChannel?.id ?? "-"} session=${externalChatId} user=${msg.author.tag} len=${text.length} attachments=${files.length}`);
     try {
-        await relayMessage(msg, text, files);
+        await relayMessage(msg, externalChatId, text, files);
     }
     catch (err) {
         console.error(`[discord] message handling failed: ${err}`);
     }
 }
-async function relayMessage(msg, text, files) {
+async function relayMessage(msg, externalChatId, text, files) {
     const { attachments, dropped } = await collectAttachments(files, { fetchFn: fetch, log: console });
     // Nothing survived on a file-only post: say so instead of relaying a
     // prompt about a file the agent never receives.
@@ -79,7 +97,7 @@ async function relayMessage(msg, text, files) {
         await msg.reply("Sorry, I could not download that attachment. Please try again.");
         return;
     }
-    const ack = await mulmo.send(msg.channelId, resolveMessageText(text, dropped), attachments.length > 0 ? attachments : undefined);
+    const ack = await mulmo.send(externalChatId, resolveMessageText(text, dropped), attachments.length > 0 ? attachments : undefined);
     if (ack.ok) {
         await sendChunked(msg, ack.reply ?? "");
     }
@@ -113,6 +131,7 @@ discord.once("ready", () => {
     console.log("MulmoClaude Discord bridge");
     console.log(`Logged in as ${discord.user?.tag}`);
     console.log(`Channels: ${allowAll ? "(all)" : [...allowedChannels].join(", ")}`);
+    console.log(`Session granularity: ${granularity}`);
 });
 discord.login(token).catch((err) => {
     console.error("Fatal:", err);

package/dist/sessionId.d.ts

@@ -0,0 +1,89 @@
+export type SessionGranularity = "channel" | "thread";
+/** Where a Discord message arrived.
+ *
+ *  A Discord thread IS a channel — it carries its own snowflake, which is
+ *  what `Message.channelId` holds. `parentChannel` is therefore present only
+ *  for threads, and always names the text/forum channel the thread hangs
+ *  off, never a category.
+ *
+ *  `sendable` travels with the id because the two are only ever useful
+ *  together: a forum channel is a legitimate allowlist entry but not a place
+ *  a message can be posted, so folding a session onto it would strand the
+ *  reply. Pairing them makes it impossible to record the id without saying
+ *  which kind it is. */
+export interface MessageChannelRef {
+    channelId: string;
+    parentChannel?: {
+        id: string;
+        sendable: boolean;
+    };
+}
+/** The slice of `Message.channel` read here. Both parent fields are optional
+ *  because a DM channel has neither. */
+interface ChannelLike {
+    isThread: () => boolean;
+    parentId?: string | null;
+    parent?: {
+        isSendable: () => boolean;
+    } | null;
+}
+/** Parse the DISCORD_SESSION_GRANULARITY env var into a safe enum value.
+ *
+ *  Unset falls back to "thread", which is what the bridge has always done:
+ *  it passes `msg.channelId` straight through, and for a message in a
+ *  thread that id IS the thread's. Any explicit invalid value is rejected
+ *  so operators notice the misconfiguration instead of silently getting
+ *  some other mode. */
+export declare function parseGranularity(raw: string | undefined): SessionGranularity;
+/** Read the channel/parent pair off an incoming message.
+ *
+ *  The `isThread()` gate is load-bearing rather than defensive: on a
+ *  `GuildChannel`, `parentId` is the id of the CATEGORY the channel sits
+ *  in, while on a `ThreadChannel` it is the parent text channel. Reading it
+ *  ungated would hand a category id to the allowlist and to session
+ *  keying.
+ *
+ *  An uncached parent reads as not sendable. Unreachable as the bridge is
+ *  configured — `Guild._patch` caches every channel in the GUILD_CREATE
+ *  payload and the `Guilds` intent is always on — so this is only about which
+ *  way a defensive branch fails. Not folding costs an extra session, which a
+ *  user can see; folding onto a parent that turns out to be a forum costs the
+ *  reply, which nobody sees. It never touches the allow decision, which runs
+ *  off the id alone. */
+export declare function readChannelRef(channelId: string, channel: ChannelLike): MessageChannelRef;
+/** Is this message's channel covered by DISCORD_ALLOWED_CHANNELS?
+ *
+ *  An empty allowlist is the "allow all" sentinel. A thread is admitted by
+ *  its PARENT channel, which is the point: thread ids are minted fresh for
+ *  every thread, so listing them is not an operable allowlist.
+ *
+ *  The channel's own id still counts. For a thread that is the pre-existing
+ *  workaround — paste the thread id into `.env` and restart — and dropping
+ *  it would be a regression. */
+export declare function isChannelAllowed(ref: MessageChannelRef, allowedChannels: ReadonlySet<string>): boolean;
+/** The externalChatId the server keys a session by. Two messages with
+ *  different ids get independent sessions.
+ *
+ *  - "thread" → the channel's own id, so a thread is its own conversation.
+ *  - "channel" → the parent channel for a thread, folding every thread
+ *    under a channel into that channel's one conversation.
+ *
+ *  Both are plain snowflakes, so the push path needs no reverse parse: the
+ *  id the server hands back resolves through `channels.fetch()` whether it
+ *  names a thread or a text channel.
+ *
+ *  Folding is refused on two grounds, and both reduce to one invariant: a
+ *  session id must name a channel the bridge may actually talk in.
+ *
+ *  - A FORUM parent cannot be posted to at all (`isSendable()` is false —
+ *    Discord has you open a post), so its id would key a session the server
+ *    can never push a reply into; the push guard drops it with only a warn
+ *    line. A forum post is its own conversation anyway.
+ *  - A parent the ALLOWLIST does not cover is a channel the operator chose
+ *    not to permit. A thread admitted by its own id (the legacy `.env`
+ *    workaround) hangs off such a parent, and folding there would aim
+ *    server-initiated pushes at it — `onPushEvent` does not consult the
+ *    allowlist. Keeping the thread's own id is safe by construction: the
+ *    message reached us, so that channel is permitted. */
+export declare function buildExternalChatId(ref: MessageChannelRef, mode: SessionGranularity, allowedChannels: ReadonlySet<string>): string;
+export {};

package/dist/sessionId.js

@@ -0,0 +1,89 @@
+// Session-granularity helpers for @mulmobridge/discord.
+//
+// Kept separate from index.ts so they can be unit-tested without
+// importing the bridge entrypoint (which opens a Gateway connection on
+// load).
+/** Parse the DISCORD_SESSION_GRANULARITY env var into a safe enum value.
+ *
+ *  Unset falls back to "thread", which is what the bridge has always done:
+ *  it passes `msg.channelId` straight through, and for a message in a
+ *  thread that id IS the thread's. Any explicit invalid value is rejected
+ *  so operators notice the misconfiguration instead of silently getting
+ *  some other mode. */
+export function parseGranularity(raw) {
+    const normalised = (raw ?? "thread").toLowerCase();
+    if (normalised === "channel" || normalised === "thread") {
+        return normalised;
+    }
+    throw new Error(`Invalid DISCORD_SESSION_GRANULARITY=${JSON.stringify(raw)}. Expected one of: channel, thread.`);
+}
+/** Read the channel/parent pair off an incoming message.
+ *
+ *  The `isThread()` gate is load-bearing rather than defensive: on a
+ *  `GuildChannel`, `parentId` is the id of the CATEGORY the channel sits
+ *  in, while on a `ThreadChannel` it is the parent text channel. Reading it
+ *  ungated would hand a category id to the allowlist and to session
+ *  keying.
+ *
+ *  An uncached parent reads as not sendable. Unreachable as the bridge is
+ *  configured — `Guild._patch` caches every channel in the GUILD_CREATE
+ *  payload and the `Guilds` intent is always on — so this is only about which
+ *  way a defensive branch fails. Not folding costs an extra session, which a
+ *  user can see; folding onto a parent that turns out to be a forum costs the
+ *  reply, which nobody sees. It never touches the allow decision, which runs
+ *  off the id alone. */
+export function readChannelRef(channelId, channel) {
+    if (!channel.isThread())
+        return { channelId };
+    const parentId = channel.parentId ?? undefined;
+    if (parentId === undefined)
+        return { channelId };
+    return { channelId, parentChannel: { id: parentId, sendable: channel.parent?.isSendable() === true } };
+}
+/** Is this message's channel covered by DISCORD_ALLOWED_CHANNELS?
+ *
+ *  An empty allowlist is the "allow all" sentinel. A thread is admitted by
+ *  its PARENT channel, which is the point: thread ids are minted fresh for
+ *  every thread, so listing them is not an operable allowlist.
+ *
+ *  The channel's own id still counts. For a thread that is the pre-existing
+ *  workaround — paste the thread id into `.env` and restart — and dropping
+ *  it would be a regression. */
+export function isChannelAllowed(ref, allowedChannels) {
+    if (allowedChannels.size === 0)
+        return true;
+    if (allowedChannels.has(ref.channelId))
+        return true;
+    return ref.parentChannel !== undefined && allowedChannels.has(ref.parentChannel.id);
+}
+/** The externalChatId the server keys a session by. Two messages with
+ *  different ids get independent sessions.
+ *
+ *  - "thread" → the channel's own id, so a thread is its own conversation.
+ *  - "channel" → the parent channel for a thread, folding every thread
+ *    under a channel into that channel's one conversation.
+ *
+ *  Both are plain snowflakes, so the push path needs no reverse parse: the
+ *  id the server hands back resolves through `channels.fetch()` whether it
+ *  names a thread or a text channel.
+ *
+ *  Folding is refused on two grounds, and both reduce to one invariant: a
+ *  session id must name a channel the bridge may actually talk in.
+ *
+ *  - A FORUM parent cannot be posted to at all (`isSendable()` is false —
+ *    Discord has you open a post), so its id would key a session the server
+ *    can never push a reply into; the push guard drops it with only a warn
+ *    line. A forum post is its own conversation anyway.
+ *  - A parent the ALLOWLIST does not cover is a channel the operator chose
+ *    not to permit. A thread admitted by its own id (the legacy `.env`
+ *    workaround) hangs off such a parent, and folding there would aim
+ *    server-initiated pushes at it — `onPushEvent` does not consult the
+ *    allowlist. Keeping the thread's own id is safe by construction: the
+ *    message reached us, so that channel is permitted. */
+export function buildExternalChatId(ref, mode, allowedChannels) {
+    const { channelId, parentChannel } = ref;
+    if (mode === "thread" || parentChannel === undefined)
+        return channelId;
+    const mayFold = parentChannel.sendable && isChannelAllowed({ channelId: parentChannel.id }, allowedChannels);
+    return mayFold ? parentChannel.id : channelId;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mulmobridge/discord",
-  "version": "1.2.1",
+  "version": "1.3.0",
   "description": "Discord bridge for MulmoBridge — connect a Discord bot to MulmoClaude",
   "type": "module",
   "main": "./dist/index.js",
@@ -29,7 +29,7 @@
     "dotenv": "^17.0.0"
   },
   "devDependencies": {
-    "@types/node": "^26.5.1",
+    "@types/node": "^26.6.2",
     "tsx": "^4.23.13",
     "typescript": "^6.0.3"
   },