@gakr-gakr/discord 0.1.0

package/src/target-resolver.ts

@@ -0,0 +1,129 @@
+import type { DirectoryConfigParams } from "autobot/plugin-sdk/directory-runtime";
+import { buildMessagingTarget, type MessagingTarget } from "autobot/plugin-sdk/messaging-targets";
+import { resolveDiscordAccount, resolveDiscordAccountAllowFrom } from "./accounts.js";
+import { rememberDiscordDirectoryUser } from "./directory-cache.js";
+import { listDiscordDirectoryPeersLive } from "./directory-live.js";
+import { allowFromContainsDiscordUserId } from "./normalize.js";
+import { parseDiscordSendTarget } from "./send-target-parsing.js";
+import { type DiscordTargetParseOptions } from "./target-parsing.js";
+
+/**
+ * Resolve a Discord username to user ID using the directory lookup.
+ * This enables sending DMs by username instead of requiring explicit user IDs.
+ */
+export async function resolveDiscordTarget(
+  raw: string,
+  options: DirectoryConfigParams,
+  parseOptions: DiscordTargetParseOptions = {},
+): Promise<MessagingTarget | undefined> {
+  const trimmed = raw.trim();
+  if (!trimmed) {
+    return undefined;
+  }
+
+  const likelyUsername = isLikelyUsername(trimmed);
+  const shouldLookup = isExplicitUserLookup(trimmed, parseOptions) || likelyUsername;
+
+  if (
+    /^\d+$/.test(trimmed) &&
+    parseOptions.defaultKind !== "user" &&
+    isConfiguredAllowedDiscordDmUser(trimmed, options)
+  ) {
+    return buildMessagingTarget("user", trimmed, trimmed);
+  }
+
+  // Parse directly if it's already a known format. Use a safe parse so ambiguous
+  // numeric targets don't throw when we still want to attempt username lookup.
+  const directParse = safeParseDiscordTarget(trimmed, parseOptions);
+  if (directParse && directParse.kind !== "channel" && !likelyUsername) {
+    return directParse;
+  }
+
+  if (!shouldLookup) {
+    return directParse ?? parseDiscordSendTarget(trimmed, parseOptions);
+  }
+
+  try {
+    const directoryEntries = await listDiscordDirectoryPeersLive({
+      ...options,
+      query: trimmed,
+      limit: 1,
+    });
+
+    const match = directoryEntries[0];
+    if (match && match.kind === "user") {
+      const userId = match.id.replace(/^user:/, "");
+      const resolvedAccountId = resolveDiscordAccount({
+        cfg: options.cfg,
+        accountId: options.accountId,
+      }).accountId;
+      rememberDiscordDirectoryUser({
+        accountId: resolvedAccountId,
+        userId,
+        handles: [trimmed, match.name, match.handle],
+      });
+      return buildMessagingTarget("user", userId, trimmed);
+    }
+  } catch {
+    // Preserve legacy fallback behavior for channel names and direct ids.
+  }
+
+  return parseDiscordSendTarget(trimmed, parseOptions);
+}
+
+export async function parseAndResolveDiscordTarget(
+  raw: string,
+  options: DirectoryConfigParams,
+  parseOptions: DiscordTargetParseOptions = {},
+): Promise<MessagingTarget> {
+  const resolved =
+    (await resolveDiscordTarget(raw, options, parseOptions)) ??
+    parseDiscordSendTarget(raw, parseOptions);
+  if (!resolved) {
+    throw new Error("Recipient is required for Discord sends");
+  }
+  return resolved;
+}
+
+function safeParseDiscordTarget(
+  input: string,
+  options: DiscordTargetParseOptions,
+): MessagingTarget | undefined {
+  try {
+    return parseDiscordSendTarget(input, options);
+  } catch {
+    return undefined;
+  }
+}
+
+function isConfiguredAllowedDiscordDmUser(input: string, options: DirectoryConfigParams): boolean {
+  const allowFrom =
+    resolveDiscordAccountAllowFrom({
+      cfg: options.cfg,
+      accountId: options.accountId,
+    }) ?? [];
+  return allowFromContainsDiscordUserId(allowFrom, input);
+}
+
+function isExplicitUserLookup(input: string, options: DiscordTargetParseOptions): boolean {
+  if (/^<@!?(\d+)>$/.test(input)) {
+    return true;
+  }
+  if (/^(user:|discord:)/.test(input)) {
+    return true;
+  }
+  if (input.startsWith("@")) {
+    return true;
+  }
+  if (/^\d+$/.test(input)) {
+    return options.defaultKind === "user";
+  }
+  return false;
+}
+
+function isLikelyUsername(input: string): boolean {
+  if (/^(user:|channel:|discord:|@|<@!?)|[\d]+$/.test(input)) {
+    return false;
+  }
+  return true;
+}

package/src/targets.ts

@@ -0,0 +1,12 @@
+import {
+  parseDiscordTarget,
+  type DiscordTarget,
+  type DiscordTargetKind,
+  type DiscordTargetParseOptions,
+  resolveDiscordChannelId,
+} from "./target-parsing.js";
+import { resolveDiscordTarget } from "./target-resolver.js";
+
+export { parseDiscordTarget, resolveDiscordChannelId };
+export type { DiscordTarget, DiscordTargetKind, DiscordTargetParseOptions };
+export { resolveDiscordTarget };

package/src/token.ts

@@ -0,0 +1,107 @@
+import type { BaseTokenResolution } from "autobot/plugin-sdk/channel-contract";
+import type { AutoBotConfig } from "autobot/plugin-sdk/config-contracts";
+import { DEFAULT_ACCOUNT_ID, normalizeAccountId } from "autobot/plugin-sdk/routing";
+import { resolveAccountEntry } from "autobot/plugin-sdk/routing";
+import {
+  normalizeResolvedSecretInputString,
+  resolveSecretInputString,
+} from "autobot/plugin-sdk/secret-input";
+import { selectDiscordRuntimeConfig } from "./runtime-config.js";
+
+type DiscordTokenSource = "env" | "config" | "none";
+export type DiscordCredentialStatus = "available" | "configured_unavailable" | "missing";
+
+export type DiscordTokenResolution = BaseTokenResolution & {
+  source: DiscordTokenSource;
+  tokenStatus: DiscordCredentialStatus;
+};
+
+type DiscordTokenValueResolution =
+  | { status: "available"; value: string }
+  | { status: "configured_unavailable" }
+  | { status: "missing" };
+
+function stripDiscordBotPrefix(token: string): string {
+  return token.replace(/^Bot\s+/i, "");
+}
+
+export function normalizeDiscordToken(raw: unknown, path: string): string | undefined {
+  const trimmed = normalizeResolvedSecretInputString({ value: raw, path });
+  if (!trimmed) {
+    return undefined;
+  }
+  return stripDiscordBotPrefix(trimmed);
+}
+
+function resolveDiscordTokenValue(params: {
+  cfg: AutoBotConfig;
+  value: unknown;
+  path: string;
+}): DiscordTokenValueResolution {
+  const resolved = resolveSecretInputString({
+    value: params.value,
+    path: params.path,
+    defaults: params.cfg.secrets?.defaults,
+    mode: "inspect",
+  });
+  if (resolved.status === "available") {
+    return {
+      status: "available",
+      value: stripDiscordBotPrefix(resolved.value),
+    };
+  }
+  if (resolved.status === "configured_unavailable") {
+    return { status: "configured_unavailable" };
+  }
+  return { status: "missing" };
+}
+
+export function resolveDiscordToken(
+  cfg: AutoBotConfig,
+  opts: { accountId?: string | null; envToken?: string | null } = {},
+): DiscordTokenResolution {
+  const selectedCfg = selectDiscordRuntimeConfig(cfg);
+  const accountId = normalizeAccountId(opts.accountId);
+  const discordCfg = selectedCfg?.channels?.discord;
+  const accountCfg = resolveAccountEntry(discordCfg?.accounts, accountId);
+  const hasAccountToken = Boolean(
+    accountCfg &&
+    Object.prototype.hasOwnProperty.call(accountCfg as Record<string, unknown>, "token"),
+  );
+  const accountToken = resolveDiscordTokenValue({
+    cfg: selectedCfg,
+    value: (accountCfg as { token?: unknown } | undefined)?.token,
+    path: `channels.discord.accounts.${accountId}.token`,
+  });
+  if (accountToken.status === "available" && accountToken.value) {
+    return { token: accountToken.value, source: "config", tokenStatus: "available" };
+  }
+  if (accountToken.status === "configured_unavailable") {
+    return { token: "", source: "config", tokenStatus: "configured_unavailable" };
+  }
+  if (hasAccountToken) {
+    return { token: "", source: "none", tokenStatus: "missing" };
+  }
+
+  const configToken = resolveDiscordTokenValue({
+    cfg: selectedCfg,
+    value: discordCfg?.token,
+    path: "channels.discord.token",
+  });
+  if (configToken.status === "available" && configToken.value) {
+    return { token: configToken.value, source: "config", tokenStatus: "available" };
+  }
+  if (configToken.status === "configured_unavailable") {
+    return { token: "", source: "config", tokenStatus: "configured_unavailable" };
+  }
+
+  const allowEnv = accountId === DEFAULT_ACCOUNT_ID;
+  const envToken = allowEnv
+    ? normalizeDiscordToken(opts.envToken ?? process.env.DISCORD_BOT_TOKEN, "DISCORD_BOT_TOKEN")
+    : undefined;
+  if (envToken) {
+    return { token: envToken, source: "env", tokenStatus: "available" };
+  }
+
+  return { token: "", source: "none", tokenStatus: "missing" };
+}

package/src/ui-colors.ts

@@ -0,0 +1,27 @@
+import type { AutoBotConfig } from "autobot/plugin-sdk/config-contracts";
+import { inspectDiscordAccount } from "./account-inspect.js";
+
+const DEFAULT_DISCORD_ACCENT_COLOR = "#5865F2";
+
+type ResolveDiscordAccentColorParams = {
+  cfg: AutoBotConfig;
+  accountId?: string | null;
+};
+
+export function normalizeDiscordAccentColor(raw?: string | null): string | null {
+  const trimmed = (raw ?? "").trim();
+  if (!trimmed) {
+    return null;
+  }
+  const normalized = trimmed.startsWith("#") ? trimmed : `#${trimmed}`;
+  if (!/^#[0-9a-fA-F]{6}$/.test(normalized)) {
+    return null;
+  }
+  return normalized.toUpperCase();
+}
+
+export function resolveDiscordAccentColor(params: ResolveDiscordAccentColorParams): string {
+  const account = inspectDiscordAccount({ cfg: params.cfg, accountId: params.accountId });
+  const configured = normalizeDiscordAccentColor(account.config.ui?.components?.accentColor);
+  return configured ?? DEFAULT_DISCORD_ACCENT_COLOR;
+}

package/src/ui.ts

@@ -0,0 +1,20 @@
+import type { AutoBotConfig } from "autobot/plugin-sdk/config-contracts";
+import { Container } from "./internal/discord.js";
+import { normalizeDiscordAccentColor, resolveDiscordAccentColor } from "./ui-colors.js";
+
+type DiscordContainerComponents = ConstructorParameters<typeof Container>[0];
+
+export class DiscordUiContainer extends Container {
+  constructor(params: {
+    cfg: AutoBotConfig;
+    accountId?: string | null;
+    components?: DiscordContainerComponents;
+    accentColor?: string;
+    spoiler?: boolean;
+  }) {
+    const accentOverride = normalizeDiscordAccentColor(params.accentColor);
+    const accentColor =
+      accentOverride ?? resolveDiscordAccentColor({ cfg: params.cfg, accountId: params.accountId });
+    super(params.components, { accentColor, spoiler: params.spoiler });
+  }
+}

package/src/voice/access.ts

@@ -0,0 +1,126 @@
+import { resolveCommandAuthorizedFromAuthorizers } from "autobot/plugin-sdk/command-auth-native";
+import type { AutoBotConfig } from "autobot/plugin-sdk/config-contracts";
+import type { DiscordAccountConfig } from "autobot/plugin-sdk/config-contracts";
+import { resolveOpenProviderRuntimeGroupPolicy } from "autobot/plugin-sdk/runtime-group-policy";
+import type { Guild } from "../internal/discord.js";
+import {
+  isDiscordGroupAllowedByPolicy,
+  resolveDiscordChannelConfigWithFallback,
+  type DiscordChannelConfigResolved,
+  resolveDiscordGuildEntry,
+  resolveDiscordMemberAccessState,
+  resolveDiscordOwnerAccess,
+} from "../monitor/allow-list.js";
+
+export async function authorizeDiscordVoiceIngress(params: {
+  cfg: AutoBotConfig;
+  discordConfig: DiscordAccountConfig;
+  accountId?: string;
+  groupPolicy?: "open" | "disabled" | "allowlist";
+  useAccessGroups?: boolean;
+  guild?: Guild<true> | Guild | null;
+  guildName?: string;
+  guildId: string;
+  channelId: string;
+  channelName?: string;
+  channelSlug: string;
+  parentId?: string;
+  parentName?: string;
+  parentSlug?: string;
+  scope?: "channel" | "thread";
+  channelLabel?: string;
+  memberRoleIds: string[];
+  ownerAllowFrom?: string[];
+  sender: { id: string; name?: string; tag?: string };
+}): Promise<
+  { ok: true; channelConfig?: DiscordChannelConfigResolved | null } | { ok: false; message: string }
+> {
+  const groupPolicy =
+    params.groupPolicy ??
+    resolveOpenProviderRuntimeGroupPolicy({
+      providerConfigPresent: params.cfg.channels?.discord !== undefined,
+      groupPolicy: params.discordConfig.groupPolicy,
+      defaultGroupPolicy: params.cfg.channels?.defaults?.groupPolicy,
+    }).groupPolicy;
+  const guild =
+    params.guild ??
+    ({ id: params.guildId, ...(params.guildName ? { name: params.guildName } : {}) } as Guild);
+  const guildInfo = resolveDiscordGuildEntry({
+    guild,
+    guildId: params.guildId,
+    guildEntries: params.discordConfig.guilds,
+  });
+  const channelConfig = params.channelId
+    ? resolveDiscordChannelConfigWithFallback({
+        guildInfo,
+        channelId: params.channelId,
+        channelName: params.channelName,
+        channelSlug: params.channelSlug,
+        parentId: params.parentId,
+        parentName: params.parentName,
+        parentSlug: params.parentSlug,
+        scope: params.scope,
+      })
+    : null;
+
+  if (channelConfig?.enabled === false) {
+    return { ok: false, message: "This channel is disabled." };
+  }
+
+  const channelAllowlistConfigured =
+    Boolean(guildInfo?.channels) && Object.keys(guildInfo?.channels ?? {}).length > 0;
+  if (!params.channelId && groupPolicy === "allowlist" && channelAllowlistConfigured) {
+    return {
+      ok: false,
+      message: `${params.channelLabel ?? "This channel"} is not allowlisted for voice commands.`,
+    };
+  }
+
+  const channelAllowed = channelConfig ? channelConfig.allowed : !channelAllowlistConfigured;
+  if (
+    !isDiscordGroupAllowedByPolicy({
+      groupPolicy,
+      guildAllowlisted: Boolean(guildInfo),
+      channelAllowlistConfigured,
+      channelAllowed,
+    }) ||
+    channelConfig?.allowed === false
+  ) {
+    return {
+      ok: false,
+      message: `${params.channelLabel ?? "This channel"} is not allowlisted for voice commands.`,
+    };
+  }
+
+  const { hasAccessRestrictions, memberAllowed } = resolveDiscordMemberAccessState({
+    channelConfig,
+    guildInfo,
+    memberRoleIds: params.memberRoleIds,
+    sender: params.sender,
+    allowNameMatching: false,
+  });
+
+  const { ownerAllowList, ownerAllowed } = resolveDiscordOwnerAccess({
+    allowFrom:
+      params.ownerAllowFrom ?? params.discordConfig.allowFrom ?? params.discordConfig.dm?.allowFrom,
+    sender: params.sender,
+    allowNameMatching: false,
+  });
+
+  const useAccessGroups = params.useAccessGroups ?? params.cfg.commands?.useAccessGroups !== false;
+  const authorizers = useAccessGroups
+    ? [
+        { configured: ownerAllowList != null, allowed: ownerAllowed },
+        { configured: hasAccessRestrictions, allowed: memberAllowed },
+      ]
+    : [{ configured: hasAccessRestrictions, allowed: memberAllowed }];
+
+  const commandAuthorized = resolveCommandAuthorizedFromAuthorizers({
+    useAccessGroups,
+    authorizers,
+    modeWhenAccessGroupsOff: "configured",
+  });
+  return commandAuthorized
+    ? { ok: true, channelConfig }
+    : { ok: false, message: "You are not authorized to use this command." };
+}

package/src/voice/audio.ts

@@ -0,0 +1,249 @@
+import fs from "node:fs/promises";
+import { createRequire } from "node:module";
+import type { Readable } from "node:stream";
+import { resamplePcm } from "autobot/plugin-sdk/realtime-voice";
+import { logVerbose, shouldLogVerbose } from "autobot/plugin-sdk/runtime-env";
+import { formatErrorMessage } from "autobot/plugin-sdk/ssrf-runtime";
+import { tempWorkspace, resolvePreferredAutoBotTmpDir } from "autobot/plugin-sdk/temp-path";
+
+const require = createRequire(import.meta.url);
+
+const SAMPLE_RATE = 48_000;
+const CHANNELS = 2;
+const BIT_DEPTH = 16;
+
+type OpusDecoder = {
+  decode: (buffer: Buffer) => Buffer;
+};
+
+type OpusDecoderFactory = {
+  load: () => OpusDecoder;
+  name: string;
+};
+
+type OpusDecoderPreference = "native" | "opusscript";
+
+let warnedOpusMissing = false;
+let cachedOpusDecoderFactory: OpusDecoderFactory | null | "unresolved" = "unresolved";
+
+function buildWavBuffer(pcm: Buffer): Buffer {
+  const blockAlign = (CHANNELS * BIT_DEPTH) / 8;
+  const byteRate = SAMPLE_RATE * blockAlign;
+  const header = Buffer.alloc(44);
+  header.write("RIFF", 0);
+  header.writeUInt32LE(36 + pcm.length, 4);
+  header.write("WAVE", 8);
+  header.write("fmt ", 12);
+  header.writeUInt32LE(16, 16);
+  header.writeUInt16LE(1, 20);
+  header.writeUInt16LE(CHANNELS, 22);
+  header.writeUInt32LE(SAMPLE_RATE, 24);
+  header.writeUInt32LE(byteRate, 28);
+  header.writeUInt16LE(blockAlign, 32);
+  header.writeUInt16LE(BIT_DEPTH, 34);
+  header.write("data", 36);
+  header.writeUInt32LE(pcm.length, 40);
+  return Buffer.concat([header, pcm]);
+}
+
+function resolveOpusDecoderFactory(params: {
+  onWarn: (message: string) => void;
+}): OpusDecoderFactory | null {
+  const nativeFactory: OpusDecoderFactory = {
+    name: "@discordjs/opus",
+    load: () => {
+      const DiscordOpus = require("@discordjs/opus") as {
+        OpusEncoder: new (
+          sampleRate: number,
+          channels: number,
+        ) => {
+          decode: (buffer: Buffer) => Buffer;
+        };
+      };
+      return new DiscordOpus.OpusEncoder(SAMPLE_RATE, CHANNELS);
+    },
+  };
+  const opusscriptFactory: OpusDecoderFactory = {
+    name: "opusscript",
+    load: () => {
+      const OpusScript = require("opusscript") as {
+        new (sampleRate: number, channels: number, application: number): OpusDecoder;
+        Application: { AUDIO: number };
+      };
+      return new OpusScript(SAMPLE_RATE, CHANNELS, OpusScript.Application.AUDIO);
+    },
+  };
+  const factories: OpusDecoderFactory[] =
+    resolveOpusDecoderPreference() === "native"
+      ? [nativeFactory, opusscriptFactory]
+      : [opusscriptFactory, nativeFactory];
+
+  const failures: string[] = [];
+  for (const factory of factories) {
+    try {
+      factory.load();
+      return factory;
+    } catch (err) {
+      failures.push(`${factory.name}: ${formatErrorMessage(err)}`);
+    }
+  }
+
+  if (!warnedOpusMissing) {
+    warnedOpusMissing = true;
+    params.onWarn(
+      `discord voice: no usable opus decoder available (${failures.join("; ")}); cannot decode voice audio`,
+    );
+  }
+  return null;
+}
+
+export function resolveOpusDecoderPreference(
+  value = process.env.AUTOBOT_DISCORD_OPUS_DECODER,
+): OpusDecoderPreference {
+  const normalized = value?.trim().toLowerCase();
+  if (normalized === "native" || normalized === "@discordjs/opus") {
+    return "native";
+  }
+  return "opusscript";
+}
+
+function getOrCreateOpusDecoderFactory(params: {
+  onWarn: (message: string) => void;
+}): OpusDecoderFactory | null {
+  if (cachedOpusDecoderFactory !== "unresolved") {
+    return cachedOpusDecoderFactory;
+  }
+  cachedOpusDecoderFactory = resolveOpusDecoderFactory(params);
+  return cachedOpusDecoderFactory;
+}
+
+function createOpusDecoder(params: {
+  onWarn: (message: string) => void;
+}): { decoder: OpusDecoder; name: string } | null {
+  const factory = getOrCreateOpusDecoderFactory(params);
+  if (!factory) {
+    return null;
+  }
+  return { decoder: factory.load(), name: factory.name };
+}
+
+export async function decodeOpusStream(
+  stream: Readable,
+  params: { onVerbose: (message: string) => void; onWarn: (message: string) => void },
+): Promise<Buffer> {
+  const selected = createOpusDecoder({ onWarn: params.onWarn });
+  if (!selected) {
+    return Buffer.alloc(0);
+  }
+  params.onVerbose(`opus decoder: ${selected.name}`);
+  const chunks: Buffer[] = [];
+  try {
+    for await (const chunk of stream) {
+      if (!chunk || !(chunk instanceof Buffer) || chunk.length === 0) {
+        continue;
+      }
+      const decoded = selected.decoder.decode(chunk);
+      if (decoded && decoded.length > 0) {
+        chunks.push(Buffer.from(decoded));
+      }
+    }
+  } catch (err) {
+    if (shouldLogVerbose()) {
+      logVerbose(`discord voice: opus decode failed: ${formatErrorMessage(err)}`);
+    }
+  }
+  return chunks.length > 0 ? Buffer.concat(chunks) : Buffer.alloc(0);
+}
+
+export async function decodeOpusStreamChunks(
+  stream: Readable,
+  params: {
+    onChunk: (pcm48kStereo: Buffer) => void;
+    onVerbose: (message: string) => void;
+    onWarn: (message: string) => void;
+  },
+): Promise<void> {
+  const selected = createOpusDecoder({ onWarn: params.onWarn });
+  if (!selected) {
+    return;
+  }
+  params.onVerbose(`opus decoder: ${selected.name}`);
+  try {
+    for await (const chunk of stream) {
+      if (!chunk || !(chunk instanceof Buffer) || chunk.length === 0) {
+        continue;
+      }
+      const decoded = selected.decoder.decode(chunk);
+      if (decoded && decoded.length > 0) {
+        params.onChunk(Buffer.from(decoded));
+      }
+    }
+  } catch (err) {
+    if (shouldLogVerbose()) {
+      logVerbose(`discord voice: opus decode failed: ${formatErrorMessage(err)}`);
+    }
+  }
+}
+
+export function convertDiscordPcm48kStereoToRealtimePcm24kMono(pcm: Buffer): Buffer {
+  const frameCount = Math.floor(pcm.length / 4);
+  if (frameCount === 0) {
+    return Buffer.alloc(0);
+  }
+  const mono48k = Buffer.alloc(frameCount * 2);
+  for (let frame = 0; frame < frameCount; frame += 1) {
+    const offset = frame * 4;
+    const left = pcm.readInt16LE(offset);
+    const right = pcm.readInt16LE(offset + 2);
+    mono48k.writeInt16LE(Math.round((left + right) / 2), frame * 2);
+  }
+  return resamplePcm(mono48k, SAMPLE_RATE, 24_000);
+}
+
+export function convertRealtimePcm24kMonoToDiscordPcm48kStereo(pcm: Buffer): Buffer {
+  const mono48k = resamplePcm(pcm, 24_000, SAMPLE_RATE);
+  const sampleCount = Math.floor(mono48k.length / 2);
+  if (sampleCount === 0) {
+    return Buffer.alloc(0);
+  }
+  const stereo = Buffer.alloc(sampleCount * 4);
+  for (let sampleIndex = 0; sampleIndex < sampleCount; sampleIndex += 1) {
+    const sample = mono48k.readInt16LE(sampleIndex * 2);
+    const offset = sampleIndex * 4;
+    stereo.writeInt16LE(sample, offset);
+    stereo.writeInt16LE(sample, offset + 2);
+  }
+  return stereo;
+}
+
+function estimateDurationSeconds(pcm: Buffer): number {
+  const bytesPerSample = (BIT_DEPTH / 8) * CHANNELS;
+  if (bytesPerSample <= 0) {
+    return 0;
+  }
+  return pcm.length / (bytesPerSample * SAMPLE_RATE);
+}
+
+export async function writeVoiceWavFile(
+  pcm: Buffer,
+): Promise<{ path: string; durationSeconds: number }> {
+  const workspace = await tempWorkspace({
+    rootDir: resolvePreferredAutoBotTmpDir(),
+    prefix: "discord-voice-",
+  });
+  const wav = buildWavBuffer(pcm);
+  const filePath = await workspace.write("segment.wav", wav);
+  scheduleTempCleanup(workspace.dir);
+  return { path: filePath, durationSeconds: estimateDurationSeconds(pcm) };
+}
+
+function scheduleTempCleanup(tempDir: string, delayMs: number = 30 * 60 * 1000): void {
+  const timer = setTimeout(() => {
+    fs.rm(tempDir, { recursive: true, force: true }).catch((err) => {
+      if (shouldLogVerbose()) {
+        logVerbose(`discord voice: temp cleanup failed for ${tempDir}: ${formatErrorMessage(err)}`);
+      }
+    });
+  }, delayMs);
+  timer.unref();
+}