@moxxy/plugin-channel-discord 0.27.0

package/src/channel/voice-handler.ts

@@ -0,0 +1,150 @@
+import type { ClientSession as Session } from '@moxxy/sdk';
+import { MAX_AUDIO_BYTES, type InboundAttachment } from '../schema.js';
+import type { ChannelLogger } from './discord-like.js';
+import type { InboundContext } from './message-handler.js';
+
+/** Abort the attachment download if Discord's CDN hasn't responded in this window. */
+const DOWNLOAD_TIMEOUT_MS = 30_000;
+
+export interface VoiceHandlerState {
+  readonly session: Session | null;
+  readonly busy: boolean;
+}
+
+export interface VoiceHandlerDeps {
+  readonly logger?: ChannelLogger;
+}
+
+export interface VoiceHandlerCallbacks {
+  readonly runUserTurn: (ctx: InboundContext, text: string) => Promise<void>;
+  /** Override the network fetch for tests. Defaults to global `fetch`. */
+  readonly fetchAudio?: (
+    url: string,
+    init?: { signal?: AbortSignal },
+  ) => Promise<{
+    ok: boolean;
+    status?: number;
+    statusText?: string;
+    headers?: { get(name: string): string | null };
+    arrayBuffer(): Promise<ArrayBuffer>;
+  }>;
+}
+
+/** The first audio attachment on the message (Discord voice messages arrive as
+ *  an `audio/ogg` attachment; uploaded audio files carry their own mime). */
+export function pickAudioAttachment(
+  attachments: ReadonlyArray<InboundAttachment>,
+): InboundAttachment | null {
+  return attachments.find((a) => (a.contentType ?? '').startsWith('audio/')) ?? null;
+}
+
+/**
+ * Handle a Discord voice message / uploaded audio file. Called AFTER the
+ * pairing + allow-list gate (the message handler owns authorization). Returns
+ * true when the message carried audio and was consumed here (successfully or
+ * not), false when there was no audio and the text path should proceed.
+ *
+ * Mirrors the Telegram voice handler: size caps (declared size, then
+ * Content-Length, then the buffered body), bounded download, transcriber gate
+ * with install guidance, a "heard:" echo, then a normal user turn.
+ */
+export async function handleVoiceMessage(
+  ctx: InboundContext,
+  state: VoiceHandlerState,
+  deps: VoiceHandlerDeps,
+  cb: VoiceHandlerCallbacks,
+): Promise<boolean> {
+  const audio = pickAudioAttachment(ctx.msg.attachments);
+  if (!audio) return false;
+
+  if (state.busy) {
+    await ctx.reply('I am still working on the previous prompt. Send /cancel to abort it.');
+    return true;
+  }
+  if (!state.session) {
+    await ctx.reply('Session is not ready yet.');
+    return true;
+  }
+
+  const transcriber = state.session.transcribers.tryGetActive();
+  if (!transcriber) {
+    await ctx.reply(
+      'Heard a voice message, but no speech-to-text backend is configured. Install @moxxy/plugin-stt-whisper and run `moxxy login openai` (or set OPENAI_API_KEY) to enable voice input.',
+    );
+    return true;
+  }
+
+  // Reject oversized uploads up-front using the size Discord reports, before
+  // we spend a download or any memory on it.
+  if (audio.size > MAX_AUDIO_BYTES) {
+    await ctx.reply(
+      `That audio is too large (${Math.round(audio.size / (1024 * 1024))}MB). The limit is ${MAX_AUDIO_BYTES / (1024 * 1024)}MB.`,
+    );
+    return true;
+  }
+
+  const fetcher = cb.fetchAudio ?? ((u: string, init?: { signal?: AbortSignal }) => fetch(u, init));
+  const ac = new AbortController();
+  const timer = setTimeout(() => ac.abort(), DOWNLOAD_TIMEOUT_MS);
+  let bytes: Uint8Array;
+  try {
+    const response = await fetcher(audio.url, { signal: ac.signal });
+    if (!response.ok) {
+      deps.logger?.warn('discord voice download failed', {
+        ...(response.status !== undefined ? { status: response.status } : {}),
+        ...(response.statusText ? { statusText: response.statusText } : {}),
+      });
+      await ctx.reply('Failed to download the voice message from Discord.');
+      return true;
+    }
+    // Trust the Content-Length header (when present) to bail before buffering
+    // a body that lies about its size on the attachment object.
+    const declaredLen = Number(response.headers?.get('content-length') ?? '');
+    if (Number.isFinite(declaredLen) && declaredLen > MAX_AUDIO_BYTES) {
+      await ctx.reply('That audio is too large to transcribe.');
+      return true;
+    }
+    const buf = await response.arrayBuffer();
+    if (buf.byteLength > MAX_AUDIO_BYTES) {
+      await ctx.reply('That audio is too large to transcribe.');
+      return true;
+    }
+    bytes = new Uint8Array(buf);
+  } catch (err) {
+    deps.logger?.warn('discord voice fetch failed', {
+      err: err instanceof Error ? err.message : String(err),
+    });
+    await ctx.reply(
+      ac.signal.aborted
+        ? 'Downloading the voice message timed out.'
+        : 'Failed to download the voice message from Discord.',
+    );
+    return true;
+  } finally {
+    clearTimeout(timer);
+  }
+
+  const mimeType = audio.contentType ?? 'audio/ogg';
+  let transcript: string;
+  try {
+    const result = await transcriber.transcribe(bytes, { mimeType });
+    transcript = result.text.trim();
+  } catch (err) {
+    deps.logger?.warn('discord voice transcription failed', {
+      err: err instanceof Error ? err.message : String(err),
+    });
+    await ctx.reply(`Transcription failed: ${err instanceof Error ? err.message : String(err)}`);
+    return true;
+  }
+
+  if (!transcript) {
+    await ctx.reply('Could not transcribe the voice message (got empty text).');
+    return true;
+  }
+
+  // Echo what we heard so the user can spot misrecognitions before the agent
+  // acts on it. Italics keep it visually distinct from a normal reply.
+  await ctx.reply(`*heard:* ${transcript}`);
+  await cb.runUserTurn(ctx, transcript);
+  return true;
+}

package/src/channel/voice-reply.test.ts

@@ -0,0 +1,142 @@
+import { promises as fs } from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { VaultStore, createStaticKeySource, deriveKey, generateSalt } from '@moxxy/plugin-vault';
+import { asTurnId, type MoxxyEvent } from '@moxxy/sdk';
+import type { ClientSession as Session } from '@moxxy/sdk';
+import { DISCORD_VOICE_REPLIES_KEY, loadVoiceReplies, saveVoiceReplies } from '../keys.js';
+import { runSlash } from './slash-handler.js';
+import { runDiscordTurn } from './turn-runner.js';
+import type { SendableChannelLike, SentMessageLike } from './discord-like.js';
+import { TypingIndicator } from './typing-indicator.js';
+
+describe('discord voice-replies vault flag round-trip', () => {
+  let tmp: string;
+  let vault: VaultStore;
+
+  beforeEach(async () => {
+    tmp = await fs.mkdtemp(path.join(os.tmpdir(), 'mox-dc-voice-'));
+    vault = new VaultStore({
+      filePath: path.join(tmp, 'vault.json'),
+      keySource: createStaticKeySource(deriveKey('test', generateSalt())),
+    });
+  });
+  afterEach(async () => {
+    await fs.rm(tmp, { recursive: true, force: true });
+  });
+
+  it('defaults to off, persists on, then off', async () => {
+    expect(await loadVoiceReplies(vault)).toBe(false);
+    await saveVoiceReplies(vault, true);
+    expect(await vault.get(DISCORD_VOICE_REPLIES_KEY)).toBe('1');
+    expect(await loadVoiceReplies(vault)).toBe(true);
+    await saveVoiceReplies(vault, false);
+    expect(await vault.get(DISCORD_VOICE_REPLIES_KEY)).toBe(null);
+    expect(await loadVoiceReplies(vault)).toBe(false);
+  });
+});
+
+describe('runSlash routes /voice to the channel callback', () => {
+  it('forwards the argument and returns the callback reply', async () => {
+    const args: string[] = [];
+    const session = { commands: { get: () => undefined } } as unknown as Session;
+    const reply = await runSlash('voice', 'on', session, {
+      toggleYolo: () => false,
+      voice: async (a) => {
+        args.push(a);
+        return '🔊 Voice replies ON';
+      },
+      performSessionAction: async () => '',
+    });
+    expect(args).toEqual(['on']);
+    expect(reply).toContain('Voice replies ON');
+  });
+});
+
+interface Recorded {
+  sends: string[];
+  channel: SendableChannelLike;
+}
+function recordedChannel(): Recorded {
+  const sends: string[] = [];
+  const channel: SendableChannelLike = {
+    send: async (payload) => {
+      sends.push(typeof payload === 'string' ? payload : payload.content ?? '');
+      const message: SentMessageLike = { edit: async () => {} };
+      return message;
+    },
+  };
+  return { sends, channel };
+}
+
+function fakeSession(script: (emit: (e: Record<string, unknown>) => void) => void): Session {
+  const listeners = new Set<(e: MoxxyEvent) => void>();
+  return {
+    log: {
+      subscribe(fn: (e: MoxxyEvent) => void) {
+        listeners.add(fn);
+        return () => listeners.delete(fn);
+      },
+    },
+    runTurn: (_p: string, opts: { turnId: string }) =>
+      (async function* () {
+        const emit = (e: Record<string, unknown>): void => {
+          const ev = { ...e, turnId: opts.turnId } as unknown as MoxxyEvent;
+          for (const fn of listeners) fn(ev);
+        };
+        script(emit);
+        yield undefined as never;
+      })(),
+  } as unknown as Session;
+}
+
+describe('runDiscordTurn onFinalReply seam (final assistant text)', () => {
+  it('calls onFinalReply with the assistant body after the text is flushed', async () => {
+    const { sends, channel } = recordedChannel();
+    const seen: string[] = [];
+    const session = fakeSession((emit) => {
+      emit({ type: 'assistant_chunk', delta: 'Hi' });
+      emit({ type: 'assistant_message', content: 'Hi there, done.' });
+    });
+    await runDiscordTurn(
+      { session, channel, typing: new TypingIndicator(), editFrameMs: 10, onFinalReply: async (t) => void seen.push(t) },
+      { text: 'hi', controller: new AbortController(), turnId: asTurnId('d1') },
+    );
+    expect(sends.length).toBeGreaterThanOrEqual(1);
+    expect(seen).toEqual(['Hi there, done.']);
+  });
+
+  it('does not speak a tool-only turn (empty assistant body)', async () => {
+    const { channel } = recordedChannel();
+    const seen: string[] = [];
+    const session = fakeSession((emit) => {
+      emit({ type: 'tool_call_requested', callId: 'c1', name: 'read', input: {} });
+    });
+    await runDiscordTurn(
+      { session, channel, typing: new TypingIndicator(), editFrameMs: 10, onFinalReply: async (t) => void seen.push(t) },
+      { text: 'hi', controller: new AbortController(), turnId: asTurnId('d2') },
+    );
+    expect(seen).toEqual([]);
+  });
+
+  it('never breaks the (already-sent) text turn when the voice hook rejects', async () => {
+    const { sends, channel } = recordedChannel();
+    const session = fakeSession((emit) => emit({ type: 'assistant_message', content: 'Done.' }));
+    await runDiscordTurn(
+      {
+        session,
+        channel,
+        typing: new TypingIndicator(),
+        editFrameMs: 10,
+        onFinalReply: async () => {
+          throw new Error('tts exploded');
+        },
+      },
+      { text: 'hi', controller: new AbortController(), turnId: asTurnId('d3') },
+    );
+    // The text still landed; the failed hook did NOT surface a "Turn failed".
+    expect(sends.join(' ')).toContain('Done.');
+    expect(sends.join(' ')).not.toContain('Turn failed');
+  });
+});