@kodelyth/discord 2026.5.39 → 2026.5.42

package/src/voice/command.test.ts

@@ -0,0 +1,170 @@
+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).toEqual({
+      name: "join",
+      type: 1,
+      description: "Join a voice channel",
+      options: [
+        {
+          name: "channel",
+          description: "Voice channel to join",
+          type: 7,
+          required: true,
+          channel_types: [2, 13],
+        },
+      ],
+    });
+  });
+
+  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,284 @@
+import {
+  ApplicationCommandOptionType,
+  ChannelType as DiscordChannelType,
+  type APIApplicationCommandChannelOption,
+} from "discord-api-types/v10";
+import type { KlawConfig } from "klaw/plugin-sdk/config-contracts";
+import type { DiscordAccountConfig } from "klaw/plugin-sdk/config-contracts";
+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: KlawConfig;
+  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,
+    accountId: params.accountId,
+    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 {
+    override name = "join";
+    override description = "Join a voice channel";
+    override defer = true;
+    override ephemeral = params.ephemeralDefault;
+    override 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 {
+    override name = "leave";
+    override description = "Leave the current voice channel";
+    override defer = true;
+    override 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 {
+    override name = "status";
+    override description = "Show active voice sessions";
+    override defer = true;
+    override 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 {
+    override name = "vc";
+    override 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 "klaw/plugin-sdk/config-contracts";
+
+export function resolveDiscordVoiceEnabled(voice: DiscordAccountConfig["voice"]): boolean {
+  if (voice?.enabled !== undefined) {
+    return voice.enabled;
+  }
+  return voice !== undefined;
+}

package/src/voice/ingress.ts

@@ -0,0 +1,164 @@
+import { agentCommandFromIngress } from "klaw/plugin-sdk/agent-runtime";
+import type { DiscordAccountConfig, KlawConfig } from "klaw/plugin-sdk/config-contracts";
+import { createSubsystemLogger, type RuntimeEnv } from "klaw/plugin-sdk/runtime-env";
+import { normalizeOptionalString } from "klaw/plugin-sdk/string-coerce-runtime";
+import { formatMention } from "../mentions.js";
+import { normalizeDiscordSlug } from "../monitor/allow-list.js";
+import { buildDiscordGroupSystemPrompt } from "../monitor/inbound-context.js";
+import { authorizeDiscordVoiceIngress } from "./access.js";
+import type { VoiceSessionEntry } from "./session.js";
+import type { DiscordVoiceSpeakerContextResolver } from "./speaker-context.js";
+
+export const DISCORD_VOICE_MESSAGE_PROVIDER = "discord-voice";
+
+const logger = createSubsystemLogger("discord/voice");
+
+export type DiscordVoiceIngressContext = {
+  extraSystemPrompt?: string;
+  senderIsOwner: boolean;
+  speakerLabel: string;
+};
+
+export type DiscordVoiceAgentTurnResult = {
+  context: DiscordVoiceIngressContext;
+  text: string;
+};
+
+function summarizeAgentTurnPayloads(payloads: readonly unknown[]): string {
+  let textPayloads = 0;
+  let nonEmptyTextPayloads = 0;
+  let reasoningPayloads = 0;
+  let errorPayloads = 0;
+  let mediaPayloads = 0;
+
+  for (const payload of payloads) {
+    if (!payload || typeof payload !== "object") {
+      continue;
+    }
+    const record = payload as Record<string, unknown>;
+    const text = record.text;
+    if (typeof text === "string") {
+      textPayloads += 1;
+      if (text.trim()) {
+        nonEmptyTextPayloads += 1;
+      }
+    }
+    if (record.isReasoning === true) {
+      reasoningPayloads += 1;
+    }
+    if (record.isError === true) {
+      errorPayloads += 1;
+    }
+    if (
+      typeof record.mediaUrl === "string" ||
+      (Array.isArray(record.mediaUrls) && record.mediaUrls.length > 0)
+    ) {
+      mediaPayloads += 1;
+    }
+  }
+
+  return `payloadCount=${payloads.length} textPayloads=${textPayloads} nonEmptyTextPayloads=${nonEmptyTextPayloads} reasoningPayloads=${reasoningPayloads} errorPayloads=${errorPayloads} mediaPayloads=${mediaPayloads}`;
+}
+
+export async function resolveDiscordVoiceIngressContext(params: {
+  entry: VoiceSessionEntry;
+  userId: string;
+  cfg: KlawConfig;
+  discordConfig: DiscordAccountConfig;
+  ownerAllowFrom?: string[];
+  fetchGuildName: (guildId: string) => Promise<string | undefined>;
+  speakerContext: DiscordVoiceSpeakerContextResolver;
+}): Promise<DiscordVoiceIngressContext | null> {
+  const { entry, userId } = params;
+  if (!entry.guildName) {
+    entry.guildName = await params.fetchGuildName(entry.guildId);
+  }
+  const speaker = await params.speakerContext.resolveContext(entry.guildId, userId);
+  const speakerIdentity = await params.speakerContext.resolveIdentity(entry.guildId, userId);
+  const access = await authorizeDiscordVoiceIngress({
+    cfg: params.cfg,
+    discordConfig: params.discordConfig,
+    guildName: entry.guildName,
+    guildId: entry.guildId,
+    channelId: entry.channelId,
+    channelName: entry.channelName,
+    channelSlug: entry.channelName ? normalizeDiscordSlug(entry.channelName) : "",
+    channelLabel: formatMention({ channelId: entry.channelId }),
+    memberRoleIds: speakerIdentity.memberRoleIds,
+    ownerAllowFrom: params.ownerAllowFrom,
+    sender: {
+      id: speakerIdentity.id,
+      name: speakerIdentity.name,
+      tag: speakerIdentity.tag,
+    },
+  });
+  if (!access.ok) {
+    return null;
+  }
+  return {
+    extraSystemPrompt: buildDiscordGroupSystemPrompt(access.channelConfig),
+    senderIsOwner: speaker.senderIsOwner,
+    speakerLabel: speaker.label,
+  };
+}
+
+export async function runDiscordVoiceAgentTurn(params: {
+  entry: VoiceSessionEntry;
+  userId: string;
+  message: string;
+  cfg: KlawConfig;
+  discordConfig: DiscordAccountConfig;
+  runtime: RuntimeEnv;
+  context?: DiscordVoiceIngressContext;
+  toolsAllow?: string[];
+  ownerAllowFrom?: string[];
+  fetchGuildName: (guildId: string) => Promise<string | undefined>;
+  speakerContext: DiscordVoiceSpeakerContextResolver;
+}): Promise<DiscordVoiceAgentTurnResult | null> {
+  const context =
+    params.context ??
+    (await resolveDiscordVoiceIngressContext({
+      entry: params.entry,
+      userId: params.userId,
+      cfg: params.cfg,
+      discordConfig: params.discordConfig,
+      ownerAllowFrom: params.ownerAllowFrom,
+      fetchGuildName: params.fetchGuildName,
+      speakerContext: params.speakerContext,
+    }));
+  if (!context) {
+    return null;
+  }
+  const voiceModel = normalizeOptionalString(params.discordConfig.voice?.model);
+  const result = await agentCommandFromIngress(
+    {
+      message: params.message,
+      sessionKey: params.entry.route.sessionKey,
+      agentId: params.entry.route.agentId,
+      messageChannel: "discord",
+      messageProvider: DISCORD_VOICE_MESSAGE_PROVIDER,
+      extraSystemPrompt: context.extraSystemPrompt,
+      senderIsOwner: context.senderIsOwner,
+      allowModelOverride: Boolean(voiceModel),
+      model: voiceModel,
+      toolsAllow: params.toolsAllow,
+      deliver: false,
+    },
+    params.runtime,
+  );
+  const payloads = result.payloads ?? [];
+  const text = payloads
+    .map((payload) => payload.text)
+    .filter((entry) => typeof entry === "string" && entry.trim())
+    .join("\n")
+    .trim();
+  if (!text) {
+    logger.info(
+      `discord voice: agent turn produced no speakable payloads guild=${params.entry.guildId} channel=${params.entry.channelId} voiceSession=${params.entry.voiceSessionKey} supervisorSession=${params.entry.route.sessionKey} agent=${params.entry.route.agentId} user=${params.userId} ${summarizeAgentTurnPayloads(payloads)}`,
+    );
+  }
+  return {
+    context,
+    text,
+  };
+}