@openclaw/discord 2026.3.13 → 2026.5.2-beta.1

package/src/voice/capture-state.ts

@@ -0,0 +1,120 @@
+import type { Readable } from "node:stream";
+
+type VoiceCaptureEntry = {
+  generation: number;
+  stream: Readable;
+};
+
+type VoiceCaptureFinalizeTimer = {
+  generation: number;
+  timer: ReturnType<typeof setTimeout>;
+};
+
+export type VoiceCaptureState = {
+  activeSpeakers: Set<string>;
+  activeCaptureStreams: Map<string, VoiceCaptureEntry>;
+  captureFinalizeTimers: Map<string, VoiceCaptureFinalizeTimer>;
+  captureGenerations: Map<string, number>;
+};
+
+export function createVoiceCaptureState(): VoiceCaptureState {
+  return {
+    activeSpeakers: new Set(),
+    activeCaptureStreams: new Map(),
+    captureFinalizeTimers: new Map(),
+    captureGenerations: new Map(),
+  };
+}
+
+export function stopVoiceCaptureState(state: VoiceCaptureState): void {
+  for (const { timer } of state.captureFinalizeTimers.values()) {
+    clearTimeout(timer);
+  }
+  state.captureFinalizeTimers.clear();
+  for (const { stream } of state.activeCaptureStreams.values()) {
+    stream.destroy();
+  }
+  state.activeCaptureStreams.clear();
+  state.captureGenerations.clear();
+  state.activeSpeakers.clear();
+}
+
+export function getActiveVoiceCapture(
+  state: VoiceCaptureState,
+  userId: string,
+): VoiceCaptureEntry | undefined {
+  return state.activeCaptureStreams.get(userId);
+}
+
+export function isVoiceCaptureActive(state: VoiceCaptureState, userId: string): boolean {
+  return state.activeSpeakers.has(userId);
+}
+
+export function clearVoiceCaptureFinalizeTimer(
+  state: VoiceCaptureState,
+  userId: string,
+  generation?: number,
+): boolean {
+  const scheduled = state.captureFinalizeTimers.get(userId);
+  if (!scheduled || (generation !== undefined && scheduled.generation !== generation)) {
+    return false;
+  }
+  clearTimeout(scheduled.timer);
+  state.captureFinalizeTimers.delete(userId);
+  return true;
+}
+
+export function beginVoiceCapture(
+  state: VoiceCaptureState,
+  userId: string,
+  stream: Readable,
+): number {
+  const generation = (state.captureGenerations.get(userId) ?? 0) + 1;
+  state.captureGenerations.set(userId, generation);
+  state.activeSpeakers.add(userId);
+  state.activeCaptureStreams.set(userId, { generation, stream });
+  clearVoiceCaptureFinalizeTimer(state, userId, generation);
+  return generation;
+}
+
+export function finishVoiceCapture(
+  state: VoiceCaptureState,
+  userId: string,
+  generation: number,
+): boolean {
+  clearVoiceCaptureFinalizeTimer(state, userId, generation);
+  const activeCapture = state.activeCaptureStreams.get(userId);
+  if (activeCapture?.generation !== generation) {
+    return false;
+  }
+  state.activeCaptureStreams.delete(userId);
+  state.activeSpeakers.delete(userId);
+  return true;
+}
+
+export function scheduleVoiceCaptureFinalize(params: {
+  state: VoiceCaptureState;
+  userId: string;
+  delayMs: number;
+  onFinalize?: (capture: VoiceCaptureEntry) => void;
+}): boolean {
+  const { state, userId, delayMs, onFinalize } = params;
+  const capture = state.activeCaptureStreams.get(userId);
+  if (!capture) {
+    return false;
+  }
+  clearVoiceCaptureFinalizeTimer(state, userId, capture.generation);
+  const timer = setTimeout(() => {
+    const activeCapture = state.activeCaptureStreams.get(userId);
+    if (!activeCapture || activeCapture.generation !== capture.generation) {
+      return;
+    }
+    state.captureFinalizeTimers.delete(userId);
+    state.activeCaptureStreams.delete(userId);
+    state.activeSpeakers.delete(userId);
+    onFinalize?.(activeCapture);
+    activeCapture.stream.destroy();
+  }, delayMs);
+  state.captureFinalizeTimers.set(userId, { generation: capture.generation, timer });
+  return true;
+}

package/src/voice/command.test.ts

@@ -0,0 +1,164 @@
+import { describe, expect, it, vi } from "vitest";
+import type { CommandInteraction, CommandWithSubcommands } from "../internal/discord.js";
+import { createPartialDiscordChannelWithThrowingGetters } from "../test-support/partial-channel.js";
+import { createDiscordVoiceCommand } from "./command.js";
+import type { DiscordVoiceManager } from "./manager.js";
+
+function findVoiceSubcommand(command: CommandWithSubcommands, name: string) {
+  const subcommands = (
+    command as unknown as { subcommands?: Array<{ name: string; run: unknown }> }
+  ).subcommands;
+  const subcommand = subcommands?.find((entry) => entry.name === name) as
+    | { run: (interaction: CommandInteraction) => Promise<void> }
+    | undefined;
+  if (!subcommand) {
+    throw new Error(`Missing vc ${name} subcommand`);
+  }
+  return subcommand;
+}
+
+function createVoiceCommandHarness(manager: DiscordVoiceManager | null = null) {
+  const command = createDiscordVoiceCommand({
+    cfg: {},
+    discordConfig: {},
+    accountId: "default",
+    groupPolicy: "open",
+    useAccessGroups: false,
+    getManager: () => manager,
+    ephemeralDefault: true,
+  });
+  return {
+    command,
+    leave: findVoiceSubcommand(command, "leave"),
+    status: findVoiceSubcommand(command, "status"),
+  };
+}
+
+function createInteraction(overrides?: Partial<CommandInteraction>): {
+  interaction: CommandInteraction;
+  reply: ReturnType<typeof vi.fn>;
+  defer: ReturnType<typeof vi.fn>;
+} {
+  const reply = vi.fn(async () => undefined);
+  const defer = vi.fn(async () => undefined);
+  const interaction = {
+    guild: undefined,
+    user: { id: "u1", username: "tester" },
+    rawData: { member: { roles: [] } },
+    defer,
+    reply,
+    ...overrides,
+  } as unknown as CommandInteraction;
+  return { interaction, reply, defer };
+}
+
+describe("createDiscordVoiceCommand", () => {
+  it("serializes subcommands without top-level command-only fields", () => {
+    const { command } = createVoiceCommandHarness(null);
+    const serialized = command.serialize();
+    const firstOption = serialized.options?.[0] as Record<string, unknown> | undefined;
+
+    expect(firstOption).toMatchObject({
+      name: "join",
+      type: 1,
+      description: expect.any(String),
+    });
+    expect(firstOption).not.toHaveProperty("contexts");
+    expect(firstOption).not.toHaveProperty("integration_types");
+    expect(firstOption).not.toHaveProperty("default_member_permissions");
+  });
+
+  it("dispatches slash-command subcommand interactions", async () => {
+    const { command } = createVoiceCommandHarness(null);
+    const { interaction, reply, defer } = createInteraction({
+      guild: { id: "g1", name: "Guild" } as CommandInteraction["guild"],
+      rawData: {
+        data: {
+          options: [{ name: "status", type: 1 }],
+        },
+        member: { roles: [] },
+      } as unknown as CommandInteraction["rawData"],
+    });
+
+    await command.run(interaction);
+
+    expect(defer).toHaveBeenCalledWith({ ephemeral: true });
+    expect(reply).toHaveBeenCalledWith({
+      content: "Voice manager is not available yet.",
+      ephemeral: true,
+    });
+  });
+
+  it("vc leave reports missing guild before manager lookup", async () => {
+    const { leave } = createVoiceCommandHarness(null);
+    const { interaction, reply } = createInteraction();
+
+    await leave.run(interaction);
+
+    expect(reply).toHaveBeenCalledTimes(1);
+    expect(reply).toHaveBeenCalledWith({
+      content: "Unable to resolve guild for this command.",
+      ephemeral: true,
+    });
+  });
+
+  it("vc status reports unavailable voice manager", async () => {
+    const { status } = createVoiceCommandHarness(null);
+    const { interaction, reply } = createInteraction({
+      guild: { id: "g1" } as CommandInteraction["guild"],
+    });
+
+    await status.run(interaction);
+
+    expect(reply).toHaveBeenCalledTimes(1);
+    expect(reply).toHaveBeenCalledWith({
+      content: "Voice manager is not available yet.",
+      ephemeral: true,
+    });
+  });
+
+  it("vc status reports no active sessions when manager has none", async () => {
+    const statusSpy = vi.fn(() => []);
+    const manager = {
+      status: statusSpy,
+    } as unknown as DiscordVoiceManager;
+    const { status } = createVoiceCommandHarness(manager);
+    const { interaction, reply } = createInteraction({
+      guild: { id: "g1", name: "Guild" } as CommandInteraction["guild"],
+    });
+
+    await status.run(interaction);
+
+    expect(statusSpy).toHaveBeenCalledTimes(1);
+    expect(reply).toHaveBeenCalledTimes(1);
+    expect(reply).toHaveBeenCalledWith({
+      content: "No active voice sessions.",
+      ephemeral: true,
+    });
+  });
+
+  it("vc status tolerates partial thread channels with throwing getters", async () => {
+    const statusSpy = vi.fn(() => []);
+    const manager = {
+      status: statusSpy,
+    } as unknown as DiscordVoiceManager;
+    const { status } = createVoiceCommandHarness(manager);
+    const partialChannel = createPartialDiscordChannelWithThrowingGetters(
+      { id: "123456789012345678" },
+      ["name", "parentId"],
+    );
+    const { interaction, reply } = createInteraction({
+      channel: partialChannel as CommandInteraction["channel"],
+      client: { fetchChannel: vi.fn(async () => null) } as unknown as CommandInteraction["client"],
+      guild: { id: "g1", name: "Guild" } as CommandInteraction["guild"],
+    });
+
+    await expect(status.run(interaction)).resolves.toBeUndefined();
+
+    expect(statusSpy).toHaveBeenCalledTimes(1);
+    expect(reply).toHaveBeenCalledWith({
+      content: "No active voice sessions.",
+      ephemeral: true,
+    });
+  });
+});

package/src/voice/command.ts

@@ -0,0 +1,283 @@
+import {
+  ApplicationCommandOptionType,
+  ChannelType as DiscordChannelType,
+  type APIApplicationCommandChannelOption,
+} from "discord-api-types/v10";
+import type { OpenClawConfig } from "openclaw/plugin-sdk/config-types";
+import type { DiscordAccountConfig } from "openclaw/plugin-sdk/config-types";
+import { resolveDiscordAccountAllowFrom } from "../accounts.js";
+import {
+  Command,
+  CommandWithSubcommands,
+  type CommandInteraction,
+  type CommandOptions,
+} from "../internal/discord.js";
+import { formatMention } from "../mentions.js";
+import { resolveDiscordChannelNameSafe } from "../monitor/channel-access.js";
+import { resolveDiscordSenderIdentity } from "../monitor/sender-identity.js";
+import { resolveDiscordThreadLikeChannelContext } from "../monitor/thread-channel-context.js";
+import { authorizeDiscordVoiceIngress } from "./access.js";
+import type { DiscordVoiceManager } from "./manager.js";
+
+const VOICE_CHANNEL_TYPES: NonNullable<APIApplicationCommandChannelOption["channel_types"]> = [
+  DiscordChannelType.GuildVoice,
+  DiscordChannelType.GuildStageVoice,
+];
+
+type VoiceCommandContext = {
+  cfg: OpenClawConfig;
+  discordConfig: DiscordAccountConfig;
+  accountId: string;
+  groupPolicy: "open" | "disabled" | "allowlist";
+  useAccessGroups: boolean;
+  getManager: () => DiscordVoiceManager | null;
+  ephemeralDefault: boolean;
+};
+
+type VoiceCommandChannelOverride = {
+  id: string;
+  name?: string;
+  parentId?: string;
+};
+
+type VoiceCommandRuntimeContext = {
+  guildId: string;
+  manager: DiscordVoiceManager;
+};
+
+async function authorizeVoiceCommand(
+  interaction: CommandInteraction,
+  params: VoiceCommandContext,
+  options?: { channelOverride?: VoiceCommandChannelOverride },
+): Promise<{ ok: boolean; message?: string; guildId?: string }> {
+  const channelOverride = options?.channelOverride;
+  const channel = channelOverride ? undefined : interaction.channel;
+  if (!interaction.guild) {
+    return { ok: false, message: "Voice commands are only available in guilds." };
+  }
+  const user = interaction.user;
+  if (!user) {
+    return { ok: false, message: "Unable to resolve command user." };
+  }
+
+  const channelId = channelOverride?.id ?? channel?.id ?? "";
+  const channelContext = await resolveDiscordThreadLikeChannelContext({
+    client: interaction.client,
+    channel: channelOverride ?? channel,
+    channelIdFallback: channelId,
+  });
+  const channelName = channelOverride?.name ?? channelContext.channelName;
+
+  const memberRoleIds = Array.isArray(interaction.rawData.member?.roles)
+    ? interaction.rawData.member.roles.map((roleId: string) => roleId)
+    : [];
+  const sender = resolveDiscordSenderIdentity({ author: user, member: interaction.rawData.member });
+  const access = await authorizeDiscordVoiceIngress({
+    cfg: params.cfg,
+    discordConfig: params.discordConfig,
+    groupPolicy: params.groupPolicy,
+    useAccessGroups: params.useAccessGroups,
+    guild: interaction.guild,
+    guildId: interaction.guild.id,
+    channelId,
+    channelName,
+    channelSlug: channelContext.channelSlug,
+    parentId: channelOverride?.parentId ?? channelContext.threadParentId,
+    parentName: channelContext.threadParentName,
+    parentSlug: channelContext.threadParentSlug,
+    scope: channelContext.isThreadChannel ? "thread" : "channel",
+    channelLabel: channelId ? formatMention({ channelId }) : "This channel",
+    memberRoleIds,
+    ownerAllowFrom: resolveDiscordAccountAllowFrom({
+      cfg: params.cfg,
+      accountId: params.accountId,
+    }),
+    sender: {
+      id: sender.id,
+      name: sender.name,
+      tag: sender.tag,
+    },
+  });
+  if (!access.ok) {
+    return { ok: false, message: access.message };
+  }
+
+  return { ok: true, guildId: interaction.guild.id };
+}
+
+async function resolveVoiceCommandRuntimeContext(
+  interaction: CommandInteraction,
+  params: Pick<VoiceCommandContext, "getManager">,
+): Promise<VoiceCommandRuntimeContext | null> {
+  const guildId = interaction.guild?.id;
+  if (!guildId) {
+    await interaction.reply({
+      content: "Unable to resolve guild for this command.",
+      ephemeral: true,
+    });
+    return null;
+  }
+  const manager = params.getManager();
+  if (!manager) {
+    await interaction.reply({
+      content: "Voice manager is not available yet.",
+      ephemeral: true,
+    });
+    return null;
+  }
+  return { guildId, manager };
+}
+
+async function ensureVoiceCommandAccess(params: {
+  interaction: CommandInteraction;
+  context: VoiceCommandContext;
+  channelOverride?: VoiceCommandChannelOverride;
+}): Promise<boolean> {
+  const access = await authorizeVoiceCommand(params.interaction, params.context, {
+    channelOverride: params.channelOverride,
+  });
+  if (access.ok) {
+    return true;
+  }
+  await params.interaction.reply({
+    content: access.message ?? "Not authorized.",
+    ephemeral: true,
+  });
+  return false;
+}
+
+export function createDiscordVoiceCommand(params: VoiceCommandContext): CommandWithSubcommands {
+  const resolveSessionChannelId = (manager: DiscordVoiceManager, guildId: string) =>
+    manager.status().find((entry) => entry.guildId === guildId)?.channelId;
+
+  class JoinCommand extends Command {
+    name = "join";
+    description = "Join a voice channel";
+    defer = true;
+    ephemeral = params.ephemeralDefault;
+    options: CommandOptions = [
+      {
+        name: "channel",
+        description: "Voice channel to join",
+        type: ApplicationCommandOptionType.Channel,
+        required: true,
+        channel_types: VOICE_CHANNEL_TYPES,
+      },
+    ];
+
+    async run(interaction: CommandInteraction) {
+      const channel = await interaction.options.getChannel("channel", true);
+      if (!channel || !("id" in channel)) {
+        await interaction.reply({ content: "Voice channel not found.", ephemeral: true });
+        return;
+      }
+
+      const access = await authorizeVoiceCommand(interaction, params, {
+        channelOverride: {
+          id: channel.id,
+          name: resolveDiscordChannelNameSafe(channel),
+        },
+      });
+      if (!access.ok) {
+        await interaction.reply({ content: access.message ?? "Not authorized.", ephemeral: true });
+        return;
+      }
+      if (!isVoiceChannelType(channel.type)) {
+        await interaction.reply({ content: "That is not a voice channel.", ephemeral: true });
+        return;
+      }
+      const guildId = access.guildId ?? ("guildId" in channel ? channel.guildId : undefined);
+      if (!guildId) {
+        await interaction.reply({
+          content: "Unable to resolve guild for this voice channel.",
+          ephemeral: true,
+        });
+        return;
+      }
+
+      const manager = params.getManager();
+      if (!manager) {
+        await interaction.reply({
+          content: "Voice manager is not available yet.",
+          ephemeral: true,
+        });
+        return;
+      }
+
+      const result = await manager.join({ guildId, channelId: channel.id });
+      await interaction.reply({ content: result.message, ephemeral: true });
+    }
+  }
+
+  class LeaveCommand extends Command {
+    name = "leave";
+    description = "Leave the current voice channel";
+    defer = true;
+    ephemeral = params.ephemeralDefault;
+
+    async run(interaction: CommandInteraction) {
+      const runtimeContext = await resolveVoiceCommandRuntimeContext(interaction, params);
+      if (!runtimeContext) {
+        return;
+      }
+      const sessionChannelId = resolveSessionChannelId(
+        runtimeContext.manager,
+        runtimeContext.guildId,
+      );
+      const authorized = await ensureVoiceCommandAccess({
+        interaction,
+        context: params,
+        channelOverride: sessionChannelId ? { id: sessionChannelId } : undefined,
+      });
+      if (!authorized) {
+        return;
+      }
+      const result = await runtimeContext.manager.leave({ guildId: runtimeContext.guildId });
+      await interaction.reply({ content: result.message, ephemeral: true });
+    }
+  }
+
+  class StatusCommand extends Command {
+    name = "status";
+    description = "Show active voice sessions";
+    defer = true;
+    ephemeral = params.ephemeralDefault;
+
+    async run(interaction: CommandInteraction) {
+      const runtimeContext = await resolveVoiceCommandRuntimeContext(interaction, params);
+      if (!runtimeContext) {
+        return;
+      }
+      const sessions = runtimeContext.manager
+        .status()
+        .filter((entry) => entry.guildId === runtimeContext.guildId);
+      const sessionChannelId = sessions[0]?.channelId;
+      const authorized = await ensureVoiceCommandAccess({
+        interaction,
+        context: params,
+        channelOverride: sessionChannelId ? { id: sessionChannelId } : undefined,
+      });
+      if (!authorized) {
+        return;
+      }
+      if (sessions.length === 0) {
+        await interaction.reply({ content: "No active voice sessions.", ephemeral: true });
+        return;
+      }
+      const lines = sessions.map(
+        (entry) => `• ${formatMention({ channelId: entry.channelId })} (guild ${entry.guildId})`,
+      );
+      await interaction.reply({ content: lines.join("\n"), ephemeral: true });
+    }
+  }
+
+  return new (class extends CommandWithSubcommands {
+    name = "vc";
+    description = "Voice channel controls";
+    subcommands = [new JoinCommand(), new LeaveCommand(), new StatusCommand()];
+  })();
+}
+
+function isVoiceChannelType(type: DiscordChannelType) {
+  return type === DiscordChannelType.GuildVoice || type === DiscordChannelType.GuildStageVoice;
+}

package/src/voice/config.ts

@@ -0,0 +1,8 @@
+import type { DiscordAccountConfig } from "openclaw/plugin-sdk/config-types";
+
+export function resolveDiscordVoiceEnabled(voice: DiscordAccountConfig["voice"]): boolean {
+  if (voice?.enabled !== undefined) {
+    return voice.enabled;
+  }
+  return voice !== undefined;
+}