Skip to content

Node-based terminal manager for AI coding agents — tmux-backed terminals and parallel agent sessions as draggable nodes on an infinite pan/zoom canvas. macOS, Linux, and a browser Server Edition.

11.0 KB
Raw Blame
import { beforeEach, describe, expect, it, vi } from 'vitest'
import { writeFileSync } from 'node:fs'
import {
  describeWhisperLoadError,
  isGgmlModelHeader,
  parseCpuFlags,
  pickWhisperBinary,
  SpeechService,
  whisperThreads,
  type WhisperEngineHandle,
} from './speech-service'
import { WhisperModelStore } from './whisper-models'
import { testTmpDir } from '../test-tmp'

describe('SpeechService', () => {
  let dir: string
  let models: WhisperModelStore
  const loads: string[] = []
  const freed: string[] = []

  function factory(result = 'hello world'): (p: string) => Promise<WhisperEngineHandle> {
    return async (modelPath: string) => {
      loads.push(modelPath)
      return {
        transcribe: vi.fn(async () => result),
        free: vi.fn(async () => { freed.push(modelPath) }),
      }
    }
  }
  const pcm = new Float32Array(16000)

  beforeEach(() => {
    dir = testTmpDir('svc-')
    models = new WhisperModelStore({ dir })
    loads.length = 0
    freed.length = 0
    writeFileSync(models.modelPath('tiny'), 'x') // "downloaded"
    writeFileSync(models.modelPath('base'), 'x')
  })

  it('transcribes with a free model without premium', async () => {
    const svc = new SpeechService({ models, isPremium: () => false, engineFactory: factory() })
    await expect(svc.transcribe(pcm, { model: 'tiny', language: 'auto' })).resolves.toBe('hello world')
  })

  it('rejects a Pro model without premium — core-side gate', async () => {
    const svc = new SpeechService({ models, isPremium: () => false, engineFactory: factory() })
    await expect(svc.transcribe(pcm, { model: 'base', language: 'auto' }))
      .rejects.toThrow(/requires nodeterm Pro/)
    expect(loads).toHaveLength(0) // never even loads the model
  })

  it('allows Pro models with premium', async () => {
    const svc = new SpeechService({ models, isPremium: () => true, engineFactory: factory() })
    await expect(svc.transcribe(pcm, { model: 'base', language: 'auto' })).resolves.toBe('hello world')
  })

  it('errors when the model is not downloaded', async () => {
    const svc = new SpeechService({ models, isPremium: () => true, engineFactory: factory() })
    await expect(svc.transcribe(pcm, { model: 'small', language: 'auto' }))
      .rejects.toThrow(/Download the/)
  })

  it('reuses one loaded engine and frees it on model switch', async () => {
    const svc = new SpeechService({ models, isPremium: () => true, engineFactory: factory() })
    await svc.transcribe(pcm, { model: 'tiny', language: 'auto' })
    await svc.transcribe(pcm, { model: 'tiny', language: 'auto' })
    expect(loads).toHaveLength(1)
    await svc.transcribe(pcm, { model: 'base', language: 'auto' })
    expect(loads).toHaveLength(2)
    expect(freed).toEqual([models.modelPath('tiny')])
  })

  it('maps an empty transcript to "No speech detected."', async () => {
    const svc = new SpeechService({ models, isPremium: () => true, engineFactory: factory('   ') })
    await expect(svc.transcribe(pcm, { model: 'tiny', language: 'auto' }))
      .rejects.toThrow('No speech detected.')
  })
})

describe('SpeechService.shutdown', () => {
  let dir: string
  let models: WhisperModelStore
  const freed: string[] = []
  const pcm = new Float32Array(16000)

  /** An engine whose transcribe is held open until the returned `release` is called —
   * this is the exact state (native transcribe in flight) that aborts the process if
   * the node env is torn down under it. */
  function blockingFactory(): {
    engineFactory: (p: string) => Promise<WhisperEngineHandle>
    release: () => void
    started: () => number
  } {
    let release = (): void => {}
    let started = 0
    const gate = new Promise<void>((r) => { release = r })
    return {
      started: () => started,
      release: () => release(),
      engineFactory: async (modelPath: string) => ({
        transcribe: async () => { started++; await gate; return 'hello world' },
        free: async () => { freed.push(modelPath) },
      }),
    }
  }

  beforeEach(() => {
    dir = testTmpDir('svc-')
    models = new WhisperModelStore({ dir })
    freed.length = 0
    writeFileSync(models.modelPath('tiny'), 'x')
  })

  it('frees the loaded engine', async () => {
    const svc = new SpeechService({
      models,
      isPremium: () => true,
      engineFactory: async (modelPath) => ({
        transcribe: async () => 'hi',
        free: async () => { freed.push(modelPath) },
      }),
    })
    await svc.transcribe(pcm, { model: 'tiny', language: 'auto' })
    await svc.shutdown()
    expect(freed).toEqual([models.modelPath('tiny')])
  })

  it('is a no-op when no engine was ever loaded', async () => {
    const svc = new SpeechService({ models, isPremium: () => true, engineFactory: async () => { throw new Error('nope') } })
    await expect(svc.shutdown()).resolves.toBeUndefined()
    expect(freed).toEqual([])
  })

  it('never frees while a transcribe is in flight — the crash guard', async () => {
    const { engineFactory, release } = blockingFactory()
    const svc = new SpeechService({ models, isPremium: () => true, engineFactory })
    const inFlight = svc.transcribe(pcm, { model: 'tiny', language: 'auto' })
    // Let the engine load and the native transcribe start.
    await new Promise((r) => setTimeout(r, 0))

    let settled = false
    const done = svc.shutdown().then(() => { settled = true })
    await new Promise((r) => setTimeout(r, 5))
    expect(freed).toEqual([]) // still transcribing: freeing here is what kills the app
    expect(settled).toBe(false)

    release()
    await expect(inFlight).resolves.toBe('hello world')
    await done
    expect(freed).toEqual([models.modelPath('tiny')]) // freed only after it settled
  })

  it('gives up after the timeout so a stuck transcribe cannot hold quit open', async () => {
    const { engineFactory, release } = blockingFactory()
    const svc = new SpeechService({ models, isPremium: () => true, engineFactory })
    void svc.transcribe(pcm, { model: 'tiny', language: 'auto' }).catch(() => {})
    await new Promise((r) => setTimeout(r, 0))
    await expect(svc.shutdown(10)).resolves.toBeUndefined()
    expect(freed).toEqual([]) // it bailed rather than freeing under a live transcribe
    release()
  })

  it('swallows a rejecting free() — quit must proceed regardless', async () => {
    const svc = new SpeechService({
      models,
      isPremium: () => true,
      engineFactory: async () => ({
        transcribe: async () => 'hi',
        free: async () => { throw new Error('whisper.free blew up') },
      }),
    })
    await svc.transcribe(pcm, { model: 'tiny', language: 'auto' })
    await expect(svc.shutdown()).resolves.toBeUndefined()
  })

  it('refuses new transcriptions afterwards instead of reloading the model', async () => {
    const loads: string[] = []
    const svc = new SpeechService({
      models,
      isPremium: () => true,
      engineFactory: async (modelPath) => {
        loads.push(modelPath)
        return { transcribe: async () => 'hi', free: async () => { freed.push(modelPath) } }
      },
    })
    await svc.shutdown()
    await expect(svc.transcribe(pcm, { model: 'tiny', language: 'auto' })).rejects.toThrow(/shutting down/)
    expect(loads).toEqual([])
  })
})

describe('describeWhisperLoadError', () => {
  it('recognizes MODULE_NOT_FOUND code', () => {
    const err = new Error('Cannot find module') as any
    err.code = 'MODULE_NOT_FOUND'
    expect(describeWhisperLoadError(err)).toBe('the smart-whisper module is not installed — run npm install')
  })

  it('recognizes ERR_MODULE_NOT_FOUND code', () => {
    const err = new Error('Module not found') as any
    err.code = 'ERR_MODULE_NOT_FOUND'
    expect(describeWhisperLoadError(err)).toBe('the smart-whisper module is not installed — run npm install')
  })

  it('recognizes NODE_MODULE_VERSION mismatch in message', () => {
    const err = new Error('The module was compiled against a different Node.js version')
    expect(describeWhisperLoadError(err)).toBe(
      'the native module was built for a different runtime — run npm run rebuild'
    )
  })

  it('recognizes NODE_MODULE_VERSION 115 in message', () => {
    const err = new Error('NODE_MODULE_VERSION 115')
    expect(describeWhisperLoadError(err)).toBe(
      'the native module was built for a different runtime — run npm run rebuild'
    )
  })

  it('returns the error message itself as fallback', () => {
    const err = new Error('boom')
    expect(describeWhisperLoadError(err)).toBe('boom')
  })
})

// whisper.cpp's loader dereferences a null context when a model file fails to load, taking the
// whole process down with SIGSEGV instead of rejecting — so a bad file must never reach it.
describe('isGgmlModelHeader', () => {
  it('accepts the ggml magic (0x67676d6c, "lmgg" on disk)', () => {
    expect(isGgmlModelHeader(Uint8Array.from([0x6c, 0x6d, 0x67, 0x67, 0x99]))).toBe(true)
  })

  it('rejects an HTML error page saved as a .bin', () => {
    expect(isGgmlModelHeader(Buffer.from('<!DOCTYPE html>'))).toBe(false)
  })

  it('rejects a truncated/empty file', () => {
    expect(isGgmlModelHeader(new Uint8Array(0))).toBe(false)
    expect(isGgmlModelHeader(Uint8Array.from([0x6c, 0x6d, 0x67]))).toBe(false)
  })

  it('rejects the big-endian byte order', () => {
    expect(isGgmlModelHeader(Uint8Array.from([0x67, 0x67, 0x6d, 0x6c]))).toBe(false)
  })
})

describe('whisper binary + threads (issue #1267)', () => {
  const avx2 = new Set(['sse2', 'avx', 'avx2', 'fma', 'f16c'])

  it('parses the flags line of /proc/cpuinfo', () => {
    const info = 'processor\t: 0\nmodel name\t: X\nflags\t\t: fpu sse2 avx avx2 fma f16c\nbugs\t\t: spectre\n'
    expect(parseCpuFlags(info)).toEqual(new Set(['fpu', 'sse2', 'avx', 'avx2', 'fma', 'f16c']))
    expect(parseCpuFlags('processor : 0\n').size).toBe(0)
  })

  it('picks the SIMD build only on linux x64 with every flag present', () => {
    expect(pickWhisperBinary({ platform: 'linux', arch: 'x64', cpuFlags: avx2 })).toBe('smart-whisper-avx2')
    for (const missing of ['avx', 'avx2', 'fma', 'f16c']) {
      const flags = new Set([...avx2].filter((f) => f !== missing))
      expect(pickWhisperBinary({ platform: 'linux', arch: 'x64', cpuFlags: flags })).toBe('smart-whisper')
    }
  })

  it('falls back to the baseline when the flags are unknown or the platform has no variant', () => {
    expect(pickWhisperBinary({ platform: 'linux', arch: 'x64', cpuFlags: null })).toBe('smart-whisper')
    expect(pickWhisperBinary({ platform: 'linux', arch: 'arm64', cpuFlags: avx2 })).toBe('smart-whisper')
    expect(pickWhisperBinary({ platform: 'darwin', arch: 'x64', cpuFlags: avx2 })).toBe('smart-whisper')
    expect(pickWhisperBinary({ platform: 'win32', arch: 'x64', cpuFlags: avx2 })).toBe('smart-whisper')
  })

  it('uses more threads than whisper.cpp\'s default 4, but never every CPU', () => {
    expect([1, 2, 4].map(whisperThreads)).toEqual([1, 2, 4])
    expect(whisperThreads(8)).toBe(6)
    expect(whisperThreads(12)).toBe(8)
    expect(whisperThreads(16)).toBe(8)
    expect(whisperThreads(64)).toBe(8)
    expect(whisperThreads(0)).toBe(1)
    expect(whisperThreads(Number.NaN)).toBe(1)
  })
})