@moxxy/plugin-telegram 0.27.0

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

@@ -0,0 +1,328 @@
+import { describe, expect, it, vi } from 'vitest';
+import type { Context } from 'grammy';
+import { Session } from '@moxxy/core';
+import { defineTranscriber } from '@moxxy/sdk';
+import { handleVoiceMessage } from './voice-handler.js';
+
+const TOKEN = '1234567890:test-token';
+
+const makeSession = (): Session => new Session({ cwd: '/tmp', silent: true });
+
+const fakeCtx = (overrides: Partial<{ chatId: number; voice: unknown; audio: unknown; filePath: string | null }> = {}) => {
+  const replies: string[] = [];
+  const reply = vi.fn(async (text: string) => {
+    replies.push(text);
+  });
+  const getFile = vi.fn(async () => ({
+    file_id: 'f',
+    file_unique_id: 'u',
+    file_path: overrides.filePath === undefined ? 'voice/file.ogg' : overrides.filePath,
+  }));
+  return {
+    ctx: {
+      chat: { id: overrides.chatId ?? 99 },
+      message: {
+        voice: overrides.voice,
+        audio: overrides.audio,
+      },
+      reply,
+      api: { getFile },
+    } as unknown as Context,
+    replies,
+    reply,
+    getFile,
+  };
+};
+
+const okFetch = (bytes: Uint8Array) =>
+  vi.fn(async () => ({ ok: true, arrayBuffer: async () => bytes.buffer.slice(0) }));
+
+describe('handleVoiceMessage', () => {
+  const baseDeps = (token = TOKEN) => ({
+    pairing: { isAuthorized: () => true } as never,
+    token,
+  });
+
+  it('rejects unauthorized chats', async () => {
+    const { ctx, replies } = fakeCtx({ voice: { file_id: 'f' } });
+    const runUserTurn = vi.fn();
+    await handleVoiceMessage(
+      ctx,
+      {
+        session: makeSession(),
+        busy: false,
+      },
+      { ...baseDeps(), pairing: { isAuthorized: () => false } as never },
+      { runUserTurn, fetchAudio: okFetch(new Uint8Array([1])) },
+    );
+    expect(replies[0]).toMatch(/paired with a different chat/);
+    expect(runUserTurn).not.toHaveBeenCalled();
+  });
+
+  it('warns when no transcriber is registered on the session', async () => {
+    const { ctx, replies } = fakeCtx({ voice: { file_id: 'f' } });
+    const runUserTurn = vi.fn();
+    const session = makeSession();
+    await handleVoiceMessage(
+      ctx,
+      {
+        session,
+        busy: false,
+      },
+      baseDeps(),
+      { runUserTurn, fetchAudio: okFetch(new Uint8Array([1])) },
+    );
+    expect(replies[0]).toMatch(/no speech-to-text backend/);
+    expect(runUserTurn).not.toHaveBeenCalled();
+  });
+
+  it('transcribes and forwards the transcript to runUserTurn', async () => {
+    const audio = new Uint8Array([1, 2, 3, 4]);
+    const session = makeSession();
+    const transcribe = vi.fn(async () => ({ text: 'hello agent' }));
+    session.transcribers.register(
+      defineTranscriber({
+        name: 't',
+        createClient: () => ({ name: 't', transcribe }),
+      }),
+    );
+    session.transcribers.setActive('t');
+
+    const { ctx, replies, getFile } = fakeCtx({
+      voice: { file_id: 'voice-1', mime_type: 'audio/ogg' },
+    });
+    const runUserTurn = vi.fn(async () => {});
+    await handleVoiceMessage(
+      ctx,
+      {
+        session,
+        busy: false,
+      },
+      baseDeps(),
+      { runUserTurn, fetchAudio: okFetch(audio) },
+    );
+    expect(getFile).toHaveBeenCalledWith('voice-1');
+    expect(transcribe).toHaveBeenCalled();
+    const transcribeArgs = transcribe.mock.calls[0]!;
+    expect((transcribeArgs[1] as { mimeType: string }).mimeType).toBe('audio/ogg');
+    expect(replies.some((r) => /heard:/.test(r) && /hello agent/.test(r))).toBe(true);
+    expect(runUserTurn).toHaveBeenCalledWith(ctx, 99, 'hello agent');
+  });
+
+  it('refuses to start a new turn while busy', async () => {
+    const session = makeSession();
+    session.transcribers.register(
+      defineTranscriber({
+        name: 't',
+        createClient: () => ({ name: 't', transcribe: async () => ({ text: 'x' }) }),
+      }),
+    );
+    session.transcribers.setActive('t');
+    const { ctx, replies } = fakeCtx({ voice: { file_id: 'f' } });
+    const runUserTurn = vi.fn();
+    await handleVoiceMessage(
+      ctx,
+      {
+        session,
+        busy: true,
+      },
+      baseDeps(),
+      { runUserTurn, fetchAudio: okFetch(new Uint8Array([1])) },
+    );
+    expect(replies[0]).toMatch(/working on the previous prompt/);
+    expect(runUserTurn).not.toHaveBeenCalled();
+  });
+
+  it('replies on empty transcript and skips the turn', async () => {
+    const session = makeSession();
+    session.transcribers.register(
+      defineTranscriber({
+        name: 't',
+        createClient: () => ({ name: 't', transcribe: async () => ({ text: '   ' }) }),
+      }),
+    );
+    session.transcribers.setActive('t');
+    const { ctx, replies } = fakeCtx({ voice: { file_id: 'f' } });
+    const runUserTurn = vi.fn();
+    await handleVoiceMessage(
+      ctx,
+      {
+        session,
+        busy: false,
+      },
+      baseDeps(),
+      { runUserTurn, fetchAudio: okFetch(new Uint8Array([1])) },
+    );
+    expect(replies.some((r) => /empty text/.test(r))).toBe(true);
+    expect(runUserTurn).not.toHaveBeenCalled();
+  });
+
+  it('logs the real HTTP status when the download fails', async () => {
+    const session = makeSession();
+    session.transcribers.register(
+      defineTranscriber({
+        name: 't',
+        createClient: () => ({ name: 't', transcribe: async () => ({ text: 'x' }) }),
+      }),
+    );
+    session.transcribers.setActive('t');
+    const { ctx, replies } = fakeCtx({ voice: { file_id: 'f' } });
+    const runUserTurn = vi.fn();
+    const warn = vi.fn();
+    await handleVoiceMessage(
+      ctx,
+      { session, busy: false },
+      { ...baseDeps(), logger: { warn } },
+      {
+        runUserTurn,
+        fetchAudio: vi.fn(async () => ({
+          ok: false,
+          status: 404,
+          statusText: 'Not Found',
+          arrayBuffer: async () => new ArrayBuffer(0),
+        })),
+      },
+    );
+    expect(replies.some((r) => /Failed to download/.test(r))).toBe(true);
+    expect(runUserTurn).not.toHaveBeenCalled();
+    expect(warn).toHaveBeenCalledWith('telegram voice download failed', {
+      status: 404,
+      statusText: 'Not Found',
+    });
+  });
+
+  it('rejects an oversized upload before downloading it', async () => {
+    const session = makeSession();
+    session.transcribers.register(
+      defineTranscriber({
+        name: 't',
+        createClient: () => ({ name: 't', transcribe: async () => ({ text: 'x' }) }),
+      }),
+    );
+    session.transcribers.setActive('t');
+    const { ctx, replies, getFile } = fakeCtx({
+      voice: { file_id: 'f', file_size: 50 * 1024 * 1024 },
+    });
+    const runUserTurn = vi.fn();
+    const fetchAudio = vi.fn();
+    await handleVoiceMessage(
+      ctx,
+      { session, busy: false },
+      baseDeps(),
+      { runUserTurn, fetchAudio },
+    );
+    expect(replies.some((r) => /too large/.test(r))).toBe(true);
+    expect(getFile).not.toHaveBeenCalled();
+    expect(fetchAudio).not.toHaveBeenCalled();
+    expect(runUserTurn).not.toHaveBeenCalled();
+  });
+
+  it('rejects a body that exceeds the cap after download (Content-Length)', async () => {
+    const session = makeSession();
+    session.transcribers.register(
+      defineTranscriber({
+        name: 't',
+        createClient: () => ({ name: 't', transcribe: async () => ({ text: 'x' }) }),
+      }),
+    );
+    session.transcribers.setActive('t');
+    const { ctx, replies } = fakeCtx({ voice: { file_id: 'f' } });
+    const runUserTurn = vi.fn();
+    await handleVoiceMessage(
+      ctx,
+      { session, busy: false },
+      baseDeps(),
+      {
+        runUserTurn,
+        fetchAudio: vi.fn(async () => ({
+          ok: true,
+          headers: { get: (n: string) => (n === 'content-length' ? String(99 * 1024 * 1024) : null) },
+          arrayBuffer: async () => new ArrayBuffer(0),
+        })),
+      },
+    );
+    expect(replies.some((r) => /too large/.test(r))).toBe(true);
+    expect(runUserTurn).not.toHaveBeenCalled();
+  });
+
+  it('passes an AbortSignal to the fetch and reports a timeout abort', async () => {
+    const session = makeSession();
+    session.transcribers.register(
+      defineTranscriber({
+        name: 't',
+        createClient: () => ({ name: 't', transcribe: async () => ({ text: 'x' }) }),
+      }),
+    );
+    session.transcribers.setActive('t');
+    const { ctx, replies } = fakeCtx({ voice: { file_id: 'f' } });
+    const runUserTurn = vi.fn();
+    let sawSignal = false;
+    const fetchAudio = vi.fn(async (_url: string, init?: { signal?: AbortSignal }) => {
+      sawSignal = init?.signal instanceof AbortSignal;
+      // Simulate the AbortController firing mid-download.
+      const err = new Error('aborted');
+      (init?.signal as AbortSignal | undefined)?.dispatchEvent?.(new Event('abort'));
+      throw err;
+    });
+    await handleVoiceMessage(
+      ctx,
+      { session, busy: false },
+      baseDeps(),
+      { runUserTurn, fetchAudio },
+    );
+    expect(sawSignal).toBe(true);
+    expect(replies.some((r) => /Failed to download|timed out/.test(r))).toBe(true);
+    expect(runUserTurn).not.toHaveBeenCalled();
+  });
+
+  it('replies (not throws) when getFile itself fails', async () => {
+    const session = makeSession();
+    session.transcribers.register(
+      defineTranscriber({
+        name: 't',
+        createClient: () => ({ name: 't', transcribe: async () => ({ text: 'x' }) }),
+      }),
+    );
+    session.transcribers.setActive('t');
+    const { ctx, replies } = fakeCtx({ voice: { file_id: 'f' } });
+    // Override getFile to throw.
+    (ctx.api as unknown as { getFile: () => Promise<never> }).getFile = vi.fn(async () => {
+      throw new Error('network down');
+    });
+    const runUserTurn = vi.fn();
+    await expect(
+      handleVoiceMessage(
+        ctx,
+        { session, busy: false },
+        baseDeps(),
+        { runUserTurn, fetchAudio: okFetch(new Uint8Array([1])) },
+      ),
+    ).resolves.toBeUndefined();
+    expect(replies.some((r) => /Could not look up/.test(r))).toBe(true);
+    expect(runUserTurn).not.toHaveBeenCalled();
+  });
+
+  it('handles uploaded audio (message:audio) with its own mime_type', async () => {
+    const session = makeSession();
+    const transcribe = vi.fn(async () => ({ text: 'recorded earlier' }));
+    session.transcribers.register(
+      defineTranscriber({ name: 't', createClient: () => ({ name: 't', transcribe }) }),
+    );
+    session.transcribers.setActive('t');
+    const { ctx } = fakeCtx({
+      audio: { file_id: 'a-1', mime_type: 'audio/mpeg' },
+    });
+    const runUserTurn = vi.fn(async () => {});
+    await handleVoiceMessage(
+      ctx,
+      {
+        session,
+        busy: false,
+      },
+      baseDeps(),
+      { runUserTurn, fetchAudio: okFetch(new Uint8Array([9])) },
+    );
+    expect((transcribe.mock.calls[0]![1] as { mimeType: string }).mimeType).toBe('audio/mpeg');
+    expect(runUserTurn).toHaveBeenCalledWith(ctx, 99, 'recorded earlier');
+  });
+});

package/src/channel/voice-handler.ts

@@ -0,0 +1,198 @@
+import type { Context } from 'grammy';
+import type { ClientSession as Session } from '@moxxy/sdk';
+import type { PairingHandler } from './pairing-handler.js';
+
+/**
+ * Hard cap on an inbound audio file we will buffer into memory before
+ * transcribing. Telegram allows ~20MB uploads via getFile, and the handler
+ * accepts arbitrary uploaded `message:audio` (not just short voice notes), so
+ * an authorized-but-hostile chat could otherwise push a large file we fully
+ * buffer. 20MB matches Telegram's own getFile ceiling.
+ */
+const MAX_AUDIO_BYTES = 20 * 1024 * 1024;
+/** Abort the file download if Telegram's CDN hasn't responded in this window. */
+const DOWNLOAD_TIMEOUT_MS = 30_000;
+
+// NB: the voice path reads only a narrow slice of the channel's state/deps.
+// Voice-as-approval-text is intentionally unsupported — a voice note never
+// satisfies an awaiting approval-text prompt (the text handler owns that
+// path) — so the wider model/turn/approval/frame fields the text handler
+// needs are deliberately absent here rather than carried dead.
+export interface VoiceHandlerState {
+  readonly session: Session | null;
+  readonly busy: boolean;
+}
+
+export interface VoiceHandlerDeps {
+  readonly pairing: PairingHandler;
+  /** Bot token, used to build the Telegram file-download URL. */
+  readonly token: string;
+  readonly logger?: { warn(msg: string, meta?: Record<string, unknown>): void };
+}
+
+export interface VoiceHandlerCallbacks {
+  readonly runUserTurn: (ctx: Context, chatId: number, text: string) => Promise<void>;
+  /** Override the network fetch for tests. Defaults to global `fetch`. */
+  readonly fetchAudio?: (
+    url: string,
+    init?: { signal?: AbortSignal },
+  ) => Promise<{
+    ok: boolean;
+    /** HTTP status — surfaced in the download-failure log for diagnostics. */
+    status?: number;
+    statusText?: string;
+    /** Content-Length header, when present — used to reject oversized bodies pre-buffer. */
+    headers?: { get(name: string): string | null };
+    arrayBuffer(): Promise<ArrayBuffer>;
+  }>;
+}
+
+/**
+ * Handle inbound voice notes and uploaded audio files. Authorization
+ * gate matches the text path. If no Transcriber is registered on the
+ * session, reply with a one-time guidance message instead of silently
+ * swallowing the audio. Otherwise: download via Bot-API file URL,
+ * transcribe through the active Transcriber, echo a short "heard:"
+ * confirmation, then run a normal user turn with the transcript.
+ */
+export async function handleVoiceMessage(
+  ctx: Context,
+  state: VoiceHandlerState,
+  deps: VoiceHandlerDeps,
+  cb: VoiceHandlerCallbacks,
+): Promise<void> {
+  const chatId = ctx.chat?.id;
+  if (!chatId) return;
+
+  // Pull whichever audio variant Telegram delivered. `voice` is a press-
+  // and-hold voice note; `audio` is an uploaded audio file. Both expose
+  // a `file_id` and (for voice) a mime_type — we trust voice's
+  // `audio/ogg` default when missing.
+  const voice = ctx.message?.voice;
+  const audio = ctx.message?.audio;
+  const media = voice ?? audio;
+  if (!media) return;
+
+  if (!deps.pairing.isAuthorized(chatId)) {
+    await ctx.reply(
+      'This bot is paired with a different chat (or not paired yet). Run `moxxy telegram pair` to (re-)pair.',
+    );
+    return;
+  }
+
+  if (state.busy) {
+    await ctx.reply('I am still working on the previous prompt. Send /cancel to abort it.');
+    return;
+  }
+
+  if (!state.session) {
+    await ctx.reply('Session is not ready yet.');
+    return;
+  }
+
+  const transcriber = state.session.transcribers.tryGetActive();
+  if (!transcriber) {
+    await ctx.reply(
+      "Heard a voice note, 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;
+  }
+
+  // Reject oversized uploads up-front using the size Telegram reports on the
+  // voice/audio object, before we spend a download or any memory on it.
+  const declaredSize = (media as { file_size?: number }).file_size;
+  if (typeof declaredSize === 'number' && declaredSize > MAX_AUDIO_BYTES) {
+    await ctx.reply(
+      `That audio is too large (${Math.round(declaredSize / (1024 * 1024))}MB). The limit is ${MAX_AUDIO_BYTES / (1024 * 1024)}MB.`,
+    );
+    return;
+  }
+
+  let fileInfo: Awaited<ReturnType<typeof ctx.api.getFile>>;
+  try {
+    fileInfo = await ctx.api.getFile(media.file_id);
+  } catch (err) {
+    deps.logger?.warn('telegram getFile failed', {
+      err: err instanceof Error ? err.message : String(err),
+    });
+    await ctx.reply('Could not look up that voice note with Telegram.');
+    return;
+  }
+  if (!fileInfo.file_path) {
+    await ctx.reply('Telegram did not return a downloadable file path for that voice note.');
+    return;
+  }
+  const url = `https://api.telegram.org/file/bot${deps.token}/${fileInfo.file_path}`;
+  const fetcher =
+    cb.fetchAudio ?? ((u: string, init?: { signal?: AbortSignal }) => fetch(u, init));
+
+  // Bound the download with an AbortSignal timeout so a hung/slow Telegram CDN
+  // connection can't block the handler indefinitely.
+  const ac = new AbortController();
+  const timer = setTimeout(() => ac.abort(), DOWNLOAD_TIMEOUT_MS);
+  let bytes: Uint8Array;
+  try {
+    const response = await fetcher(url, { signal: ac.signal });
+    if (!response.ok) {
+      deps.logger?.warn('telegram voice download failed', {
+        ...(response.status !== undefined ? { status: response.status } : {}),
+        ...(response.statusText ? { statusText: response.statusText } : {}),
+      });
+      await ctx.reply('Failed to download the voice note from Telegram.');
+      return;
+    }
+    // Trust the Content-Length header (when present) to bail before buffering a
+    // body that lies about its size on the voice/audio 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;
+    }
+    const buf = await response.arrayBuffer();
+    if (buf.byteLength > MAX_AUDIO_BYTES) {
+      await ctx.reply('That audio is too large to transcribe.');
+      return;
+    }
+    bytes = new Uint8Array(buf);
+  } catch (err) {
+    deps.logger?.warn('telegram voice fetch failed', {
+      err: err instanceof Error ? err.message : String(err),
+    });
+    await ctx.reply(
+      ac.signal.aborted
+        ? 'Downloading the voice note timed out.'
+        : 'Failed to download the voice note from Telegram.',
+    );
+    return;
+  } finally {
+    clearTimeout(timer);
+  }
+
+  // Voice notes are OGG/Opus by default; uploaded audio carries its own mime.
+  const mimeType = media.mime_type ?? (voice ? 'audio/ogg' : 'audio/mpeg');
+  let transcript: string;
+  try {
+    const result = await transcriber.transcribe(bytes, { mimeType });
+    transcript = result.text.trim();
+  } catch (err) {
+    deps.logger?.warn('telegram voice transcription failed', {
+      err: err instanceof Error ? err.message : String(err),
+    });
+    await ctx.reply(
+      `Transcription failed: ${err instanceof Error ? err.message : String(err)}`,
+    );
+    return;
+  }
+
+  if (!transcript) {
+    await ctx.reply('Could not transcribe the voice note (got empty text).');
+    return;
+  }
+
+  // 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}`, { parse_mode: 'Markdown' });
+
+  await cb.runUserTurn(ctx, chatId, transcript);
+}