@openclaw/discord 2026.3.13 → 2026.5.1-beta.1

package/src/voice/manager.ts

@@ -0,0 +1,691 @@
+import type { OpenClawConfig } from "openclaw/plugin-sdk/config-types";
+import type { DiscordAccountConfig } from "openclaw/plugin-sdk/config-types";
+import { resolveAgentRoute } from "openclaw/plugin-sdk/routing";
+import { createSubsystemLogger } from "openclaw/plugin-sdk/runtime-env";
+import type { RuntimeEnv } from "openclaw/plugin-sdk/runtime-env";
+import { formatErrorMessage } from "openclaw/plugin-sdk/ssrf-runtime";
+import { resolveDiscordAccountAllowFrom } from "../accounts.js";
+import { type Client, ReadyListener, ResumedListener } from "../internal/discord.js";
+import type { VoicePlugin } from "../internal/voice.js";
+import { formatMention } from "../mentions.js";
+import { decodeOpusStream, writeVoiceWavFile } from "./audio.js";
+import {
+  beginVoiceCapture,
+  clearVoiceCaptureFinalizeTimer,
+  createVoiceCaptureState,
+  finishVoiceCapture,
+  getActiveVoiceCapture,
+  isVoiceCaptureActive,
+  scheduleVoiceCaptureFinalize,
+  stopVoiceCaptureState,
+} from "./capture-state.js";
+import { resolveDiscordVoiceEnabled } from "./config.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");
+
+type DiscordVoiceSdk = ReturnType<typeof loadDiscordVoiceSdk>;
+type DiscordVoiceConnection = ReturnType<DiscordVoiceSdk["joinVoiceChannel"]>;
+
+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 startAutoJoin(manager: Pick<DiscordVoiceManager, "autoJoin">) {
+  void manager
+    .autoJoin()
+    .catch((err) => logger.warn(`discord voice: autoJoin failed: ${formatErrorMessage(err)}`));
+}
+
+export class DiscordVoiceManager {
+  private sessions = new Map<string, VoiceSessionEntry>();
+  private botUserId?: string;
+  private readonly voiceEnabled: boolean;
+  private autoJoinTask: Promise<void> | null = null;
+  private readonly ownerAllowFrom?: string[];
+  private readonly speakerContext: DiscordVoiceSpeakerContextResolver;
+
+  constructor(
+    private params: {
+      client: Client;
+      cfg: OpenClawConfig;
+      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.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 ?? [];
+      logVoiceVerbose(`autoJoin: ${entries.length} entries`);
+      const seenGuilds = new Set<string>();
+      for (const entry of entries) {
+        const guildId = entry.guildId.trim();
+        if (!guildId) {
+          continue;
+        }
+        if (seenGuilds.has(guildId)) {
+          logger.warn(
+            `discord voice: autoJoin has multiple entries for guild ${guildId}; skipping`,
+          );
+          continue;
+        }
+        seenGuilds.add(guildId);
+        logVoiceVerbose(`autoJoin: joining guild ${guildId} channel ${entry.channelId}`);
+        await this.join({
+          guildId: entry.guildId,
+          channelId: entry.channelId,
+        });
+      }
+    })().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,
+    }));
+  }
+
+  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." };
+    }
+    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 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}`,
+      );
+    }
+    const route = resolveAgentRoute({
+      cfg: this.params.cfg,
+      channel: "discord",
+      accountId: this.params.accountId,
+      guildId,
+      peer: { kind: "channel", id: sessionChannelId },
+    });
+
+    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;
+    const clearSessionIfCurrent = () => {
+      const active = this.sessions.get(guildId);
+      if (active?.connection === connection) {
+        this.sessions.delete(guildId);
+      }
+    };
+
+    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,
+      route,
+      connection,
+      player,
+      playbackQueue: Promise.resolve(),
+      processingQueue: Promise.resolve(),
+      capture: createVoiceCaptureState(),
+      receiveRecovery: createVoiceReceiveRecoveryState(),
+      stop: () => {
+        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);
+        }
+        player.stop();
+        destroyVoiceConnectionSafely({
+          connection,
+          voiceSdk,
+          reason: `stop guild ${guildId} channel ${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();
+        destroyVoiceConnectionSafely({
+          connection,
+          voiceSdk,
+          reason: `disconnect recovery failed guild ${guildId} channel ${channelId}`,
+        });
+      }
+    };
+    destroyedHandler = () => {
+      clearSessionIfCurrent();
+    };
+    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);
+    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 destroy(): Promise<void> {
+    for (const entry of this.sessions.values()) {
+      entry.stop();
+    }
+    this.sessions.clear();
+  }
+
+  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) {
+    scheduleVoiceCaptureFinalize({
+      state: entry.capture,
+      userId,
+      delayMs: CAPTURE_FINALIZE_GRACE_MS,
+      onFinalize: () => {
+        logVoiceVerbose(
+          `capture finalize: guild ${entry.guildId} channel ${entry.channelId} user ${userId} reason=${reason} grace=${CAPTURE_FINALIZE_GRACE_MS}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();
+    this.enableDaveReceivePassthrough(
+      entry,
+      `speaker ${userId} start`,
+      DAVE_RECEIVE_PASSTHROUGH_REARM_EXPIRY_SECONDS,
+    );
+    if (entry.player.state.status === voiceSdk.AudioPlayerStatus.Playing) {
+      entry.player.stop(true);
+    }
+
+    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 {
+      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 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);
+    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);
+  }
+}

package/src/voice/prompt.test.ts

@@ -0,0 +1,16 @@
+import { describe, expect, it } from "vitest";
+import { DISCORD_VOICE_SPOKEN_OUTPUT_CONTRACT, formatVoiceIngressPrompt } from "./prompt.js";
+
+describe("formatVoiceIngressPrompt", () => {
+  it("formats speaker-labeled voice input with the spoken-output contract", () => {
+    expect(formatVoiceIngressPrompt("hello there", "speaker-1")).toBe(
+      `${DISCORD_VOICE_SPOKEN_OUTPUT_CONTRACT}\n\nVoice transcript from speaker "speaker-1":\nhello there`,
+    );
+  });
+
+  it("keeps unlabeled transcripts under the spoken-output contract", () => {
+    expect(formatVoiceIngressPrompt("hello there")).toBe(
+      `${DISCORD_VOICE_SPOKEN_OUTPUT_CONTRACT}\n\nhello there`,
+    );
+  });
+});