Fixes #756 (#763)

2026-07-14 20:26:15 +00:00
parent c32d85a337
commit ba13c08890
30 changed files with 2914 additions and 365 deletions
--- a/plugins/discord/src/index.ts
+++ b/plugins/discord/src/index.ts
@@ -1,10 +1,38 @@
-import { createHmac, randomUUID, timingSafeEqual } from 'node:crypto';
-import { ChannelType, Client, GatewayIntentBits, type Message as DiscordMessage } from 'discord.js';
+import { createHash, createHmac, randomUUID, timingSafeEqual } from 'node:crypto';
+import { ChannelDeliveryError } from '@mosaicstack/types';
+import type {
+  ChannelAdapterHealthDto,
+  ChannelAuthorizedPrincipalDto,
+  ChannelConversationRouteDto,
+  ChannelEgressDto,
+  ChannelEgressPort,
+  ChannelIngressDto,
+  ChannelIngressPort,
+  ChannelMessageDto,
+  OfficialChannelAdapter,
+} from '@mosaicstack/types';
+import {
+  ChannelType,
+  Client,
+  GatewayIntentBits,
+  ThreadAutoArchiveDuration,
+  type Message as DiscordMessage,
+} from 'discord.js';
 import { io, type Socket } from 'socket.io-client';

+export interface DiscordPluginDependencies {
+  ingressPort?: ChannelIngressPort;
+  client?: Client;
+  socketFactory?: (url: string, options: Parameters<typeof io>[1]) => Socket;
+}
+
 export interface DiscordPluginConfig {
  token: string;
  gatewayUrl: string;
+  /** Maximum authorized turns per Discord user/channel per minute. */
+  messageRateLimitPerMinute?: number;
+  /** Maximum mention-triggered thread routes per Discord user/channel per minute. */
+  threadRateLimitPerMinute?: number;
  /** Shared service credential injected by the approved secret mechanism. */
  serviceToken: string;
  /** Which guild to bind to (single-guild only for v0.1.0). */
@@ -30,13 +58,23 @@ export interface DiscordInteractionUserBinding {
 export type DiscordInteractionPairing = DiscordInteractionRole | DiscordInteractionUserBinding;

 export interface DiscordInteractionBinding {
+  /** Stable logical agent identity used in channel conversation routes. */
  instanceId: string;
+  /** Trusted gateway database agent-config ID selected for this binding. */
+  agentConfigId: string;
  guildId: string;
  channelId: string;
  /** Pairing roster keyed by Discord user ID. */
  pairedUsers: Readonly<Record<string, DiscordInteractionPairing>>;
 }

+const DEFAULT_MESSAGE_RATE_LIMIT_PER_MINUTE = 30;
+const DEFAULT_THREAD_RATE_LIMIT_PER_MINUTE = 5;
+const RATE_LIMIT_WINDOW_MS = 60_000;
+const DELIVERY_MAX_ATTEMPTS = 3;
+const DELIVERY_RETRY_BASE_MS = 50;
+const MAX_CONVERSATION_ROUTES = 1_000;
+
 const operationRoles: Readonly<
  Record<DiscordInteractionOperation, readonly DiscordInteractionRole[]>
 > = {
@@ -90,6 +128,7 @@ export function parseDiscordInteractionBindings(
    const candidate = binding as Partial<DiscordInteractionBinding>;
    if (
      !candidate.instanceId ||
+      !candidate.agentConfigId ||
      !candidate.guildId ||
      !candidate.channelId ||
      !candidate.pairedUsers ||
@@ -130,6 +169,7 @@ export function parseDiscordInteractionBindings(
    ) as Record<string, DiscordInteractionPairing>;
    return {
      instanceId: candidate.instanceId,
+      agentConfigId: candidate.agentConfigId,
      guildId: candidate.guildId,
      channelId: candidate.channelId,
      pairedUsers,
@@ -154,6 +194,7 @@ export interface DiscordAttachment {
  name: string;
  url: string;
  contentType: string | null;
+  sizeBytes?: number;
 }

 export interface DiscordIngressEnvelope {
@@ -229,27 +270,37 @@ export function verifyDiscordIngressEnvelope(
  return envelope.payload;
 }

-export class DiscordPlugin {
+export class DiscordPlugin implements OfficialChannelAdapter, ChannelEgressPort {
+  readonly name = 'discord';
+
  private client: Client;
  private socket: Socket | null = null;
-  /** Map Discord channel ID → Mosaic conversation ID. */
-  private channelConversations = new Map<string, string>();
+  /** Bounded last-authorized routes for response-target egress validation. */
+  private conversationRoutes = new Map<string, ChannelConversationRouteDto>();
  /** Track in-flight responses to avoid duplicate streaming. */
  private pendingResponses = new Map<string, string>();
+  private readonly messageRateWindows = new Map<string, number[]>();
+  private readonly threadRateWindows = new Map<string, number[]>();

-  constructor(private readonly config: DiscordPluginConfig) {
-    this.client = new Client({
-      intents: [
-        GatewayIntentBits.Guilds,
-        GatewayIntentBits.GuildMessages,
-        GatewayIntentBits.MessageContent,
-        GatewayIntentBits.DirectMessages,
-      ],
-    });
+  constructor(
+    private readonly config: DiscordPluginConfig,
+    private readonly dependencies: DiscordPluginDependencies = {},
+  ) {
+    this.client =
+      dependencies.client ??
+      new Client({
+        intents: [
+          GatewayIntentBits.Guilds,
+          GatewayIntentBits.GuildMessages,
+          GatewayIntentBits.MessageContent,
+          GatewayIntentBits.DirectMessages,
+        ],
+      });
  }

  async start(): Promise<void> {
-    this.socket = io(`${this.config.gatewayUrl}/chat`, {
+    const socketFactory = this.dependencies.socketFactory ?? io;
+    this.socket = socketFactory(`${this.config.gatewayUrl}/chat`, {
      auth: { discordServiceToken: this.config.serviceToken },
      transports: ['websocket'],
    });
@@ -276,11 +327,13 @@ export class DiscordPlugin {

    this.socket.on('agent:end', (data: { conversationId: string }) => {
      const text = this.pendingResponses.get(data.conversationId);
+      this.pendingResponses.delete(data.conversationId);
      if (text) {
-        this.pendingResponses.delete(data.conversationId);
-        this.sendToDiscord(data.conversationId, text).catch((err: unknown) => {
+        this.sendAgentResponse(data.conversationId, text).catch((err: unknown) => {
          console.error(`[discord] Error sending response for ${data.conversationId}:`, err);
        });
+      } else {
+        this.conversationRoutes.delete(data.conversationId);
      }
    });

@@ -288,15 +341,33 @@ export class DiscordPlugin {
      this.pendingResponses.set(data.conversationId, '');
    });

-    this.client.on('messageCreate', (message: DiscordMessage) =>
-      this.handleDiscordMessage(message),
-    );
+    this.socket.on('error', (data: { conversationId?: unknown }) => {
+      if (typeof data.conversationId !== 'string') return;
+      this.pendingResponses.delete(data.conversationId);
+      this.conversationRoutes.delete(data.conversationId);
+    });
+
+    this.client.on('messageCreate', (message: DiscordMessage) => {
+      void Promise.resolve(this.handleDiscordMessage(message)).catch((error: unknown): void => {
+        const errorName = error instanceof Error ? error.name : 'UnknownError';
+        console.error(
+          `[discord] Message routing failed. channel=${message.channelId} message=${message.id} error=${errorName}`,
+        );
+      });
+    });

    this.client.on('ready', () => {
      console.log(`[discord] Bot logged in as ${this.client.user?.tag}`);
    });

-    await this.client.login(this.config.token);
+    try {
+      await this.client.login(this.config.token);
+    } catch (error: unknown) {
+      this.socket.disconnect();
+      this.socket = null;
+      await this.client.destroy();
+      throw error;
+    }
  }

  async stop(): Promise<void> {
@@ -304,6 +375,14 @@ export class DiscordPlugin {
    await this.client.destroy();
  }

+  async health(): Promise<ChannelAdapterHealthDto> {
+    const discordReady = this.client.isReady();
+    const gatewayConnected = this.socket?.connected === true;
+    if (discordReady && gatewayConnected) return { status: 'connected' };
+    if (discordReady || gatewayConnected) return { status: 'degraded' };
+    return { status: 'disconnected' };
+  }
+
  async createProjectChannel(project: {
    id: string;
    name: string;
@@ -325,77 +404,224 @@ export class DiscordPlugin {
      topic: project.description ?? `Mosaic project: ${project.name}`,
    });

-    this.channelConversations.set(channel.id, `discord-${channel.id}`);
+    // A project channel has no logical-agent conversation until a configured
+    // binding authorizes a message. Do not seed a legacy channel-only key.
    return { channelId: channel.id };
  }

-  private handleDiscordMessage(message: DiscordMessage): void {
-    if (message.author.bot || !this.client.user) return;
-    if (!message.guildId || !this.isAllowedMessage(message)) return;
+  private handleDiscordMessage(message: DiscordMessage): void | Promise<void> {
+    if (message.author.bot || !this.client.user || !message.guildId) return;
+
+    const authorizationChannelId = this.authorizationChannelId(message);
+    if (!this.isAllowedMessage(message, authorizationChannelId)) return;

    const isMention = message.mentions.has(this.client.user);
-    if (!isMention) return;
+    const content = isMention
+      ? message.content.replace(new RegExp(`<@!?${this.client.user.id}>`, 'g'), '').trim()
+      : message.content.trim();
+    if (!content && message.attachments.size === 0) return;
+    const operation = this.interactionOperation(content);
+    const binding = resolveDiscordInteractionBinding(
+      this.config.interactionBindings ?? [],
+      message.guildId,
+      authorizationChannelId,
+      message.author.id,
+      operation,
+    );
+    // Pairing and operation-specific role checks happen before thread creation
+    // or any gateway dispatch, including privileged control events.
+    if (!binding) return;

-    const content = message.content
-      .replace(new RegExp(`<@!?${this.client.user.id}>`, 'g'), '')
-      .trim();
-    if (!content) return;
-    if (!this.socket?.connected) {
+    const rateKey = `${message.guildId}:${authorizationChannelId}:${message.author.id}`;
+    if (
+      !this.consumeRateLimit(
+        this.messageRateWindows,
+        rateKey,
+        this.config.messageRateLimitPerMinute ?? DEFAULT_MESSAGE_RATE_LIMIT_PER_MINUTE,
+      )
+    ) {
+      console.error(
+        `[discord] Message rate limit reached. guild=${message.guildId} channel=${authorizationChannelId} user=${message.author.id}`,
+      );
+      return;
+    }
+
+    const createThread = isMention && operation === 'send';
+    if (
+      createThread &&
+      !this.consumeRateLimit(
+        this.threadRateWindows,
+        rateKey,
+        this.config.threadRateLimitPerMinute ?? DEFAULT_THREAD_RATE_LIMIT_PER_MINUTE,
+      )
+    ) {
+      console.error(
+        `[discord] Thread rate limit reached. guild=${message.guildId} channel=${authorizationChannelId} user=${message.author.id}`,
+      );
+      return;
+    }
+
+    if (!this.dependencies.ingressPort && !this.socket?.connected) {
      console.error(
        `[discord] Cannot forward message: not connected to gateway. channel=${message.channelId} message=${message.id}`,
      );
      return;
    }

-    const channelId = message.channelId;
-    const parentChannelId = 'parentId' in message.channel ? message.channel.parentId : null;
-    const bindingChannelId = parentChannelId ?? channelId;
-    const binding = resolveDiscordInteractionBinding(
-      this.config.interactionBindings ?? [],
-      message.guildId,
-      bindingChannelId,
-      message.author.id,
-      'send',
+    // Approval/stop commands act on the current durable session. They remain
+    // at the current channel/thread target rather than creating a new topic.
+    const route = this.resolveConversationRoute(
+      message,
+      binding,
+      authorizationChannelId,
+      createThread,
    );
-    if (!binding) return;
-    const conversationId =
-      this.channelConversations.get(channelId) ?? `${binding.instanceId}:discord:${channelId}`;
-    this.channelConversations.set(channelId, conversationId);
+    if (route instanceof Promise) {
+      return route.then((resolved: ChannelConversationRouteDto): void | Promise<void> =>
+        this.dispatchDiscordIngress(message, content, operation, binding, resolved),
+      );
+    }
+    return this.dispatchDiscordIngress(message, content, operation, binding, route);
+  }

+  private dispatchDiscordIngress(
+    message: DiscordMessage,
+    content: string,
+    operation: 'send' | 'approve' | 'stop',
+    binding: DiscordInteractionBinding,
+    route: ChannelConversationRouteDto,
+  ): void | Promise<void> {
+    const guildId = message.guildId;
+    if (!guildId) return;
+    if (operation === 'send') this.rememberConversationRoute(route);
+    const correlationId = randomUUID();
+    const ingress: ChannelIngressDto = {
+      correlationId,
+      nativeMessageId: message.id,
+      operation:
+        operation === 'approve'
+          ? 'approval.create'
+          : operation === 'stop'
+            ? 'session.stop'
+            : 'message.send',
+      principal: this.authorizedPrincipal(binding, message.author.id),
+      message: this.channelMessage(message, content, route),
+      route,
+    };
+    if (this.dependencies.ingressPort) {
+      return this.dependencies.ingressPort.receive(ingress).catch((error: unknown) => {
+        if (operation === 'send') this.conversationRoutes.delete(route.conversationId);
+        throw error;
+      });
+    }
+    const socket = this.socket;
+    if (!socket?.connected) {
+      console.error(
+        `[discord] Cannot dispatch routed message: gateway disconnected. channel=${message.channelId} message=${message.id}`,
+      );
+      return;
+    }
+    this.emitDiscordIngress(socket, ingress);
+  }
+
+  private authorizedPrincipal(
+    binding: DiscordInteractionBinding,
+    channelUserId: string,
+  ): ChannelAuthorizedPrincipalDto {
+    const pairing = binding.pairedUsers[channelUserId];
+    if (!pairing) throw new Error('Authorized Discord pairing is unavailable');
+    if (typeof pairing === 'string') return { channelUserId, role: pairing };
+    return {
+      channelUserId,
+      role: pairing.role,
+      ...(pairing.mosaicUserId ? { mosaicUserId: pairing.mosaicUserId } : {}),
+    };
+  }
+
+  private channelMessage(
+    message: DiscordMessage,
+    content: string,
+    route: ChannelConversationRouteDto,
+  ): ChannelMessageDto {
+    const attachments = Array.from(message.attachments.values()).map((attachment) => ({
+      id: attachment.id,
+      name: attachment.name,
+      url: attachment.url,
+      mimeType: attachment.contentType,
+      sizeBytes: attachment.size,
+    }));
+    const firstContentType = attachments[0]?.mimeType;
+    return {
+      id: randomUUID(),
+      channelName: this.name,
+      channelId: route.responseTarget.channelId,
+      senderId: message.author.id,
+      senderKind: 'user',
+      content,
+      contentKind:
+        content.length > 0 ? 'markdown' : firstContentType?.startsWith('image/') ? 'image' : 'file',
+      timestamp:
+        message.createdAt instanceof Date
+          ? message.createdAt.toISOString()
+          : new Date().toISOString(),
+      ...(route.responseTarget.threadId ? { threadId: route.responseTarget.threadId } : {}),
+      ...(attachments.length > 0 ? { attachments } : {}),
+      metadata: {
+        channelMessageId: message.id,
+        guildId: message.guildId ?? '',
+      },
+    };
+  }
+
+  private emitDiscordIngress(socket: Socket, ingress: ChannelIngressDto): void {
    const envelope = createDiscordIngressEnvelope(
      {
-        correlationId: randomUUID(),
-        messageId: message.id,
-        guildId: message.guildId,
-        channelId: bindingChannelId,
-        userId: message.author.id,
-        conversationId,
-        content,
-        threadId: parentChannelId ? channelId : undefined,
-        attachments: Array.from(message.attachments.values()).map((attachment) => ({
+        correlationId: ingress.correlationId,
+        messageId: ingress.nativeMessageId,
+        guildId: String(ingress.message.metadata['guildId'] ?? ''),
+        channelId: ingress.route.authorizationChannelId,
+        userId: ingress.principal.channelUserId,
+        conversationId: ingress.route.conversationId,
+        content: ingress.message.content,
+        ...(ingress.route.responseTarget.threadId
+          ? { threadId: ingress.route.responseTarget.threadId }
+          : {}),
+        attachments: ingress.message.attachments?.map((attachment) => ({
          id: attachment.id,
          name: attachment.name,
          url: attachment.url,
-          contentType: attachment.contentType,
+          contentType: attachment.mimeType,
+          ...(attachment.sizeBytes !== undefined ? { sizeBytes: attachment.sizeBytes } : {}),
        })),
      },
      this.config.serviceToken,
    );
-    this.socket.emit(
-      /^\/approve$/i.test(content)
+    socket.emit(
+      ingress.operation === 'approval.create'
        ? 'discord:approve'
-        : content.startsWith('/stop ')
+        : ingress.operation === 'session.stop'
          ? 'discord:stop'
          : 'message',
      envelope,
    );
  }

-  private isAllowedMessage(message: DiscordMessage): boolean {
+  private authorizationChannelId(message: DiscordMessage): string {
+    // A normal guild channel can itself have a category parent. Only Discord
+    // threads inherit authorization from a configured parent text channel.
+    const channel = message.channel as DiscordMessage['channel'] & {
+      isThread?: () => boolean;
+      parentId?: string | null;
+    };
+    const isThread =
+      typeof channel.isThread === 'function'
+        ? channel.isThread()
+        : channel.parentId !== undefined && channel.parentId !== null;
+    return isThread && channel.parentId ? channel.parentId : message.channelId;
+  }
+
+  private isAllowedMessage(message: DiscordMessage, authorizationChannelId: string): boolean {
    const guildId = message.guildId;
-    const parentChannelId = 'parentId' in message.channel ? message.channel.parentId : null;
-    // Threads inherit their authorization boundary from their configured parent.
-    const authorizationChannelId = parentChannelId ?? message.channelId;
    return (
      guildId !== null &&
      includesId(this.config.allowedGuildIds, guildId) &&
@@ -404,31 +630,282 @@ export class DiscordPlugin {
    );
  }

-  private async sendToDiscord(conversationId: string, text: string): Promise<void> {
-    const channelId = Array.from(this.channelConversations.entries()).find(
-      ([, convId]) => convId === conversationId,
-    )?.[0];
-
-    if (!channelId) {
-      console.error(`[discord] No channel found for conversation ${conversationId}`);
-      return;
+  private resolveConversationRoute(
+    message: DiscordMessage,
+    binding: DiscordInteractionBinding,
+    authorizationChannelId: string,
+    createThread: boolean,
+  ): ChannelConversationRouteDto | Promise<ChannelConversationRouteDto> {
+    if (authorizationChannelId !== message.channelId) {
+      return this.createConversationRoute(
+        binding,
+        authorizationChannelId,
+        message.channelId,
+        message.channelId,
+      );
+    }
+    if (!createThread) {
+      return this.createConversationRoute(binding, authorizationChannelId, message.channelId);
    }

+    if (message.hasThread) {
+      const cachedThread = message.thread;
+      if (cachedThread) {
+        return this.createConversationRoute(
+          binding,
+          authorizationChannelId,
+          cachedThread.id,
+          cachedThread.id,
+        );
+      }
+      if (!('threads' in message.channel)) {
+        return Promise.reject(new Error('Existing Discord thread manager is unavailable'));
+      }
+      return message.channel.threads
+        .fetch(message.id)
+        .then((thread): ChannelConversationRouteDto => {
+          if (!thread) throw new Error('Existing Discord thread is unavailable');
+          return this.createConversationRoute(
+            binding,
+            authorizationChannelId,
+            thread.id,
+            thread.id,
+          );
+        });
+    }
+    return message
+      .startThread({
+        name: `Mosaic conversation ${message.id.slice(-8)}`,
+        autoArchiveDuration: ThreadAutoArchiveDuration.OneHour,
+        reason: 'Authorized Mosaic mention',
+      })
+      .then(
+        (thread): ChannelConversationRouteDto =>
+          this.createConversationRoute(binding, authorizationChannelId, thread.id, thread.id),
+      );
+  }
+
+  private createConversationRoute(
+    binding: DiscordInteractionBinding,
+    authorizationChannelId: string,
+    responseChannelId: string,
+    threadId?: string,
+  ): ChannelConversationRouteDto {
+    // Recompute from configuration on every turn so a stale in-memory map can
+    // never carry a channel-only or differently bound agent identity forward.
+    const conversationId = `${binding.instanceId}:discord:${responseChannelId}`;
+    return {
+      bindingId: `${binding.guildId}:${binding.channelId}:${binding.instanceId}`,
+      logicalAgentId: binding.instanceId,
+      conversationId,
+      channelName: this.name,
+      authorizationChannelId,
+      responseTarget: {
+        channelId: responseChannelId,
+        ...(threadId ? { threadId } : {}),
+      },
+    };
+  }
+
+  private consumeRateLimit(
+    windows: Map<string, number[]>,
+    key: string,
+    limit: number,
+    now = Date.now(),
+  ): boolean {
+    const active = (windows.get(key) ?? []).filter(
+      (timestamp: number): boolean => now - timestamp < RATE_LIMIT_WINDOW_MS,
+    );
+    if (active.length >= Math.max(1, limit)) {
+      windows.set(key, active);
+      return false;
+    }
+    active.push(now);
+    windows.set(key, active);
+    return true;
+  }
+
+  private interactionOperation(content: string): 'send' | 'approve' | 'stop' {
+    if (/^\/approve$/i.test(content)) return 'approve';
+    if (/^\/stop\s+\S+/i.test(content)) return 'stop';
+    return 'send';
+  }
+
+  async send(egress: ChannelEgressDto): Promise<void> {
+    if (!this.isConfiguredRoute(egress.route) || !this.isMessageAlignedWithRoute(egress)) {
+      throw new ChannelDeliveryError(
+        'invalid_route',
+        `Discord egress route is not authorized for conversation ${egress.route.conversationId}`,
+      );
+    }
+    const channelId = egress.route.responseTarget.channelId;
    const channel = this.client.channels.cache.get(channelId);
    if (!channel || !('send' in channel)) {
-      console.error(
-        `[discord] Channel ${channelId} not sendable for conversation ${conversationId}`,
+      throw new ChannelDeliveryError(
+        'destination_unavailable',
+        `Discord destination is unavailable for conversation ${egress.route.conversationId}`,
      );
-      return;
    }

-    for (const chunk of this.chunkText(text, 1900)) {
+    const chunks = this.chunkText(egress.message.content, 1900);
+    for (const [chunkIndex, chunk] of chunks.entries()) {
+      await this.sendChunkWithRetry(
+        channel as {
+          send(options: { content: string; nonce: string; enforceNonce: true }): Promise<unknown>;
+        },
+        chunk,
+        egress.correlationId,
+        chunkIndex,
+        egress.route.conversationId,
+      );
+    }
+  }
+
+  private async sendChunkWithRetry(
+    channel: {
+      send(options: { content: string; nonce: string; enforceNonce: true }): Promise<unknown>;
+    },
+    chunk: string,
+    correlationId: string,
+    chunkIndex: number,
+    conversationId: string,
+  ): Promise<void> {
+    const nonce = createHash('sha256')
+      .update(`${correlationId}:${chunkIndex}`)
+      .digest('hex')
+      .slice(0, 25);
+    let lastError: unknown;
+    for (let attempt = 1; attempt <= DELIVERY_MAX_ATTEMPTS; attempt += 1) {
      try {
-        await (channel as { send: (content: string) => Promise<unknown> }).send(chunk);
-      } catch (err: unknown) {
-        console.error(`[discord] Failed to send message to channel ${channelId}:`, err);
+        await channel.send({ content: chunk, nonce, enforceNonce: true });
+        return;
+      } catch (error: unknown) {
+        lastError = error;
+        const retryable = this.isTransientDeliveryError(error);
+        if (!retryable) {
+          throw new ChannelDeliveryError(
+            'delivery_failed',
+            `Discord delivery failed for conversation ${conversationId}`,
+            false,
+            { cause: error },
+          );
+        }
+        if (attempt < DELIVERY_MAX_ATTEMPTS) {
+          await new Promise<void>((resolve): void => {
+            setTimeout(resolve, DELIVERY_RETRY_BASE_MS * 2 ** (attempt - 1));
+          });
+        }
      }
    }
+    throw new ChannelDeliveryError(
+      'delivery_failed',
+      `Discord delivery failed for conversation ${conversationId}`,
+      true,
+      { cause: lastError },
+    );
+  }
+
+  private isTransientDeliveryError(error: unknown): boolean {
+    if (typeof error !== 'object' || error === null) return false;
+    const candidate = error as { status?: unknown; code?: unknown };
+    if (
+      typeof candidate.status === 'number' &&
+      (candidate.status === 429 || candidate.status >= 500)
+    ) {
+      return true;
+    }
+    return (
+      typeof candidate.code === 'string' &&
+      ['ECONNRESET', 'ETIMEDOUT', 'EAI_AGAIN', 'UND_ERR_CONNECT_TIMEOUT'].includes(candidate.code)
+    );
+  }
+
+  private async sendAgentResponse(conversationId: string, text: string): Promise<void> {
+    const route = this.conversationRoutes.get(conversationId);
+    if (!route) {
+      throw new ChannelDeliveryError(
+        'invalid_route',
+        `Discord response route is unavailable for conversation ${conversationId}`,
+      );
+    }
+    try {
+      await this.send({
+        correlationId: randomUUID(),
+        route,
+        message: {
+          id: randomUUID(),
+          channelName: this.name,
+          channelId: route.responseTarget.channelId,
+          senderId: route.logicalAgentId,
+          senderKind: 'agent',
+          content: text,
+          contentKind: 'markdown',
+          timestamp: new Date().toISOString(),
+          ...(route.responseTarget.threadId ? { threadId: route.responseTarget.threadId } : {}),
+          metadata: {},
+        },
+      });
+    } finally {
+      this.conversationRoutes.delete(conversationId);
+    }
+  }
+
+  /** Compatibility wrapper while Socket.IO agent events carry only conversation ID. */
+  private async sendToDiscord(conversationId: string, text: string): Promise<void> {
+    await this.sendAgentResponse(conversationId, text);
+  }
+
+  private rememberConversationRoute(route: ChannelConversationRouteDto): void {
+    if (
+      !this.conversationRoutes.has(route.conversationId) &&
+      this.conversationRoutes.size >= MAX_CONVERSATION_ROUTES
+    ) {
+      throw new ChannelDeliveryError(
+        'delivery_failed',
+        'Discord has reached its active response-route limit',
+        true,
+      );
+    }
+    this.conversationRoutes.set(route.conversationId, route);
+  }
+
+  private isConfiguredRoute(route: ChannelConversationRouteDto): boolean {
+    if (
+      route.channelName !== this.name ||
+      route.conversationId !==
+        `${route.logicalAgentId}:${this.name}:${route.responseTarget.channelId}`
+    ) {
+      return false;
+    }
+    const bindingMatches = (this.config.interactionBindings ?? []).some(
+      (binding): boolean =>
+        route.bindingId === `${binding.guildId}:${binding.channelId}:${binding.instanceId}` &&
+        route.logicalAgentId === binding.instanceId &&
+        route.authorizationChannelId === binding.channelId,
+    );
+    if (!bindingMatches) return false;
+    if (
+      route.responseTarget.channelId === route.authorizationChannelId &&
+      route.responseTarget.threadId === undefined
+    ) {
+      return true;
+    }
+    const observed = this.conversationRoutes.get(route.conversationId);
+    return (
+      observed?.bindingId === route.bindingId &&
+      observed.logicalAgentId === route.logicalAgentId &&
+      observed.authorizationChannelId === route.authorizationChannelId &&
+      observed.responseTarget.channelId === route.responseTarget.channelId &&
+      observed.responseTarget.threadId === route.responseTarget.threadId
+    );
+  }
+
+  private isMessageAlignedWithRoute(egress: ChannelEgressDto): boolean {
+    return (
+      egress.message.channelName === this.name &&
+      egress.message.channelId === egress.route.responseTarget.channelId &&
+      egress.message.threadId === egress.route.responseTarget.threadId
+    );
  }

  private chunkText(text: string, maxLength: number): string[] {