@mulmobridge/discord 1.0.2 → 1.1.0

package/README.md

@@ -4,6 +4,14 @@
 
 Discord bridge for [MulmoClaude](https://github.com/receptron/mulmoclaude). The bot responds to messages in channels it has access to.
 
+## Attachments
+
+Files posted with a message are downloaded from Discord's CDN and forwarded to MulmoClaude, so you can paste a screenshot and ask about it. A post with **only** files and no text is forwarded too, with `Describe / analyze this file.` as the body.
+
+- Up to 10 files per message, 8 MB each — anything larger is skipped and noted in the message MulmoClaude receives.
+- 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.
+
 ## Setup
 
 ### 1. Create a Discord Application

package/dist/attachments.d.ts

@@ -0,0 +1,44 @@
+import type { Attachment } from "@mulmobridge/protocol";
+/** The fields of discord.js' `Attachment` this bridge reads. */
+export interface DiscordAttachmentLike {
+    url: string;
+    name: string;
+    size: number;
+    contentType: string | null;
+}
+export interface CollectedAttachments {
+    attachments: Attachment[];
+    /** Attachments on the message that could not be forwarded — over the
+     *  cap, past the count limit, or the download failed. */
+    dropped: number;
+}
+export type FetchFn = (url: string, init: RequestInit) => Promise<Response>;
+export interface DownloadDeps {
+    fetchFn: FetchFn;
+    log?: {
+        warn: (message: string) => void;
+    };
+}
+/** Per-file byte cap. chat-service's own gate is 20 MB of base64
+ *  across the whole message (~15 MB raw), so one file stays well
+ *  under it. Discord's free-tier upload limit is 10 MB. */
+export declare const MAX_ATTACHMENT_BYTES: number;
+/** chat-service's `parseAttachments` drops everything past the tenth
+ *  entry, so downloading more than that is wasted bandwidth. */
+export declare const MAX_ATTACHMENT_COUNT = 10;
+/** …and it drops whatever pushes the message past this much base64,
+ *  silently. Mirrored here so the bridge can say what it left out. */
+export declare const MAX_TOTAL_BASE64_CHARS: number;
+export declare function isDiscordCdnUrl(raw: string): boolean;
+/** Discord's `contentType` carries parameters (`text/plain; charset=utf-8`)
+ *  and is null for types it cannot sniff, so fall back to the filename. */
+export declare function resolveMimeType(file: DiscordAttachmentLike): string;
+export declare function downloadAttachment(file: DiscordAttachmentLike, deps: DownloadDeps): Promise<Attachment | null>;
+/** Length of the base64 a payload of `byteLength` bytes encodes to —
+ *  4 characters per 3-byte group, rounded up. That string length, not
+ *  the raw size, is what the server's per-message budget counts. */
+export declare function base64Length(byteLength: number): number;
+export declare function collectAttachments(files: DiscordAttachmentLike[], deps: DownloadDeps): Promise<CollectedAttachments>;
+/** The body sent to MulmoClaude: a placeholder when the user posted
+ *  only files, plus a note when some of them were lost. */
+export declare function resolveMessageText(text: string, dropped: number): string;

package/dist/attachments.js

@@ -0,0 +1,182 @@
+// Attachment handling for the Discord bridge (#2939). Kept out of
+// `index.ts` so the download rules can be exercised with a stubbed
+// fetch — no gateway, no CDN, no env reads.
+import { mimeFromExtension } from "@mulmobridge/client";
+// Discord serves message attachments from its own CDN. A URL pointing
+// anywhere else means the payload was tampered with, so it is refused
+// rather than turned into a server-side request forgery primitive.
+const ALLOWED_HOST_SUFFIXES = [".discordapp.com", ".discordapp.net", ".discord.com"];
+/** Per-file byte cap. chat-service's own gate is 20 MB of base64
+ *  across the whole message (~15 MB raw), so one file stays well
+ *  under it. Discord's free-tier upload limit is 10 MB. */
+export const MAX_ATTACHMENT_BYTES = 8 * 1024 * 1024;
+/** chat-service's `parseAttachments` drops everything past the tenth
+ *  entry, so downloading more than that is wasted bandwidth. */
+export const MAX_ATTACHMENT_COUNT = 10;
+/** …and it drops whatever pushes the message past this much base64,
+ *  silently. Mirrored here so the bridge can say what it left out. */
+export const MAX_TOTAL_BASE64_CHARS = 20 * 1024 * 1024;
+const FETCH_TIMEOUT_MS = 30_000;
+const FALLBACK_MIME = "application/octet-stream";
+/** chat-service rejects an empty `text`, so an attachment-only message
+ *  needs a body. Same wording as the Telegram and LINE bridges — an
+ *  instruction, so the agent treats the file as the subject. */
+const ATTACHMENT_ONLY_PROMPT = "Describe / analyze this file.";
+const LOG_LABEL_MAX_CHARS = 100;
+const UNPRINTABLE_RE = /[^\p{L}\p{N}\p{P}\p{S}\p{Zs}]/gu;
+const defaultLog = { warn: (message) => console.warn(message) };
+export function isDiscordCdnUrl(raw) {
+    const url = parseUrl(raw);
+    if (url === null || url.protocol !== "https:")
+        return false;
+    const hostname = url.hostname.toLowerCase();
+    return ALLOWED_HOST_SUFFIXES.some((suffix) => hostname.endsWith(suffix));
+}
+function parseUrl(raw) {
+    try {
+        return new URL(raw);
+    }
+    catch {
+        return null;
+    }
+}
+/** Discord's `contentType` carries parameters (`text/plain; charset=utf-8`)
+ *  and is null for types it cannot sniff, so fall back to the filename. */
+export function resolveMimeType(file) {
+    const declared = (file.contentType ?? "").split(";")[0]?.trim().toLowerCase() ?? "";
+    if (declared.length > 0)
+        return declared;
+    const dot = file.name.lastIndexOf(".");
+    if (dot < 0 || dot === file.name.length - 1)
+        return FALLBACK_MIME;
+    return mimeFromExtension(file.name.slice(dot + 1), FALLBACK_MIME);
+}
+/** Why this file cannot be fetched at all, or null when it may be. */
+function refuseReason(file) {
+    if (!isDiscordCdnUrl(file.url))
+        return "not served from a Discord CDN host";
+    if (file.size > MAX_ATTACHMENT_BYTES)
+        return `${file.size} bytes is over the ${MAX_ATTACHMENT_BYTES} byte cap`;
+    return null;
+}
+/** A filename reaches the log verbatim; control characters in it would
+ *  forge log lines, so keep only printable categories. */
+function logLabel(name) {
+    return name.replace(UNPRINTABLE_RE, " ").slice(0, LOG_LABEL_MAX_CHARS);
+}
+async function drainCapped(reader, maxBytes) {
+    const chunks = [];
+    let total = 0;
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done)
+            return Buffer.concat(chunks);
+        total += value.byteLength;
+        if (total > maxBytes) {
+            await reader.cancel();
+            return null;
+        }
+        chunks.push(value);
+    }
+}
+/** Read at most `maxBytes`, aborting mid-stream rather than after the
+ *  fact — `arrayBuffer()` would have already materialised the body. */
+async function readCappedBody(res, maxBytes) {
+    const { body } = res;
+    if (body === null)
+        return null;
+    const declared = Number(res.headers.get("content-length") ?? "");
+    if (Number.isFinite(declared) && declared > maxBytes) {
+        // Returning without draining would leave the connection open until
+        // the socket times out, one leak per oversized attachment.
+        await body.cancel();
+        return null;
+    }
+    return drainCapped(body.getReader(), maxBytes);
+}
+export async function downloadAttachment(file, deps) {
+    const log = deps.log ?? defaultLog;
+    const refused = refuseReason(file);
+    if (refused !== null) {
+        log.warn(`[discord] attachment skipped: ${logLabel(file.name)} — ${refused}`);
+        return null;
+    }
+    try {
+        const res = await deps.fetchFn(file.url, { signal: AbortSignal.timeout(FETCH_TIMEOUT_MS), redirect: "error" });
+        if (!res.ok) {
+            log.warn(`[discord] attachment fetch failed: ${logLabel(file.name)} — HTTP ${res.status}`);
+            return null;
+        }
+        const bytes = await readCappedBody(res, MAX_ATTACHMENT_BYTES);
+        if (bytes === null) {
+            log.warn(`[discord] attachment skipped: ${logLabel(file.name)} — body over the ${MAX_ATTACHMENT_BYTES} byte cap`);
+            return null;
+        }
+        return { mimeType: resolveMimeType(file), data: bytes.toString("base64"), filename: file.name };
+    }
+    catch (err) {
+        log.warn(`[discord] attachment download failed: ${logLabel(file.name)} — ${err}`);
+        return null;
+    }
+}
+/** Length of the base64 a payload of `byteLength` bytes encodes to —
+ *  4 characters per 3-byte group, rounded up. That string length, not
+ *  the raw size, is what the server's per-message budget counts. */
+export function base64Length(byteLength) {
+    return Math.ceil(byteLength / 3) * 4;
+}
+/** Spend the server's per-message budget before anything is downloaded —
+ *  Discord states each file's size up front. Without this the bridge
+ *  would ship attachments that `parseAttachments` silently truncates,
+ *  so the user is never told a file went missing. A file that does not
+ *  fit is skipped rather than ending the loop: a smaller one after it
+ *  may still fit. */
+function withinBudget(files) {
+    const considered = [];
+    const skipped = [];
+    let remaining = MAX_TOTAL_BASE64_CHARS;
+    files.forEach((file) => {
+        const cost = base64Length(file.size);
+        if (considered.length >= MAX_ATTACHMENT_COUNT || cost > remaining) {
+            skipped.push(file);
+            return;
+        }
+        remaining -= cost;
+        considered.push(file);
+    });
+    return { considered, skipped };
+}
+/** Re-check the budget against the bytes actually in hand. `withinBudget`
+ *  spends it on Discord's declared sizes; this is what makes the guarantee
+ *  hold if a declared size ever under-reports, since the server would
+ *  otherwise truncate the overflow without telling anyone. */
+function fitBudget(attachments) {
+    const kept = [];
+    let remaining = MAX_TOTAL_BASE64_CHARS;
+    attachments.forEach((attachment) => {
+        const cost = attachment.data?.length ?? 0;
+        if (cost > remaining)
+            return;
+        remaining -= cost;
+        kept.push(attachment);
+    });
+    return kept;
+}
+export async function collectAttachments(files, deps) {
+    const log = deps.log ?? defaultLog;
+    const { considered, skipped } = withinBudget(files);
+    skipped.forEach((file) => log.warn(`[discord] attachment skipped: ${logLabel(file.name)} — over what one message may carry`));
+    const results = await Promise.all(considered.map((file) => downloadAttachment(file, deps)));
+    const attachments = fitBudget(results.filter((entry) => entry !== null));
+    return { attachments, dropped: files.length - attachments.length };
+}
+/** The body sent to MulmoClaude: a placeholder when the user posted
+ *  only files, plus a note when some of them were lost. */
+export function resolveMessageText(text, dropped) {
+    const trimmed = text.trim();
+    const body = trimmed.length > 0 ? trimmed : ATTACHMENT_ONLY_PROMPT;
+    if (dropped <= 0)
+        return body;
+    const plural = dropped === 1 ? "file" : "files";
+    return `${body}\n\n(note: ${dropped} attached ${plural} could not be downloaded)`;
+}

package/dist/index.js

@@ -12,6 +12,7 @@ import "dotenv/config";
 import { Client, GatewayIntentBits, Partials } from "discord.js";
 import { createBridgeClient } from "@mulmobridge/client";
 import { parseCsvSet } from "@mulmoclaude/common";
+import { collectAttachments, resolveMessageText } from "./attachments.js";
 const TRANSPORT_ID = "discord";
 const MAX_DISCORD_LENGTH = 2000;
 const token = process.env.DISCORD_BOT_TOKEN;
@@ -52,26 +53,39 @@ async function onMessageCreate(msg) {
     if (msg.author.bot)
         return;
     const { channelId } = msg;
-    const text = msg.content.trim();
-    if (!text)
-        return;
+    // Checked before the attachment downloads so a denied channel never
+    // makes the bridge fetch anything.
     if (!allowAll && !allowedChannels.has(channelId))
         return;
-    console.log(`[discord] message channel=${channelId} user=${msg.author.tag} len=${text.length}`);
+    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}`);
     try {
-        const ack = await mulmo.send(channelId, text);
-        if (ack.ok) {
-            await sendChunked(msg, ack.reply ?? "");
-        }
-        else {
-            const status = ack.status ? ` (${ack.status})` : "";
-            await msg.reply(`Error${status}: ${ack.error ?? "unknown"}`);
-        }
+        await relayMessage(msg, text, files);
     }
     catch (err) {
         console.error(`[discord] message handling failed: ${err}`);
     }
 }
+async function relayMessage(msg, 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.
+    if (text.length === 0 && attachments.length === 0) {
+        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);
+    if (ack.ok) {
+        await sendChunked(msg, ack.reply ?? "");
+    }
+    else {
+        const status = ack.status ? ` (${ack.status})` : "";
+        await msg.reply(`Error${status}: ${ack.error ?? "unknown"}`);
+    }
+}
 async function sendChunked(msg, text) {
     if (text.length === 0) {
         await msg.reply("(empty reply)");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mulmobridge/discord",
-  "version": "1.0.2",
+  "version": "1.1.0",
   "description": "Discord bridge for MulmoBridge — connect a Discord bot to MulmoClaude",
   "type": "module",
   "main": "./dist/index.js",
@@ -16,20 +16,21 @@
     "build": "tsc",
     "prepack": "yarn build",
     "typecheck": "tsc --noEmit",
-    "test": "echo no tests yet",
-    "lint": "eslint src"
+    "test": "tsx --test test/test_*.ts",
+    "lint": "eslint src test"
   },
   "license": "MIT",
   "author": "Receptron Team",
   "dependencies": {
-    "@mulmobridge/client": "^1.0.1",
+    "@mulmobridge/client": "^1.0.2",
     "@mulmobridge/protocol": "^1.0.1",
-    "@mulmoclaude/common": "^1.1.1",
+    "@mulmoclaude/common": "^1.2.0",
     "discord.js": "^14.27.0",
     "dotenv": "^17.0.0"
   },
   "devDependencies": {
     "@types/node": "^26.1.2",
+    "tsx": "^4.23.5",
     "typescript": "^6.0.3"
   },
   "homepage": "https://github.com/receptron/mulmoclaude/tree/main/packages/bridges/discord#readme",