fix(dictation): make the pre-record model check a cancellable pending start

- A toggle, Escape, stop or controller teardown during the model check now
  drops the pending start, and the check rechecks current voice settings
  before opening the mic.
- A press mid-download keeps the setup pill with its progress; only a model
  seen ready is cached as ready.
- A cancelled or failed update no longer deletes the old model files, and the
  renderer keeps offering the setup target it showed until the model is ready.
- The check is prefetched off the startup path and in-flight checks are shared,
  so the first press rarely waits on main.
This commit is contained in:
Jinjing
2026-11-10 00:16:49 -08:00
parent 5d8acbcde8
commit 59e06fcefb
7 changed files with 235 additions and 24 deletions
+53 -1
View File
@@ -1,4 +1,4 @@
import { mkdirSync, mkdtempSync, rmSync, truncateSync, writeFileSync } from 'node:fs'
import { existsSync, mkdirSync, mkdtempSync, rmSync, truncateSync, writeFileSync } from 'node:fs'
import { tmpdir } from 'node:os'
import { join } from 'node:path'
import { beforeEach, describe, expect, it, vi } from 'vitest'
@@ -76,6 +76,58 @@ describe('ModelManager', () => {
}
})
it('keeps the old files after a cancelled or failed update, so the update is offered again', async () => {
const dir = mkdtempSync(join(tmpdir(), 'orca-model-manager-'))
try {
const modelId = 'parakeet-tdt-0.6b-v2-int8'
const manager = new ModelManager(dir, openElectronSpeechDownloadRequest)
const modelDir = manager.getModelDir(modelId)
mkdirSync(modelDir, { recursive: true })
for (const [name, size] of [
['encoder.int8.onnx', 652_184_296],
['decoder.int8.onnx', 7_257_753],
['joiner.int8.onnx', 1_739_080],
['tokens.txt', 9_384]
] as const) {
writeFileSync(join(modelDir, name), '')
truncateSync(join(modelDir, name), size)
}
// oxlint-disable-next-line typescript/consistent-type-assertions -- SAFETY: the test stubs the protected file download step.
const internals = manager as unknown as {
downloadModelFiles: (
manifest: unknown,
stagingDir: string,
modelId: string,
isAborted: () => boolean,
signal: AbortSignal
) => Promise<void>
}
internals.downloadModelFiles = (_manifest, _stagingDir, _modelId, _isAborted, signal) =>
new Promise((_, reject) => {
signal.addEventListener('abort', () => reject(new Error('aborted')))
})
const cancelled = manager.downloadModel(modelId)
manager.cancelDownload(modelId)
await expect(cancelled).resolves.toBeUndefined()
expect((await manager.getModelState(modelId)).needsUpdate).toBe(true)
const failed = new ModelManager(dir, openElectronSpeechDownloadRequest)
// oxlint-disable-next-line typescript/consistent-type-assertions -- SAFETY: as above.
;(failed as unknown as typeof internals).downloadModelFiles = async () => {
throw new Error('network down')
}
await expect(failed.downloadModel(modelId)).rejects.toThrow('network down')
expect(existsSync(`${modelDir}.partial`)).toBe(false)
const state = await new ModelManager(dir, openElectronSpeechDownloadRequest).getModelState(
modelId
)
expect(state.needsUpdate).toBe(true)
} finally {
rmSync(dir, { recursive: true, force: true })
}
})
it('aborts an in-flight model download request when cancelled', async () => {
const dir = mkdtempSync(join(tmpdir(), 'orca-model-manager-'))
try {
+6 -1
View File
@@ -184,6 +184,8 @@ export class ModelManager extends SpeechModelDownloadTransport {
}
}
this.activeDownloads.set(modelId, handle)
// Until the swap starts, modelDir holds only the old files, which are how the update is found again.
let replacingModelDir = false
try {
await this.downloadModelFiles(
@@ -198,6 +200,7 @@ export class ModelManager extends SpeechModelDownloadTransport {
return
}
replacingModelDir = true
await rm(modelDir, { recursive: true, force: true })
await rename(stagingDir, modelDir)
this.updateState(modelId, 'ready')
@@ -209,7 +212,9 @@ export class ModelManager extends SpeechModelDownloadTransport {
console.error('[speech] Model download failed:', modelId, err)
this.updateState(modelId, 'error', undefined, String(err))
}
removeModelDownloadFiles(modelDir, stagingDir, legacyArchivePath)
if (replacingModelDir) {
removeModelDownloadFiles(modelDir, stagingDir, legacyArchivePath)
}
if (!aborted) {
// Settings awaits real failures; cancellation stays quiet.
throw err
@@ -76,8 +76,8 @@ export function DictationController() {
// A new recording gets a fresh pill (timer and all); a retry keeps the one it failed in.
const [recordingKey, setRecordingKey] = useState(0)
const isIdle = useCallback(() => sessionRef.current.phase === 'idle', [])
const { setupTarget, closeSetup, invalidatePendingStart, readyToRecord } =
useDictationSpeechModelSetup(isIdle, setPillAnchor)
const { setupTarget, closeSetup, hasPendingStart, invalidatePendingStart, readyToRecord } =
useDictationSpeechModelSetup(settings?.voice, isIdle, setPillAnchor)
const queuedSend = useDictationQueuedSend(sessionRef, keptRef)
const { clear: clearQueuedSend, release: releaseQueuedSend } = queuedSend
@@ -357,12 +357,17 @@ export function DictationController() {
}, [settings, dispatch, finishDictationSession, showFailure])
const toggleDictation = useCallback(() => {
// A second press while the model check runs takes the first one back.
if (hasPendingStart()) {
invalidatePendingStart()
return
}
if (isDictationUnderway(sessionRef.current.phase)) {
void stopDictation()
} else {
void startDictation()
}
}, [startDictation, stopDictation])
}, [startDictation, stopDictation, hasPendingStart, invalidatePendingStart])
useDictationControls(settings?.voice, dictationState, {
start: () => void startDictation(),
@@ -373,7 +378,9 @@ export function DictationController() {
enterQueues: (event) => queuedSend.queueTerminalEnter(event.target),
// The error pill leaves Esc to Settings and dialogs; only its ✕ discards the recording.
escCancels: () =>
isDictationUnderway(sessionRef.current.phase) || sessionRef.current.phase === 'stopping'
hasPendingStart() ||
isDictationUnderway(sessionRef.current.phase) ||
sessionRef.current.phase === 'stopping'
})
const { isHolding } = useHoldDictationGesture({
@@ -123,4 +123,68 @@ describe('dictation shortcut and the speech model update', () => {
expect(startCapture).toHaveBeenCalledOnce()
expect(startDictation).toHaveBeenCalledWith('parakeet', {}, expect.any(String))
})
it('drops a press whose model check is still running when the press is taken back', async () => {
modelStates = [{ id: 'parakeet', status: 'ready' }]
let releaseStates = (): void => {}
getModelStates.mockImplementationOnce(
() => new Promise((resolve) => (releaseStates = () => resolve(modelStates)))
)
await mountAndPress()
// A second toggle cancels instead of launching another check.
await act(async () => pressShortcut())
await act(async () => releaseStates())
expect(getModelStates).toHaveBeenCalledOnce()
expect(startCapture).not.toHaveBeenCalled()
})
it('lets Escape cancel a press whose model check is still running', async () => {
modelStates = [{ id: 'parakeet', status: 'ready' }]
let releaseStates = (): void => {}
getModelStates.mockImplementationOnce(
() => new Promise((resolve) => (releaseStates = () => resolve(modelStates)))
)
await mountAndPress()
await act(async () => {
document.dispatchEvent(new KeyboardEvent('keydown', { key: 'Escape', bubbles: true }))
})
await act(async () => releaseStates())
expect(startCapture).not.toHaveBeenCalled()
})
it('never opens the mic when voice is turned off while the check runs', async () => {
modelStates = [{ id: 'parakeet', status: 'ready' }]
let releaseStates = (): void => {}
getModelStates.mockImplementationOnce(
() => new Promise((resolve) => (releaseStates = () => resolve(modelStates)))
)
await mountAndPress()
await act(async () => root.render(null))
await act(async () => releaseStates())
expect(startCapture).not.toHaveBeenCalled()
expect(startDictation).not.toHaveBeenCalled()
})
it('keeps the setup pill, not the mic, when pressed mid-download', async () => {
modelStates = [{ id: 'parakeet', status: 'downloading', progress: 0.4 }]
await mountAndPress()
await act(async () => pressShortcut())
expect(document.querySelector('[data-testid="dictation-setup-pill"]')).not.toBeNull()
expect(startCapture).not.toHaveBeenCalled()
})
it('offers the update again after a download was cancelled', async () => {
modelStates = [{ id: 'parakeet', status: 'not-downloaded', needsUpdate: true }]
await mountAndPress()
// The cancelled download's state lost its needsUpdate.
modelStates = [{ id: 'parakeet', status: 'not-downloaded' }]
await act(async () => pressShortcut())
expect(document.querySelector('[data-testid="dictation-setup-pill"]')).not.toBeNull()
expect(startCapture).not.toHaveBeenCalled()
})
})
@@ -3,6 +3,7 @@ import { isPairedWebClientWindow } from '@/lib/desktop-window-chrome'
import type { SpeechModelManifest, VoiceSettings } from '../../../../shared/speech-types'
import {
findSpeechModelUpdateTarget,
isSpeechModelReady,
type SpeechModelUpdateTarget
} from './speech-model-update-target'
@@ -21,27 +22,56 @@ export function loadSpeechCatalog(): Promise<SpeechModelManifest[]> {
return catalogRequest
}
// A model found up to date stays so: legacy or retired files never come back, so later presses skip the check.
const upToDateModelIds = new Set<string>()
// Only a model seen ready stays so: legacy or retired files never come back, so later presses skip the check.
const readyModelIds = new Set<string>()
// What the pill offered stays offered until the model is ready, so a cancelled or failed download can resume.
const offeredTargets = new Map<string, SpeechModelUpdateTarget>()
// A press during a prefetch joins it instead of asking main again.
const inFlightChecks = new Map<string, Promise<SpeechModelUpdateTarget | null>>()
type CheckedVoice = Pick<VoiceSettings, 'enabled' | 'sttModel'>
/** True when no check is needed before recording with this model. */
export function isSpeechModelKnownReady(voice: CheckedVoice): boolean {
return !voice.enabled || readyModelIds.has(voice.sttModel) || isPairedWebClientWindow()
}
/** The download the selected model needs before it can dictate, checked before any mic capture. */
export async function checkSpeechModelUpdate(
voice: Pick<VoiceSettings, 'enabled' | 'sttModel'>
export function checkSpeechModelUpdate(
voice: CheckedVoice
): Promise<SpeechModelUpdateTarget | null> {
// Why skip paired web clients: the models live on the host, whose own window shows this.
if (!voice.enabled || upToDateModelIds.has(voice.sttModel) || isPairedWebClientWindow()) {
return null
if (isSpeechModelKnownReady(voice)) {
return Promise.resolve(null)
}
const modelId = voice.sttModel
let check = inFlightChecks.get(modelId)
if (!check) {
check = runCheck(voice).finally(() => inFlightChecks.delete(modelId))
inFlightChecks.set(modelId, check)
}
return check
}
async function runCheck(voice: CheckedVoice): Promise<SpeechModelUpdateTarget | null> {
try {
const [catalog, states] = await Promise.all([
loadSpeechCatalog(),
window.api.speech.getModelStates()
])
useAppStore.getState().setModelStates(states)
const target = findSpeechModelUpdateTarget(voice, catalog, states)
// An empty catalog proves nothing, so it isn't remembered as up to date.
if (!target && catalog.length > 0) {
upToDateModelIds.add(voice.sttModel)
const selected = states.find((state) => state.id === voice.sttModel)
if (isSpeechModelReady(selected)) {
readyModelIds.add(voice.sttModel)
offeredTargets.delete(voice.sttModel)
return null
}
const target =
findSpeechModelUpdateTarget(voice, catalog, states) ??
offeredTargets.get(voice.sttModel) ??
null
if (target) {
offeredTargets.set(voice.sttModel, target)
}
return target
} catch {
@@ -52,5 +82,7 @@ export async function checkSpeechModelUpdate(
export function resetSpeechModelUpdateCheckForTests(): void {
catalogRequest = null
upToDateModelIds.clear()
readyModelIds.clear()
offeredTargets.clear()
inFlightChecks.clear()
}
@@ -33,5 +33,18 @@ export function findSpeechModelUpdateTarget(
const retired = catalog.find(
(m) => m.replacedBy === model.id && stateOf(m.id)?.status === 'ready'
)
return retired ? { model, retired } : null
if (retired) {
return { model, retired }
}
// A download in flight has no needsUpdate, yet the model still can't dictate; the pill shows its progress.
return isSpeechModelDownloading(selected) ? { model } : null
}
export function isSpeechModelDownloading(state: SpeechModelState | undefined): boolean {
return state?.status === 'downloading' || state?.status === 'extracting'
}
/** Only a ready model with no pending update is known to dictate. */
export function isSpeechModelReady(state: SpeechModelState | undefined): boolean {
return state?.status === 'ready' && !state.needsUpdate
}
@@ -1,17 +1,24 @@
import { useCallback, useRef, useState } from 'react'
import { useCallback, useEffect, useRef, useState } from 'react'
import { useAppStore } from '@/store'
import type { VoiceSettings } from '../../../../shared/speech-types'
import { captureInsertionTarget } from './dictation-insertion-target'
import { dictationPillAnchorFor, type DictationPillAnchor } from './dictation-pill-anchor'
import { checkSpeechModelUpdate } from './speech-model-update-check'
import { checkSpeechModelUpdate, isSpeechModelKnownReady } from './speech-model-update-check'
import type { SpeechModelUpdateTarget } from './speech-model-update-target'
type CheckedVoice = Pick<VoiceSettings, 'enabled' | 'sttModel'>
const PREFETCH_DELAY_MS = 1500
/** The pill's offer of the download the selected model needs, made in place of recording. */
export function useDictationSpeechModelSetup(
voice: CheckedVoice | undefined,
isIdle: () => boolean,
setPillAnchor: (anchor: DictationPillAnchor | null) => void
) {
const [setupTarget, setSetupTarget] = useState<SpeechModelUpdateTarget | null>(null)
// A stop or cancel while the check runs means that press no longer wants a recording.
// The press whose model check is still running; a stop, cancel, toggle or teardown drops it.
const pendingStartRef = useRef<number | null>(null)
const startRequestRef = useRef(0)
const closeSetup = useCallback(() => {
@@ -21,18 +28,49 @@ export function useDictationSpeechModelSetup(
}
}, [isIdle, setPillAnchor])
const hasPendingStart = useCallback(() => pendingStartRef.current !== null, [])
const invalidatePendingStart = useCallback(() => {
startRequestRef.current += 1
pendingStartRef.current = null
}, [])
// An unmounted controller (voice turned off) must never open the mic from a check it started.
useEffect(() => invalidatePendingStart, [invalidatePendingStart])
// Warms the check off the startup path, so the first press records without waiting on main.
const enabled = voice?.enabled === true
const sttModel = voice?.sttModel
useEffect(() => {
if (!enabled || !sttModel || isSpeechModelKnownReady({ enabled, sttModel })) {
return
}
const timer = window.setTimeout(
() => void checkSpeechModelUpdate({ enabled, sttModel }),
PREFETCH_DELAY_MS
)
return () => window.clearTimeout(timer)
}, [enabled, sttModel])
/** Checked before the mic opens, so a model the engine can't load never records; true to go on. */
const readyToRecord = useCallback(
async (voice: Pick<VoiceSettings, 'enabled' | 'sttModel'>): Promise<boolean> => {
async (requested: CheckedVoice): Promise<boolean> => {
if (isSpeechModelKnownReady(requested)) {
setSetupTarget(null)
return true
}
const request = ++startRequestRef.current
const target = await checkSpeechModelUpdate(voice)
pendingStartRef.current = request
const target = await checkSpeechModelUpdate(requested)
if (request !== startRequestRef.current) {
return false
}
pendingStartRef.current = null
// Settings may have turned voice off or switched models while the check ran.
const current = useAppStore.getState().settings?.voice
if (!current?.enabled || current.sttModel !== requested.sttModel) {
return false
}
if (target) {
if (isIdle()) {
setPillAnchor(dictationPillAnchorFor(captureInsertionTarget()))
@@ -46,5 +84,5 @@ export function useDictationSpeechModelSetup(
[isIdle, setPillAnchor]
)
return { setupTarget, closeSetup, invalidatePendingStart, readyToRecord }
return { setupTarget, closeSetup, hasPendingStart, invalidatePendingStart, readyToRecord }
}