talon-agent 3.33.3 → 3.34.0

package/src/frontend/discord/guild-policy.ts

@@ -0,0 +1,89 @@
+/**
+ * Guild whitelist enforcement — the bot only operates in `allowedGuilds`.
+ *
+ * Two entry points: the sweep run once at ready (defense in depth against
+ * guilds joined while the bot was offline) and the `guildCreate` handler
+ * that reacts the moment the bot is added somewhere. Both tell the admins
+ * and, when `leaveUnauthorizedGuilds` is set, leave.
+ */
+
+import type { Client, Guild } from "discord.js";
+import { log, logError, logWarn } from "../../util/log.js";
+import { registerCommandsForGuilds } from "./commands/index.js";
+import type { DiscordRuntime } from "./runtime.js";
+
+async function notifyAdmins(
+  client: Client,
+  adminUserIds: readonly string[],
+  content: string,
+): Promise<void> {
+  for (const adminId of adminUserIds) {
+    try {
+      const admin = await client.users.fetch(adminId);
+      await admin.send({ content, allowedMentions: { parse: [] } });
+    } catch {
+      /* ignore */
+    }
+  }
+}
+
+async function leaveGuild(guild: Guild): Promise<void> {
+  try {
+    await guild.leave();
+  } catch (err) {
+    logWarn(
+      "discord",
+      `Failed to leave guild ${guild.id}: ${err instanceof Error ? err.message : err}`,
+    );
+  }
+}
+
+/** Ready-time sweep: leave every guild the bot is in that isn't whitelisted. */
+export async function leaveNonWhitelistedGuilds(
+  runtime: DiscordRuntime,
+  client: Client<true>,
+): Promise<void> {
+  const dc = runtime.discord;
+  for (const guild of client.guilds.cache.values()) {
+    if (dc.allowedGuilds.includes(guild.id)) continue;
+    log(
+      "discord",
+      `Leaving non-whitelisted guild "${guild.name}" (${guild.id})`,
+    );
+    await notifyAdmins(
+      client,
+      dc.adminUserIds,
+      `🚪 Leaving non-whitelisted guild "${guild.name}" (${guild.id}).`,
+    );
+    await leaveGuild(guild);
+  }
+}
+
+/** guildCreate: bot was added to a new guild → enforce whitelist immediately. */
+export async function onGuildCreate(
+  runtime: DiscordRuntime,
+  guild: Guild,
+): Promise<void> {
+  const { client, config, discord: dc } = runtime;
+  if (dc.allowedGuilds.includes(guild.id)) {
+    log("discord", `Joined whitelisted guild "${guild.name}" (${guild.id})`);
+    // Re-register commands for this guild
+    try {
+      await registerCommandsForGuilds(client, config);
+    } catch (err) {
+      logError("discord", `Re-register commands after guildCreate failed`, err);
+    }
+    return;
+  }
+  log("discord", `Joined non-whitelisted guild "${guild.name}" (${guild.id})`);
+  await notifyAdmins(
+    client,
+    dc.adminUserIds,
+    dc.leaveUnauthorizedGuilds
+      ? `🚨 Bot was added to non-whitelisted guild "${guild.name}" (${guild.id}). Leaving.`
+      : `⚠️ Bot was added to non-whitelisted guild "${guild.name}" (${guild.id}). Commands will not be registered.`,
+  );
+  if (dc.leaveUnauthorizedGuilds) {
+    await leaveGuild(guild);
+  }
+}

package/src/frontend/discord/index.ts

@@ -5,39 +5,33 @@
  *  - access control (config.discord.allowedUsers / allowedGuilds / allowedChannels / adminUserIds)
  *  - slash command registration (per-guild for allowedGuilds, optional global for DM)
  *  - message handlers (mention/reply/channel-mode gating)
- *  - component (button/select) interaction routing → callbacks.ts
+ *  - component (button/select) interaction routing → callbacks/
  *  - guildCreate auto-leave for non-whitelisted guilds (+ admin notify)
  *  - graceful shutdown
  *
  * Registers a Discord-specific action handler with the gateway so MCP tool
  * calls (send_message, react, etc.) reach the Discord API.
+ *
+ * This file is wiring only: it constructs the shared runtime (runtime.ts),
+ * binds the client's event handlers, and owns the frontend surface. The
+ * behaviour lives in the modules — ready, guild-policy, diagnostics,
+ * outbound, connection, and the handlers/commands/callbacks trees.
  */
 
-import {
-  Client,
-  GatewayIntentBits,
-  Partials,
-  ActivityType,
-  Events,
-} from "discord.js";
-import { once } from "node:events";
 import type { TalonConfig } from "../../util/config.js";
 import type { ContextManager } from "../../core/types.js";
 import type { Gateway } from "../../core/engine/gateway.js";
-import { log, logError, logWarn } from "../../util/log.js";
+import { log } from "../../util/log.js";
 import { createDiscordActionHandler } from "./actions/index.js";
-import {
-  registerCommandsForGuilds,
-  registerInteractionRouter,
-} from "./commands/index.js";
+import { registerInteractionRouter } from "./commands/index.js";
+import { connect, disconnect } from "./connection.js";
+import { bindClientDiagnostics } from "./diagnostics.js";
+import { onGuildCreate } from "./guild-policy.js";
+import { setAccessControl } from "./handlers/index.js";
 import { registerMiddleware } from "./middleware.js";
-import {
-  setAccessControl,
-  lookupDiscordChat,
-  registerDiscordChat,
-} from "./handlers/index.js";
-import { sendChunked } from "./handlers/index.js";
-import { deriveNumericChatId } from "../../util/chat-id.js";
+import { sendMessage, sendTyping } from "./outbound.js";
+import { onClientReady } from "./ready.js";
+import { createDiscordRuntime, type DiscordRuntime } from "./runtime.js";
 
 // ── Frontend type ───────────────────────────────────────────────────────────
 
@@ -54,6 +48,28 @@ export type DiscordFrontend = {
 
 // ── Factory ─────────────────────────────────────────────────────────────────
 
+async function init(runtime: DiscordRuntime): Promise<void> {
+  const { client, config, gateway } = runtime;
+
+  // Register Discord action handler with the gateway
+  gateway.registerFrontendHandler(
+    "discord",
+    createDiscordActionHandler(client, gateway),
+  );
+
+  const port = await gateway.start(19876);
+  log("discord", `Gateway started on port ${port}`);
+
+  // Hook event listeners BEFORE login so we don't miss the ready event.
+  client.once("clientReady", (c) => onClientReady(runtime, c));
+  client.on("guildCreate", (guild) => onGuildCreate(runtime, guild));
+  bindClientDiagnostics(client);
+
+  // Wire message handlers and slash command/component routers
+  registerMiddleware(client, config);
+  registerInteractionRouter(client, config, gateway);
+}
+
 export function createDiscordFrontend(
   config: TalonConfig,
   gateway: Gateway,
@@ -64,30 +80,9 @@ export function createDiscordFrontend(
     );
   }
   const dc = config.discord;
+  const runtime = createDiscordRuntime(config, dc, gateway);
 
-  const client = new Client({
-    intents: [
-      GatewayIntentBits.Guilds,
-      GatewayIntentBits.GuildMessages,
-      GatewayIntentBits.GuildMembers,
-      GatewayIntentBits.MessageContent,
-      GatewayIntentBits.DirectMessages,
-      GatewayIntentBits.GuildMessageReactions,
-      GatewayIntentBits.DirectMessageReactions,
-    ],
-    // Partials.Reaction is what makes reactions on messages that predate the
-    // current cache arrive at all — without it the soul's reaction tap only
-    // ever sees freshly-cached messages.
-    partials: [
-      Partials.Channel,
-      Partials.Message,
-      Partials.User,
-      Partials.Reaction,
-    ],
-    allowedMentions: { parse: [] }, // never ping anyone unless we explicitly opt in
-  });
-
-  // Wire access control config into handlers.ts
+  // Wire access control config into handlers/
   setAccessControl({
     allowedUsers: dc.allowedUsers,
     allowedGuilds: dc.allowedGuilds,
@@ -103,270 +98,14 @@ export function createDiscordFrontend(
     getMessageCount: (chatId: number) => gateway.getMessageCount(chatId),
   };
 
-  // sendTyping: looks up the registered Discord channel and sends typing.
-  // No-ops gracefully if we don't have the channel cached yet.
-  const sendTyping = async (chatId: number): Promise<void> => {
-    const info = lookupDiscordChat(chatId);
-    if (!info) return;
-    try {
-      const ch = await client.channels.fetch(info.channelId);
-      if (ch && "sendTyping" in ch) {
-        await (ch as { sendTyping: () => Promise<void> }).sendTyping();
-      }
-    } catch {
-      /* channel not resolvable — ignore */
-    }
-  };
-
-  // sendMessage (plain): used by cron and pulse to reach a specific chat.
-  // chatId here is the numericChatId stored in the registry.
-  const sendMessage = async (chatId: number, text: string): Promise<void> => {
-    if (!text.trim()) return;
-    const info = lookupDiscordChat(chatId);
-    if (!info) {
-      logWarn(
-        "discord",
-        `sendMessage: no registered channel for chatId ${chatId}`,
-      );
-      return;
-    }
-    try {
-      const ch = await client.channels.fetch(info.channelId);
-      if (
-        ch &&
-        "isSendable" in ch &&
-        (ch as { isSendable: () => boolean }).isSendable()
-      ) {
-        await sendChunked(ch as never, text);
-      }
-    } catch (err) {
-      logError(
-        "discord",
-        `sendMessage failed for chat ${chatId}: ${err instanceof Error ? err.message : err}`,
-      );
-    }
-  };
-
   return {
     name: "discord",
     context,
-    sendTyping,
-    sendMessage,
+    sendTyping: (chatId) => sendTyping(runtime, chatId),
+    sendMessage: (chatId, text) => sendMessage(runtime, chatId, text),
     getBridgePort: () => gateway.getPort(),
-
-    async init() {
-      // Register Discord action handler with the gateway
-      gateway.registerFrontendHandler(
-        "discord",
-        createDiscordActionHandler(client, gateway),
-      );
-
-      const port = await gateway.start(19876);
-      log("discord", `Gateway started on port ${port}`);
-
-      // Hook event listeners BEFORE login so we don't miss the ready event.
-      client.once("clientReady", async (c) => {
-        log("discord", `Logged in as ${c.user.tag} (${c.user.id})`);
-
-        if (dc.presence) {
-          try {
-            c.user.setPresence({
-              activities: [{ name: dc.presence, type: ActivityType.Custom }],
-              status: "online",
-            });
-          } catch {
-            /* ignore */
-          }
-        }
-
-        // Discover any existing DM channels with allowedUsers and register them
-        // in the chat registry so cron/pulse can target them. We don't pre-open
-        // unrequested DMs — only those Discord already exposes.
-        for (const userId of dc.allowedUsers) {
-          try {
-            const user = await c.users.fetch(userId);
-            const dm = await user.createDM();
-            const chatId = `discord_dm_${userId}`;
-            registerDiscordChat({
-              channelId: dm.id,
-              guildId: null,
-              userId,
-              numericChatId: deriveNumericChatId(chatId),
-              chatId,
-            });
-          } catch {
-            /* user not reachable — skip */
-          }
-        }
-
-        // Register slash commands per-guild + optionally global for DM
-        try {
-          await registerCommandsForGuilds(c, config);
-        } catch (err) {
-          logError("discord", "Slash command registration failed", err);
-        }
-
-        // Defense in depth: leave any guild we're in but isn't whitelisted
-        if (dc.leaveUnauthorizedGuilds) {
-          for (const guild of c.guilds.cache.values()) {
-            if (dc.allowedGuilds.includes(guild.id)) continue;
-            log(
-              "discord",
-              `Leaving non-whitelisted guild "${guild.name}" (${guild.id})`,
-            );
-            // Notify admins
-            for (const adminId of dc.adminUserIds) {
-              try {
-                const admin = await c.users.fetch(adminId);
-                await admin.send({
-                  content: `🚪 Leaving non-whitelisted guild "${guild.name}" (${guild.id}).`,
-                  allowedMentions: { parse: [] },
-                });
-              } catch {
-                /* ignore */
-              }
-            }
-            try {
-              await guild.leave();
-            } catch (err) {
-              logWarn(
-                "discord",
-                `Failed to leave guild ${guild.id}: ${err instanceof Error ? err.message : err}`,
-              );
-            }
-          }
-        }
-      });
-
-      // guildCreate: bot was added to a new guild → enforce whitelist immediately
-      client.on("guildCreate", async (guild) => {
-        if (dc.allowedGuilds.includes(guild.id)) {
-          log(
-            "discord",
-            `Joined whitelisted guild "${guild.name}" (${guild.id})`,
-          );
-          // Re-register commands for this guild
-          try {
-            await registerCommandsForGuilds(client, config);
-          } catch (err) {
-            logError(
-              "discord",
-              `Re-register commands after guildCreate failed`,
-              err,
-            );
-          }
-          return;
-        }
-        log(
-          "discord",
-          `Joined non-whitelisted guild "${guild.name}" (${guild.id})`,
-        );
-        // Notify admins
-        for (const adminId of dc.adminUserIds) {
-          try {
-            const admin = await client.users.fetch(adminId);
-            await admin.send({
-              content: dc.leaveUnauthorizedGuilds
-                ? `🚨 Bot was added to non-whitelisted guild "${guild.name}" (${guild.id}). Leaving.`
-                : `⚠️ Bot was added to non-whitelisted guild "${guild.name}" (${guild.id}). Commands will not be registered.`,
-              allowedMentions: { parse: [] },
-            });
-          } catch {
-            /* ignore */
-          }
-        }
-        if (dc.leaveUnauthorizedGuilds) {
-          try {
-            await guild.leave();
-          } catch (err) {
-            logWarn(
-              "discord",
-              `Failed to leave guild ${guild.id}: ${err instanceof Error ? err.message : err}`,
-            );
-          }
-        }
-      });
-
-      client.on("error", (err) => {
-        logError("discord", "Client error", err);
-      });
-      client.on("warn", (msg) => {
-        logWarn("discord", msg);
-      });
-
-      // Surface gateway close codes — discord.js auto-reconnects on most, but
-      // 4004 (auth failed), 4013 (invalid intents), 4014 (disallowed intents)
-      // are terminal: the bot will hang silent in IDENTIFY without an alert.
-      client.on(Events.ShardDisconnect, (event, shardId) => {
-        const code = event?.code;
-        const reason = event?.reason || "(no reason)";
-        const fatal = code === 4004 || code === 4013 || code === 4014;
-        const label =
-          code === 4004
-            ? "AUTHENTICATION_FAILED — bot token invalid/revoked"
-            : code === 4013
-              ? "INVALID_INTENTS — declared intent doesn't exist"
-              : code === 4014
-                ? "DISALLOWED_INTENTS — privileged intent (GuildMembers/MessageContent/Presence) not enabled in Developer Portal"
-                : `code=${code}`;
-        if (fatal) {
-          logError(
-            "discord",
-            `Shard ${shardId} disconnected fatally: ${label} (${reason})`,
-          );
-        } else {
-          logWarn(
-            "discord",
-            `Shard ${shardId} disconnected: ${label} (${reason})`,
-          );
-        }
-      });
-
-      // Rate-limit / invalid-request observability. discord.js handles retries
-      // automatically; we just want logs so we know when we're flirting with
-      // the Cloudflare 10k-invalid-requests/10min cap.
-      client.rest.on("rateLimited", (info) => {
-        logWarn(
-          "discord",
-          `Rate-limited ${info.method} ${info.route} — wait ${info.timeToReset}ms (global=${info.global})`,
-        );
-      });
-      client.rest.on("invalidRequestWarning", (info) => {
-        logError(
-          "discord",
-          `Invalid-request warning: ${info.count} bad requests in last ${info.remainingTime}ms — approaching IP ban threshold`,
-        );
-      });
-
-      // Wire message handlers and slash command/component routers
-      registerMiddleware(client, config);
-      registerInteractionRouter(client, config, gateway);
-    },
-
-    async start() {
-      await client.login(dc.botToken);
-      // Wait for the WebSocket READY event before returning — login() resolves
-      // after HTTP IDENTIFY but client.user / client.guilds.cache are empty
-      // until READY fires. Anything called after start() can then safely read
-      // gateway state.
-      if (!client.isReady()) {
-        await once(client, Events.ClientReady);
-      }
-    },
-
-    async stop() {
-      try {
-        await client.destroy();
-        log("shutdown", "Discord client disconnected");
-      } catch (err) {
-        logError("shutdown", "Discord stop error", err);
-      }
-      try {
-        await gateway.stop();
-        log("shutdown", "Gateway stopped");
-      } catch (err) {
-        logError("shutdown", "Gateway stop error", err);
-      }
-    },
+    init: () => init(runtime),
+    start: () => connect(runtime),
+    stop: () => disconnect(runtime),
   };
 }

package/src/frontend/discord/outbound.ts

@@ -0,0 +1,61 @@
+/**
+ * Outbound primitives the rest of the daemon reaches Discord through:
+ * typing indicators and plain sends addressed by numeric chat id (cron,
+ * pulse). Both resolve the channel via the chat registry and no-op when it
+ * isn't known yet.
+ */
+
+import { logError, logWarn } from "../../util/log.js";
+import { lookupDiscordChat, sendChunked } from "./handlers/index.js";
+import type { DiscordRuntime } from "./runtime.js";
+
+// sendTyping: looks up the registered Discord channel and sends typing.
+// No-ops gracefully if we don't have the channel cached yet.
+export async function sendTyping(
+  runtime: DiscordRuntime,
+  chatId: number,
+): Promise<void> {
+  const info = lookupDiscordChat(chatId);
+  if (!info) return;
+  try {
+    const ch = await runtime.client.channels.fetch(info.channelId);
+    if (ch && "sendTyping" in ch) {
+      await (ch as { sendTyping: () => Promise<void> }).sendTyping();
+    }
+  } catch {
+    /* channel not resolvable — ignore */
+  }
+}
+
+// sendMessage (plain): used by cron and pulse to reach a specific chat.
+// chatId here is the numericChatId stored in the registry.
+export async function sendMessage(
+  runtime: DiscordRuntime,
+  chatId: number,
+  text: string,
+): Promise<void> {
+  if (!text.trim()) return;
+  const info = lookupDiscordChat(chatId);
+  if (!info) {
+    logWarn(
+      "discord",
+      `sendMessage: no registered channel for chatId ${chatId}`,
+    );
+    return;
+  }
+  try {
+    const ch = await runtime.client.channels.fetch(info.channelId);
+    if (
+      ch &&
+      "isSendable" in ch &&
+      (ch as { isSendable: () => boolean }).isSendable()
+    ) {
+      await sendChunked(ch as never, text);
+    }
+  } catch (err) {
+    logError(
+      "discord",
+      `sendMessage failed for chat ${chatId}: ${err instanceof Error ? err.message : err}`,
+    );
+  }
+}

package/src/frontend/discord/ready.ts

@@ -0,0 +1,73 @@
+/**
+ * The `clientReady` handler — everything that needs a logged-in client:
+ * presence, DM discovery for the chat registry, slash-command registration,
+ * and the guild whitelist sweep.
+ */
+
+import { ActivityType, type Client } from "discord.js";
+import { log, logError } from "../../util/log.js";
+import { deriveNumericChatId } from "../../util/chat-id.js";
+import { registerCommandsForGuilds } from "./commands/index.js";
+import { registerDiscordChat } from "./handlers/index.js";
+import { leaveNonWhitelistedGuilds } from "./guild-policy.js";
+import type { DiscordRuntime } from "./runtime.js";
+
+/**
+ * Discover any existing DM channels with allowedUsers and register them in
+ * the chat registry so cron/pulse can target them. We don't pre-open
+ * unrequested DMs — only those Discord already exposes.
+ */
+async function registerAllowedUserDms(
+  runtime: DiscordRuntime,
+  client: Client<true>,
+): Promise<void> {
+  for (const userId of runtime.discord.allowedUsers) {
+    try {
+      const user = await client.users.fetch(userId);
+      const dm = await user.createDM();
+      const chatId = `discord_dm_${userId}`;
+      registerDiscordChat({
+        channelId: dm.id,
+        guildId: null,
+        userId,
+        numericChatId: deriveNumericChatId(chatId),
+        chatId,
+      });
+    } catch {
+      /* user not reachable — skip */
+    }
+  }
+}
+
+export async function onClientReady(
+  runtime: DiscordRuntime,
+  client: Client<true>,
+): Promise<void> {
+  const { config, discord: dc } = runtime;
+  log("discord", `Logged in as ${client.user.tag} (${client.user.id})`);
+
+  if (dc.presence) {
+    try {
+      client.user.setPresence({
+        activities: [{ name: dc.presence, type: ActivityType.Custom }],
+        status: "online",
+      });
+    } catch {
+      /* ignore */
+    }
+  }
+
+  await registerAllowedUserDms(runtime, client);
+
+  // Register slash commands per-guild + optionally global for DM
+  try {
+    await registerCommandsForGuilds(client, config);
+  } catch (err) {
+    logError("discord", "Slash command registration failed", err);
+  }
+
+  // Defense in depth: leave any guild we're in but isn't whitelisted
+  if (dc.leaveUnauthorizedGuilds) {
+    await leaveNonWhitelistedGuilds(runtime, client);
+  }
+}

package/src/frontend/discord/runtime.ts

@@ -0,0 +1,55 @@
+/**
+ * Discord frontend runtime — the state every module of this frontend shares.
+ *
+ * `createDiscordFrontend` used to hold the client and config as closure
+ * variables with every gateway-event handler nested inside `init`. It is
+ * now one explicit object, constructed once, that each module (ready,
+ * guild-policy, diagnostics, outbound, connection) takes as its first
+ * parameter. The runtime carries state only; the modules own the behaviour.
+ */
+
+import { Client, GatewayIntentBits, Partials } from "discord.js";
+import type { TalonConfig } from "../../util/config.js";
+import type { Gateway } from "../../core/engine/gateway.js";
+
+/** `config.discord`, narrowed once — the factory refuses to build without it. */
+export type DiscordConfig = NonNullable<TalonConfig["discord"]>;
+
+export type DiscordRuntime = {
+  readonly config: TalonConfig;
+  readonly discord: DiscordConfig;
+  readonly gateway: Gateway;
+  readonly client: Client;
+};
+
+function createClient(): Client {
+  return new Client({
+    intents: [
+      GatewayIntentBits.Guilds,
+      GatewayIntentBits.GuildMessages,
+      GatewayIntentBits.GuildMembers,
+      GatewayIntentBits.MessageContent,
+      GatewayIntentBits.DirectMessages,
+      GatewayIntentBits.GuildMessageReactions,
+      GatewayIntentBits.DirectMessageReactions,
+    ],
+    // Partials.Reaction is what makes reactions on messages that predate the
+    // current cache arrive at all — without it the soul's reaction tap only
+    // ever sees freshly-cached messages.
+    partials: [
+      Partials.Channel,
+      Partials.Message,
+      Partials.User,
+      Partials.Reaction,
+    ],
+    allowedMentions: { parse: [] }, // never ping anyone unless we explicitly opt in
+  });
+}
+
+export function createDiscordRuntime(
+  config: TalonConfig,
+  discord: DiscordConfig,
+  gateway: Gateway,
+): DiscordRuntime {
+  return { config, discord, gateway, client: createClient() };
+}