@moxxy/plugin-channel-discord 0.27.0

package/src/channel/slash-handler.ts

@@ -0,0 +1,136 @@
+import type { ClientSession as Session } from '@moxxy/sdk';
+import type { ChannelLogger } from './discord-like.js';
+
+export interface SlashCallbacks {
+  /** Toggle yolo and return its new value (so we can echo the right message). */
+  toggleYolo(): boolean;
+  /** Handle `/voice [on|off|status]` — persist + apply, return the reply text. */
+  voice(arg: string): Promise<string>;
+  /** Apply a `session-action` result emitted from a registered command. */
+  performSessionAction(action: 'new' | 'clear' | 'exit', notice: string | undefined): Promise<string>;
+}
+
+/**
+ * Slash-command dispatcher shared by the plain-text path (`/info` typed as a
+ * message) and the application-command path (a real Discord slash command —
+ * the interaction handler routes both here). Returns the reply text to send.
+ *
+ * First tries the shared `session.commands` registry — the universal commands
+ * (/info, /clear, /new, /exit, /help) plus plugin-contributed ones — then
+ * falls through to Discord-local cases (/yolo, /tools, /skills). /cancel and
+ * /allow, /deny are handled by the message/interaction layer (they need channel
+ * state this dispatcher doesn't carry).
+ */
+export async function runSlash(
+  name: string,
+  args: string,
+  session: Session,
+  cb: SlashCallbacks,
+): Promise<string> {
+  const registered = session.commands.get(name);
+  if (registered) {
+    try {
+      const result = await registered.handler({
+        channel: 'discord',
+        sessionId: session.id,
+        args,
+        session,
+      });
+      if (result.kind === 'text') return result.text;
+      if (result.kind === 'session-action') {
+        return cb.performSessionAction(result.action, result.notice);
+      }
+      if (result.kind === 'error') return `error: ${result.message}`;
+      return `✓ /${name}`;
+    } catch (err) {
+      return `command /${name} failed: ${err instanceof Error ? err.message : String(err)}`;
+    }
+  }
+
+  switch (name) {
+    case 'yolo': {
+      const enabled = cb.toggleYolo();
+      return enabled
+        ? '⚠ yolo mode ON — tool calls auto-approved for the rest of this session'
+        : 'yolo mode OFF — tool prompts will resume';
+    }
+    case 'voice':
+      return cb.voice(args);
+    case 'tools': {
+      const list = session.tools
+        .list()
+        .map((t) => `${t.name} — ${t.description}`)
+        .join('\n');
+      return list || '(no tools registered)';
+    }
+    case 'skills': {
+      const list = session.skills
+        .list()
+        .map((s) => `${s.frontmatter.name} — ${s.frontmatter.description}`)
+        .join('\n');
+      return list || '(no skills discovered)';
+    }
+    default:
+      return `unknown command: /${name} (try /help)`;
+  }
+}
+
+/** Discord application-command name constraint. */
+const COMMAND_NAME_RE = /^[a-z0-9_-]{1,32}$/;
+
+export interface AppCommandJson {
+  readonly name: string;
+  readonly description: string;
+}
+
+/**
+ * Build the application-command list to publish: the shared registry commands
+ * (parity with Telegram's `publishBotCommands`) plus the Discord-local ones.
+ * Names that don't fit Discord's `^[a-z0-9_-]{1,32}$` constraint are skipped
+ * (they remain reachable as plain-text `/name` messages); descriptions are
+ * clamped to Discord's 1..100 chars.
+ */
+export function buildAppCommands(session: Session): AppCommandJson[] {
+  const LOCAL: AppCommandJson[] = [
+    { name: 'yolo', description: 'Toggle auto-approve mode' },
+    { name: 'voice', description: 'Toggle spoken voice replies' },
+    { name: 'tools', description: 'List the tools the active session can call' },
+    { name: 'skills', description: 'List the discovered skills' },
+    { name: 'cancel', description: 'Abort the current turn' },
+    { name: 'allow', description: 'Allow this guild channel to drive moxxy (paired user only)' },
+    { name: 'deny', description: 'Remove this guild channel from the allow-list' },
+  ];
+  const shared = session.commands
+    .listForChannel('discord')
+    .map((c) => ({ name: c.name, description: c.description }));
+  const seen = new Set(shared.map((c) => c.name));
+  return [...shared, ...LOCAL.filter((c) => !seen.has(c.name))]
+    .filter((c) => COMMAND_NAME_RE.test(c.name))
+    .sort((a, b) => a.name.localeCompare(b.name))
+    .map((c) => ({ name: c.name, description: (c.description || c.name).slice(0, 100) || c.name }));
+}
+
+/** The slice of a discord.js application-command manager we publish through. */
+export interface AppCommandPublisher {
+  set(commands: ReadonlyArray<AppCommandJson>): Promise<unknown>;
+}
+
+/**
+ * Publish the commands to Discord so they appear in the client's "/" picker.
+ * Best-effort: a network failure here doesn't block channel startup — the
+ * commands still work as plain-text messages.
+ */
+export async function publishAppCommands(
+  publisher: AppCommandPublisher | null,
+  session: Session | null,
+  logger?: ChannelLogger,
+): Promise<void> {
+  if (!publisher || !session) return;
+  try {
+    await publisher.set(buildAppCommands(session));
+  } catch (err) {
+    logger?.warn('discord commands.set failed', {
+      err: err instanceof Error ? err.message : String(err),
+    });
+  }
+}

package/src/channel/turn-runner.test.ts

@@ -0,0 +1,177 @@
+import { describe, expect, it } from 'vitest';
+import { asTurnId, type MoxxyEvent } from '@moxxy/sdk';
+import type { ClientSession as Session } from '@moxxy/sdk';
+import type { SendableChannelLike, SentMessageLike } from './discord-like.js';
+import { TypingIndicator } from './typing-indicator.js';
+import {
+  clampEditFrameMs,
+  DEFAULT_EDIT_FRAME_MS,
+  MIN_EDIT_FRAME_MS,
+  runDiscordTurn,
+} from './turn-runner.js';
+
+const sleep = (ms: number): Promise<void> => new Promise((r) => setTimeout(r, ms));
+
+describe('clampEditFrameMs (Discord edit rate limit ~5 edits/5s)', () => {
+  it('defaults when unset and floors configured values at 1200ms', () => {
+    expect(clampEditFrameMs(undefined)).toBe(DEFAULT_EDIT_FRAME_MS);
+    expect(DEFAULT_EDIT_FRAME_MS).toBeGreaterThanOrEqual(1_200);
+    expect(clampEditFrameMs(50)).toBe(MIN_EDIT_FRAME_MS);
+    expect(MIN_EDIT_FRAME_MS).toBeGreaterThanOrEqual(1_200);
+    expect(clampEditFrameMs(5_000)).toBe(5_000);
+    expect(clampEditFrameMs(Number.NaN)).toBe(DEFAULT_EDIT_FRAME_MS);
+  });
+});
+
+interface Recorded {
+  sends: string[];
+  edits: string[];
+  channel: SendableChannelLike;
+}
+
+function recordedChannel(): Recorded {
+  const sends: string[] = [];
+  const edits: string[] = [];
+  const channel: SendableChannelLike = {
+    send: async (payload) => {
+      sends.push(typeof payload === 'string' ? payload : payload.content);
+      const message: SentMessageLike = {
+        edit: async (content: string) => {
+          edits.push(content);
+        },
+      };
+      return message;
+    },
+  };
+  return { sends, edits, channel };
+}
+
+/**
+ * Fake session: `runTurn` pushes scripted events (stamped with the given
+ * turnId) through the log subscribers, mirroring how the real Session fans
+ * out; the async iterable then completes.
+ */
+function fakeSession(
+  script: (emit: (e: Record<string, unknown>) => Promise<void>) => Promise<void>,
+): Session {
+  const listeners = new Set<(e: MoxxyEvent) => void>();
+  return {
+    log: {
+      subscribe(fn: (e: MoxxyEvent) => void) {
+        listeners.add(fn);
+        return () => listeners.delete(fn);
+      },
+    },
+    runTurn: (_prompt: string, opts: { turnId: string }) =>
+      (async function* () {
+        const emit = async (e: Record<string, unknown>): Promise<void> => {
+          const event = { ...e, turnId: opts.turnId } as unknown as MoxxyEvent;
+          for (const fn of listeners) fn(event);
+        };
+        await script(emit);
+        // The iterator yields nothing extra — rendering happens via the log.
+        yield undefined as never;
+      })(),
+  } as unknown as Session;
+}
+
+describe('runDiscordTurn — send-once-then-edit streaming', () => {
+  it('sends the first frame, edits it as chunks stream, edits the final in place', async () => {
+    const { sends, edits, channel } = recordedChannel();
+    const session = fakeSession(async (emit) => {
+      await emit({ type: 'assistant_chunk', delta: 'Hello' });
+      await sleep(30);
+      await emit({ type: 'assistant_chunk', delta: ', world' });
+      await sleep(30);
+      await emit({ type: 'assistant_message', content: 'Hello, world. Done.' });
+    });
+    await runDiscordTurn(
+      { session, channel, typing: new TypingIndicator(), editFrameMs: 10 },
+      { text: 'hi', controller: new AbortController(), turnId: asTurnId('turn-1') },
+    );
+    // Exactly one streamed message; later frames are edits of it.
+    expect(sends).toHaveLength(1);
+    expect(sends[0]!.startsWith('Hello')).toBe(true);
+    expect(edits.length).toBeGreaterThanOrEqual(1);
+    expect(edits[edits.length - 1]).toBe('Hello, world. Done.');
+  });
+
+  it('splits a long FINAL frame: edits the head, sends the tails as follow-ups', async () => {
+    const { sends, edits, channel } = recordedChannel();
+    const line = 'y'.repeat(100);
+    const long = Array.from({ length: 45 }, () => line).join('\n'); // ~4545 chars > 1900*2
+    const session = fakeSession(async (emit) => {
+      await emit({ type: 'assistant_chunk', delta: 'start' });
+      await sleep(30);
+      await emit({ type: 'assistant_message', content: long });
+    });
+    await runDiscordTurn(
+      { session, channel, typing: new TypingIndicator(), editFrameMs: 10 },
+      { text: 'hi', controller: new AbortController(), turnId: asTurnId('turn-2') },
+    );
+    // First send is the streamed head; final tails arrive as extra sends.
+    expect(sends.length).toBeGreaterThanOrEqual(3); // head + >=2 tails
+    const finalHead = edits[edits.length - 1]!;
+    expect(finalHead.length).toBeLessThanOrEqual(1_900);
+    // Reassembling head + tails recovers the whole final text.
+    const reassembled = [finalHead, ...sends.slice(1)].join('\n');
+    expect(reassembled).toBe(long);
+  });
+
+  it('posts a placeholder when the turn rendered nothing', async () => {
+    const { sends, channel } = recordedChannel();
+    const session = fakeSession(async () => undefined);
+    await runDiscordTurn(
+      { session, channel, typing: new TypingIndicator(), editFrameMs: 10 },
+      { text: 'hi', controller: new AbortController(), turnId: asTurnId('turn-3') },
+    );
+    expect(sends).toEqual(['*(no output)*']);
+  });
+
+  it('ignores events from OTHER turns (invariant #8: filter by turnId)', async () => {
+    const { sends, edits, channel } = recordedChannel();
+    const listeners = new Set<(e: MoxxyEvent) => void>();
+    const session = {
+      log: {
+        subscribe(fn: (e: MoxxyEvent) => void) {
+          listeners.add(fn);
+          return () => listeners.delete(fn);
+        },
+      },
+      runTurn: (_prompt: string, opts: { turnId: string }) =>
+        (async function* () {
+          const fan = (e: Record<string, unknown>): void => {
+            for (const fn of listeners) fn(e as unknown as MoxxyEvent);
+          };
+          // A concurrent foreign turn's chunk must NOT render here.
+          fan({ type: 'assistant_chunk', delta: 'FOREIGN', turnId: 'other-turn' });
+          fan({ type: 'assistant_message', content: 'mine', turnId: opts.turnId });
+          yield undefined as never;
+        })(),
+    } as unknown as Session;
+    await runDiscordTurn(
+      { session, channel, typing: new TypingIndicator(), editFrameMs: 10 },
+      { text: 'hi', controller: new AbortController(), turnId: asTurnId('turn-4') },
+    );
+    const all = [...sends, ...edits].join(' ');
+    expect(all).toContain('mine');
+    expect(all).not.toContain('FOREIGN');
+  });
+
+  it('surfaces a failed turn into the channel instead of dangling', async () => {
+    const { sends, channel } = recordedChannel();
+    const session = {
+      log: { subscribe: () => () => undefined },
+      runTurn: () =>
+        (async function* () {
+          yield undefined as never;
+          throw new Error('provider exploded');
+        })(),
+    } as unknown as Session;
+    await runDiscordTurn(
+      { session, channel, typing: new TypingIndicator(), editFrameMs: 10 },
+      { text: 'hi', controller: new AbortController(), turnId: asTurnId('turn-5') },
+    );
+    expect(sends.join(' ')).toMatch(/Turn failed: provider exploded/);
+  });
+});

package/src/channel/turn-runner.ts

@@ -0,0 +1,139 @@
+import type { newTurnId } from '@moxxy/core';
+import type { ClientSession as Session } from '@moxxy/sdk';
+import { FramePump, driveTurn, subscribeTurn } from '@moxxy/channel-kit';
+import { DiscordTurnRenderer, splitForDiscord } from '../render.js';
+import type { ChannelLogger, SendableChannelLike, SentMessageLike } from './discord-like.js';
+import type { TypingIndicator } from './typing-indicator.js';
+
+/**
+ * Discord's per-channel edit budget is ~5 edits / 5s; the streaming edit
+ * throttle must stay at or above 1200ms so a long turn never trips the rate
+ * limiter (which would delay-queue frames and lag the stream).
+ */
+export const MIN_EDIT_FRAME_MS = 1_200;
+export const DEFAULT_EDIT_FRAME_MS = 1_500;
+
+/** Clamp a configured editFrameMs to the Discord-safe floor. */
+export function clampEditFrameMs(requested: number | undefined): number {
+  if (typeof requested !== 'number' || !Number.isFinite(requested)) return DEFAULT_EDIT_FRAME_MS;
+  return Math.max(MIN_EDIT_FRAME_MS, requested);
+}
+
+export interface RunDiscordTurnDeps {
+  readonly session: Session;
+  readonly channel: SendableChannelLike;
+  readonly typing: TypingIndicator;
+  readonly editFrameMs: number;
+  readonly logger?: ChannelLogger;
+  /**
+   * Called once with the FINAL assistant text after it has been flushed to the
+   * channel (so the text reply always lands first). Backs the optional voice
+   * reply. Best-effort — its failure is logged and never breaks the text turn.
+   */
+  readonly onFinalReply?: (text: string) => Promise<void>;
+}
+
+export interface RunDiscordTurnOptions {
+  readonly text: string;
+  readonly model?: string | undefined;
+  readonly controller: AbortController;
+  /** Pre-minted turn id; the channel records it as an own-turn id. */
+  readonly turnId: ReturnType<typeof newTurnId>;
+}
+
+/**
+ * Drive a single Discord turn end-to-end: start typing, subscribe the frame
+ * pump to THIS turn's events (filtered by turnId — `session.log` fans out to
+ * every listener, so a concurrent turn on the same Session would otherwise
+ * stream into this channel, AGENTS.md invariant #8), run the turn, flush the
+ * final frame, unwind in `finally`.
+ *
+ * The streaming loop is `@moxxy/channel-kit`'s {@link FramePump} ("send once,
+ * then edit that message", throttled to `editFrameMs`) over a
+ * {@link DiscordTurnRenderer} snapshot. Delivery handles the 2000-char cap:
+ * mid-stream frames edit only the first split part; the FINAL frame sends the
+ * overflow tail parts as follow-up messages (`alwaysFlushFinal` so the sink's
+ * final-only work is never skipped).
+ */
+export async function runDiscordTurn(
+  deps: RunDiscordTurnDeps,
+  opts: RunDiscordTurnOptions,
+): Promise<void> {
+  const { session, channel, typing, editFrameMs, logger, onFinalReply } = deps;
+  const { text, model, controller, turnId } = opts;
+
+  const renderer = new DiscordTurnRenderer();
+  const sendPart = async (part: string): Promise<SentMessageLike | null> => {
+    try {
+      return await channel.send(part);
+    } catch (err) {
+      logger?.warn('discord send failed', { err: String(err) });
+      return null;
+    }
+  };
+  const pump = new FramePump<SentMessageLike>({
+    editFrameMs,
+    frame: () => renderer.snapshot(),
+    // Guarantee at least one message even when the turn produced no text.
+    emptyFinalText: '*(no output)*',
+    // The sink does final-only work (split-overflow tails), so the final frame
+    // must reach it even when the text didn't change since the last edit.
+    alwaysFlushFinal: true,
+    sink: {
+      send: async (t, final) => {
+        const parts = splitForDiscord(t);
+        const sent = await sendPart(parts[0]!);
+        if (final) for (const tail of parts.slice(1)) await sendPart(tail);
+        return sent;
+      },
+      edit: async (message, t, final) => {
+        const parts = splitForDiscord(t);
+        try {
+          await message.edit(parts[0]!);
+        } catch (err) {
+          logger?.warn('discord edit failed', { err: String(err) });
+        }
+        if (final) for (const tail of parts.slice(1)) await sendPart(tail);
+      },
+    },
+  });
+
+  typing.start(channel);
+  const unsubscribe = subscribeTurn(session, turnId, (event) => {
+    if (renderer.accept(event)) pump.scheduleEdit();
+  });
+
+  try {
+    await driveTurn(session, {
+      turnId,
+      prompt: text,
+      ...(model ? { model } : {}),
+      signal: controller.signal,
+    });
+    await pump.flush(true);
+    // The text reply is now out. Speak the final assistant body if a voice
+    // reply is wired — isolated so a synth/transcode/transport failure can
+    // never break (or re-report) the already-delivered text turn.
+    if (onFinalReply) {
+      const finalText = renderer.finalText();
+      if (finalText) {
+        try {
+          await onFinalReply(finalText);
+        } catch (err) {
+          logger?.warn('discord voice reply hook failed', {
+            err: err instanceof Error ? err.message : String(err),
+          });
+        }
+      }
+    }
+  } catch (err) {
+    logger?.warn('discord turn failed', {
+      err: err instanceof Error ? err.message : String(err),
+    });
+    await sendPart(`Turn failed: ${err instanceof Error ? err.message : String(err)}`);
+  } finally {
+    typing.stop();
+    unsubscribe();
+    pump.dispose();
+  }
+}

package/src/channel/typing-indicator.ts

@@ -0,0 +1,31 @@
+import type { SendableChannelLike } from './discord-like.js';
+
+/** Discord's typing indicator expires ~10s after `sendTyping`; refresh under that. */
+const REFRESH_MS = 8_000;
+
+/**
+ * Keeps the "moxxy is typing…" indicator alive for the duration of a turn.
+ * Best-effort: transport errors are swallowed (a failed typing ping must never
+ * abort a turn).
+ */
+export class TypingIndicator {
+  private timer: ReturnType<typeof setInterval> | null = null;
+
+  start(channel: SendableChannelLike): void {
+    this.stop();
+    if (!channel.sendTyping) return;
+    const ping = (): void => {
+      void channel.sendTyping?.()?.catch?.(() => undefined);
+    };
+    ping();
+    this.timer = setInterval(ping, REFRESH_MS);
+    this.timer.unref?.();
+  }
+
+  stop(): void {
+    if (this.timer) {
+      clearInterval(this.timer);
+      this.timer = null;
+    }
+  }
+}

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

@@ -0,0 +1,177 @@
+import { describe, expect, it, vi } from 'vitest';
+import type { ClientSession as Session } from '@moxxy/sdk';
+import type { InboundMessage } from '../schema.js';
+import { MAX_AUDIO_BYTES } from '../schema.js';
+import type { InboundContext } from './message-handler.js';
+import { handleVoiceMessage, pickAudioAttachment } from './voice-handler.js';
+
+function audioMsg(overrides: Partial<InboundMessage['attachments'][number]> = {}): InboundMessage {
+  return {
+    id: '999999999999',
+    content: '',
+    channelId: '555555555555',
+    guildId: null,
+    authorId: '111111111111',
+    authorIsBot: false,
+    attachments: [
+      {
+        id: '888888888888',
+        url: 'https://cdn.example/voice.ogg',
+        contentType: 'audio/ogg',
+        size: 1_000,
+        name: 'voice-message.ogg',
+        ...overrides,
+      },
+    ],
+  };
+}
+
+function makeCtx(msg: InboundMessage): { ctx: InboundContext; replies: string[] } {
+  const replies: string[] = [];
+  return {
+    replies,
+    ctx: {
+      msg,
+      channel: { send: async () => ({ edit: async () => undefined }) },
+      reply: async (text: string) => {
+        replies.push(text);
+      },
+    },
+  };
+}
+
+function sessionWithTranscriber(transcribe: ((bytes: Uint8Array, o: { mimeType: string }) => Promise<{ text: string }>) | null): Session {
+  return {
+    transcribers: {
+      tryGetActive: () => (transcribe ? { transcribe } : null),
+    },
+  } as unknown as Session;
+}
+
+const okFetch = (bytes = 16) =>
+  vi.fn(async () => ({
+    ok: true,
+    headers: { get: () => String(bytes) },
+    arrayBuffer: async () => new ArrayBuffer(bytes),
+  }));
+
+describe('pickAudioAttachment', () => {
+  it('picks the first audio/* attachment and ignores others', () => {
+    const msg = audioMsg();
+    expect(pickAudioAttachment(msg.attachments)?.contentType).toBe('audio/ogg');
+    expect(pickAudioAttachment([{ ...msg.attachments[0]!, contentType: 'image/png' }])).toBeNull();
+    expect(pickAudioAttachment([{ ...msg.attachments[0]!, contentType: null }])).toBeNull();
+  });
+});
+
+describe('handleVoiceMessage', () => {
+  it('returns false for messages without audio (text path proceeds)', async () => {
+    const { ctx } = makeCtx({ ...audioMsg(), attachments: [] });
+    const consumed = await handleVoiceMessage(
+      ctx,
+      { session: sessionWithTranscriber(null), busy: false },
+      {},
+      { runUserTurn: vi.fn() },
+    );
+    expect(consumed).toBe(false);
+  });
+
+  it('guides the user when no transcriber is configured', async () => {
+    const { ctx, replies } = makeCtx(audioMsg());
+    const runUserTurn = vi.fn();
+    const consumed = await handleVoiceMessage(
+      ctx,
+      { session: sessionWithTranscriber(null), busy: false },
+      {},
+      { runUserTurn },
+    );
+    expect(consumed).toBe(true);
+    expect(replies[0]).toMatch(/plugin-stt-whisper/);
+    expect(runUserTurn).not.toHaveBeenCalled();
+  });
+
+  it('rejects a declared-oversized attachment BEFORE downloading', async () => {
+    const fetchAudio = okFetch();
+    const { ctx, replies } = makeCtx(audioMsg({ size: MAX_AUDIO_BYTES + 1 }));
+    await handleVoiceMessage(
+      ctx,
+      { session: sessionWithTranscriber(async () => ({ text: 'x' })), busy: false },
+      {},
+      { runUserTurn: vi.fn(), fetchAudio },
+    );
+    expect(replies[0]).toMatch(/too large/);
+    expect(fetchAudio).not.toHaveBeenCalled();
+  });
+
+  it('rejects on a lying Content-Length header before buffering', async () => {
+    const fetchAudio = vi.fn(async () => ({
+      ok: true,
+      headers: { get: () => String(MAX_AUDIO_BYTES + 1) },
+      arrayBuffer: async () => new ArrayBuffer(8),
+    }));
+    const { ctx, replies } = makeCtx(audioMsg());
+    await handleVoiceMessage(
+      ctx,
+      { session: sessionWithTranscriber(async () => ({ text: 'x' })), busy: false },
+      {},
+      { runUserTurn: vi.fn(), fetchAudio },
+    );
+    expect(replies[0]).toMatch(/too large/);
+  });
+
+  it('rejects an oversized BUFFERED body (no content-length)', async () => {
+    const fetchAudio = vi.fn(async () => ({
+      ok: true,
+      headers: { get: () => null },
+      arrayBuffer: async () => new ArrayBuffer(MAX_AUDIO_BYTES + 1),
+    }));
+    const { ctx, replies } = makeCtx(audioMsg());
+    await handleVoiceMessage(
+      ctx,
+      { session: sessionWithTranscriber(async () => ({ text: 'x' })), busy: false },
+      {},
+      { runUserTurn: vi.fn(), fetchAudio },
+    );
+    expect(replies[0]).toMatch(/too large/);
+  });
+
+  it('refuses while busy', async () => {
+    const { ctx, replies } = makeCtx(audioMsg());
+    await handleVoiceMessage(
+      ctx,
+      { session: sessionWithTranscriber(async () => ({ text: 'x' })), busy: true },
+      {},
+      { runUserTurn: vi.fn() },
+    );
+    expect(replies[0]).toMatch(/still working/);
+  });
+
+  it('transcribes and runs a user turn with a "heard:" echo', async () => {
+    const transcribe = vi.fn(async () => ({ text: '  turn on the lights  ' }));
+    const runUserTurn = vi.fn();
+    const { ctx, replies } = makeCtx(audioMsg());
+    const consumed = await handleVoiceMessage(
+      ctx,
+      { session: sessionWithTranscriber(transcribe), busy: false },
+      {},
+      { runUserTurn, fetchAudio: okFetch() },
+    );
+    expect(consumed).toBe(true);
+    expect(transcribe).toHaveBeenCalledWith(expect.any(Uint8Array), { mimeType: 'audio/ogg' });
+    expect(replies[0]).toBe('*heard:* turn on the lights');
+    expect(runUserTurn).toHaveBeenCalledWith(ctx, 'turn on the lights');
+  });
+
+  it('reports empty transcriptions instead of running an empty turn', async () => {
+    const runUserTurn = vi.fn();
+    const { ctx, replies } = makeCtx(audioMsg());
+    await handleVoiceMessage(
+      ctx,
+      { session: sessionWithTranscriber(async () => ({ text: '   ' })), busy: false },
+      {},
+      { runUserTurn, fetchAudio: okFetch() },
+    );
+    expect(replies[0]).toMatch(/empty text/);
+    expect(runUserTurn).not.toHaveBeenCalled();
+  });
+});