Harden audio transcription fetch path with retries and timeout

src/tools/builtin/audio-transcribe.test.ts

@@ -309,13 +309,36 @@ describe('createAudioTranscribeTool', () => {
     });
 
     it('handles network errors gracefully', async () => {
-      mockFetch.mockRejectedValueOnce(new Error('ECONNREFUSED'));
+      mockFetch.mockRejectedValue(new Error('ECONNREFUSED'));
 
       const result = await tool.execute({ data: 'AAAAAAA=', mime_type: 'audio/wav' });
       expect(result.success).toBe(false);
       expect(result.error).toMatch(/ECONNREFUSED/);
     });
 
+    it('retries transient fetch failures before succeeding', async () => {
+      mockFetch
+        .mockRejectedValueOnce(new TypeError('fetch failed'))
+        .mockResolvedValueOnce({
+          ok: true,
+          text: async () => JSON.stringify({ text: 'Recovered transcript' }),
+        });
+
+      const result = await tool.execute({ data: 'AAAAAAA=', mime_type: 'audio/wav' });
+      expect(result.success).toBe(true);
+      expect(result.output).toBe('Recovered transcript');
+      expect(mockFetch).toHaveBeenCalledTimes(2);
+    });
+
+    it('returns endpoint context when transient failures are exhausted', async () => {
+      mockFetch.mockRejectedValue(new TypeError('fetch failed'));
+
+      const result = await tool.execute({ data: 'AAAAAAA=', mime_type: 'audio/wav' });
+      expect(result.success).toBe(false);
+      expect(result.error).toMatch(/failed after 3 attempt/);
+      expect(result.error).toMatch(/audio\/transcriptions/);
+    });
+
     it('returns clear error when transcription payload has no text field', async () => {
       mockFetch.mockResolvedValueOnce({
         ok: true,

src/tools/builtin/audio-transcribe.ts

@@ -25,6 +25,53 @@ const PROVIDER_ENDPOINTS: Record<string, string> = {
   llamacpp: 'http://localhost:8080/v1/audio/transcriptions',
 };
 
+const TRANSCRIPTION_FETCH_MAX_ATTEMPTS = 3;
+const TRANSCRIPTION_FETCH_TIMEOUT_MS = 45_000;
+const TRANSCRIPTION_FETCH_BASE_DELAY_MS = 250;
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function isTransientNetworkError(error: unknown): boolean {
+  const message = (error instanceof Error ? error.message : String(error)).toLowerCase();
+  return message.includes('fetch failed')
+    || message.includes('network')
+    || message.includes('timeout')
+    || message.includes('timed out')
+    || message.includes('econnrefused')
+    || message.includes('econnreset')
+    || message.includes('enotfound')
+    || message.includes('ehostunreach');
+}
+
+async function fetchWithRetry(endpoint: string, init: RequestInit): Promise<Response> {
+  for (let attempt = 1; attempt <= TRANSCRIPTION_FETCH_MAX_ATTEMPTS; attempt += 1) {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), TRANSCRIPTION_FETCH_TIMEOUT_MS);
+    try {
+      return await fetch(endpoint, { ...init, signal: controller.signal });
+    } catch (error) {
+      const timedOut = error instanceof Error && error.name === 'AbortError';
+      const normalizedMessage = timedOut
+        ? `request timed out after ${TRANSCRIPTION_FETCH_TIMEOUT_MS}ms`
+        : (error instanceof Error ? error.message : String(error));
+      const retriable = timedOut || isTransientNetworkError(error);
+      const exhausted = attempt >= TRANSCRIPTION_FETCH_MAX_ATTEMPTS;
+      if (!retriable || exhausted) {
+        throw new Error(
+          `Transcription request to ${endpoint} failed after ${attempt} attempt(s): ${normalizedMessage}`,
+        );
+      }
+      await sleep(TRANSCRIPTION_FETCH_BASE_DELAY_MS * (2 ** (attempt - 1)));
+    } finally {
+      clearTimeout(timeout);
+    }
+  }
+
+  throw new Error(`Transcription request to ${endpoint} failed after retries`);
+}
+
 function validateUrl(url: string): { valid: boolean; error?: string } {
   let parsed: URL;
   try {
@@ -387,7 +434,7 @@ export function createAudioTranscribeTool(audioConfig?: AudioTranscriptionConfig
           fetchOptions.headers = headers;
         }
 
-        const response = await fetch(endpoint, fetchOptions);
+        const response = await fetchWithRetry(endpoint, fetchOptions);
 
         if (!response.ok) {
           const errorText = await response.text();