@kodelyth/discord 2026.5.39 → 2026.5.42

package/src/voice/manager.ts

@@ -0,0 +1,1155 @@
+import type { KlawConfig } from "klaw/plugin-sdk/config-contracts";
+import type { DiscordAccountConfig } from "klaw/plugin-sdk/config-contracts";
+import { resolveAgentRoute } from "klaw/plugin-sdk/routing";
+import { createSubsystemLogger } from "klaw/plugin-sdk/runtime-env";
+import type { RuntimeEnv } from "klaw/plugin-sdk/runtime-env";
+import { formatErrorMessage } from "klaw/plugin-sdk/ssrf-runtime";
+import { resolveDiscordAccountAllowFrom } from "../accounts.js";
+import {
+  type APIVoiceState,
+  type Client,
+  ReadyListener,
+  ResumedListener,
+  VoiceStateUpdateListener,
+} from "../internal/discord.js";
+import type { VoicePlugin } from "../internal/voice.js";
+import { formatMention } from "../mentions.js";
+import { parseDiscordTarget } from "../target-parsing.js";
+import { decodeOpusStream, decodeOpusStreamChunks, writeVoiceWavFile } from "./audio.js";
+import {
+  beginVoiceCapture,
+  clearVoiceCaptureFinalizeTimer,
+  createVoiceCaptureState,
+  finishVoiceCapture,
+  getActiveVoiceCapture,
+  isVoiceCaptureActive,
+  scheduleVoiceCaptureFinalize,
+  stopVoiceCaptureState,
+} from "./capture-state.js";
+import { resolveDiscordVoiceEnabled } from "./config.js";
+import {
+  type DiscordVoiceIngressContext,
+  resolveDiscordVoiceIngressContext,
+  runDiscordVoiceAgentTurn,
+} from "./ingress.js";
+import {
+  DiscordRealtimeVoiceSession,
+  isDiscordRealtimeVoiceMode,
+  resolveDiscordVoiceMode,
+} from "./realtime.js";
+import {
+  analyzeVoiceReceiveError,
+  createVoiceReceiveRecoveryState,
+  DAVE_RECEIVE_PASSTHROUGH_INITIAL_EXPIRY_SECONDS,
+  DAVE_RECEIVE_PASSTHROUGH_REARM_EXPIRY_SECONDS,
+  enableDaveReceivePassthrough as tryEnableDaveReceivePassthrough,
+  finishVoiceDecryptRecovery,
+  noteVoiceDecryptFailure,
+  resetVoiceReceiveRecoveryState,
+} from "./receive-recovery.js";
+import { loadDiscordVoiceSdk } from "./sdk-runtime.js";
+import { processDiscordVoiceSegment } from "./segment.js";
+import {
+  CAPTURE_FINALIZE_GRACE_MS,
+  isVoiceChannel,
+  logVoiceVerbose,
+  resolveVoiceTimeoutMs,
+  MIN_SEGMENT_SECONDS,
+  VOICE_CONNECT_READY_TIMEOUT_MS,
+  VOICE_RECONNECT_GRACE_MS,
+  type VoiceOperationResult,
+  type VoiceSessionEntry,
+} from "./session.js";
+import { DiscordVoiceSpeakerContextResolver } from "./speaker-context.js";
+
+const logger = createSubsystemLogger("discord/voice");
+const VOICE_LOG_PREVIEW_CHARS = 500;
+const DISCORD_VOICE_FATAL_AUTOJOIN_ERROR_PATTERNS = [
+  "api key missing",
+  "incorrect api key",
+  "invalid api key",
+  "unauthorized",
+  "authentication",
+  "permission denied",
+  "forbidden",
+];
+
+type DiscordVoiceSdk = ReturnType<typeof loadDiscordVoiceSdk>;
+type DiscordVoiceConnection = ReturnType<DiscordVoiceSdk["joinVoiceChannel"]>;
+type VoiceChannelResidency = {
+  guildId: string;
+  channelId: string;
+};
+
+function formatVoiceLogPreview(text: string): string {
+  const oneLine = text.replace(/\s+/g, " ").trim();
+  if (oneLine.length <= VOICE_LOG_PREVIEW_CHARS) {
+    return oneLine;
+  }
+  return `${oneLine.slice(0, VOICE_LOG_PREVIEW_CHARS)}...`;
+}
+
+function isVoiceConnectionDestroyed(
+  connection: DiscordVoiceConnection,
+  voiceSdk: DiscordVoiceSdk,
+): boolean {
+  return connection.state.status === voiceSdk.VoiceConnectionStatus.Destroyed;
+}
+
+function destroyVoiceConnectionSafely(params: {
+  connection: DiscordVoiceConnection;
+  voiceSdk: DiscordVoiceSdk;
+  reason: string;
+}): void {
+  if (isVoiceConnectionDestroyed(params.connection, params.voiceSdk)) {
+    logVoiceVerbose(`destroy skipped: ${params.reason}; connection already destroyed`);
+    return;
+  }
+  try {
+    params.connection.destroy();
+  } catch (err) {
+    const message = formatErrorMessage(err);
+    if (message.includes("already been destroyed")) {
+      logVoiceVerbose(`destroy skipped: ${params.reason}; ${message}`);
+      return;
+    }
+    logger.warn(`discord voice: destroy failed: ${params.reason}: ${message}`);
+  }
+}
+
+function normalizeVoiceChannelResidencies(
+  entries: Array<{ guildId?: string; channelId?: string }> | undefined,
+): VoiceChannelResidency[] {
+  const normalized: VoiceChannelResidency[] = [];
+  for (const entry of entries ?? []) {
+    const guildId = entry.guildId?.trim();
+    const channelId = entry.channelId?.trim();
+    if (guildId && channelId) {
+      normalized.push({ guildId, channelId });
+    }
+  }
+  return normalized;
+}
+
+function isVoiceChannelAllowed(params: {
+  allowedChannels: VoiceChannelResidency[] | null;
+  guildId: string;
+  channelId: string;
+}): boolean {
+  return (
+    params.allowedChannels === null ||
+    params.allowedChannels.some(
+      (entry) => entry.guildId === params.guildId && entry.channelId === params.channelId,
+    )
+  );
+}
+
+function formatAutoJoinFailureKey(entry: { guildId: string; channelId: string }): string {
+  return `${entry.guildId}:${entry.channelId}`;
+}
+
+function isFatalAutoJoinFailure(message: string): boolean {
+  const normalized = message.toLowerCase();
+  return DISCORD_VOICE_FATAL_AUTOJOIN_ERROR_PATTERNS.some((pattern) =>
+    normalized.includes(pattern),
+  );
+}
+
+function startAutoJoin(manager: Pick<DiscordVoiceManager, "autoJoin">) {
+  void manager
+    .autoJoin()
+    .catch((err) => logger.warn(`discord voice: autoJoin failed: ${formatErrorMessage(err)}`));
+}
+
+function resolveDiscordVoiceAgentRoute(params: {
+  cfg: KlawConfig;
+  accountId: string;
+  guildId: string;
+  sessionChannelId: string;
+  voiceConfig: DiscordAccountConfig["voice"];
+}) {
+  const voiceRoute = resolveAgentRoute({
+    cfg: params.cfg,
+    channel: "discord",
+    accountId: params.accountId,
+    guildId: params.guildId,
+    peer: { kind: "channel", id: params.sessionChannelId },
+  });
+  const agentSession = params.voiceConfig?.agentSession;
+  if (agentSession?.mode !== "target") {
+    return {
+      route: voiceRoute,
+      voiceRoute,
+      agentSessionMode: "voice" as const,
+      agentSessionTarget: undefined,
+    };
+  }
+  const target = agentSession.target?.trim();
+  if (!target) {
+    throw new Error('channels.discord.voice.agentSession.target is required when mode is "target"');
+  }
+  const parsed = parseDiscordTarget(target, { defaultKind: "channel" });
+  if (!parsed) {
+    throw new Error(`Invalid Discord voice agent session target "${target}"`);
+  }
+  const route = resolveAgentRoute({
+    cfg: params.cfg,
+    channel: "discord",
+    accountId: params.accountId,
+    guildId: params.guildId,
+    peer: {
+      kind: parsed.kind === "user" ? "direct" : "channel",
+      id: parsed.id,
+    },
+  });
+  return {
+    route,
+    voiceRoute,
+    agentSessionMode: "target" as const,
+    agentSessionTarget: parsed.normalized,
+  };
+}
+
+export class DiscordVoiceManager {
+  private sessions = new Map<string, VoiceSessionEntry>();
+  private botUserId?: string;
+  private readonly voiceEnabled: boolean;
+  private autoJoinTask: Promise<void> | null = null;
+  private readonly fatalAutoJoinFailures = new Map<
+    string,
+    { message: string; skipLogged: boolean }
+  >();
+  private readonly ownerAllowFrom?: string[];
+  private readonly speakerContext: DiscordVoiceSpeakerContextResolver;
+  private readonly allowedChannels: VoiceChannelResidency[] | null;
+
+  constructor(
+    private params: {
+      client: Client;
+      cfg: KlawConfig;
+      discordConfig: DiscordAccountConfig;
+      accountId: string;
+      runtime: RuntimeEnv;
+      botUserId?: string;
+    },
+  ) {
+    this.botUserId = params.botUserId;
+    this.voiceEnabled = resolveDiscordVoiceEnabled(params.discordConfig.voice);
+    this.ownerAllowFrom =
+      resolveDiscordAccountAllowFrom({ cfg: params.cfg, accountId: params.accountId }) ??
+      params.discordConfig.allowFrom ??
+      params.discordConfig.dm?.allowFrom ??
+      [];
+    this.allowedChannels =
+      params.discordConfig.voice?.allowedChannels === undefined
+        ? null
+        : normalizeVoiceChannelResidencies(params.discordConfig.voice.allowedChannels);
+    this.speakerContext = new DiscordVoiceSpeakerContextResolver({
+      client: params.client,
+      ownerAllowFrom: this.ownerAllowFrom,
+    });
+  }
+
+  setBotUserId(id?: string) {
+    if (id) {
+      this.botUserId = id;
+    }
+  }
+
+  isEnabled() {
+    return this.voiceEnabled;
+  }
+
+  async autoJoin(): Promise<void> {
+    if (!this.voiceEnabled) {
+      return;
+    }
+    if (this.autoJoinTask) {
+      return this.autoJoinTask;
+    }
+    this.autoJoinTask = (async () => {
+      const entries = this.params.discordConfig.voice?.autoJoin ?? [];
+      const entriesByGuild = new Map<string, { guildId: string; channelId: string }>();
+      const duplicateGuilds = new Set<string>();
+      for (const entry of entries) {
+        const guildId = entry.guildId.trim();
+        const channelId = entry.channelId.trim();
+        if (!guildId || !channelId) {
+          continue;
+        }
+        if (entriesByGuild.has(guildId)) {
+          duplicateGuilds.add(guildId);
+        }
+        entriesByGuild.set(guildId, { guildId, channelId });
+      }
+
+      logVoiceVerbose(`autoJoin: ${entries.length} entries, ${entriesByGuild.size} guilds`);
+      for (const guildId of duplicateGuilds) {
+        const selected = entriesByGuild.get(guildId);
+        if (selected) {
+          logger.warn(
+            `discord voice: autoJoin has multiple entries for guild ${guildId}; using channel ${selected.channelId}`,
+          );
+        }
+      }
+
+      for (const entry of entriesByGuild.values()) {
+        const failureKey = formatAutoJoinFailureKey(entry);
+        const fatalFailure = this.fatalAutoJoinFailures.get(failureKey);
+        if (fatalFailure) {
+          if (!fatalFailure.skipLogged) {
+            logger.warn(
+              `discord voice: autoJoin suppressed guild=${entry.guildId} channel=${entry.channelId} after fatal startup failure; retry with /vc join or reload config after fixing credentials: ${fatalFailure.message}`,
+            );
+            fatalFailure.skipLogged = true;
+          }
+          continue;
+        }
+        logVoiceVerbose(`autoJoin: joining guild ${entry.guildId} channel ${entry.channelId}`);
+        const result = await this.join({
+          guildId: entry.guildId,
+          channelId: entry.channelId,
+        });
+        if (!result.ok) {
+          logger.warn(
+            `discord voice: autoJoin skipped guild=${entry.guildId} channel=${entry.channelId}: ${result.message}`,
+          );
+          if (isFatalAutoJoinFailure(result.message)) {
+            this.fatalAutoJoinFailures.set(failureKey, {
+              message: result.message,
+              skipLogged: false,
+            });
+          }
+        }
+      }
+    })().finally(() => {
+      this.autoJoinTask = null;
+    });
+    return this.autoJoinTask;
+  }
+
+  status(): VoiceOperationResult[] {
+    return Array.from(this.sessions.values()).map((session) => ({
+      ok: true,
+      message: `connected: guild ${session.guildId} channel ${session.channelId}`,
+      guildId: session.guildId,
+      channelId: session.channelId,
+    }));
+  }
+
+  isAllowedVoiceChannel(params: { guildId: string; channelId: string }): boolean {
+    return isVoiceChannelAllowed({
+      allowedChannels: this.allowedChannels,
+      guildId: params.guildId.trim(),
+      channelId: params.channelId.trim(),
+    });
+  }
+
+  async join(params: { guildId: string; channelId: string }): Promise<VoiceOperationResult> {
+    if (!this.voiceEnabled) {
+      return {
+        ok: false,
+        message: "Discord voice is disabled (channels.discord.voice.enabled).",
+      };
+    }
+    const guildId = params.guildId.trim();
+    const channelId = params.channelId.trim();
+    if (!guildId || !channelId) {
+      return { ok: false, message: "Missing guildId or channelId." };
+    }
+    if (!this.isAllowedVoiceChannel({ guildId, channelId })) {
+      logger.warn(
+        `discord voice: join rejected for non-allowed channel guild=${guildId} channel=${channelId}`,
+      );
+      return {
+        ok: false,
+        message: `${formatMention({ channelId })} is not allowed by channels.discord.voice.allowedChannels.`,
+        guildId,
+        channelId,
+      };
+    }
+    logVoiceVerbose(`join requested: guild ${guildId} channel ${channelId}`);
+
+    const existing = this.sessions.get(guildId);
+    if (existing && existing.channelId === channelId) {
+      logVoiceVerbose(`join: already connected to guild ${guildId} channel ${channelId}`);
+      return {
+        ok: true,
+        message: `Already connected to ${formatMention({ channelId })}.`,
+        guildId,
+        channelId,
+      };
+    }
+    if (existing) {
+      logVoiceVerbose(`join: replacing existing session for guild ${guildId}`);
+      await this.leave({ guildId });
+    }
+
+    const channelInfo = await this.params.client.fetchChannel(channelId).catch(() => null);
+    if (!channelInfo || ("type" in channelInfo && !isVoiceChannel(channelInfo.type))) {
+      return { ok: false, message: `Channel ${channelId} is not a voice channel.` };
+    }
+    const channelGuildId = "guildId" in channelInfo ? channelInfo.guildId : undefined;
+    if (channelGuildId && channelGuildId !== guildId) {
+      return { ok: false, message: "Voice channel is not in this guild." };
+    }
+
+    const voicePlugin = this.params.client.getPlugin<VoicePlugin>("voice");
+    if (!voicePlugin) {
+      return { ok: false, message: "Discord voice plugin is not available." };
+    }
+
+    const voiceConfig = this.params.discordConfig.voice;
+    const voiceMode = resolveDiscordVoiceMode(voiceConfig);
+    const adapterCreator = voicePlugin.getGatewayAdapterCreator(guildId);
+    const daveEncryption = voiceConfig?.daveEncryption;
+    const decryptionFailureTolerance = voiceConfig?.decryptionFailureTolerance;
+    const connectReadyTimeoutMs = resolveVoiceTimeoutMs(
+      voiceConfig?.connectTimeoutMs,
+      VOICE_CONNECT_READY_TIMEOUT_MS,
+    );
+    const reconnectGraceMs = resolveVoiceTimeoutMs(
+      voiceConfig?.reconnectGraceMs,
+      VOICE_RECONNECT_GRACE_MS,
+    );
+    logVoiceVerbose(
+      `join: DAVE settings encryption=${daveEncryption === false ? "off" : "on"} tolerance=${
+        decryptionFailureTolerance ?? "default"
+      } connectTimeout=${connectReadyTimeoutMs}ms reconnectGrace=${reconnectGraceMs}ms`,
+    );
+    const voiceSdk = loadDiscordVoiceSdk();
+    const existingEntry = this.sessions.get(guildId);
+    if (existingEntry) {
+      existingEntry.stop();
+      this.sessions.delete(guildId);
+    }
+    const staleConnection = voiceSdk.getVoiceConnection(guildId);
+    if (staleConnection) {
+      destroyVoiceConnectionSafely({
+        connection: staleConnection,
+        voiceSdk,
+        reason: `stale connection before join guild ${guildId}`,
+      });
+    }
+    const connection = voiceSdk.joinVoiceChannel({
+      channelId,
+      guildId,
+      adapterCreator,
+      selfDeaf: false,
+      selfMute: false,
+      daveEncryption,
+      decryptionFailureTolerance,
+    });
+
+    try {
+      await voiceSdk.entersState(
+        connection,
+        voiceSdk.VoiceConnectionStatus.Ready,
+        connectReadyTimeoutMs,
+      );
+      logVoiceVerbose(`join: connected to guild ${guildId} channel ${channelId}`);
+    } catch (err) {
+      logger.warn(
+        `discord voice: join failed before ready: guild ${guildId} channel ${channelId} timeout=${connectReadyTimeoutMs}ms error=${formatErrorMessage(err)}`,
+      );
+      destroyVoiceConnectionSafely({
+        connection,
+        voiceSdk,
+        reason: `failed join cleanup guild ${guildId} channel ${channelId}`,
+      });
+      return { ok: false, message: `Failed to join voice channel: ${formatErrorMessage(err)}` };
+    }
+
+    const sessionChannelId = channelInfo?.id ?? channelId;
+    // Use the voice channel id as the session channel so text chat in the voice channel
+    // shares the same session as spoken audio.
+    if (sessionChannelId !== channelId) {
+      logVoiceVerbose(
+        `join: using session channel ${sessionChannelId} for voice channel ${channelId}`,
+      );
+    }
+    let routeInfo: ReturnType<typeof resolveDiscordVoiceAgentRoute>;
+    try {
+      routeInfo = resolveDiscordVoiceAgentRoute({
+        cfg: this.params.cfg,
+        accountId: this.params.accountId,
+        guildId,
+        sessionChannelId,
+        voiceConfig,
+      });
+    } catch (err) {
+      destroyVoiceConnectionSafely({
+        connection,
+        voiceSdk,
+        reason: `voice agent session route failed guild ${guildId} channel ${channelId}`,
+      });
+      return {
+        ok: false,
+        message: `Failed to resolve Discord voice agent session: ${formatErrorMessage(err)}`,
+        guildId,
+        channelId,
+      };
+    }
+    const { route, voiceRoute, agentSessionMode, agentSessionTarget } = routeInfo;
+    logger.info(
+      `discord voice: joining guild=${guildId} channel=${channelId} mode=${voiceMode} agent=${route.agentId} voiceSession=${voiceRoute.sessionKey} supervisorSession=${route.sessionKey} agentSessionMode=${agentSessionMode}${agentSessionTarget ? ` agentSessionTarget=${agentSessionTarget}` : ""} voiceModel=${voiceConfig?.model ?? "route-default"} realtimeProvider=${voiceConfig?.realtime?.provider ?? "auto"} realtimeModel=${voiceConfig?.realtime?.model ?? "provider-default"} realtimeVoice=${voiceConfig?.realtime?.voice ?? "provider-default"}`,
+    );
+
+    const player = voiceSdk.createAudioPlayer();
+    connection.subscribe(player);
+
+    let speakingHandler: ((userId: string) => void) | undefined;
+    let speakingEndHandler: ((userId: string) => void) | undefined;
+    let disconnectedHandler: (() => Promise<void>) | undefined;
+    let destroyedHandler: (() => void) | undefined;
+    let playerErrorHandler: ((err: Error) => void) | undefined;
+    let stopped = false;
+    const clearSessionIfCurrent = () => {
+      const active = this.sessions.get(guildId);
+      if (active?.connection === connection) {
+        this.sessions.delete(guildId);
+      }
+    };
+    const stopEntry = (
+      entry: VoiceSessionEntry,
+      options: { destroyConnection: boolean; reason: string },
+    ) => {
+      if (stopped) {
+        return;
+      }
+      stopped = true;
+      if (speakingHandler) {
+        connection.receiver.speaking.off("start", speakingHandler);
+      }
+      if (speakingEndHandler) {
+        connection.receiver.speaking.off("end", speakingEndHandler);
+      }
+      stopVoiceCaptureState(entry.capture);
+      if (disconnectedHandler) {
+        connection.off(voiceSdk.VoiceConnectionStatus.Disconnected, disconnectedHandler);
+      }
+      if (destroyedHandler) {
+        connection.off(voiceSdk.VoiceConnectionStatus.Destroyed, destroyedHandler);
+      }
+      if (playerErrorHandler) {
+        player.off("error", playerErrorHandler);
+      }
+      entry.realtime?.close();
+      entry.realtime = undefined;
+      player.stop();
+      if (options.destroyConnection) {
+        destroyVoiceConnectionSafely({
+          connection,
+          voiceSdk,
+          reason: options.reason,
+        });
+      }
+    };
+
+    const entry: VoiceSessionEntry = {
+      guildId,
+      guildName:
+        channelInfo &&
+        "guild" in channelInfo &&
+        channelInfo.guild &&
+        typeof channelInfo.guild.name === "string"
+          ? channelInfo.guild.name
+          : undefined,
+      channelId,
+      channelName:
+        channelInfo && "name" in channelInfo && typeof channelInfo.name === "string"
+          ? channelInfo.name
+          : undefined,
+      sessionChannelId,
+      voiceSessionKey: voiceRoute.sessionKey,
+      route,
+      connection,
+      player,
+      playbackQueue: Promise.resolve(),
+      processingQueue: Promise.resolve(),
+      capture: createVoiceCaptureState(),
+      receiveRecovery: createVoiceReceiveRecoveryState(),
+      stop: () => {
+        stopEntry(entry, {
+          destroyConnection: true,
+          reason: `stop guild ${guildId} channel ${channelId}`,
+        });
+      },
+    };
+
+    if (voiceMode !== "stt-tts") {
+      entry.realtime = new DiscordRealtimeVoiceSession({
+        cfg: this.params.cfg,
+        discordConfig: this.params.discordConfig,
+        entry,
+        mode: voiceMode,
+        runAgentTurn: ({ context, message, toolsAllow, userId }) =>
+          this.runDiscordRealtimeAgentTurn({ context, entry, message, toolsAllow, userId }),
+      });
+      try {
+        await entry.realtime.connect();
+      } catch (err) {
+        entry.realtime.close();
+        destroyVoiceConnectionSafely({
+          connection,
+          voiceSdk,
+          reason: `realtime setup failed guild ${guildId} channel ${channelId}`,
+        });
+        return {
+          ok: false,
+          message: `Failed to start Discord realtime voice: ${formatErrorMessage(err)}`,
+          guildId,
+          channelId,
+        };
+      }
+    }
+
+    speakingHandler = (userId: string) => {
+      void this.handleSpeakingStart(entry, userId).catch((err) => {
+        logger.warn(`discord voice: capture failed: ${formatErrorMessage(err)}`);
+      });
+    };
+    speakingEndHandler = (userId: string) => {
+      this.scheduleCaptureFinalize(entry, userId, "speaker end");
+    };
+
+    disconnectedHandler = async () => {
+      try {
+        logVoiceVerbose(
+          `disconnected: attempting recovery guild ${guildId} channel ${channelId} grace=${reconnectGraceMs}ms`,
+        );
+        await Promise.race([
+          voiceSdk.entersState(
+            connection,
+            voiceSdk.VoiceConnectionStatus.Signalling,
+            reconnectGraceMs,
+          ),
+          voiceSdk.entersState(
+            connection,
+            voiceSdk.VoiceConnectionStatus.Connecting,
+            reconnectGraceMs,
+          ),
+        ]);
+        logVoiceVerbose(`disconnected: recovery started guild ${guildId} channel ${channelId}`);
+      } catch (err) {
+        logger.warn(
+          `discord voice: disconnect recovery failed: guild ${guildId} channel ${channelId} timeout=${reconnectGraceMs}ms error=${formatErrorMessage(err)}; destroying connection`,
+        );
+        clearSessionIfCurrent();
+        stopEntry(entry, {
+          destroyConnection: true,
+          reason: `disconnect recovery failed guild ${guildId} channel ${channelId}`,
+        });
+      }
+    };
+    destroyedHandler = () => {
+      clearSessionIfCurrent();
+      stopEntry(entry, {
+        destroyConnection: false,
+        reason: `destroyed guild ${guildId} channel ${channelId}`,
+      });
+    };
+    playerErrorHandler = (err: Error) => {
+      logger.warn(`discord voice: playback error: ${formatErrorMessage(err)}`);
+    };
+
+    this.enableDaveReceivePassthrough(
+      entry,
+      "post-join warmup",
+      DAVE_RECEIVE_PASSTHROUGH_INITIAL_EXPIRY_SECONDS,
+    );
+    connection.receiver.speaking.on("start", speakingHandler);
+    connection.receiver.speaking.on("end", speakingEndHandler);
+    connection.on(voiceSdk.VoiceConnectionStatus.Disconnected, disconnectedHandler);
+    connection.on(voiceSdk.VoiceConnectionStatus.Destroyed, destroyedHandler);
+    player.on("error", playerErrorHandler);
+
+    this.sessions.set(guildId, entry);
+    this.fatalAutoJoinFailures.delete(formatAutoJoinFailureKey({ guildId, channelId }));
+    logger.info(
+      `discord voice: joined guild=${guildId} channel=${channelId} mode=${voiceMode} agent=${route.agentId} voiceSession=${voiceRoute.sessionKey} supervisorSession=${route.sessionKey} voiceModel=${voiceConfig?.model ?? "route-default"}`,
+    );
+    return {
+      ok: true,
+      message: `Joined ${formatMention({ channelId })}.`,
+      guildId,
+      channelId,
+    };
+  }
+
+  async leave(params: { guildId: string; channelId?: string }): Promise<VoiceOperationResult> {
+    const guildId = params.guildId.trim();
+    logVoiceVerbose(`leave requested: guild ${guildId} channel ${params.channelId ?? "current"}`);
+    const entry = this.sessions.get(guildId);
+    if (!entry) {
+      return { ok: false, message: "Not connected to a voice channel." };
+    }
+    if (params.channelId && params.channelId !== entry.channelId) {
+      return { ok: false, message: "Not connected to that voice channel." };
+    }
+    entry.stop();
+    this.sessions.delete(guildId);
+    logVoiceVerbose(`leave: disconnected from guild ${guildId} channel ${entry.channelId}`);
+    return {
+      ok: true,
+      message: `Left ${formatMention({ channelId: entry.channelId })}.`,
+      guildId,
+      channelId: entry.channelId,
+    };
+  }
+
+  async handleVoiceStateUpdate(data: APIVoiceState): Promise<void> {
+    if (!this.botUserId || data.user_id !== this.botUserId) {
+      return;
+    }
+    const guildId = data.guild_id?.trim();
+    const channelId = data.channel_id?.trim();
+    if (!guildId || !channelId) {
+      return;
+    }
+
+    const existing = this.sessions.get(guildId);
+    if (this.isAllowedVoiceChannel({ guildId, channelId })) {
+      if (existing && existing.channelId !== channelId) {
+        logger.warn(
+          `discord voice: bot moved to allowed channel guild=${guildId} from=${existing.channelId} to=${channelId}; rebuilding voice session`,
+        );
+        await this.join({ guildId, channelId });
+      }
+      return;
+    }
+
+    logger.warn(
+      `discord voice: bot moved to non-allowed channel guild=${guildId} channel=${channelId}; leaving`,
+    );
+    if (existing) {
+      await this.leave({ guildId });
+    } else {
+      const voiceSdk = loadDiscordVoiceSdk();
+      const connection = voiceSdk.getVoiceConnection(guildId);
+      if (connection) {
+        destroyVoiceConnectionSafely({
+          connection,
+          voiceSdk,
+          reason: `non-allowed voice state guild ${guildId} channel ${channelId}`,
+        });
+      }
+    }
+
+    const target = this.resolveVoiceResidencyTarget(guildId);
+    if (target) {
+      logger.warn(
+        `discord voice: rejoining allowed voice channel guild=${guildId} channel=${target.channelId}`,
+      );
+      await this.join(target);
+    }
+  }
+
+  async destroy(): Promise<void> {
+    for (const entry of this.sessions.values()) {
+      entry.stop();
+    }
+    this.sessions.clear();
+  }
+
+  private resolveVoiceResidencyTarget(guildId: string): VoiceChannelResidency | null {
+    const autoJoinTarget = normalizeVoiceChannelResidencies(
+      this.params.discordConfig.voice?.autoJoin,
+    )
+      .toReversed()
+      .find((entry) => entry.guildId === guildId);
+    if (autoJoinTarget && this.isAllowedVoiceChannel(autoJoinTarget)) {
+      return autoJoinTarget;
+    }
+    if (this.allowedChannels === null) {
+      return null;
+    }
+    const guildAllowed = this.allowedChannels.filter((entry) => entry.guildId === guildId);
+    return guildAllowed.length === 1 ? guildAllowed[0] : null;
+  }
+
+  private enqueueProcessing(entry: VoiceSessionEntry, task: () => Promise<void>) {
+    entry.processingQueue = entry.processingQueue
+      .then(task)
+      .catch((err) => logger.warn(`discord voice: processing failed: ${formatErrorMessage(err)}`));
+  }
+
+  private enqueuePlayback(entry: VoiceSessionEntry, task: () => Promise<void>) {
+    entry.playbackQueue = entry.playbackQueue
+      .then(task)
+      .catch((err) => logger.warn(`discord voice: playback failed: ${formatErrorMessage(err)}`));
+  }
+
+  private clearCaptureFinalizeTimer(entry: VoiceSessionEntry, userId: string, generation?: number) {
+    return clearVoiceCaptureFinalizeTimer(entry.capture, userId, generation);
+  }
+
+  private scheduleCaptureFinalize(entry: VoiceSessionEntry, userId: string, reason: string) {
+    const graceMs = resolveVoiceTimeoutMs(
+      this.params.discordConfig.voice?.captureSilenceGraceMs,
+      CAPTURE_FINALIZE_GRACE_MS,
+    );
+    scheduleVoiceCaptureFinalize({
+      state: entry.capture,
+      userId,
+      delayMs: graceMs,
+      onFinalize: () => {
+        logVoiceVerbose(
+          `capture finalize: guild ${entry.guildId} channel ${entry.channelId} user ${userId} reason=${reason} grace=${graceMs}ms`,
+        );
+      },
+    });
+  }
+
+  private async handleSpeakingStart(entry: VoiceSessionEntry, userId: string) {
+    if (!userId) {
+      return;
+    }
+    if (this.botUserId && userId === this.botUserId) {
+      return;
+    }
+    if (isVoiceCaptureActive(entry.capture, userId)) {
+      const activeCapture = getActiveVoiceCapture(entry.capture, userId);
+      const extended = activeCapture
+        ? this.clearCaptureFinalizeTimer(entry, userId, activeCapture.generation)
+        : false;
+      logVoiceVerbose(
+        `capture start ignored (already active): guild ${entry.guildId} channel ${entry.channelId} user ${userId}${extended ? " (finalize canceled)" : ""}`,
+      );
+      return;
+    }
+
+    logVoiceVerbose(
+      `capture start: guild ${entry.guildId} channel ${entry.channelId} user ${userId}`,
+    );
+    const voiceSdk = loadDiscordVoiceSdk();
+    const voiceMode = resolveDiscordVoiceMode(this.params.discordConfig.voice);
+    const realtime =
+      entry.realtime && isDiscordRealtimeVoiceMode(voiceMode) ? entry.realtime : undefined;
+    if (entry.player.state.status === voiceSdk.AudioPlayerStatus.Playing && !realtime) {
+      logVoiceVerbose(
+        `capture ignored during playback: guild ${entry.guildId} channel ${entry.channelId} user ${userId}`,
+      );
+      return;
+    }
+    const realtimeIngress = realtime
+      ? await this.resolveDiscordVoiceIngressContext(entry, userId)
+      : undefined;
+    if (realtime && !realtimeIngress) {
+      logVoiceVerbose(
+        `realtime capture unauthorized: guild ${entry.guildId} channel ${entry.channelId} user ${userId}`,
+      );
+      return;
+    }
+    if (entry.player.state.status === voiceSdk.AudioPlayerStatus.Playing && realtime) {
+      if (!realtime.isBargeInEnabled()) {
+        logger.info(
+          `discord voice: realtime capture ignored during playback (barge-in disabled): guild ${entry.guildId} channel ${entry.channelId} user ${userId}`,
+        );
+        return;
+      }
+      logVoiceVerbose(
+        `realtime barge-in: guild ${entry.guildId} channel ${entry.channelId} user ${userId}`,
+      );
+      logger.info(
+        `discord voice: realtime barge-in detected source=speaker-start guild=${entry.guildId} channel=${entry.channelId} user=${userId} playerStatus=${entry.player.state.status}`,
+      );
+      realtime.handleBargeIn("speaker-start");
+    }
+    this.enableDaveReceivePassthrough(
+      entry,
+      `speaker ${userId} start`,
+      DAVE_RECEIVE_PASSTHROUGH_REARM_EXPIRY_SECONDS,
+    );
+    const stream = entry.connection.receiver.subscribe(userId, {
+      end: {
+        behavior: voiceSdk.EndBehaviorType.Manual,
+      },
+    });
+    const generation = beginVoiceCapture(entry.capture, userId, stream);
+    let streamAborted = false;
+    stream.on("error", (err) => {
+      streamAborted = analyzeVoiceReceiveError(err).isAbortLike;
+      this.handleReceiveError(entry, err);
+    });
+
+    try {
+      if (realtime && realtimeIngress) {
+        const turn = realtime.beginSpeakerTurn(realtimeIngress, userId);
+        try {
+          await this.processRealtimeAudioCapture({ entry, stream, turn });
+        } finally {
+          turn.close();
+        }
+        return;
+      }
+      const pcm = await decodeOpusStream(stream, {
+        onVerbose: logVoiceVerbose,
+        onWarn: (message) => logger.warn(message),
+      });
+      if (pcm.length === 0) {
+        logVoiceVerbose(
+          `capture empty: guild ${entry.guildId} channel ${entry.channelId} user ${userId}`,
+        );
+        return;
+      }
+      this.resetDecryptFailureState(entry);
+      const { path: wavPath, durationSeconds } = await writeVoiceWavFile(pcm);
+      const minimumDurationSeconds = streamAborted ? 0.2 : MIN_SEGMENT_SECONDS;
+      if (durationSeconds < minimumDurationSeconds) {
+        logVoiceVerbose(
+          `capture too short (${durationSeconds.toFixed(2)}s): guild ${entry.guildId} channel ${entry.channelId} user ${userId}`,
+        );
+        return;
+      }
+      logVoiceVerbose(
+        `capture ready (${durationSeconds.toFixed(2)}s): guild ${entry.guildId} channel ${entry.channelId} user ${userId}`,
+      );
+      this.enqueueProcessing(entry, async () => {
+        await this.processSegment({ entry, wavPath, userId, durationSeconds });
+      });
+    } finally {
+      finishVoiceCapture(entry.capture, userId, generation);
+    }
+  }
+
+  private async processRealtimeAudioCapture(params: {
+    entry: VoiceSessionEntry;
+    stream: import("node:stream").Readable;
+    turn: import("./session.js").VoiceRealtimeSpeakerTurn;
+  }): Promise<void> {
+    const { entry, stream, turn } = params;
+    let resetReceiveRecovery = false;
+    await decodeOpusStreamChunks(stream, {
+      onChunk: (pcm) => {
+        if (!resetReceiveRecovery && pcm.length > 0) {
+          resetReceiveRecovery = true;
+          this.resetDecryptFailureState(entry);
+        }
+        turn.sendInputAudio(pcm);
+      },
+      onVerbose: logVoiceVerbose,
+      onWarn: (message) => logger.warn(message),
+    });
+  }
+
+  private async resolveDiscordVoiceIngressContext(
+    entry: VoiceSessionEntry,
+    userId: string,
+  ): Promise<DiscordVoiceIngressContext | null> {
+    return await resolveDiscordVoiceIngressContext({
+      entry,
+      userId,
+      cfg: this.params.cfg,
+      discordConfig: this.params.discordConfig,
+      ownerAllowFrom: this.ownerAllowFrom,
+      fetchGuildName: async (guildId) => {
+        const guild = await this.params.client.fetchGuild(guildId).catch(() => null);
+        return guild && typeof guild.name === "string" && guild.name.trim()
+          ? guild.name
+          : undefined;
+      },
+      speakerContext: this.speakerContext,
+    });
+  }
+
+  private async runDiscordRealtimeAgentTurn(params: {
+    context: {
+      extraSystemPrompt?: string;
+      senderIsOwner: boolean;
+      speakerLabel: string;
+    };
+    entry: VoiceSessionEntry;
+    message: string;
+    toolsAllow?: string[];
+    userId: string;
+  }): Promise<string> {
+    const { context, entry, message, toolsAllow, userId } = params;
+    logger.info(
+      `discord voice: agent turn start guild=${entry.guildId} channel=${entry.channelId} voiceSession=${entry.voiceSessionKey} supervisorSession=${entry.route.sessionKey} agent=${entry.route.agentId} user=${userId} speaker=${context.speakerLabel} owner=${context.senderIsOwner} model=${this.params.discordConfig.voice?.model ?? "route-default"} message=${formatVoiceLogPreview(message)}`,
+    );
+    const turn = await runDiscordVoiceAgentTurn({
+      entry,
+      userId,
+      message,
+      cfg: this.params.cfg,
+      discordConfig: this.params.discordConfig,
+      runtime: this.params.runtime,
+      context,
+      toolsAllow,
+      ownerAllowFrom: this.ownerAllowFrom,
+      fetchGuildName: async (guildId) => {
+        const guild = await this.params.client.fetchGuild(guildId).catch(() => null);
+        return guild && typeof guild.name === "string" && guild.name.trim()
+          ? guild.name
+          : undefined;
+      },
+      speakerContext: this.speakerContext,
+    });
+    if (!turn) {
+      logVoiceVerbose(
+        `realtime agent unauthorized: guild ${entry.guildId} channel ${entry.channelId} user ${userId}`,
+      );
+      return "";
+    }
+    logger.info(
+      `discord voice: agent turn answer (${turn.text.length} chars) guild=${entry.guildId} channel=${entry.channelId} voiceSession=${entry.voiceSessionKey} supervisorSession=${entry.route.sessionKey} agent=${entry.route.agentId}: ${formatVoiceLogPreview(turn.text)}`,
+    );
+    return turn.text;
+  }
+
+  private async processSegment(params: {
+    entry: VoiceSessionEntry;
+    wavPath: string;
+    userId: string;
+    durationSeconds: number;
+  }) {
+    await processDiscordVoiceSegment({
+      ...params,
+      cfg: this.params.cfg,
+      discordConfig: this.params.discordConfig,
+      ownerAllowFrom: this.ownerAllowFrom,
+      runtime: this.params.runtime,
+      speakerContext: this.speakerContext,
+      fetchGuildName: async (guildId) => {
+        const guild = await this.params.client.fetchGuild(guildId).catch(() => null);
+        return guild && typeof guild.name === "string" && guild.name.trim()
+          ? guild.name
+          : undefined;
+      },
+      enqueuePlayback: (entry, task) => {
+        this.enqueuePlayback(entry, task);
+      },
+    });
+  }
+
+  private handleReceiveError(entry: VoiceSessionEntry, err: unknown) {
+    const analysis = analyzeVoiceReceiveError(err);
+    if (analysis.isAbortLike && !analysis.countsAsDecryptFailure) {
+      logVoiceVerbose(`receive stream ended: ${analysis.message}`);
+      return;
+    }
+    logger.warn(`discord voice: receive error: ${analysis.message}`);
+    if (analysis.shouldAttemptPassthrough) {
+      this.enableDaveReceivePassthrough(
+        entry,
+        "receive decrypt error",
+        DAVE_RECEIVE_PASSTHROUGH_REARM_EXPIRY_SECONDS,
+      );
+    }
+    if (!analysis.countsAsDecryptFailure) {
+      return;
+    }
+    const decryptFailure = noteVoiceDecryptFailure(entry.receiveRecovery);
+    if (decryptFailure.firstFailure) {
+      logger.warn(
+        "discord voice: DAVE decrypt failures detected; voice receive may be unstable (upstream: discordjs/discord.js#11419)",
+      );
+    }
+    if (!decryptFailure.shouldRecover) {
+      return;
+    }
+    void this.recoverFromDecryptFailures(entry)
+      .catch((recoverErr) =>
+        logger.warn(`discord voice: decrypt recovery failed: ${formatErrorMessage(recoverErr)}`),
+      )
+      .finally(() => {
+        finishVoiceDecryptRecovery(entry.receiveRecovery);
+      });
+  }
+
+  private enableDaveReceivePassthrough(
+    entry: Pick<VoiceSessionEntry, "guildId" | "channelId" | "connection">,
+    reason: string,
+    expirySeconds: number,
+  ): boolean {
+    const voiceSdk = loadDiscordVoiceSdk();
+    return tryEnableDaveReceivePassthrough({
+      target: {
+        guildId: entry.guildId,
+        channelId: entry.channelId,
+        connection: entry.connection as {
+          state: {
+            status: unknown;
+            networking?: {
+              state?: {
+                code?: unknown;
+                dave?: {
+                  session?: {
+                    setPassthroughMode: (passthrough: boolean, expirySeconds: number) => void;
+                  };
+                };
+              };
+            };
+          };
+        },
+      },
+      sdk: {
+        VoiceConnectionStatus: {
+          Ready: voiceSdk.VoiceConnectionStatus.Ready,
+        },
+        NetworkingStatusCode: {
+          Ready: voiceSdk.NetworkingStatusCode.Ready,
+          Resuming: voiceSdk.NetworkingStatusCode.Resuming,
+        },
+      },
+      reason,
+      expirySeconds,
+      onVerbose: logVoiceVerbose,
+      onWarn: (message) => logger.warn(message),
+    });
+  }
+
+  private resetDecryptFailureState(entry: VoiceSessionEntry) {
+    resetVoiceReceiveRecoveryState(entry.receiveRecovery);
+  }
+
+  private async recoverFromDecryptFailures(entry: VoiceSessionEntry) {
+    const active = this.sessions.get(entry.guildId);
+    if (!active || active.connection !== entry.connection) {
+      return;
+    }
+    logger.warn(
+      `discord voice: repeated decrypt failures; attempting rejoin for guild ${entry.guildId} channel ${entry.channelId}`,
+    );
+    const leaveResult = await this.leave({ guildId: entry.guildId });
+    if (!leaveResult.ok) {
+      logger.warn(`discord voice: decrypt recovery leave failed: ${leaveResult.message}`);
+      return;
+    }
+    const result = await this.join({ guildId: entry.guildId, channelId: entry.channelId });
+    if (!result.ok) {
+      logger.warn(`discord voice: rejoin after decrypt failures failed: ${result.message}`);
+    }
+  }
+}
+
+export class DiscordVoiceReadyListener extends ReadyListener {
+  constructor(private manager: DiscordVoiceManager) {
+    super();
+  }
+
+  async handle(_data: unknown, _client: Client): Promise<void> {
+    startAutoJoin(this.manager);
+  }
+}
+
+export class DiscordVoiceResumedListener extends ResumedListener {
+  constructor(private manager: DiscordVoiceManager) {
+    super();
+  }
+
+  async handle(_data: unknown, _client: Client): Promise<void> {
+    startAutoJoin(this.manager);
+  }
+}
+
+export class DiscordVoiceStateUpdateListener extends VoiceStateUpdateListener {
+  constructor(private manager: DiscordVoiceManager) {
+    super();
+  }
+
+  async handle(data: APIVoiceState, _client: Client): Promise<void> {
+    await this.manager.handleVoiceStateUpdate(data);
+  }
+}