Skip to content

Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS

32.5 KB
Raw Blame
import { describe, it, expect, vi, beforeEach } from 'vitest';
import express from 'express';
const { request } = await import('../lib/testHelper.js');

vi.mock('../services/voice/studio.js', () => ({ createStudioVoice: vi.fn(), assignStudioVoice: vi.fn() }));

// Mock all voice service modules before importing the router so the route
// file's top-level imports resolve to the mocks.
vi.mock('../services/voice/config.js', () => ({
  getVoiceConfig: vi.fn(),
  updateVoiceConfig: vi.fn(),
}));
vi.mock('../services/voice/health.js', () => ({
  checkAll: vi.fn(),
  invalidateHealthCache: vi.fn(),
}));
vi.mock('../services/voice/bootstrap.js', () => ({
  reconcile: vi.fn(),
  verifyBinaries: vi.fn(),
  verifyModels: vi.fn(),
  downloadPiperVoice: vi.fn(),
  // POST /api/voice/whisper imports these at module load — without the
  // mock entries the destructured imports resolve to `undefined` and the
  // route TypeErrors the first time it's hit.
  startWhisper: vi.fn(),
  stopWhisper: vi.fn(),
}));
vi.mock('../services/voice/tts.js', () => ({
  synthesize: vi.fn(),
  listVoices: vi.fn(),
  listVoiceEngines: vi.fn(),
  VALID_ENGINES: new Set(['kokoro', 'piper', 'qwen3-tts']),
}));
vi.mock('../services/voice/profiles.js', async (importActual) => ({
  ...(await importActual()),
  listVoiceProfiles: vi.fn(),
  promotePresetProfile: vi.fn(),
  createVoiceDesignCandidate: vi.fn(),
  createClonedVoiceCandidate: vi.fn(),
  promoteVoiceProfile: vi.fn(),
}));
vi.mock('../services/voice/profileBenchmarks.js', () => ({
  renderProfileBenchmark: vi.fn(),
  benchmarkProfileInteractive: vi.fn(),
  completeProfileInteractiveBenchmark: vi.fn(),
}));
vi.mock('../services/voice/qwen3TtsRuntime.js', () => ({
  getQwen3RuntimeStatus: vi.fn(),
  downloadQwen3Model: vi.fn(),
  DEFAULT_DESIGN_MODEL: 'Qwen/Qwen3-TTS-12Hz-1.7B-VoiceDesign',
}));
vi.mock('../services/voice/fineTuning.js', () => ({
  startFineTuningJob: vi.fn(),
  listFineTuningJobs: vi.fn(),
  getFineTuningJobStatus: vi.fn(),
  cancelFineTuningJob: vi.fn(),
  promoteCheckpoint: vi.fn(),
}));
vi.mock('../services/voice/piper-voices.js', () => ({
  findPiperVoice: vi.fn(),
}));
vi.mock('../services/voice/proactiveSpeech.js', async () => {
  const actual = await vi.importActual('../services/voice/proactiveSpeech.js');
  return {
    ...actual,
    speakProactive: vi.fn(),
  };
});
vi.mock('../services/voice/facetimeBridge.js', () => ({
  checkSetup: vi.fn(),
  probe: vi.fn(),
  call: vi.fn(),
  hangup: vi.fn(),
}));

const config = await import('../services/voice/config.js');
const health = await import('../services/voice/health.js');
const bootstrap = await import('../services/voice/bootstrap.js');
const tts = await import('../services/voice/tts.js');
const voiceProfiles = await import('../services/voice/profiles.js');
const profileBenchmarks = await import('../services/voice/profileBenchmarks.js');
const qwen3TtsRuntime = await import('../services/voice/qwen3TtsRuntime.js');
const fineTuning = await import('../services/voice/fineTuning.js');
const { ServerError } = await import('../lib/errorHandler.js');
const piperVoices = await import('../services/voice/piper-voices.js');
const proactiveSpeech = await import('../services/voice/proactiveSpeech.js');
const facetimeBridge = await import('../services/voice/facetimeBridge.js');
const { default: voiceRoutes } = await import('./voice.js');
const { errorEvents } = await import('../lib/errorHandler.js');

// Node's EventEmitter throws if 'error' is emitted with zero listeners.
// asyncHandler emits to errorEvents on every route failure, so swallow it
// here — assertions go through the HTTP response, not the emitter.
errorEvents.on('error', () => {});

const DEFAULT_CFG = {
  enabled: false,
  stt: { engine: 'web-speech', endpoint: 'http://127.0.0.1:5562' },
  tts: { engine: 'kokoro', rate: 1, kokoro: { modelId: 'kokoro-test', dtype: 'q8' } },
};

const buildApp = ({ io = { emit: () => {} } } = {}) => {
  const app = express();
  // A local caller on a password-free install holds host control, so PUT
  // /config reconciles (#13055); hostControlVoiceConfig.test.js covers the rest.
  app.use((req, _res, next) => { req.portosAuthContext = { enabled: false }; next(); });
  app.use(express.json());
  // /speak fails fast when io is missing (a 500 misconfiguration error
  // rather than a 200 { ok:false, reason:'no-io' } that monitoring would
  // miss). Attach a stub io by default; pass io:null to exercise the
  // misconfiguration branch.
  if (io) app.set('io', io);
  app.use('/api/voice', voiceRoutes);
  return app;
};

describe('Voice Routes', () => {
  beforeEach(() => {
    vi.clearAllMocks();
    config.getVoiceConfig.mockResolvedValue(DEFAULT_CFG);
  });

  describe('machine-local voice profiles & Voice Lab', () => {
    it('reports the preset engine capability contract', async () => {
      tts.listVoiceEngines.mockResolvedValue([{ id: 'kokoro', capabilities: { preset: true, formant: false } }]);
      const res = await request(buildApp()).get('/api/voice/engines');
      expect(res.status).toBe(200);
      expect(res.body.engines).toEqual([{ id: 'kokoro', capabilities: { preset: true, formant: false } }]);
    });

    it('lists only the requested machine-local character binding', async () => {
      voiceProfiles.listVoiceProfiles.mockResolvedValue([{ id: 'voice-profile-1' }]);
      const res = await request(buildApp()).get('/api/voice/profiles?universeId=uni-1&characterId=char-1');
      expect(res.status).toBe(200);
      expect(voiceProfiles.listVoiceProfiles).toHaveBeenCalledWith({ universeId: 'uni-1', characterId: 'char-1' });
      expect(res.body.profiles).toEqual([{ id: 'voice-profile-1' }]);
    });

    it('promotes a preset with the current local model and delivery provenance', async () => {
      voiceProfiles.promotePresetProfile.mockResolvedValue({ id: 'voice-profile-1' });
      const res = await request(buildApp()).post('/api/voice/profiles/preset').send({
        universeId: 'uni-1', characterId: 'char-1', voiceId: 'piper:en_US-lessac-medium',
      });
      expect(res.status).toBe(201);
      expect(voiceProfiles.promotePresetProfile).toHaveBeenCalledWith(expect.objectContaining({
        modelRevision: 'piper:en_US-lessac-medium', delivery: { rate: 1 },
      }));
      expect(res.body).toEqual({ profile: { id: 'voice-profile-1' } });
    });

    it.each([
      ['piper:en_GB-jenny_dioco-medium', 'piper:en_GB-jenny_dioco-medium'],
      ['qwen3:warm-narrator', 'Qwen/Qwen3-TTS-12Hz-1.7B-VoiceDesign'],
      ['qwen3-tts:warm-narrator', 'Qwen/Qwen3-TTS-12Hz-1.7B-VoiceDesign'],
    ])('preserves the model revision for %s preset promotion', async (voiceId, modelRevision) => {
      voiceProfiles.promotePresetProfile.mockResolvedValue({ id: 'voice-profile-1' });
      const res = await request(buildApp()).post('/api/voice/profiles/preset').send({
        universeId: 'uni-1', characterId: 'char-1', voiceId,
      });
      expect(res.status).toBe(201);
      expect(voiceProfiles.promotePresetProfile).toHaveBeenCalledWith(expect.objectContaining({
        modelRevision,
      }));
    });

    it('creates a candidate voice design profile without altering approved binding', async () => {
      voiceProfiles.createVoiceDesignCandidate.mockResolvedValue({ id: 'voice-design-1', kind: 'designed', approval: { status: 'draft' } });
      const res = await request(buildApp()).post('/api/voice/profiles/design').send({
        universeId: 'uni-1', characterId: 'char-1', instructions: 'warm low alto', seed: 42,
      });
      expect(res.status).toBe(201);
      expect(voiceProfiles.createVoiceDesignCandidate).toHaveBeenCalledWith(expect.objectContaining({
        instructions: 'warm low alto', seed: 42,
      }));
      expect(res.body.profile.kind).toBe('designed');
    });

    it('creates a consented clone candidate profile with verified performer consent', async () => {
      voiceProfiles.createClonedVoiceCandidate.mockResolvedValue({ id: 'voice-clone-1', kind: 'cloned', approval: { status: 'draft' } });
      const res = await request(buildApp()).post('/api/voice/profiles/clone').send({
        universeId: 'uni-1',
        characterId: 'char-1',
        filename: 'reference.wav',
        audioBase64: Buffer.from('mockwav').toString('base64'),
        transcript: 'sample transcript',
        performerConsentConfirmed: true,
      });
      expect(res.status).toBe(201);
      expect(voiceProfiles.createClonedVoiceCandidate).toHaveBeenCalledWith(expect.objectContaining({
        filename: 'reference.wav',
        transcript: 'sample transcript',
        performerConsentConfirmed: true,
      }));
    });

    it('promotes candidate profile and sets routes', async () => {
      voiceProfiles.promoteVoiceProfile.mockResolvedValue({ id: 'voice-profile-1', approval: { status: 'approved' } });
      const res = await request(buildApp()).post('/api/voice/profiles/voice-profile-1/promote').send({
        routes: { studio: { enabled: true }, interactive: { enabled: true } },
      });
      expect(res.status).toBe(200);
      expect(voiceProfiles.promoteVoiceProfile).toHaveBeenCalledWith('voice-profile-1', expect.any(Object));
    });

    it('runs interactive latency qualification benchmark', async () => {
      profileBenchmarks.benchmarkProfileInteractive.mockResolvedValue({ benchmarkId: 'example-probe', audioBase64: 'fixture' });
      const res = await request(buildApp()).post('/api/voice/profiles/voice-profile-1/benchmark-interactive').send({
        maxFirstAudioMs: 800,
      });
      expect(res.status).toBe(200);
      expect(res.body).toEqual({ benchmark: { benchmarkId: 'example-probe', audioBase64: 'fixture' } });
      expect(profileBenchmarks.benchmarkProfileInteractive).toHaveBeenCalledWith('voice-profile-1', { maxFirstAudioMs: 800 });
    });

    it('validates a playback receipt before completing interactive qualification', async () => {
      profileBenchmarks.completeProfileInteractiveBenchmark.mockResolvedValue({ id: 'voice-profile-1' });
      const receipt = { benchmarkId: '12345678-1234-4234-8234-123456789012', renderRequestLatencyMs: 150, playbackStartupMs: 50 };
      const res = await request(buildApp()).post('/api/voice/profiles/voice-profile-1/benchmark-interactive/complete').send(receipt);
      expect(res.status).toBe(200);
      expect(res.body).toEqual({ profile: { id: 'voice-profile-1' } });
      expect(profileBenchmarks.completeProfileInteractiveBenchmark).toHaveBeenCalledWith('voice-profile-1', receipt);
      const invalid = await request(buildApp()).post('/api/voice/profiles/voice-profile-1/benchmark-interactive/complete')
        .send({ ...receipt, playbackStartupMs: -1 });
      expect(invalid.status).toBe(400);
    });

    it('runs fixed benchmarks only for a valid profile id', async () => {
      profileBenchmarks.renderProfileBenchmark.mockResolvedValue({ id: 'voice-profile-1' });
      const res = await request(buildApp()).post('/api/voice/profiles/voice-profile-1/benchmark').send({});
      expect(res.status).toBe(200);
      expect(profileBenchmarks.renderProfileBenchmark).toHaveBeenCalledWith('voice-profile-1');
    });

    it('manages fine-tuning lifecycle: start, status, cancel, promote', async () => {
      const jobId = '11111111-2222-4333-8444-555555555555';
      fineTuning.startFineTuningJob.mockResolvedValue({ jobId, status: 'running' });
      fineTuning.getFineTuningJobStatus.mockResolvedValue({ jobId, status: 'completed', checkpoints: [{ id: 'ckpt-1' }] });
      fineTuning.cancelFineTuningJob.mockReturnValue({ ok: true, jobId, status: 'cancelled' });
      fineTuning.promoteCheckpoint.mockResolvedValue({ id: 'voice-profile-1', kind: 'fine-tuned' });

      const startRes = await request(buildApp()).post('/api/voice/profiles/voice-profile-1/fine-tune/start').send({ epochs: 5 });
      expect(startRes.status).toBe(202);

      const statusRes = await request(buildApp()).get(`/api/voice/profiles/voice-profile-1/fine-tune/${jobId}`);
      expect(statusRes.status).toBe(200);
      expect(statusRes.body.status).toBe('completed');
      expect(fineTuning.getFineTuningJobStatus).toHaveBeenCalledWith(jobId, 'voice-profile-1');

      const cancelRes = await request(buildApp()).post(`/api/voice/profiles/voice-profile-1/fine-tune/${jobId}/cancel`).send({});
      expect(cancelRes.status).toBe(200);
      // Cancel is scoped to the profile in the URL, like status and promote.
      expect(fineTuning.cancelFineTuningJob).toHaveBeenCalledWith(jobId, 'voice-profile-1');

      const promoteRes = await request(buildApp()).post(`/api/voice/profiles/voice-profile-1/fine-tune/${jobId}/promote`).send({ checkpointId: 'ckpt-1' });
      expect(promoteRes.status).toBe(200);
      expect(promoteRes.body.profile.kind).toBe('fine-tuned');
    });

    it('lists a profile\'s fine-tuning jobs so the Voice Lab recovers them after a reload', async () => {
      const jobs = [{ id: '11111111-2222-4333-8444-555555555555', status: 'interrupted', checkpoints: [] }];
      fineTuning.listFineTuningJobs.mockResolvedValue(jobs);

      const res = await request(buildApp()).get('/api/voice/profiles/voice-profile-1/fine-tune');
      expect(res.status).toBe(200);
      expect(res.body).toEqual({ jobs });
      expect(fineTuning.listFineTuningJobs).toHaveBeenCalledWith('voice-profile-1');

      fineTuning.listFineTuningJobs.mockClear();
      const bad = await request(buildApp()).get('/api/voice/profiles/Not_A_Profile/fine-tune');
      expect(bad.status).toBe(400);
      expect(fineTuning.listFineTuningJobs).not.toHaveBeenCalled();
    });

    it('rejects a fine-tuning job id that could escape the profile directory', async () => {
      const res = await request(buildApp())
        .get('/api/voice/profiles/voice-profile-1/fine-tune/..%2F..%2Fother-profile');
      expect(res.status).toBe(400);
      expect(fineTuning.getFineTuningJobStatus).not.toHaveBeenCalled();
    });

    it('probes Qwen3 runtime status and downloads model on demand', async () => {
      qwen3TtsRuntime.getQwen3RuntimeStatus.mockResolvedValue({ ok: true, installed: true });
      qwen3TtsRuntime.downloadQwen3Model.mockResolvedValue({ ok: true, modelId: 'Qwen/Qwen3-TTS-12Hz-1.7B-VoiceDesign' });

      const statusRes = await request(buildApp()).get('/api/voice/qwen3/status');
      expect(statusRes.status).toBe(200);
      expect(statusRes.body.ok).toBe(true);

      const downloadRes = await request(buildApp()).post('/api/voice/qwen3/download-model').send({
        modelId: 'Qwen/Qwen3-TTS-12Hz-1.7B-VoiceDesign',
      });
      expect(downloadRes.status).toBe(200);
      expect(downloadRes.body.modelId).toBe('Qwen/Qwen3-TTS-12Hz-1.7B-VoiceDesign');
    });
  });

  describe('GET /api/voice/config', () => {
    it('returns the merged voice config', async () => {
      const res = await request(buildApp()).get('/api/voice/config');
      expect(res.status).toBe(200);
      expect(res.body.stt.engine).toBe('web-speech');
    });
  });

  describe('PUT /api/voice/config', () => {
    it('rejects unknown top-level keys via the Zod strict schema', async () => {
      const res = await request(buildApp()).put('/api/voice/config').send({ bogus: true });
      expect(res.status).toBe(400);
      expect(res.body.code).toBe('VALIDATION_ERROR');
      expect(res.body.error).toMatch(/Invalid voice config/);
      expect(config.updateVoiceConfig).not.toHaveBeenCalled();
    });

    it('rejects an invalid stt engine value', async () => {
      const res = await request(buildApp())
        .put('/api/voice/config')
        .send({ stt: { engine: 'cloud-api' } });
      expect(res.status).toBe(400);
      expect(res.body.code).toBe('VALIDATION_ERROR');
      expect(config.updateVoiceConfig).not.toHaveBeenCalled();
    });

    it('rejects an invalid tts engine value', async () => {
      const res = await request(buildApp())
        .put('/api/voice/config')
        .send({ tts: { engine: 'elevenlabs' } });
      expect(res.status).toBe(400);
      expect(config.updateVoiceConfig).not.toHaveBeenCalled();
    });

    it('saves a valid patch and runs reconcile', async () => {
      const next = { ...DEFAULT_CFG, enabled: true };
      config.updateVoiceConfig.mockResolvedValue(next);
      bootstrap.reconcile.mockResolvedValue({ skipped: 'web-speech', piperProvisioned: false });

      const res = await request(buildApp())
        .put('/api/voice/config')
        .send({ enabled: true });
      expect(res.status).toBe(200);
      expect(res.body.config.enabled).toBe(true);
      expect(res.body.reconciliation).toEqual({ skipped: 'web-speech', piperProvisioned: false });
      expect(config.updateVoiceConfig).toHaveBeenCalledWith({ enabled: true });
      expect(health.invalidateHealthCache).toHaveBeenCalled();
    });

    it('accepts a valid llm.fastPath patch (fast-resolution cascade)', async () => {
      config.updateVoiceConfig.mockResolvedValue({ ...DEFAULT_CFG });
      bootstrap.reconcile.mockResolvedValue({ skipped: true });
      const patch = { llm: { fastPath: { enabled: true, triggers: true, browserLlm: true, browser: { temperature: 0.5, topK: 4 } } } };
      const res = await request(buildApp()).put('/api/voice/config').send(patch);
      expect(res.status).toBe(200);
      expect(config.updateVoiceConfig).toHaveBeenCalledWith(patch);
    });

    it('accepts Qwen3-TTS engine and voice configuration', async () => {
      config.updateVoiceConfig.mockResolvedValue({ ...DEFAULT_CFG });
      bootstrap.reconcile.mockResolvedValue({ skipped: true });
      const patch = {
        tts: {
          engine: 'qwen3-tts',
          qwen3: { modelId: 'Qwen/Qwen3-TTS-12Hz-1.7B-VoiceDesign', voice: 'warm-narrator' },
        },
      };

      const res = await request(buildApp()).put('/api/voice/config').send(patch);

      expect(res.status).toBe(200);
      expect(config.updateVoiceConfig).toHaveBeenCalledWith(patch);
    });

    it('accepts a facetime.autoAnswer patch', async () => {
      config.updateVoiceConfig.mockResolvedValue({ ...DEFAULT_CFG });
      bootstrap.reconcile.mockResolvedValue({ skipped: true });
      const patch = { facetime: { autoAnswer: true } };
      const res = await request(buildApp()).put('/api/voice/config').send(patch);
      expect(res.status).toBe(200);
      expect(config.updateVoiceConfig).toHaveBeenCalledWith(patch);
    });

    it('rejects a non-boolean facetime.autoAnswer', async () => {
      const res = await request(buildApp())
        .put('/api/voice/config')
        .send({ facetime: { autoAnswer: 'yes' } });
      expect(res.status).toBe(400);
      expect(res.body.code).toBe('VALIDATION_ERROR');
      expect(config.updateVoiceConfig).not.toHaveBeenCalled();
    });

    it('rejects out-of-range fastPath.browser params', async () => {
      const res = await request(buildApp())
        .put('/api/voice/config')
        .send({ llm: { fastPath: { browser: { temperature: 9 } } } });
      expect(res.status).toBe(400);
      expect(res.body.code).toBe('VALIDATION_ERROR');
      expect(config.updateVoiceConfig).not.toHaveBeenCalled();
    });

    it.each([
      [true, {}, true],
      [true, { error: 'setup failed' }, false],
      [false, { skipped: true }, false],
    ])('clears retirement only after enabled successful reconciliation (%s, %j)', async (enabled, result, cleared) => {
      const migrated = { enabled, tts: { engine: 'piper', retiredEngine: 'kokoro' } };
      const settled = { enabled, tts: { engine: 'piper' } };
      config.updateVoiceConfig.mockReset();
      config.updateVoiceConfig.mockResolvedValueOnce(migrated).mockResolvedValueOnce(settled);
      bootstrap.reconcile.mockResolvedValue(result);
      const res = await request(buildApp()).put('/api/voice/config').send({ enabled });
      expect(res.status).toBe(200);
      expect(config.updateVoiceConfig).toHaveBeenCalledTimes(cleared ? 2 : 1);
      expect(res.body.config).toEqual(cleared ? settled : migrated);
      if (cleared) expect(config.updateVoiceConfig).toHaveBeenLastCalledWith({ tts: { retiredEngine: null } });
    });

    it('reports reconcile failures without 500-ing the route', async () => {
      config.updateVoiceConfig.mockResolvedValue({ ...DEFAULT_CFG, enabled: true });
      bootstrap.reconcile.mockRejectedValue(new Error('whisper-server not on PATH'));

      const res = await request(buildApp())
        .put('/api/voice/config')
        .send({ enabled: true });
      expect(res.status).toBe(200);
      expect(res.body.reconciliation).toEqual({ error: 'whisper-server not on PATH' });
    });
  });

  describe('GET /api/voice/status', () => {
    it('returns the expected shape', async () => {
      health.checkAll.mockResolvedValue({ whisper: { ok: true } });
      bootstrap.verifyBinaries.mockResolvedValue({ whisper: '/usr/bin/whisper-server', piper: null, piperRequired: false });
      bootstrap.verifyModels.mockReturnValue({ sttModel: '/p/model.bin', ttsVoice: 'kokoro:x' });

      const res = await request(buildApp()).get('/api/voice/status');
      expect(res.status).toBe(200);
      expect(res.body).toMatchObject({
        enabled: false,
        sttEngine: 'web-speech',
        ttsEngine: 'kokoro',
        services: { whisper: { ok: true } },
        binaries: { whisper: '/usr/bin/whisper-server' },
        models: { sttModel: '/p/model.bin' },
      });
    });
  });

  describe('GET /api/voice/voices', () => {
    it('delegates to listVoices with the requested engine and returns { engine, voices } shape', async () => {
      tts.listVoices.mockResolvedValue({ engine: 'kokoro', voices: [{ id: 'af_heart' }] });
      const res = await request(buildApp()).get('/api/voice/voices?engine=kokoro');
      expect(res.status).toBe(200);
      expect(res.body).toEqual({ engine: 'kokoro', voices: [{ id: 'af_heart' }] });
      expect(tts.listVoices).toHaveBeenCalledWith('kokoro');
    });

    it('ignores unknown engine query values', async () => {
      tts.listVoices.mockResolvedValue({ engine: 'kokoro', voices: [] });
      await request(buildApp()).get('/api/voice/voices?engine=elevenlabs');
      expect(tts.listVoices).toHaveBeenCalledWith(undefined);
    });
  });

  describe('POST /api/voice/piper/fetch', () => {
    it('rejects unknown piper voice ids with 400', async () => {
      piperVoices.findPiperVoice.mockReturnValue(null);
      const res = await request(buildApp())
        .post('/api/voice/piper/fetch')
        .send({ voice: 'en_US-fake-high' });
      expect(res.status).toBe(400);
      expect(res.body.error).toMatch(/unknown piper voice/);
      expect(bootstrap.downloadPiperVoice).not.toHaveBeenCalled();
    });

    it('downloads a valid voice and returns the result', async () => {
      piperVoices.findPiperVoice.mockReturnValue({ id: 'en_GB-jenny_dioco-medium' });
      bootstrap.downloadPiperVoice.mockResolvedValue({ skipped: true, voicePath: '~/.portos/voice/voices/en_GB-jenny_dioco-medium.onnx' });

      const res = await request(buildApp())
        .post('/api/voice/piper/fetch')
        .send({ voice: 'en_GB-jenny_dioco-medium' });
      expect(res.status).toBe(200);
      expect(res.body.voice).toBe('en_GB-jenny_dioco-medium');
      expect(res.body.skipped).toBe(true);
      expect(bootstrap.downloadPiperVoice).toHaveBeenCalled();
    });
  });

  describe('POST /api/voice/test', () => {
    it('requires text', async () => {
      const res = await request(buildApp()).post('/api/voice/test').send({});
      expect(res.status).toBe(400);
      expect(res.body.code).toBe('VALIDATION_ERROR');
    });

    it('returns WAV bytes on success', async () => {
      tts.synthesize.mockResolvedValue({ wav: Buffer.from([0x52, 0x49, 0x46, 0x46]), latencyMs: 123 });
      const res = await request(buildApp())
        .post('/api/voice/test')
        .send({ text: 'hello', voice: 'af_heart', engine: 'kokoro' });
      expect(res.status).toBe(200);
      expect(res.headers['content-type']).toMatch(/audio\/wav/);
      expect(res.headers['x-tts-latency-ms']).toBe('123');
    });

    it('maps ServerError UNKNOWN_VOICE from synthesize() to a 400 response', async () => {
      tts.synthesize.mockRejectedValue(new ServerError('voice id not in catalog', {
        status: 400,
        code: 'UNKNOWN_VOICE',
      }));
      const res = await request(buildApp())
        .post('/api/voice/test')
        .send({ text: 'hello', voice: 'nonexistent', engine: 'piper' });
      expect(res.status).toBe(400);
      expect(res.body.error).toBe('voice id not in catalog');
      expect(res.body.code).toBe('UNKNOWN_VOICE');
    });

    it('lets unrelated synth errors bubble to asyncHandler (500)', async () => {
      tts.synthesize.mockRejectedValue(new Error('synth crashed'));
      const res = await request(buildApp())
        .post('/api/voice/test')
        .send({ text: 'hello', voice: 'whatever', engine: 'piper' });
      expect(res.status).toBe(500);
    });
  });

  describe('POST /api/voice/speak', () => {
    it('rejects empty text via the Zod schema', async () => {
      const res = await request(buildApp()).post('/api/voice/speak').send({ text: '' });
      expect(res.status).toBe(400);
      expect(res.body.code).toBe('VALIDATION_ERROR');
      expect(proactiveSpeech.speakProactive).not.toHaveBeenCalled();
    });

    // Regression: schema trims before .min(1) so whitespace-only payloads
    // fail at the HTTP boundary with a 400, not at the downstream
    // speakProactive empty-text branch with a 200 {ok:false}.
    it.each(['   ', '\t', '\n', '   \t  \n  '])('rejects whitespace-only text "%s"', async (text) => {
      const res = await request(buildApp()).post('/api/voice/speak').send({ text });
      expect(res.status).toBe(400);
      expect(res.body.code).toBe('VALIDATION_ERROR');
      expect(proactiveSpeech.speakProactive).not.toHaveBeenCalled();
    });

    it('rejects invalid priority enum', async () => {
      const res = await request(buildApp())
        .post('/api/voice/speak')
        .send({ text: 'hi', priority: 'urgent' });
      expect(res.status).toBe(400);
      expect(res.body.code).toBe('VALIDATION_ERROR');
    });

    it('forwards text + priority to speakProactive and returns its result', async () => {
      proactiveSpeech.speakProactive.mockResolvedValue({ ok: true, latencyMs: 18 });
      const res = await request(buildApp())
        .post('/api/voice/speak')
        .send({ text: 'Heads up — meeting in five.', priority: 'high', source: 'cos' });
      expect(res.status).toBe(200);
      expect(res.body).toEqual({ ok: true, latencyMs: 18 });
      expect(proactiveSpeech.speakProactive).toHaveBeenCalledTimes(1);
      const [args] = proactiveSpeech.speakProactive.mock.calls[0];
      expect(args.text).toBe('Heads up — meeting in five.');
      expect(args.priority).toBe('high');
      expect(args.source).toBe('cos');
    });

    it('propagates suppression results (ok:false) without throwing', async () => {
      proactiveSpeech.speakProactive.mockResolvedValue({ ok: false, reason: 'quiet-hours' });
      const res = await request(buildApp()).post('/api/voice/speak').send({ text: 'late night ping' });
      expect(res.status).toBe(200);
      expect(res.body).toEqual({ ok: false, reason: 'quiet-hours' });
    });

    // Misconfiguration must surface as a real HTTP error so monitoring
    // sees it — a 200 ok:false here would silently mask a Socket.IO that
    // never attached.
    it('returns 500 VOICE_IO_UNAVAILABLE when io is not configured', async () => {
      proactiveSpeech.speakProactive.mockResolvedValue({ ok: true, latencyMs: 1 });
      const res = await request(buildApp({ io: null }))
        .post('/api/voice/speak')
        .send({ text: 'hi' });
      expect(res.status).toBe(500);
      expect(res.body.code).toBe('VOICE_IO_UNAVAILABLE');
      expect(proactiveSpeech.speakProactive).not.toHaveBeenCalled();
    });

    // Empty / whitespace-only source must NOT override speakProactive's
    // default of 'cos'. The schema transforms it to undefined so the
    // default kicks in.
    it.each(['', '   ', '\t'])('drops empty/whitespace source "%s" so default applies', async (source) => {
      proactiveSpeech.speakProactive.mockResolvedValue({ ok: true });
      const res = await request(buildApp())
        .post('/api/voice/speak')
        .send({ text: 'hi', source });
      expect(res.status).toBe(200);
      expect(proactiveSpeech.speakProactive).toHaveBeenCalledTimes(1);
      const [args] = proactiveSpeech.speakProactive.mock.calls[0];
      expect(args.source).toBeUndefined();
    });
  });

  describe('GET /api/voice/tts/status', () => {
    it('returns an inert compatibility snapshot for retired Kokoro', async () => {
      const res = await request(buildApp()).get('/api/voice/tts/status');
      expect(res.status).toBe(200);
      expect(res.body).toEqual({ kokoro: { state: 'lazy', loadedKey: null, retired: true } });
    });
  });

  describe('POST /api/voice/tts/unload', () => {
    it('keeps unload safe for cached clients', async () => {
      const res = await request(buildApp()).post('/api/voice/tts/unload');
      expect(res.status).toBe(200);
      expect(res.body).toEqual({ unloaded: false, retired: true });
    });
  });

  describe('POST /api/voice/whisper', () => {
    it('stops whisper and invalidates the health cache', async () => {
      const res = await request(buildApp()).post('/api/voice/whisper').send({ action: 'stop' });
      expect(res.status).toBe(200);
      expect(res.body).toEqual({ success: true, action: 'stop' });
      expect(bootstrap.stopWhisper).toHaveBeenCalledTimes(1);
      expect(bootstrap.startWhisper).not.toHaveBeenCalled();
      expect(health.invalidateHealthCache).toHaveBeenCalled();
    });

    it('starts whisper from the current config and returns the bootstrap result', async () => {
      bootstrap.startWhisper.mockResolvedValue({ restarted: true });
      const res = await request(buildApp()).post('/api/voice/whisper').send({ action: 'start' });
      expect(res.status).toBe(200);
      expect(res.body).toEqual({ success: true, action: 'start', restarted: true });
      expect(config.getVoiceConfig).toHaveBeenCalled();
      expect(bootstrap.startWhisper).toHaveBeenCalledWith(DEFAULT_CFG);
      expect(bootstrap.stopWhisper).not.toHaveBeenCalled();
      expect(health.invalidateHealthCache).toHaveBeenCalled();
    });

    it('rejects an invalid action with 400 without touching whisper', async () => {
      const res = await request(buildApp()).post('/api/voice/whisper').send({ action: 'restart' });
      expect(res.status).toBe(400);
      expect(res.body.code).toBe('VALIDATION_ERROR');
      expect(bootstrap.startWhisper).not.toHaveBeenCalled();
      expect(bootstrap.stopWhisper).not.toHaveBeenCalled();
    });
  });

  describe('FaceTime Audio control plane', () => {
    it('GET /api/voice/facetime/status reports setup without spawning the helper', async () => {
      facetimeBridge.checkSetup.mockResolvedValue({ ready: true });
      const res = await request(buildApp()).get('/api/voice/facetime/status');
      expect(res.status).toBe(200);
      expect(res.body).toEqual({ ready: true });
      expect(facetimeBridge.probe).not.toHaveBeenCalled();
    });

    it.each(['probe', 'call', 'hangup'])('POST /api/voice/facetime/%s dispatches to the matching bridge command', async (command) => {
      facetimeBridge[command].mockResolvedValue({ ok: true, command });
      const res = await request(buildApp()).post(`/api/voice/facetime/${command}`).send({});
      expect(res.status).toBe(200);
      expect(res.body).toEqual({ ok: true, command });
      expect(facetimeBridge[command]).toHaveBeenCalledTimes(1);
    });

    it('POST /api/voice/facetime/probe propagates a bridge failure as an error response', async () => {
      facetimeBridge.probe.mockRejectedValue(new ServerError('helper not installed', { status: 409 }));
      const res = await request(buildApp()).post('/api/voice/facetime/probe').send({});
      expect(res.status).toBe(409);
    });

    it('rejects an unexpected body field with 400 without touching the bridge', async () => {
      const res = await request(buildApp()).post('/api/voice/facetime/call').send({ extra: 'nope' });
      expect(res.status).toBe(400);
      expect(facetimeBridge.call).not.toHaveBeenCalled();
    });
  });
});

describe('Voice Studio HTTP contract', () => {
  it('validates controls before generation and emits only a payload-free invalidation after success', async () => {
    const { createStudioVoice } = await import('../services/voice/studio.js');
    const emit = vi.fn();
    const app = buildApp({ io: { emit } });
    createStudioVoice.mockResolvedValue({ id: 'voice-example', label: 'Example voice' });
    const invalid = await request(app).post('/api/voice/studio/design').send({ label: 'Example', instructions: 'Alto', text: 'Hello', pitchSemitones: 99 });
    expect(invalid.status).toBe(400);
    expect(createStudioVoice).not.toHaveBeenCalled();
    const valid = await request(app).post('/api/voice/studio/design').send({ label: 'Example', instructions: 'Alto', text: 'Hello' });
    expect(valid.status).toBe(201);
    expect(emit).toHaveBeenCalledWith('voice-studio:changed', {});
  });
});