feat: conditional Gateway intents for MESSAGE_CONTENT (#24)

The Gateway identify payload always requested MESSAGE_CONTENT, which caused Discord to close the session with code 4014 when the app did not have that privileged intent enabled. This change computes intents from the enabled runtime features so slash-command-only deployments stay connected while message-based features still opt into the broader subscription set.

Constraint: Discord rejects Gateway sessions that request unauthorized privileged intents

Rejected: Require Message Content Intent for every install | breaks slash-command-only setups

Confidence: high

Scope-risk: narrow

Reversibility: clean

Directive: Keep message-content intent conditional on features that actually consume message bodies

Tested: npm test; npm run typecheck

Not-tested: Live Discord Gateway handshake on a fresh non-privileged bot after merge

Co-authored-by: Kfir <suukpehoy@gmail.com>

Author: kfiramar

src/gateway.ts

@@ -6,6 +6,9 @@ const GATEWAY_ENCODING = "json";
 const MAX_CONSECUTIVE_FAILURES = 5;
 const MAX_BACKOFF_MS = 60_000;
 const DEFAULT_RECONNECT_MS = 5000;
+const GUILD_INTENT = 1;
+const GUILD_MESSAGES_INTENT = 512;
+const MESSAGE_CONTENT_INTENT = 32768;
 
 interface GatewayPayload {
   op: number;
@@ -44,6 +47,11 @@ export interface MessageCreateEvent {
 type InteractionHandler = (interaction: InteractionCreateEvent) => Promise<unknown>;
 type MessageHandler = (message: MessageCreateEvent) => Promise<void>;
 
+export interface GatewayOptions {
+  listenForMessages?: boolean;
+  includeMessageContent?: boolean;
+}
+
 export async function respondViaCallback(
   ctx: PluginContext,
   interactionId: string,
@@ -81,6 +89,7 @@ export async function connectGateway(
   token: string,
   onInteraction: InteractionHandler,
   onMessage?: MessageHandler,
+  options: GatewayOptions = {},
 ): Promise<{ close: () => void }> {
   if (typeof WebSocket === "undefined") {
     ctx.logger.warn(
@@ -105,6 +114,12 @@ export async function connectGateway(
   let closed = false;
   let consecutiveFailures = 0;
   let lastHeartbeatIntervalMs = 41250;
+  const listenForMessages = options.listenForMessages ?? Boolean(onMessage);
+  const includeMessageContent = options.includeMessageContent ?? listenForMessages;
+  const intents =
+    GUILD_INTENT |
+    (listenForMessages ? GUILD_MESSAGES_INTENT : 0) |
+    (includeMessageContent ? MESSAGE_CONTENT_INTENT : 0);
 
   function getReconnectDelay(): number {
     if (consecutiveFailures >= MAX_CONSECUTIVE_FAILURES) {
@@ -148,7 +163,7 @@ export async function connectGateway(
               op: 2,
               d: {
                 token: `Bot ${token}`,
-                intents: 1 | 512 | 32768, // GUILDS | GUILD_MESSAGES | MESSAGE_CONTENT
+                intents,
                 properties: {
                   os: "linux",
                   browser: "paperclip-plugin-discord",

src/worker.ts

@@ -256,14 +256,25 @@ const plugin = definePlugin({
       }
     }
 
+    const gatewayNeedsMessages =
+      config.enableInbound !== false ||
+      config.enableMediaPipeline === true ||
+      config.enableCustomCommands === true ||
+      config.enableProactiveSuggestions === true ||
+      config.enableIntelligence === true;
+
     // --- Gateway connection for real-time interaction handling ---
     const gateway = await connectGateway(
       ctx,
       token,
       async (interaction) => {
         return handleInteraction(ctx, interaction as any, cmdCtx);
       },
-      handleMessageCreate,
+      gatewayNeedsMessages ? handleMessageCreate : undefined,
+      {
+        listenForMessages: gatewayNeedsMessages,
+        includeMessageContent: gatewayNeedsMessages,
+      },
     );
 
     ctx.events.on("plugin.stopping", async () => {

tests/gateway.test.ts

@@ -45,6 +45,59 @@ describe("connectGateway", () => {
     expect(handler).not.toHaveBeenCalled();
     result.close(); // should not throw
   });
+
+  it("uses guild-only intents when message subscriptions are disabled", async () => {
+    class FakeWebSocket {
+      static instances: FakeWebSocket[] = [];
+      onopen: (() => void) | null = null;
+      onmessage: ((event: { data: string }) => void) | null = null;
+      onclose: ((event: { code: number; reason: string }) => void) | null = null;
+      onerror: (() => void) | null = null;
+      sent: string[] = [];
+
+      constructor(_url: string) {
+        FakeWebSocket.instances.push(this);
+      }
+
+      send(payload: string) {
+        this.sent.push(payload);
+      }
+
+      close() {}
+    }
+
+    globalThis.WebSocket = FakeWebSocket as unknown as typeof WebSocket;
+
+    const { connectGateway } = await import("../src/gateway.js");
+    const ctx = makeCtx();
+    (ctx.http.fetch as unknown as ReturnType<typeof vi.fn>).mockResolvedValue({
+      ok: true,
+      json: async () => ({ url: "wss://gateway.discord.test" }),
+    });
+
+    const result = await connectGateway(ctx, "fake-token", vi.fn(), undefined, {
+      listenForMessages: false,
+      includeMessageContent: false,
+    });
+
+    const socket = FakeWebSocket.instances[0];
+    expect(socket).toBeDefined();
+
+    socket.onmessage?.({
+      data: JSON.stringify({
+        op: 10,
+        d: { heartbeat_interval: 10000 },
+        s: null,
+        t: null,
+      }),
+    });
+
+    const identify = JSON.parse(socket.sent[0] ?? "{}");
+    expect(identify.op).toBe(2);
+    expect(identify.d.intents).toBe(1);
+
+    result.close();
+  });
 });
 
 describe("respondViaCallback", () => {