Skip to content

armgit / cindy

Public Imported from GitHub
0

Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。

fix(voice): 明确账户限流提示并停止无效供应商切换 (#5102)

Dash8fc8bc40b802
diff --git a/apps/desktop/help-knowledge/voice-input.md b/apps/desktop/help-knowledge/voice-input.md
index bd6d716513..edf6f2b7ba 100644
--- a/apps/desktop/help-knowledge/voice-input.md
+++ b/apps/desktop/help-knowledge/voice-input.md
@@ -35,6 +35,7 @@ Voice input lets you dictate instead of typing. Hold a shortcut, talk, release
**Notes:**
+- If Cindy reports "Too many voice requests", wait a moment before starting another recording. Cindy voice providers share this account limit, so automatic provider switching stops for that attempt. The limit does not mark the providers as faulty or impose a provider cooldown.
- Push-and-hold is the primary activation mode; **Fast activation** changes the warm-up behavior, not the trigger itself.
- If the global shortcut fails to register (e.g. it's already taken by another app like an IME), you'll see a warning in the page; pick a different shortcut.
- If the connection drops mid-dictation, the text recognized up to that point is kept — it lands in the composer (or stays in the overlay with a copy button) alongside the error, instead of being discarded. That salvaged text is raw ASR output: refinement needs the connection that just failed, so it is skipped.
diff --git a/apps/desktop/src/main/voice-input/FallbackAsrProvider.ts b/apps/desktop/src/main/voice-input/FallbackAsrProvider.ts
index 44e22f3ee0..c044015087 100644
--- a/apps/desktop/src/main/voice-input/FallbackAsrProvider.ts
+++ b/apps/desktop/src/main/voice-input/FallbackAsrProvider.ts
@@ -6,6 +6,7 @@ import {
markVoiceInputProviderSuccess,
} from './VoiceInputProviderHealth.js';
import type { VoiceInputProviderKind } from './voiceInputAsrConfig.js';
+import { isVoiceInputStartRateLimited } from './voiceInputStartError.js';
const log = createLogger('voice-input:asr-fallback');
@@ -32,6 +33,8 @@ export type FallbackAsrCandidate = {
export type FallbackAsrProviderOptions = {
/** Delay between launching unresolved candidates. Defaults to 1.5s; null disables hedging. */
hedgeDelayMs?: number | null;
+ /** Managed candidates share an account quota; switching cannot bypass that limit. */
+ sharedAccountRateLimit?: boolean;
};
type CandidateAttemptResult = {
@@ -73,6 +76,7 @@ type CandidateAttempt = {
export class FallbackAsrProvider implements AsrProvider {
private readonly candidates: FallbackAsrCandidate[];
private readonly hedgeDelayMs: number | null;
+ private readonly sharedAccountRateLimit: boolean;
private active: AsrProvider | null = null;
private activeKind: VoiceInputProviderKind | null = null;
private readonly eventCallbacks: Array<(event: AsrEvent) => void> = [];
@@ -95,6 +99,7 @@ export class FallbackAsrProvider implements AsrProvider {
throw new Error('FallbackAsrProvider requires at least one ASR provider candidate.');
}
this.candidates = candidates;
+ this.sharedAccountRateLimit = options.sharedAccountRateLimit ?? false;
this.hedgeDelayMs = options.hedgeDelayMs === null
? null
: Math.max(0, options.hedgeDelayMs ?? DEFAULT_HEDGE_DELAY_MS);
@@ -163,6 +168,18 @@ export class FallbackAsrProvider implements AsrProvider {
}
this.attempts.delete(result.index);
if (result.status === 'failed') {
+ if (this.isSharedAccountRateLimit(result.error)) {
+ // A concurrent winner takes precedence over a losing attempt's error.
+ if (this.active) return;
+ // Reuse disposal to cancel pending/late candidates before returning
+ // the original error, without waiting for network cleanup to finish.
+ void this.dispose();
+ log.info('shared voice account rate limit reached; skipping ASR fallback', {
+ provider: this.candidates[result.index].kind,
+ phase: result.phase ?? 'start',
+ });
+ throw result.error;
+ }
lastError = result.error;
const candidate = this.candidates[result.index];
failures.push(this.handleCandidateFailure(
@@ -249,6 +266,9 @@ export class FallbackAsrProvider implements AsrProvider {
try {
await provider.recover!();
} catch (error) {
+ // Reconnecting allocates another managed session and can hit the same
+ // account quota. It is not evidence that this provider is unhealthy.
+ if (this.isSharedAccountRateLimit(error)) throw error;
// Recovery exhausted mid-session: the run ends as today, but the sticky
// cooldown makes the NEXT dictation start from the following candidate.
markVoiceInputProviderFailure(
@@ -260,6 +280,10 @@ export class FallbackAsrProvider implements AsrProvider {
}
}
+ private isSharedAccountRateLimit(error: unknown): boolean {
+ return this.sharedAccountRateLimit && isVoiceInputStartRateLimited(error);
+ }
+
async dispose(): Promise<void> {
this.disposed = true;
for (const attempt of this.attempts.values()) attempt.cancelled = true;
diff --git a/apps/desktop/src/main/voice-input/__tests__/FallbackAsrProvider.test.ts b/apps/desktop/src/main/voice-input/__tests__/FallbackAsrProvider.test.ts
index 0a08ed2168..610fb98b57 100644
--- a/apps/desktop/src/main/voice-input/__tests__/FallbackAsrProvider.test.ts
+++ b/apps/desktop/src/main/voice-input/__tests__/FallbackAsrProvider.test.ts
@@ -1,6 +1,9 @@
import { beforeEach, describe, expect, it, vi } from 'vitest';
import type { AsrEvent, AsrProvider } from '@cindy/voice-input-core';
+import { VoiceInputController, VoiceTimelineLogger } from '@cindy/voice-input-core';
+import { getVoiceInputRateLimitMessage } from '../voiceInputStartError.js';
+import { VOICE_INPUT_RATE_LIMITED_MESSAGE } from '../../../shared/voiceInputErrors.js';
import { FallbackAsrProvider, type FallbackAsrCandidate } from '../FallbackAsrProvider.js';
import {
@@ -56,11 +59,170 @@ function candidate(kind: string, provider: MockAsrProvider | (() => Promise<AsrP
const chunk = (byte: number): ArrayBuffer => new Uint8Array([byte]).buffer;
+const accountRateLimit = (): Error => Object.assign(new Error('语音请求过于频繁'), {
+ code: 'RATE_LIMITED',
+ statusCode: 429,
+});
+
describe('FallbackAsrProvider', () => {
beforeEach(() => {
resetVoiceInputProviderHealthForTests();
});
+ it.each([
+ { managed: true, error: accountRateLimit(), limited: true },
+ { managed: true, error: new Error('network down'), limited: false },
+ { managed: false, error: accountRateLimit(), limited: false },
+ ])('preserves the recovery cause and recognized text through the controller (%#)', async ({ managed, error, limited }) => {
+ const primary = makeMockProvider({ recover: async () => { throw error; } });
+ const backup = makeMockProvider();
+ const fallback = new FallbackAsrProvider([
+ candidate('litellm-volcengine-sauc-asr', primary),
+ candidate('litellm-qwen3-asr-flash-realtime', backup),
+ ], { sharedAccountRateLimit: managed });
+ const onError = vi.fn();
+ const submitted: string[] = [];
+ const controller = new VoiceInputController({
+ asr: fallback,
+ logger: new VoiceTimelineLogger(),
+ recoveryErrorMessage: managed ? getVoiceInputRateLimitMessage : undefined,
+ callbacks: {
+ onDraftChanged: () => {},
+ onSubmitted: (text, segment) => {
+ submitted.push(text);
+ return { id: 'range', segmentIds: [segment.id], startOffset: 0, endOffset: text.length, userTouched: false };
+ },
+ onError,
+ },
+ });
+ try {
+ await controller.start();
+ primary.emit({ type: 'partial', text: 'keep these words', at: Date.now() });
+ primary.emit({ type: 'disconnected', at: Date.now() });
+ await vi.waitFor(() => expect(onError).toHaveBeenCalledOnce());
+ expect(onError).toHaveBeenCalledWith(
+ limited ? VOICE_INPUT_RATE_LIMITED_MESSAGE : 'Voice input stopped receiving recognition. Please try again.',
+ limited ? undefined : 'recognition_stalled',
+ { transcriptKept: true },
+ );
+ expect(submitted).toEqual(['keep these words']);
+ expect(backup.start).not.toHaveBeenCalled();
+ expect(isVoiceInputProviderCoolingDown('asr', 'litellm-volcengine-sauc-asr')).toBe(!limited);
+ } finally {
+ await controller.cancel();
+ await fallback.dispose();
+ }
+ });
+
+ it.each(['create', 'start'] as const)('stops on shared account rate limits during %s without penalizing providers', async (phase) => {
+ const error = accountRateLimit();
+ const first = makeMockProvider({ startError: error });
+ const createBackup = vi.fn(async () => makeMockProvider());
+ const fallback = new FallbackAsrProvider([
+ candidate('litellm-volcengine-sauc-asr', phase === 'create' ? async () => { throw error; } : first),
+ candidate('litellm-qwen3-asr-flash-realtime', createBackup),
+ ], { hedgeDelayMs: null, sharedAccountRateLimit: true });
+
+ await expect(fallback.start()).rejects.toBe(error);
+
+ expect(createBackup).not.toHaveBeenCalled();
+ expect(fallback.activeProviderKind).toBeNull();
+ expect(isVoiceInputProviderCoolingDown('asr', 'litellm-volcengine-sauc-asr')).toBe(false);
+ expect(isVoiceInputProviderCoolingDown('asr', 'litellm-qwen3-asr-flash-realtime')).toBe(false);
+ if (phase === 'start') await vi.waitFor(() => expect(first.dispose).toHaveBeenCalledOnce());
+
+ // A subsequent user attempt can use the primary immediately, without
+ // waiting for a provider cooldown introduced by this failed run.
+ const retry = new FallbackAsrProvider([
+ candidate('litellm-volcengine-sauc-asr', makeMockProvider()),
+ ], { sharedAccountRateLimit: true });
+ await retry.start();
+ expect(retry.activeProviderKind).toBe('litellm-volcengine-sauc-asr');
+ });
+
+ it('preserves earlier real failures but surfaces the later account rate limit unchanged', async () => {
+ const error = accountRateLimit();
+ const third = vi.fn(async () => makeMockProvider());
+ const fallback = new FallbackAsrProvider([
+ candidate('litellm-volcengine-sauc-asr', makeMockProvider({ startError: new Error('connection refused') })),
+ candidate('litellm-qwen3-asr-flash-realtime', makeMockProvider({ startError: error })),
+ candidate('litellm-gpt-realtime-whisper', third),
+ ], { hedgeDelayMs: null, sharedAccountRateLimit: true });
+
+ await expect(fallback.start()).rejects.toBe(error);
+ expect(third).not.toHaveBeenCalled();
+ expect(isVoiceInputProviderCoolingDown('asr', 'litellm-volcengine-sauc-asr')).toBe(true);
+ expect(isVoiceInputProviderCoolingDown('asr', 'litellm-qwen3-asr-flash-realtime')).toBe(false);
+ });
+
+ it.each([
+ { sharedAccountRateLimit: false, error: accountRateLimit() },
+ { sharedAccountRateLimit: true, error: new Error('Upstream handshake failed: HTTP 429') },
+ ])('keeps independent provider failures eligible for fallback (%#)', async ({ sharedAccountRateLimit, error }) => {
+ const backup = makeMockProvider();
+ const fallback = new FallbackAsrProvider([
+ candidate('litellm-volcengine-sauc-asr', makeMockProvider({ startError: error })),
+ candidate('litellm-qwen3-asr-flash-realtime', backup),
+ ], { hedgeDelayMs: null, sharedAccountRateLimit });
+
+ await fallback.start();
+ expect(backup.start).toHaveBeenCalledOnce();
+ expect(isVoiceInputProviderCoolingDown('asr', 'litellm-volcengine-sauc-asr')).toBe(true);
+ });
+
+ it('does not penalize the active provider when recovery hits the shared account quota', async () => {
+ const error = accountRateLimit();
+ const backup = makeMockProvider();
+ const fallback = new FallbackAsrProvider([
+ candidate('litellm-volcengine-sauc-asr', makeMockProvider({ recover: async () => { throw error; } })),
+ candidate('litellm-qwen3-asr-flash-realtime', backup),
+ ], { sharedAccountRateLimit: true });
+
+ await fallback.start();
+ await expect(fallback.recover!()).rejects.toBe(error);
+ expect(backup.start).not.toHaveBeenCalled();
+ expect(isVoiceInputProviderCoolingDown('asr', 'litellm-volcengine-sauc-asr')).toBe(false);
+ });
+
+ it.each(['create', 'start'] as const)('cleans up a hedged candidate that finishes %s after an account rate limit', async (phase) => {
+ let rejectPrimary!: (error: Error) => void;
+ let releaseBackup!: () => void;
+ const primary = makeMockProvider({
+ startGate: new Promise<void>((_resolve, reject) => { rejectPrimary = reject; }),
+ });
+ const backupGate = new Promise<void>((resolve) => { releaseBackup = resolve; });
+ const backup = makeMockProvider({ startGate: phase === 'start' ? backupGate : undefined });
+ const createBackup = vi.fn(async () => {
+ if (phase === 'create') await backupGate;
+ return backup;
+ });
+ const third = vi.fn(async () => makeMockProvider());
+ const fallback = new FallbackAsrProvider([
+ candidate('litellm-volcengine-sauc-asr', primary),
+ candidate('litellm-qwen3-asr-flash-realtime', createBackup),
+ candidate('litellm-gpt-realtime-whisper', third),
+ ], { hedgeDelayMs: 1_000, sharedAccountRateLimit: true });
+ vi.useFakeTimers();
+ try {
+ const error = accountRateLimit();
+ const result = fallback.start().catch((failure: unknown) => failure);
+ await vi.advanceTimersByTimeAsync(1_000);
+ expect(createBackup).toHaveBeenCalledOnce();
+ rejectPrimary(error);
+ expect(await result).toBe(error);
+ releaseBackup();
+ await vi.advanceTimersByTimeAsync(5_000);
+ expect(backup.dispose).toHaveBeenCalledOnce();
+ expect(third).not.toHaveBeenCalled();
+ expect(fallback.activeProviderKind).toBeNull();
+ expect(isVoiceInputProviderCoolingDown('asr', 'litellm-volcengine-sauc-asr')).toBe(false);
+ expect(isVoiceInputProviderCoolingDown('asr', 'litellm-qwen3-asr-flash-realtime')).toBe(false);
+ if (phase === 'create') expect(backup.start).not.toHaveBeenCalled();
+ } finally {
+ vi.useRealTimers();
+ }
+ });
+
it('uses the first candidate when it starts successfully and forwards its events', async () => {
const first = makeMockProvider();
const second = makeMockProvider();
diff --git a/apps/desktop/src/main/voice-input/__tests__/voiceInputStartError.test.ts b/apps/desktop/src/main/voice-input/__tests__/voiceInputStartError.test.ts
new file mode 100644
index 0000000000..631d950d1d
--- /dev/null
+++ b/apps/desktop/src/main/voice-input/__tests__/voiceInputStartError.test.ts
@@ -0,0 +1,30 @@
+import { describe, expect, it } from 'vitest';
+import { isVoiceInputStartRateLimited } from '../voiceInputStartError.js';
+
+function apiError(code = 'RATE_LIMITED', statusCode = 429): Error {
+ return Object.assign(new Error('upstream details must not determine the message'), { code, statusCode });
+}
+
+describe('voice input start rate-limit message', () => {
+ it('recognizes a structured session rate limit', () => {
+ expect(isVoiceInputStartRateLimited(apiError())).toBe(true);
+ });
+
+ it('recognizes the three-provider aggregate produced by ASR fallback', () => {
+ expect(isVoiceInputStartRateLimited(new AggregateError([
+ apiError(), apiError(), apiError(),
+ ], 'All 3 voice input ASR providers failed to start'))).toBe(true);
+ });
+
+ it.each([
+ new AggregateError([apiError(), new Error('connection timed out')]),
+ new AggregateError([]),
+ apiError('INTERNAL_ERROR', 503),
+ apiError('RATE_LIMITED', 500),
+ apiError('QUOTA_EXCEEDED', 429),
+ new Error('RATE_LIMITED 429 语音请求过于频繁'),
+ null,
+ ])('keeps unknown, mixed, and unstructured failures generic (%#)', (error) => {
+ expect(isVoiceInputStartRateLimited(error)).toBe(false);
+ });
+});
diff --git a/apps/desktop/src/main/voice-input/index.ts b/apps/desktop/src/main/voice-input/index.ts
index 92e220e002..b774b5b932 100644
--- a/apps/desktop/src/main/voice-input/index.ts
+++ b/apps/desktop/src/main/voice-input/index.ts
@@ -22,6 +22,7 @@ import {
type VoiceTimelineEvent,
} from '@cindy/voice-input-core';
import { createLogger } from '../logger.js';
+import { getVoiceInputRateLimitMessage } from './voiceInputStartError.js';
import {
isProviderModelRouteDisabled,
isUtilityRouteDisabled,
@@ -2215,6 +2216,7 @@ export function registerVoiceInputIpc(): void {
// losing session. BYOK providers have independent credentials and
// may use the staggered client-side hedge.
hedgeDelayMs: voiceContext ? null : undefined,
+ sharedAccountRateLimit: Boolean(voiceContext),
});
} catch (error) {
const message = error instanceof Error ? error.message : String(error);
@@ -2344,6 +2346,7 @@ export function registerVoiceInputIpc(): void {
asr: provider,
refiner,
pauseRefinementEnabled: true,
+ recoveryErrorMessage: voiceContext ? getVoiceInputRateLimitMessage : undefined,
logger,
callbacks: {
onStateChanged: (state, outcome) => {
@@ -2439,7 +2442,9 @@ export function registerVoiceInputIpc(): void {
await cleanupVoiceInputProvider(provider, 'start_failed');
return {
ok: false,
- error: voiceContext ? CINDY_VOICE_SERVICE_UNAVAILABLE_MESSAGE : message,
+ error: voiceContext
+ ? (getVoiceInputRateLimitMessage(error) ?? CINDY_VOICE_SERVICE_UNAVAILABLE_MESSAGE)
+ : message,
};
}
});
diff --git a/apps/desktop/src/main/voice-input/voiceInputStartError.ts b/apps/desktop/src/main/voice-input/voiceInputStartError.ts
new file mode 100644
index 0000000000..7f5af4f623
--- /dev/null
+++ b/apps/desktop/src/main/voice-input/voiceInputStartError.ts
@@ -0,0 +1,18 @@
+import { VOICE_INPUT_RATE_LIMITED_MESSAGE } from '../../shared/voiceInputErrors.js';
+
+/** Classify structured session-allocation errors without exposing upstream text. */
+export function isVoiceInputStartRateLimited(error: unknown): boolean {
+ // FallbackAsrProvider retains each original ServerApiError in .errors.
+ // Mixed failures must keep the generic message: waiting may not fix them.
+ const failures: unknown[] = error instanceof AggregateError ? error.errors : [error];
+ return failures.length > 0 && failures.every((failure) => (
+ failure instanceof Error
+ && 'code' in failure && failure.code === 'RATE_LIMITED'
+ && 'statusCode' in failure && failure.statusCode === 429
+ ));
+}
+
+/** Only recognized account limits may replace the controller's recovery fallback. */
+export function getVoiceInputRateLimitMessage(error: unknown): string | undefined {
+ return isVoiceInputStartRateLimited(error) ? VOICE_INPUT_RATE_LIMITED_MESSAGE : undefined;
+}
diff --git a/apps/desktop/src/renderer/i18n/locales/en/common.json b/apps/desktop/src/renderer/i18n/locales/en/common.json
index 417f3c44a0..016a833eb8 100644
--- a/apps/desktop/src/renderer/i18n/locales/en/common.json
+++ b/apps/desktop/src/renderer/i18n/locales/en/common.json
@@ -8847,6 +8847,7 @@
}
},
"voiceInputOverlay": {
+ "rateLimited": "Too many voice requests. Wait a moment, then try again.",
"status": {
"listening": "Voice input",
"submitting": "Finalizing",
diff --git a/apps/desktop/src/renderer/i18n/locales/ja/common.json b/apps/desktop/src/renderer/i18n/locales/ja/common.json
index df6c8e9ddb..85230c030b 100644
--- a/apps/desktop/src/renderer/i18n/locales/ja/common.json
+++ b/apps/desktop/src/renderer/i18n/locales/ja/common.json
@@ -8845,6 +8845,7 @@
}
},
"voiceInputOverlay": {
+ "rateLimited": "音声リクエストが多すぎます。しばらく待ってから再試行してください。",
"status": {
"listening": "音声入力中",
"submitting": "確定中",
diff --git a/apps/desktop/src/renderer/i18n/locales/ko/common.json b/apps/desktop/src/renderer/i18n/locales/ko/common.json
index 2a2d21f825..1128c40159 100644
--- a/apps/desktop/src/renderer/i18n/locales/ko/common.json
+++ b/apps/desktop/src/renderer/i18n/locales/ko/common.json
@@ -8845,6 +8845,7 @@
}
},
"voiceInputOverlay": {
+ "rateLimited": "음성 요청이 너무 많습니다. 잠시 후 다시 시도하세요.",
"status": {
"listening": "음성 입력 중",
"submitting": "확정 중",
diff --git a/apps/desktop/src/renderer/i18n/locales/zh-CN/common.json b/apps/desktop/src/renderer/i18n/locales/zh-CN/common.json
index ef389bb670..af1e9e01ac 100644
--- a/apps/desktop/src/renderer/i18n/locales/zh-CN/common.json
+++ b/apps/desktop/src/renderer/i18n/locales/zh-CN/common.json
@@ -8845,6 +8845,7 @@
}
},
"voiceInputOverlay": {
+ "rateLimited": "语音请求过于频繁,请稍后重试。",
"status": {
"listening": "语音输入中",
"submitting": "正在确认",
diff --git a/apps/desktop/src/renderer/i18n/locales/zh-TW/common.json b/apps/desktop/src/renderer/i18n/locales/zh-TW/common.json
index 753e0e17a2..6a63f9eb3c 100644
--- a/apps/desktop/src/renderer/i18n/locales/zh-TW/common.json
+++ b/apps/desktop/src/renderer/i18n/locales/zh-TW/common.json
@@ -8845,6 +8845,7 @@
}
},
"voiceInputOverlay": {
+ "rateLimited": "語音請求過於頻繁,請稍後再試。",
"status": {
"listening": "語音輸入中",
"submitting": "正在確認",
diff --git a/apps/desktop/src/renderer/voice-input/VoiceInputOverlay.tsx b/apps/desktop/src/renderer/voice-input/VoiceInputOverlay.tsx
index f0bd2b8cba..7892722b1f 100644
--- a/apps/desktop/src/renderer/voice-input/VoiceInputOverlay.tsx
+++ b/apps/desktop/src/renderer/voice-input/VoiceInputOverlay.tsx
@@ -71,7 +71,7 @@ import { formatVoiceInputShortcut } from './shortcut';
import { VoiceInputMicWaveIcon } from './VoiceInputMicWaveIcon';
import { getVoiceInputWorkletUrl } from './workletUrl';
import { VoiceInputPointerHintLayer } from './VoiceInputPointerHintLayer';
-import { isVoiceInputServiceConnectionError, VOICE_INPUT_ERROR_CODE_KEYS } from './overlayErrors';
+import { getVoiceInputErrorMessageKey, VOICE_INPUT_ERROR_CODE_KEYS } from './overlayErrors';
import {
resolveVoiceInputReadinessRecovery,
type VoiceInputRecoverySettingsTab,
@@ -462,10 +462,8 @@ export function VoiceInputOverlay() {
}, []);
const formatVoiceInputStartError = useCallback((message: string): string => {
- if (isVoiceInputServiceConnectionError(message)) {
- return t('voiceInputOverlay.asrServiceUnavailable');
- }
- return message;
+ const key = getVoiceInputErrorMessageKey(message);
+ return key ? t(key) : message;
}, [t]);
const formatVoiceInputError = useCallback((
diff --git a/apps/desktop/src/renderer/voice-input/__tests__/overlayErrors.test.ts b/apps/desktop/src/renderer/voice-input/__tests__/overlayErrors.test.ts
index 6932db495e..1d0499497a 100644
--- a/apps/desktop/src/renderer/voice-input/__tests__/overlayErrors.test.ts
+++ b/apps/desktop/src/renderer/voice-input/__tests__/overlayErrors.test.ts
@@ -1,9 +1,25 @@
import { describe, expect, it } from 'vitest';
import { TEST_XD_GATEWAY_BASE_URL as XD_GATEWAY_BASE_URL } from '../../../test/vitest/clientEndpointsFixture';
-import { isVoiceInputServiceConnectionError } from '../overlayErrors';
+import { createInstance } from 'i18next';
+import { VOICE_INPUT_RATE_LIMITED_MESSAGE } from '../../../shared/voiceInputErrors';
+import { getVoiceInputErrorMessageKey, isVoiceInputServiceConnectionError } from '../overlayErrors';
describe('voice input overlay error classification', () => {
+ it('localizes the same start/recovery message using the renderer language after a switch', async () => {
+ const local = createInstance();
+ await local.init({ lng: 'en', resources: {
+ en: { translation: { voiceInputOverlay: { rateLimited: 'English limit message' } } },
+ ja: { translation: { voiceInputOverlay: { rateLimited: 'Japanese limit message' } } },
+ } });
+ const key = getVoiceInputErrorMessageKey(VOICE_INPUT_RATE_LIMITED_MESSAGE)!;
+ expect(local.t(key)).toBe('English limit message');
+ await local.changeLanguage('ja');
+ expect(local.t(getVoiceInputErrorMessageKey(VOICE_INPUT_RATE_LIMITED_MESSAGE)!)).toBe('Japanese limit message');
+ expect(getVoiceInputErrorMessageKey('Upstream HTTP 429')).toBeUndefined();
+ expect(getVoiceInputErrorMessageKey('WebSocket connection timed out')).toBe('voiceInputOverlay.asrServiceUnavailable');
+ });
+
it('detects transport failures as service connection errors', () => {
expect(isVoiceInputServiceConnectionError(`getaddrinfo ENOTFOUND ${new URL(XD_GATEWAY_BASE_URL).host}`)).toBe(true);
expect(isVoiceInputServiceConnectionError('WebSocket connection timed out')).toBe(true);
diff --git a/apps/desktop/src/renderer/voice-input/overlayErrors.ts b/apps/desktop/src/renderer/voice-input/overlayErrors.ts
index cfb3e08318..9a5531628a 100644
--- a/apps/desktop/src/renderer/voice-input/overlayErrors.ts
+++ b/apps/desktop/src/renderer/voice-input/overlayErrors.ts
@@ -1,4 +1,5 @@
import type { VoiceInputErrorCode } from '@cindy/voice-input-core';
+import { VOICE_INPUT_RATE_LIMITED_MESSAGE } from '../../shared/voiceInputErrors';
/**
* i18n keys for the failures the voice controller classifies itself. Their
@@ -18,3 +19,10 @@ const VOICE_INPUT_SERVICE_CONNECTION_ERROR_PATTERN =
export function isVoiceInputServiceConnectionError(message: string): boolean {
return VOICE_INPUT_SERVICE_CONNECTION_ERROR_PATTERN.test(message);
}
+
+/** Resolve known messages at display time using this renderer's current locale. */
+export function getVoiceInputErrorMessageKey(message: string): string | undefined {
+ if (message === VOICE_INPUT_RATE_LIMITED_MESSAGE) return 'voiceInputOverlay.rateLimited';
+ if (isVoiceInputServiceConnectionError(message)) return 'voiceInputOverlay.asrServiceUnavailable';
+ return undefined;
+}
diff --git a/apps/desktop/src/renderer/voice-input/useVoiceInput.ts b/apps/desktop/src/renderer/voice-input/useVoiceInput.ts
index e3d8265c75..68318453bc 100644
--- a/apps/desktop/src/renderer/voice-input/useVoiceInput.ts
+++ b/apps/desktop/src/renderer/voice-input/useVoiceInput.ts
@@ -65,7 +65,7 @@ import {
resolveInsertedTextRange,
type EditorTextRange,
} from './editorRangeMapping';
-import { isVoiceInputServiceConnectionError, VOICE_INPUT_ERROR_CODE_KEYS } from './overlayErrors';
+import { getVoiceInputErrorMessageKey, VOICE_INPUT_ERROR_CODE_KEYS } from './overlayErrors';
import {
hasArmedDetachedVoiceDraft,
settleArmedDetachedVoiceDraft,
@@ -411,9 +411,8 @@ export function useVoiceInput(
}, [clearInlineErrorDismissTimer]);
const formatVoiceInputStartError = useCallback((message: string): string => {
- return isVoiceInputServiceConnectionError(message)
- ? t('voiceInputOverlay.asrServiceUnavailable')
- : message;
+ const key = getVoiceInputErrorMessageKey(message);
+ return key ? t(key) : message;
}, [t]);
const formatVoiceInputError = useCallback((
diff --git a/apps/desktop/src/shared/voiceInputErrors.ts b/apps/desktop/src/shared/voiceInputErrors.ts
new file mode 100644
index 0000000000..b49e31197a
--- /dev/null
+++ b/apps/desktop/src/shared/voiceInputErrors.ts
@@ -0,0 +1,2 @@
+/** Safe, locale-neutral fallback text carried by the existing voice error payload. */
+export const VOICE_INPUT_RATE_LIMITED_MESSAGE = 'Too many voice requests. Wait a moment, then try again.';
diff --git a/packages/voice-input-core/src/VoiceInputController.ts b/packages/voice-input-core/src/VoiceInputController.ts
index 768a9bd645..5ea15e2b56 100644
--- a/packages/voice-input-core/src/VoiceInputController.ts
+++ b/packages/voice-input-core/src/VoiceInputController.ts
@@ -43,6 +43,8 @@ type VoiceInputControllerOptions = {
stableWaitMs?: number;
/** Host opt-in: refine during a speech pause and publish a live draft. */
pauseRefinementEnabled?: boolean;
+ /** Host opt-in for known recovery failures; undefined keeps the generic error. */
+ recoveryErrorMessage?: (error: unknown) => string | undefined;
};
type CryptoWithUuid = {
@@ -91,6 +93,7 @@ export class VoiceInputController {
private readonly callbacks: VoiceInputCallbacks;
private readonly stableWaitMs: number;
private readonly pauseRefinementEnabled: boolean;
+ private readonly recoveryErrorMessage?: (error: unknown) => string | undefined;
private lastSoundAt = 0;
private lastTranscriptChangeAt = 0;
private pauseRefinement?: PendingRefinement;
@@ -156,6 +159,7 @@ export class VoiceInputController {
this.callbacks = options.callbacks;
this.stableWaitMs = options.stableWaitMs ?? 500;
this.pauseRefinementEnabled = options.pauseRefinementEnabled ?? false;
+ this.recoveryErrorMessage = options.recoveryErrorMessage;
this.asr.onEvent((event) => this.handleAsrEvent(event));
}
@@ -870,7 +874,11 @@ export class VoiceInputController {
reason,
});
this.stopStallWatchdog();
- this.fail('Voice input stopped receiving recognition. Please try again.', 'recognition_stalled');
+ const message = this.recoveryErrorMessage?.(error);
+ this.fail(
+ message ?? 'Voice input stopped receiving recognition. Please try again.',
+ message === undefined ? 'recognition_stalled' : undefined,
+ );
})
.finally(() => {
if (runId !== this.runId) return;