@makerbi/remodex 2.0.0 → 2.3.0

package/src/voice-handler.js

@@ -1,15 +1,36 @@
 // FILE: voice-handler.js
-// Purpose: Handles bridge-owned voice transcription requests without exposing auth tokens to iPhone.
+// Purpose: Handles bridge-owned voice transcription and prewarm requests without exposing auth tokens to iPhone.
 // Layer: Bridge handler
 // Exports: createVoiceHandler, resolveVoiceAuth
-// Depends on: global fetch/FormData/Blob, local codex app-server auth via sendCodexRequest
+// Depends on: global fetch/FormData/Blob, local codex app-server auth via sendCodexRequest, ./voice-audio
+
+const {
+  hasConsistentVoiceWavLayout,
+  isSupportedVoiceWavFormat,
+  readM4AInfo,
+  readWavInfo,
+  wavDurationMs,
+} = require("./voice-audio");
 
-const OPENAI_TRANSCRIPTIONS_URL = "https://api.openai.com/v1/audio/transcriptions";
 const CHATGPT_TRANSCRIPTIONS_URL = "https://chatgpt.com/backend-api/transcribe";
-const DEFAULT_TRANSCRIPTION_MODEL = "gpt-4o-mini-transcribe";
 const MAX_AUDIO_BYTES = 10 * 1024 * 1024;
 const MAX_DURATION_SECONDS = 150;
 const MAX_DURATION_MS = MAX_DURATION_SECONDS * 1_000;
+const DEFAULT_TRANSCRIPTION_TIMEOUT_MS = 175_000;
+const MAX_DURATION_DRIFT_MS = 2_000;
+const AUTH_CACHE_TTL_MS = 60_000;
+const PRECONNECT_MIN_INTERVAL_MS = 2_000;
+const PRECONNECT_TIMEOUT_MS = 10_000;
+// Live endpoint probes confirmed subscription uploads accept AAC m4a alongside WAV.
+const VOICE_AUDIO_FORMATS = ["wav", "m4a"];
+const VOICE_WAV_MIME_TYPE = "audio/wav";
+const VOICE_M4A_MIME_TYPE = "audio/mp4";
+// Cloudflare rejects Node's default fetch identity on chatgpt.com with an HTML 403,
+// which used to fail every bridge upload and force the slow phone-direct fallback.
+// If the accepted identity changes again (symptom: transcription turns slow because
+// every upload falls back to the phone), override it without a release via env.
+const VOICE_UPLOAD_USER_AGENT = process.env.REMODEX_VOICE_UPLOAD_USER_AGENT
+  || "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.4 Safari/605.1.15";
 
 function createVoiceHandler({
   sendCodexRequest,
@@ -17,17 +38,93 @@ function createVoiceHandler({
   FormDataImpl = globalThis.FormData,
   BlobImpl = globalThis.Blob,
   logPrefix = "[remodex]",
-  env = process.env,
+  logger = console,
+  transcriptionTimeoutMs = DEFAULT_TRANSCRIPTION_TIMEOUT_MS,
 } = {}) {
-  function handleVoiceRequest(rawMessage, sendResponse) {
-    let parsed;
-    try {
-      parsed = JSON.parse(rawMessage);
-    } catch {
+  // Keeps a short-lived auth context plus TLS preconnect so the post-recording
+  // transcription request skips the token refresh and handshake round trips.
+  const warmState = {
+    authPromise: null,
+    authLoadedAt: 0,
+    lastPreconnectAt: 0,
+  };
+
+  function cacheAuthPromise(promise) {
+    warmState.authPromise = promise;
+    warmState.authLoadedAt = Date.now();
+    promise.catch(() => {
+      if (warmState.authPromise === promise) {
+        warmState.authPromise = null;
+      }
+    });
+    return promise;
+  }
+
+  function loadAuth() {
+    if (warmState.authPromise && Date.now() - warmState.authLoadedAt < AUTH_CACHE_TTL_MS) {
+      return warmState.authPromise;
+    }
+    return cacheAuthPromise(loadAuthContext(sendCodexRequest, { refreshToken: false }));
+  }
+
+  function refreshAuth() {
+    return cacheAuthPromise(loadAuthContext(sendCodexRequest, { refreshToken: true }));
+  }
+
+  // Opens (or revives) the HTTPS connection to the provider so the upload fetch reuses it.
+  function preconnectTranscriptionOrigin() {
+    if (typeof fetchImpl !== "function") {
+      return;
+    }
+    const now = Date.now();
+    if (now - warmState.lastPreconnectAt < PRECONNECT_MIN_INTERVAL_MS) {
+      return;
+    }
+    warmState.lastPreconnectAt = now;
+
+    const controller = typeof AbortController === "function" ? new AbortController() : null;
+    const timeoutID = controller
+      ? setTimeout(() => controller.abort(new Error("voice preconnect timed out")), PRECONNECT_TIMEOUT_MS)
+      : null;
+    timeoutID?.unref?.();
+
+    Promise.resolve()
+      .then(() => fetchImpl(new URL("/", CHATGPT_TRANSCRIPTIONS_URL).toString(), {
+        method: "HEAD",
+        headers: { "User-Agent": VOICE_UPLOAD_USER_AGENT },
+        signal: controller?.signal,
+      }))
+      .then((response) => {
+        response?.body?.cancel?.()?.catch?.(() => {});
+      })
+      .catch(() => {})
+      .finally(() => {
+        if (timeoutID) {
+          clearTimeout(timeoutID);
+        }
+      });
+  }
+
+  function handlePrewarmRequest(id, sendResponse) {
+    preconnectTranscriptionOrigin();
+    loadAuth().catch(() => {});
+    logVoiceEvent(logger, "log", logPrefix, "prewarm requested");
+    if (id != null) {
+      sendResponse(JSON.stringify({ id, result: { ok: true, formats: VOICE_AUDIO_FORMATS } }));
+    }
+  }
+
+  function handleVoiceRequest(rawMessage, sendResponse, parsedMessage = null) {
+    const parsed = parsedMessage || parseJsonMessage(rawMessage);
+    if (!parsed) {
       return false;
     }
 
     const method = typeof parsed?.method === "string" ? parsed.method.trim() : "";
+    if (method === "voice/prewarm") {
+      handlePrewarmRequest(parsed.id, sendResponse);
+      return true;
+    }
     if (method !== "voice/transcribe") {
       return false;
     }
@@ -40,21 +137,25 @@ function createVoiceHandler({
       fetchImpl,
       FormDataImpl,
       BlobImpl,
-      env,
+      logger,
+      logPrefix,
+      transcriptionTimeoutMs,
+      loadAuth,
+      refreshAuth,
     })
       .then((result) => {
         sendResponse(JSON.stringify({ id, result }));
       })
       .catch((error) => {
-        console.error(`${logPrefix} voice transcription failed: ${error.message}`);
+        logVoiceEvent(logger, "error", logPrefix, "failed", {
+          errorCode: error.errorCode || "voice_transcription_failed",
+        });
         sendResponse(JSON.stringify({
           id,
           error: {
             code: -32000,
             message: error.userMessage || error.message || "Voice transcription failed.",
-            data: {
-              errorCode: error.errorCode || "voice_transcription_failed",
-            },
+            data: voiceErrorData(error),
           },
         }));
       });
@@ -67,12 +168,30 @@ function createVoiceHandler({
   };
 }
 
+function parseJsonMessage(rawMessage) {
+  try {
+    return JSON.parse(rawMessage);
+  } catch {
+    return null;
+  }
+}
+
 // ─── Audio validation helpers ───────────────────────────────
 
 // Validates iPhone-owned audio input and proxies it to the official transcription endpoint.
 async function transcribeVoice(
   params,
-  { sendCodexRequest, fetchImpl, FormDataImpl, BlobImpl, env = process.env }
+  {
+    sendCodexRequest,
+    fetchImpl,
+    FormDataImpl,
+    BlobImpl,
+    logger = console,
+    logPrefix = "[remodex]",
+    transcriptionTimeoutMs = DEFAULT_TRANSCRIPTION_TIMEOUT_MS,
+    loadAuth = () => loadAuthContext(sendCodexRequest, { refreshToken: false }),
+    refreshAuth = () => loadAuthContext(sendCodexRequest, { refreshToken: true }),
+  }
 ) {
   if (typeof sendCodexRequest !== "function") {
     throw voiceError("bridge_not_ready", "Voice transcription is not available right now.");
@@ -82,8 +201,8 @@ async function transcribeVoice(
   }
 
   const mimeType = readString(params.mimeType);
-  if (mimeType !== "audio/wav") {
-    throw voiceError("unsupported_mime_type", "Only WAV audio is supported for voice transcription.");
+  if (!isSupportedVoiceMimeType(mimeType)) {
+    throw voiceError("unsupported_mime_type", "Only WAV or M4A audio is supported for voice transcription.");
   }
 
   const sampleRateHz = readPositiveNumber(params.sampleRateHz);
@@ -103,94 +222,156 @@ async function transcribeVoice(
   if (audioBuffer.length > MAX_AUDIO_BYTES) {
     throw voiceError("audio_too_large", "Voice messages are limited to 10 MB.");
   }
-  const wavInfo = readWavInfo(audioBuffer);
-  if (!wavInfo) {
-    throw voiceError("invalid_audio", "The recorded audio is not a valid WAV file.");
+  const audioInfo = readVoiceAudioInfo(audioBuffer, mimeType);
+  const actualDurationMs = audioInfo.durationMs;
+  if (!Number.isFinite(actualDurationMs) || actualDurationMs <= 0) {
+    throw voiceError("invalid_audio", "The recorded audio is not a valid audio file.");
   }
-  if (wavInfo.audioFormat !== 1
-    || wavInfo.channelCount !== 1
-    || wavInfo.sampleRateHz !== 24_000
-    || wavInfo.bitsPerSample !== 16) {
-    throw voiceError("unsupported_sample_rate", "Voice transcription requires 24 kHz mono WAV audio.");
+  if (actualDurationMs > MAX_DURATION_MS) {
+    throw voiceError("duration_too_long", `Voice messages are limited to ${MAX_DURATION_SECONDS} seconds.`);
   }
+  if (actualDurationMs > durationMs + MAX_DURATION_DRIFT_MS) {
+    throw voiceError("duration_mismatch", "The recorded audio duration did not match the voice request.");
+  }
+
+  logVoiceEvent(logger, "log", logPrefix, "request received", {
+    durationMs,
+    actualDurationMs: Math.round(actualDurationMs),
+    audioBytes: audioBuffer.length,
+  });
 
-  const authContext = await loadAuthContext(sendCodexRequest, { env });
+  const authContext = await loadAuth();
   return requestTranscription({
     authContext,
     audioBuffer,
     mimeType,
+    filename: audioInfo.filename,
     fetchImpl,
     FormDataImpl,
     BlobImpl,
-    sendCodexRequest,
-    env,
+    refreshAuth,
+    logger,
+    logPrefix,
+    transcriptionTimeoutMs,
   });
 }
 
+// Posts the validated clip to the active transcription provider and logs only safe metadata.
 async function requestTranscription({
   authContext,
   audioBuffer,
   mimeType,
+  filename = "voice.wav",
   fetchImpl,
   FormDataImpl,
   BlobImpl,
-  sendCodexRequest,
-  env,
+  refreshAuth,
+  logger = console,
+  logPrefix = "[remodex]",
+  transcriptionTimeoutMs = DEFAULT_TRANSCRIPTION_TIMEOUT_MS,
 }) {
-  const makeAttempt = async (activeAuthContext) => {
+  const makeAttempt = async (activeAuthContext, attempt) => {
+    logVoiceEvent(logger, "log", logPrefix, "auth selected", {
+      attempt,
+      source: activeAuthContext.authSource,
+      method: activeAuthContext.authMethodClass,
+      provider: activeAuthContext.provider,
+    });
+
     const formData = new FormDataImpl();
-    formData.append("file", new BlobImpl([audioBuffer], { type: mimeType }), "voice.wav");
-    if (!activeAuthContext.isChatGPT) {
-      formData.append("model", DEFAULT_TRANSCRIPTION_MODEL);
-    }
+    formData.append("file", new BlobImpl([audioBuffer], { type: mimeType }), filename);
 
     const headers = {
       Authorization: `Bearer ${activeAuthContext.token}`,
+      "User-Agent": VOICE_UPLOAD_USER_AGENT,
     };
 
-    return fetchImpl(activeAuthContext.transcriptionURL, {
-      method: "POST",
-      headers,
-      body: formData,
+    const timeoutMs = Number.isFinite(transcriptionTimeoutMs)
+      ? Math.max(0, Math.floor(transcriptionTimeoutMs))
+      : DEFAULT_TRANSCRIPTION_TIMEOUT_MS;
+    const controller = typeof AbortController === "function" && timeoutMs > 0
+      ? new AbortController()
+      : null;
+    const timeoutID = controller
+      ? setTimeout(() => {
+        controller.abort(createTranscriptionTimeoutError(timeoutMs));
+      }, timeoutMs)
+      : null;
+    timeoutID?.unref?.();
+
+    let response;
+    try {
+      response = await fetchImpl(activeAuthContext.transcriptionURL, {
+        method: "POST",
+        headers,
+        body: formData,
+        signal: controller?.signal,
+      });
+    } catch (error) {
+      if (isAbortError(error, controller)) {
+        logVoiceEvent(logger, "warn", logPrefix, "provider status", {
+          attempt,
+          provider: activeAuthContext.provider,
+          status: "timeout",
+          ok: false,
+        });
+        throw voiceError(
+          "transcription_timeout",
+          "Voice transcription timed out. Try a shorter clip or retry when the connection is stable.",
+          { provider: activeAuthContext.provider }
+        );
+      }
+
+      logVoiceEvent(logger, "warn", logPrefix, "provider status", {
+        attempt,
+        provider: activeAuthContext.provider,
+        status: "network_error",
+        ok: false,
+      });
+      throw voiceError(
+        "transcription_network_error",
+        "Voice transcription could not reach the provider.",
+        { provider: activeAuthContext.provider }
+      );
+    } finally {
+      if (timeoutID) {
+        clearTimeout(timeoutID);
+      }
+    }
+
+    logVoiceEvent(logger, response.ok ? "log" : "warn", logPrefix, "provider status", {
+      attempt,
+      provider: activeAuthContext.provider,
+      status: response.status,
+      ok: Boolean(response.ok),
     });
+    return response;
   };
 
   let activeAuthContext = authContext;
-  let response = await makeAttempt(activeAuthContext);
+  let attempt = 1;
+  let response = await makeAttempt(activeAuthContext, attempt);
   if (response.status === 401 || response.status === 403) {
-    activeAuthContext = await loadAuthContext(sendCodexRequest, { env });
-    response = await makeAttempt(activeAuthContext);
-    if (!response.ok
-      && (response.status === 401 || response.status === 403)
-      && activeAuthContext.isChatGPT) {
-      const apiKeyContext = loadEnvApiKeyAuthContext(env);
-      if (apiKeyContext) {
-        activeAuthContext = apiKeyContext;
-        response = await makeAttempt(activeAuthContext);
-      }
-    }
+    // First attempt runs on a cached/non-refreshed token, so force a refresh here.
+    activeAuthContext = await refreshAuth();
+    attempt += 1;
+    response = await makeAttempt(activeAuthContext, attempt);
   }
 
   if (!response.ok) {
-    let errorMessage = `Transcription failed with status ${response.status}.`;
-    try {
-      const errorPayload = await response.json();
-      const providerMessage = readString(errorPayload?.error?.message) || readString(errorPayload?.message);
-      if (providerMessage) {
-        errorMessage = providerMessage;
-      }
-    } catch {
-      // Keep the generic message when the provider body is empty or non-JSON.
-    }
-
     if (response.status === 401 || response.status === 403) {
-      const message = activeAuthContext.isChatGPT
-        ? "Your ChatGPT login has expired. Sign in again."
-        : "Your OpenAI API key was rejected. Update the API key on the Mac, then try again.";
-      throw voiceError("auth_rejected", message);
+      throw voiceError(
+        "auth_rejected",
+        "Your ChatGPT login has expired. Sign in again.",
+        { provider: activeAuthContext.provider }
+      );
     }
 
-    throw voiceError("transcription_failed", errorMessage);
+    throw voiceError(
+      "transcription_failed",
+      `Voice transcription failed with provider status ${response.status}.`,
+      { provider: activeAuthContext.provider, status: response.status }
+    );
   }
 
   const payload = await response.json().catch(() => null);
@@ -199,56 +380,50 @@ async function requestTranscription({
     throw voiceError("transcription_invalid_response", "The transcription response did not include any text.");
   }
 
+  logVoiceEvent(logger, "log", logPrefix, "success", {
+    provider: activeAuthContext.provider,
+    status: response.status,
+    textLength: text.length,
+  });
+
   return { text };
 }
 
-// Reads the current bridge-owned auth state from the local codex app-server and refreshes if needed.
-async function loadAuthContext(sendCodexRequest, { env = process.env } = {}) {
-  const authStatus = await readVoiceAuthStatus(sendCodexRequest);
+// Reads the current bridge-owned ChatGPT auth state; refresh is reserved for 401/403 retries.
+async function loadAuthContext(sendCodexRequest, { refreshToken = false } = {}) {
+  const authStatus = await readVoiceAuthStatus(sendCodexRequest, { refreshToken });
 
   const authMethod = readString(authStatus?.authMethod);
   const token = normalizeBearerToken(authStatus?.authToken);
   const isChatGPT = isChatGPTAuthMethod(authMethod);
 
   if (!token) {
-    const apiKeyContext = loadEnvApiKeyAuthContext(env);
-    if (apiKeyContext) {
-      return apiKeyContext;
-    }
-    throw voiceError("not_authenticated", "Sign in with ChatGPT or configure an OpenAI API key before using voice transcription.");
+    throw voiceError("not_authenticated", "Sign in with ChatGPT before using voice transcription.");
   }
 
-  return {
-    authMethod,
-    token,
-    isChatGPT,
-    transcriptionURL: isChatGPT ? CHATGPT_TRANSCRIPTIONS_URL : OPENAI_TRANSCRIPTIONS_URL,
-  };
-}
-
-function loadEnvApiKeyAuthContext(env = process.env) {
-  const token = normalizeBearerToken(env?.OPENAI_API_KEY);
-  if (!token) {
-    return null;
+  if (!isChatGPT) {
+    throw voiceError("not_chatgpt", "Voice transcription requires a ChatGPT account.");
   }
 
   return {
-    authMethod: "apiKey",
+    authMethod,
+    authSource: "mac_runtime",
+    authMethodClass: "chatgpt",
+    provider: "chatgpt",
     token,
-    isChatGPT: false,
-    transcriptionURL: OPENAI_TRANSCRIPTIONS_URL,
+    transcriptionURL: CHATGPT_TRANSCRIPTIONS_URL,
   };
 }
 
-async function readVoiceAuthStatus(sendCodexRequest) {
+async function readVoiceAuthStatus(sendCodexRequest, { refreshToken = true } = {}) {
   try {
     return await sendCodexRequest("getAuthStatus", {
       includeToken: true,
-      refreshToken: true,
+      refreshToken,
     });
-  } catch (err) {
-    console.error(`[remodex] voice auth: getAuthStatus RPC failed: ${err.message}`);
-    throw voiceError("auth_unavailable", "Could not read OpenAI auth from the Mac runtime. Is the bridge running?");
+  } catch {
+    console.error("[remodex] voice auth: getAuthStatus RPC failed");
+    throw voiceError("auth_unavailable", "Could not read ChatGPT auth from the Mac runtime. Is the bridge running?");
   }
 }
 
@@ -258,10 +433,6 @@ function decodeAudioBase64(value) {
     throw voiceError("missing_audio", "The voice request did not include any audio.");
   }
 
-  if (!isLikelyBase64(normalized)) {
-    throw voiceError("invalid_audio", "The recorded audio could not be decoded.");
-  }
-
   const audioBuffer = Buffer.from(normalized, "base64");
   if (!audioBuffer.length) {
     throw voiceError("invalid_audio", "The recorded audio could not be decoded.");
@@ -271,10 +442,6 @@ function decodeAudioBase64(value) {
     throw voiceError("invalid_audio", "The recorded audio could not be decoded.");
   }
 
-  if (!hasRiffWaveHeader(audioBuffer)) {
-    throw voiceError("invalid_audio", "The recorded audio is not a valid WAV file.");
-  }
-
   return audioBuffer;
 }
 
@@ -283,81 +450,36 @@ function normalizeBase64(value) {
   return typeof value === "string" ? value.replace(/\s+/g, "").trim() : "";
 }
 
-function isLikelyBase64(value) {
-  if (typeof value !== "string" || value.length === 0 || value.length % 4 !== 0) {
-    return false;
-  }
+function isSupportedVoiceMimeType(mimeType) {
+  return mimeType === VOICE_WAV_MIME_TYPE || mimeType === VOICE_M4A_MIME_TYPE;
+}
 
-  const paddingStart = value.indexOf("=");
-  if (paddingStart !== -1) {
-    const paddingLength = value.length - paddingStart;
-    if (paddingLength > 2) {
-      return false;
+function readVoiceAudioInfo(buffer, mimeType) {
+  if (mimeType === VOICE_WAV_MIME_TYPE) {
+    const wavInfo = readWavInfo(buffer);
+    if (!wavInfo) {
+      throw voiceError("invalid_audio", "The recorded audio is not a valid WAV file.");
     }
-    for (let i = paddingStart; i < value.length; i += 1) {
-      if (value[i] !== "=") {
-        return false;
-      }
+    if (!isSupportedVoiceWavFormat(wavInfo)) {
+      throw voiceError("unsupported_sample_rate", "Voice transcription requires 24 kHz mono WAV audio.");
     }
-  }
-
-  // Avoid one giant regex: V8 can overflow its stack on multi-MB voice clips.
-  const dataEnd = paddingStart === -1 ? value.length : paddingStart;
-  for (let i = 0; i < dataEnd; i += 1) {
-    const code = value.charCodeAt(i);
-    const isUppercase = code >= 65 && code <= 90;
-    const isLowercase = code >= 97 && code <= 122;
-    const isDigit = code >= 48 && code <= 57;
-    if (!isUppercase && !isLowercase && !isDigit && value[i] !== "+" && value[i] !== "/") {
-      return false;
+    if (!hasConsistentVoiceWavLayout(wavInfo)) {
+      throw voiceError("invalid_audio", "The recorded audio is not a valid WAV file.");
     }
+    return {
+      durationMs: wavDurationMs(wavInfo),
+      filename: "voice.wav",
+    };
   }
 
-  return true;
-}
-
-function hasRiffWaveHeader(buffer) {
-  return buffer.length >= 44
-    && buffer.toString("ascii", 0, 4) === "RIFF"
-    && buffer.toString("ascii", 8, 12) === "WAVE";
-}
-
-// Parses chunked WAV metadata so extra chunks before fmt/data do not break valid clips.
-function readWavInfo(buffer) {
-  if (!hasRiffWaveHeader(buffer)) {
-    return null;
+  const m4aInfo = readM4AInfo(buffer);
+  if (!m4aInfo) {
+    throw voiceError("invalid_audio", "The recorded audio is not a valid M4A file.");
   }
-
-  let offset = 12;
-  let info = null;
-  let hasData = false;
-  while (offset + 8 <= buffer.length) {
-    const chunkId = buffer.toString("ascii", offset, offset + 4);
-    const chunkSize = buffer.readUInt32LE(offset + 4);
-    const payloadStart = offset + 8;
-    const payloadEnd = payloadStart + chunkSize;
-    if (payloadEnd > buffer.length) {
-      return null;
-    }
-
-    if (chunkId === "fmt ") {
-      if (chunkSize < 16) {
-        return null;
-      }
-      info = {
-        audioFormat: buffer.readUInt16LE(payloadStart),
-        channelCount: buffer.readUInt16LE(payloadStart + 2),
-        sampleRateHz: buffer.readUInt32LE(payloadStart + 4),
-        bitsPerSample: buffer.readUInt16LE(payloadStart + 14),
-      };
-    } else if (chunkId === "data") {
-      hasData = chunkSize > 0;
-    }
-
-    offset = payloadEnd + (chunkSize % 2);
-  }
-
-  return info && hasData ? info : null;
+  return {
+    durationMs: m4aInfo.durationMs,
+    filename: "voice.m4a",
+  };
 }
 
 function readString(value) {
@@ -378,15 +500,83 @@ function isChatGPTAuthMethod(value) {
   return normalized.includes("chatgpt");
 }
 
+// Formats fixed safe fields only; callers must pass classifications, counts, and statuses.
+function logVoiceEvent(logger, level, logPrefix, event, fields = {}) {
+  const writer = resolveLogWriter(logger, level);
+  const details = Object.entries(fields)
+    .map(([key, value]) => `${key}=${formatLogValue(value)}`)
+    .join(" ");
+  writer(`${logPrefix} voice transcribe ${event}${details ? ` ${details}` : ""}`);
+}
+
+function resolveLogWriter(logger, level) {
+  if (typeof logger?.[level] === "function") {
+    return logger[level].bind(logger);
+  }
+  if (level === "warn" && typeof logger?.log === "function") {
+    return logger.log.bind(logger);
+  }
+  if (level === "error" && typeof logger?.warn === "function") {
+    return logger.warn.bind(logger);
+  }
+  if (typeof console[level] === "function") {
+    return console[level].bind(console);
+  }
+  return console.log.bind(console);
+}
+
+function formatLogValue(value) {
+  if (typeof value === "number" && Number.isFinite(value)) {
+    return String(value);
+  }
+  if (typeof value === "boolean") {
+    return value ? "true" : "false";
+  }
+  return String(value).replace(/[^a-zA-Z0-9_.:-]/g, "_");
+}
+
 function readPositiveNumber(value) {
   const numericValue = typeof value === "number" ? value : Number(value);
   return Number.isFinite(numericValue) && numericValue >= 0 ? numericValue : 0;
 }
 
-function voiceError(errorCode, userMessage) {
+function createTranscriptionTimeoutError(timeoutMs) {
+  const error = new Error(`Voice transcription timed out after ${timeoutMs}ms`);
+  error.name = "AbortError";
+  error.code = "voice_transcription_timeout";
+  return error;
+}
+
+function isAbortError(error, controller) {
+  return Boolean(controller?.signal?.aborted)
+    || error?.name === "AbortError"
+    || error?.code === "ABORT_ERR"
+    || error?.code === "voice_transcription_timeout";
+}
+
+function voiceErrorData(error) {
+  const data = {
+    errorCode: error.errorCode || "voice_transcription_failed",
+  };
+  if (error.provider === "chatgpt") {
+    data.provider = error.provider;
+  }
+  if (Number.isInteger(error.status)) {
+    data.status = error.status;
+  }
+  return data;
+}
+
+function voiceError(errorCode, userMessage, details = {}) {
   const error = new Error(userMessage);
   error.errorCode = errorCode;
   error.userMessage = userMessage;
+  if (details.provider === "chatgpt") {
+    error.provider = details.provider;
+  }
+  if (Number.isInteger(details.status)) {
+    error.status = details.status;
+  }
   return error;
 }