@absolutejs/voice 0.0.19 → 0.0.21

package/dist/index.js

@@ -69,6 +69,61 @@ var __decorateElement = (array, flags, name, decorators, target, extra) => {
   return k || __decoratorMetadata(array, target), desc && __defProp(target, name, desc), p ? k ^ 4 ? extra : desc : target;
 };
 
+// src/audioConditioning.ts
+var DEFAULT_TARGET_LEVEL = 0.08;
+var DEFAULT_MAX_GAIN = 3;
+var DEFAULT_NOISE_GATE_THRESHOLD = 0.006;
+var DEFAULT_NOISE_GATE_ATTENUATION = 0.15;
+var toInt16Array = (audio) => {
+  if (audio instanceof ArrayBuffer) {
+    return new Int16Array(audio, 0, Math.floor(audio.byteLength / 2));
+  }
+  return new Int16Array(audio.buffer, audio.byteOffset, Math.floor(audio.byteLength / 2));
+};
+var computeRms = (samples) => {
+  if (samples.length === 0) {
+    return 0;
+  }
+  let sumSquares = 0;
+  for (const sample of samples) {
+    const normalized = sample / 32768;
+    sumSquares += normalized * normalized;
+  }
+  return Math.sqrt(sumSquares / samples.length);
+};
+var resolveAudioConditioningConfig = (config) => {
+  if (!config || config.enabled === false) {
+    return;
+  }
+  return {
+    enabled: true,
+    maxGain: config.maxGain ?? DEFAULT_MAX_GAIN,
+    noiseGateAttenuation: config.noiseGateAttenuation ?? DEFAULT_NOISE_GATE_ATTENUATION,
+    noiseGateThreshold: config.noiseGateThreshold ?? DEFAULT_NOISE_GATE_THRESHOLD,
+    targetLevel: config.targetLevel ?? DEFAULT_TARGET_LEVEL
+  };
+};
+var conditionAudioChunk = (audio, config) => {
+  if (!config) {
+    return audio;
+  }
+  const source = toInt16Array(audio);
+  if (source.length === 0) {
+    return audio;
+  }
+  const rms = computeRms(source);
+  const output = new Int16Array(source.length);
+  const gateFactor = rms < config.noiseGateThreshold ? config.noiseGateAttenuation : 1;
+  const baseLevel = Math.max(rms * gateFactor, 0.000001);
+  const gain = Math.min(config.maxGain, config.targetLevel / baseLevel);
+  const appliedGain = Math.max(0.25, gain) * gateFactor;
+  for (let index = 0;index < source.length; index += 1) {
+    const next = Math.round(source[index] * appliedGain);
+    output[index] = Math.max(-32768, Math.min(32767, next));
+  }
+  return new Uint8Array(output.buffer);
+};
+
 // src/plugin.ts
 import { Elysia } from "elysia";
 import { resolve } from "path";
@@ -118,6 +173,10 @@ var defaultMetrics = (input) => {
     '<span class="voice-metric-label">Session</span>',
     `<span class="voice-metric-value">${escapeHtml(input.sessionId)}</span>`,
     "</div>",
+    input.session?.scenarioId ? `<div class="voice-metric">
+				<span class="voice-metric-label">Scenario</span>
+				<span class="voice-metric-value">${escapeHtml(input.session.scenarioId)}</span>
+			</div>` : "",
     '<div class="voice-metric">',
     '<span class="voice-metric-label">Status</span>',
     `<span class="voice-metric-value">${escapeHtml(input.status)}</span>`,
@@ -207,24 +266,245 @@ var resolveLogger = (logger) => ({
   ...logger
 });
 
+// src/turnProfiles.ts
+var TURN_PROFILE_DEFAULTS = {
+  balanced: {
+    qualityProfile: "general",
+    silenceMs: 1400,
+    speechThreshold: 0.012,
+    transcriptStabilityMs: 1000
+  },
+  fast: {
+    qualityProfile: "general",
+    silenceMs: 700,
+    speechThreshold: 0.015,
+    transcriptStabilityMs: 450
+  },
+  "long-form": {
+    qualityProfile: "general",
+    silenceMs: 2200,
+    speechThreshold: 0.01,
+    transcriptStabilityMs: 1500
+  }
+};
+var QUALITY_PROFILE_DEFAULTS = {
+  general: {},
+  "accent-heavy": {
+    silenceMs: 1200,
+    speechThreshold: 0.01,
+    transcriptStabilityMs: 1200
+  },
+  "noisy-room": {
+    silenceMs: 2000,
+    speechThreshold: 0.02,
+    transcriptStabilityMs: 1600
+  },
+  "short-command": {
+    silenceMs: 500,
+    speechThreshold: 0.016,
+    transcriptStabilityMs: 420
+  }
+};
+var DEFAULT_TURN_PROFILE = "fast";
+var DEFAULT_QUALITY_PROFILE = "general";
+var resolveTurnDetectionConfig = (config) => {
+  const profile = config?.profile ?? DEFAULT_TURN_PROFILE;
+  const qualityProfile = config?.qualityProfile ?? DEFAULT_QUALITY_PROFILE;
+  const preset = TURN_PROFILE_DEFAULTS[profile];
+  const quality = QUALITY_PROFILE_DEFAULTS[qualityProfile];
+  return {
+    profile,
+    qualityProfile,
+    silenceMs: config?.silenceMs ?? quality.silenceMs ?? preset.silenceMs,
+    speechThreshold: config?.speechThreshold ?? quality.speechThreshold ?? preset.speechThreshold,
+    transcriptStabilityMs: config?.transcriptStabilityMs ?? quality.transcriptStabilityMs ?? preset.transcriptStabilityMs
+  };
+};
+
+// src/presets.ts
+var PRESET_INPUTS = {
+  chat: {
+    audioConditioning: {
+      enabled: true,
+      maxGain: 2.5,
+      noiseGateAttenuation: 0,
+      noiseGateThreshold: 0.004,
+      targetLevel: 0.08
+    },
+    capture: {
+      channelCount: 1,
+      sampleRateHz: 16000
+    },
+    connection: {
+      maxReconnectAttempts: 10,
+      pingInterval: 30000,
+      reconnect: true
+    },
+    sttLifecycle: "continuous",
+    turnDetection: {
+      qualityProfile: "short-command",
+      profile: "balanced"
+    }
+  },
+  default: {
+    capture: {
+      channelCount: 1,
+      sampleRateHz: 16000
+    },
+    connection: {
+      maxReconnectAttempts: 10,
+      pingInterval: 30000,
+      reconnect: true
+    },
+    sttLifecycle: "continuous",
+    turnDetection: {
+      qualityProfile: "general",
+      profile: "fast"
+    }
+  },
+  dictation: {
+    audioConditioning: {
+      enabled: true,
+      maxGain: 2.25,
+      noiseGateAttenuation: 0.05,
+      noiseGateThreshold: 0.003,
+      targetLevel: 0.08
+    },
+    capture: {
+      channelCount: 1,
+      sampleRateHz: 16000
+    },
+    connection: {
+      maxReconnectAttempts: 12,
+      pingInterval: 30000,
+      reconnect: true
+    },
+    sttLifecycle: "continuous",
+    turnDetection: {
+      qualityProfile: "accent-heavy",
+      profile: "long-form"
+    }
+  },
+  "guided-intake": {
+    audioConditioning: {
+      enabled: true,
+      maxGain: 2.5,
+      noiseGateAttenuation: 0,
+      noiseGateThreshold: 0.004,
+      targetLevel: 0.08
+    },
+    capture: {
+      channelCount: 1,
+      sampleRateHz: 16000
+    },
+    connection: {
+      maxReconnectAttempts: 12,
+      pingInterval: 30000,
+      reconnect: true
+    },
+    sttLifecycle: "turn-scoped",
+    turnDetection: {
+      qualityProfile: "accent-heavy",
+      profile: "long-form"
+    }
+  },
+  "noisy-room": {
+    audioConditioning: {
+      enabled: true,
+      maxGain: 3,
+      noiseGateAttenuation: 0.12,
+      noiseGateThreshold: 0.006,
+      targetLevel: 0.085
+    },
+    capture: {
+      channelCount: 1,
+      sampleRateHz: 16000
+    },
+    connection: {
+      maxReconnectAttempts: 14,
+      pingInterval: 45000,
+      reconnect: true
+    },
+    sttLifecycle: "continuous",
+    turnDetection: {
+      qualityProfile: "noisy-room",
+      profile: "long-form",
+      silenceMs: 2100,
+      speechThreshold: 0.02,
+      transcriptStabilityMs: 1650
+    }
+  },
+  reliability: {
+    audioConditioning: {
+      enabled: true,
+      maxGain: 2.9,
+      noiseGateAttenuation: 0.08,
+      noiseGateThreshold: 0.005,
+      targetLevel: 0.08
+    },
+    capture: {
+      channelCount: 1,
+      sampleRateHz: 16000
+    },
+    connection: {
+      maxReconnectAttempts: 14,
+      pingInterval: 45000,
+      reconnect: true
+    },
+    sttLifecycle: "continuous",
+    turnDetection: {
+      qualityProfile: "noisy-room",
+      profile: "long-form"
+    }
+  }
+};
+var resolveVoiceRuntimePreset = (name = "default") => {
+  const preset = PRESET_INPUTS[name];
+  return {
+    audioConditioning: resolveAudioConditioningConfig(preset.audioConditioning),
+    capture: {
+      channelCount: preset.capture?.channelCount ?? 1,
+      sampleRateHz: preset.capture?.sampleRateHz ?? 16000
+    },
+    connection: {
+      ...preset.connection
+    },
+    name,
+    sttLifecycle: preset.sttLifecycle ?? "continuous",
+    turnDetection: resolveTurnDetectionConfig(preset.turnDetection)
+  };
+};
+
 // src/store.ts
 var createId = () => crypto.randomUUID();
-var createVoiceSessionRecord = (id) => ({
+var createVoiceSessionRecord = (id, scenarioId) => ({
   committedTurnIds: [],
   createdAt: Date.now(),
   currentTurn: {
     finalText: "",
+    lastSpeechAt: undefined,
+    lastTranscriptAt: undefined,
+    partialEndedAt: undefined,
+    partialStartedAt: undefined,
     partialText: "",
+    silenceStartedAt: undefined,
     transcripts: []
   },
   id,
+  scenarioId,
   reconnect: { attempts: 0 },
   status: "active",
   transcripts: [],
-  turns: []
+  turns: [],
+  lastCommittedTurn: {
+    committedAt: 0,
+    signature: "",
+    text: "",
+    transcriptIds: []
+  }
 });
-var resetVoiceSessionRecord = (id, existing) => ({
-  ...createVoiceSessionRecord(id),
+var resetVoiceSessionRecord = (id, existing, scenarioId) => ({
+  ...createVoiceSessionRecord(id, scenarioId),
   metadata: existing?.metadata
 });
 var toVoiceSessionSummary = (session) => ({
@@ -261,6 +541,61 @@ var measureAudioLevel = (audio) => {
   return Math.sqrt(sumSquares / samples.length);
 };
 var normalizeText = (value) => value.trim().replace(/\s+/g, " ");
+var countWords = (value) => value.length > 0 ? value.split(" ").length : 0;
+var selectPreferredTranscriptText = (currentText, nextText) => {
+  const current = normalizeText(currentText);
+  const next = normalizeText(nextText);
+  if (!current) {
+    return next;
+  }
+  if (!next) {
+    return current;
+  }
+  if (current === next || current.includes(next)) {
+    return current;
+  }
+  if (next.includes(current)) {
+    return next;
+  }
+  if (countWords(next) > countWords(current)) {
+    return next;
+  }
+  return current;
+};
+var mergeSequentialTranscriptText = (currentText, nextText) => {
+  const current = normalizeText(currentText);
+  const next = normalizeText(nextText);
+  if (!current) {
+    return next;
+  }
+  if (!next) {
+    return current;
+  }
+  const currentWords = current.split(" ");
+  const nextWords = next.split(" ");
+  const maxOverlap = Math.min(currentWords.length, nextWords.length);
+  for (let overlap = maxOverlap;overlap > 0; overlap -= 1) {
+    const currentSuffix = currentWords.slice(-overlap).join(" ");
+    const nextPrefix = nextWords.slice(0, overlap).join(" ");
+    if (currentSuffix === nextPrefix) {
+      return [...currentWords, ...nextWords.slice(overlap)].join(" ");
+    }
+  }
+  return `${current} ${next}`.trim();
+};
+var countCommonPrefixWords = (currentText, nextText) => {
+  const currentWords = normalizeText(currentText).split(" ").filter(Boolean);
+  const nextWords = normalizeText(nextText).split(" ").filter(Boolean);
+  const maxWords = Math.min(currentWords.length, nextWords.length);
+  let count = 0;
+  for (let index = 0;index < maxWords; index += 1) {
+    if (currentWords[index] !== nextWords[index]) {
+      break;
+    }
+    count += 1;
+  }
+  return count;
+};
 var mergeTranscriptTexts = (transcripts) => {
   const merged = [];
   for (const transcript of transcripts) {
@@ -284,24 +619,141 @@ var mergeTranscriptTexts = (transcripts) => {
   }
   return merged.join(" ").trim();
 };
-var buildTurnText = (transcripts, partialText) => {
+var buildTurnText = (transcripts, partialText, options = {}) => {
   const finalText = mergeTranscriptTexts(transcripts);
-  if (finalText) {
-    return finalText;
+  const nextPartial = normalizeText(partialText);
+  const lastFinalEndedAtMs = [...transcripts].reverse().find((transcript) => typeof transcript.endedAtMs === "number")?.endedAtMs;
+  if (finalText && nextPartial && typeof lastFinalEndedAtMs === "number" && typeof options.partialStartedAtMs === "number" && options.partialStartedAtMs - lastFinalEndedAtMs >= 250 && countCommonPrefixWords(finalText, nextPartial) === 0) {
+    return mergeSequentialTranscriptText(finalText, nextPartial);
   }
-  return normalizeText(partialText);
+  return selectPreferredTranscriptText(finalText, nextPartial);
 };
 
 // src/session.ts
 var DEFAULT_RECONNECT_TIMEOUT = 30000;
 var DEFAULT_MAX_RECONNECT_ATTEMPTS = 10;
+var DEFAULT_TRANSCRIPT_STABILITY_MS = 450;
+var DEFAULT_FALLBACK_REPLAY_MS = 8000;
+var DEFAULT_FALLBACK_SETTLE_MS = 220;
+var DEFAULT_FALLBACK_COMPLETION_TIMEOUT_MS = 2500;
+var DEFAULT_FALLBACK_CONFIDENCE_THRESHOLD = 0.6;
+var DEFAULT_FALLBACK_MIN_TEXT_LENGTH = 2;
+var DEFAULT_FALLBACK_MAX_ATTEMPTS_PER_TURN = 1;
+var DEFAULT_DUPLICATE_TURN_WINDOW_MS = 5000;
+var FALLBACK_CONFIDENCE_SELECTION_DELTA = 0.05;
+var FALLBACK_WORD_COUNT_SELECTION_MARGIN_RATIO = 0.12;
+var DEFAULT_FORMAT = {
+  channels: 1,
+  container: "raw",
+  encoding: "pcm_s16le",
+  sampleRateHz: 16000
+};
 var toError = (value) => value instanceof Error ? value : new Error(String(value));
 var createEmptyCurrentTurn = () => ({
   finalText: "",
+  lastSpeechAt: undefined,
+  lastTranscriptAt: undefined,
+  partialEndedAt: undefined,
+  partialStartedAt: undefined,
   partialText: "",
+  silenceStartedAt: undefined,
   transcripts: []
 });
 var cloneTranscript = (transcript) => ({ ...transcript });
+var countWords2 = (text) => text.trim().split(/\s+/).filter(Boolean).length;
+var normalizeText2 = (text) => text.trim().replace(/\s+/g, " ");
+var getAudioChunkDurationMs = (chunk) => chunk.byteLength / (DEFAULT_FORMAT.sampleRateHz * DEFAULT_FORMAT.channels * 2) * 1000;
+var getBufferedAudioDurationMs = (chunks) => chunks.reduce((total, chunk) => total + getAudioChunkDurationMs(chunk), 0);
+var calculateMeanConfidence = (transcripts) => {
+  let sum = 0;
+  let total = 0;
+  for (const transcript of transcripts) {
+    if (typeof transcript.confidence === "number") {
+      sum += transcript.confidence;
+      total += 1;
+    }
+  }
+  if (total === 0) {
+    return 0;
+  }
+  return sum / total;
+};
+var createTurnQuality = (transcripts, source, fallbackUsed, fallbackDiagnostics, correctionDiagnostics) => {
+  const sampledTranscripts = transcripts.filter((transcript) => typeof transcript.confidence === "number");
+  const confidenceSampleCount = sampledTranscripts.length;
+  return {
+    averageConfidence: confidenceSampleCount > 0 ? sampledTranscripts.reduce((sum, transcript) => sum + transcript.confidence, 0) / confidenceSampleCount : undefined,
+    confidenceSampleCount,
+    correction: correctionDiagnostics,
+    fallback: fallbackDiagnostics,
+    fallbackUsed,
+    finalTranscriptCount: transcripts.filter((transcript) => transcript.isFinal).length,
+    partialTranscriptCount: transcripts.filter((transcript) => !transcript.isFinal).length,
+    selectedTranscriptCount: transcripts.length,
+    source
+  };
+};
+var normalizeCorrectionText = (text) => normalizeText2(text);
+var isFallbackNeeded = (candidate, config) => {
+  const trimmed = normalizeText2(candidate.text);
+  const wordCount = countWords2(trimmed);
+  if (config.trigger === "always") {
+    return true;
+  }
+  if (config.trigger === "empty-turn") {
+    return wordCount < config.minTextLength;
+  }
+  const averageConfidence = calculateMeanConfidence(candidate.transcripts);
+  if (config.trigger === "low-confidence") {
+    return averageConfidence > 0 && averageConfidence < config.confidenceThreshold;
+  }
+  return averageConfidence > 0 && averageConfidence < config.confidenceThreshold || wordCount < config.minTextLength;
+};
+var selectBetterTurnText = (candidate, fallback) => {
+  if (!fallback.text) {
+    return {
+      reason: "fallback-empty",
+      winner: candidate
+    };
+  }
+  if (!candidate.text) {
+    return {
+      reason: "primary-empty",
+      winner: fallback
+    };
+  }
+  const largestWordCount = Math.max(candidate.wordCount, fallback.wordCount, 1);
+  const wordCountDelta = fallback.wordCount - candidate.wordCount;
+  const wordCountDeltaRatio = Math.abs(wordCountDelta) / largestWordCount;
+  if (wordCountDeltaRatio >= FALLBACK_WORD_COUNT_SELECTION_MARGIN_RATIO && wordCountDelta !== 0) {
+    return {
+      reason: "word-count-margin",
+      winner: wordCountDelta > 0 ? fallback : candidate
+    };
+  }
+  if (fallback.confidence > candidate.confidence + FALLBACK_CONFIDENCE_SELECTION_DELTA) {
+    return {
+      reason: "confidence-margin",
+      winner: fallback
+    };
+  }
+  if (candidate.confidence > fallback.confidence + FALLBACK_CONFIDENCE_SELECTION_DELTA) {
+    return {
+      reason: "kept-primary",
+      winner: candidate
+    };
+  }
+  if (fallback.wordCount > candidate.wordCount) {
+    return {
+      reason: "word-count-tiebreak",
+      winner: fallback
+    };
+  }
+  return {
+    reason: "kept-primary",
+    winner: candidate
+  };
+};
 var setTurnResult = (session, turnId, input) => {
   session.turns = session.turns.map((turn) => turn.id === turnId ? {
     ...turn,
@@ -318,12 +770,55 @@ var createVoiceSession = (options) => {
   };
   const turnDetection = {
     silenceMs: options.turnDetection.silenceMs ?? DEFAULT_SILENCE_MS,
-    speechThreshold: options.turnDetection.speechThreshold ?? DEFAULT_SPEECH_THRESHOLD
+    speechThreshold: options.turnDetection.speechThreshold ?? DEFAULT_SPEECH_THRESHOLD,
+    transcriptStabilityMs: options.turnDetection.transcriptStabilityMs ?? DEFAULT_TRANSCRIPT_STABILITY_MS
   };
+  const sttFallback = options.sttFallback ? {
+    adapter: options.sttFallback.adapter,
+    completionTimeoutMs: options.sttFallback.completionTimeoutMs ?? DEFAULT_FALLBACK_COMPLETION_TIMEOUT_MS,
+    confidenceThreshold: options.sttFallback.confidenceThreshold ?? DEFAULT_FALLBACK_CONFIDENCE_THRESHOLD,
+    maxAttemptsPerTurn: options.sttFallback.maxAttemptsPerTurn ?? DEFAULT_FALLBACK_MAX_ATTEMPTS_PER_TURN,
+    minTextLength: options.sttFallback.minTextLength ?? DEFAULT_FALLBACK_MIN_TEXT_LENGTH,
+    replayWindowMs: options.sttFallback.replayWindowMs ?? DEFAULT_FALLBACK_REPLAY_MS,
+    settleMs: options.sttFallback.settleMs ?? DEFAULT_FALLBACK_SETTLE_MS,
+    trigger: options.sttFallback.trigger ?? "empty-or-low-confidence"
+  } : undefined;
+  const phraseHints = options.phraseHints ?? [];
   let socket = options.socket;
   let sttSession = null;
   let silenceTimer = null;
   let speechDetected = false;
+  let operationQueue = Promise.resolve();
+  let adapterGenerationCounter = 0;
+  let activeAdapterGeneration = 0;
+  const currentTurnAudio = [];
+  let fallbackAttemptsForCurrentTurn = 0;
+  const pruneTurnAudio = () => {
+    const replayWindowMs = sttFallback?.replayWindowMs ?? DEFAULT_FALLBACK_REPLAY_MS;
+    const cutoffAt = Date.now() - replayWindowMs;
+    let index = 0;
+    while (index < currentTurnAudio.length && currentTurnAudio[index].recordedAt < cutoffAt) {
+      index += 1;
+    }
+    if (index > 0) {
+      currentTurnAudio.splice(0, index);
+    }
+  };
+  const pushTurnAudio = (audio) => {
+    const chunk = audio instanceof ArrayBuffer ? new Uint8Array(audio.slice(0)) : new Uint8Array(audio.buffer.slice(audio.byteOffset, audio.byteOffset + audio.byteLength));
+    currentTurnAudio.push({
+      chunk,
+      recordedAt: Date.now()
+    });
+    pruneTurnAudio();
+  };
+  const getFallbackWindowAudio = () => {
+    if (!sttFallback?.adapter) {
+      return [];
+    }
+    pruneTurnAudio();
+    return currentTurnAudio.map((audio) => audio.chunk);
+  };
   const clearSilenceTimer = () => {
     if (!silenceTimer) {
       return;
@@ -349,12 +844,28 @@ var createVoiceSession = (options) => {
     await options.store.set(options.id, session);
     return session;
   };
+  const runSerial = (phase, operation) => {
+    const result = operationQueue.then(async () => {
+      logger.debug("voice session operation", {
+        phase,
+        sessionId: options.id
+      });
+      return await operation();
+    });
+    operationQueue = result.then(() => {
+      return;
+    }, () => {
+      return;
+    });
+    return result;
+  };
   const closeAdapter = async (reason) => {
     if (!sttSession) {
       return;
     }
     const activeSession = sttSession;
     sttSession = null;
+    activeAdapterGeneration = 0;
     try {
       await activeSession.close(reason);
     } catch (error) {
@@ -364,13 +875,87 @@ var createVoiceSession = (options) => {
       });
     }
   };
-  const scheduleSilenceCommit = () => {
-    if (silenceTimer) {
+  const scheduleTurnCommit = (delayMs, reason, reset = true) => {
+    if (!reset && silenceTimer) {
       return;
     }
+    if (reset) {
+      clearSilenceTimer();
+    }
     silenceTimer = setTimeout(() => {
-      api.commitTurn("silence");
-    }, turnDetection.silenceMs);
+      silenceTimer = null;
+      api.commitTurn(reason);
+    }, delayMs);
+  };
+  const scheduleSilenceCommit = (delayMs = turnDetection.silenceMs, reset = true) => scheduleTurnCommit(delayMs, "silence", reset);
+  const requestTurnCommit = async (reason) => {
+    const session = await readSession();
+    const text = buildTurnText(session.currentTurn.transcripts, session.currentTurn.partialText, {
+      partialEndedAtMs: session.currentTurn.partialEndedAt,
+      partialStartedAtMs: session.currentTurn.partialStartedAt
+    });
+    if (!text) {
+      return;
+    }
+    const transcriptStabilityAge = session.currentTurn.lastTranscriptAt !== undefined ? Date.now() - session.currentTurn.lastTranscriptAt : undefined;
+    if (reason !== "manual" && typeof transcriptStabilityAge === "number" && transcriptStabilityAge < turnDetection.transcriptStabilityMs) {
+      scheduleTurnCommit(turnDetection.transcriptStabilityMs - transcriptStabilityAge, reason);
+      return;
+    }
+    await commitTurnInternal(reason);
+  };
+  const failInternal = async (error) => {
+    clearSilenceTimer();
+    const session = await writeSession((currentSession) => {
+      currentSession.lastActivityAt = Date.now();
+      currentSession.status = "failed";
+    });
+    const resolvedError = toError(error);
+    await send({
+      message: resolvedError.message,
+      recoverable: false,
+      type: "error"
+    });
+    await closeAdapter("failed");
+    speechDetected = false;
+    rewindFallbackTurnAudio();
+    await options.route.onError?.({
+      api,
+      context: options.context,
+      error: resolvedError,
+      session,
+      sessionId: options.id
+    });
+  };
+  const completeInternal = async (result) => {
+    clearSilenceTimer();
+    const session = await writeSession((currentSession) => {
+      if (currentSession.status === "completed") {
+        return;
+      }
+      currentSession.lastActivityAt = Date.now();
+      currentSession.status = "completed";
+      if (result !== undefined && currentSession.turns.length > 0) {
+        const lastTurn = currentSession.turns.at(-1);
+        if (lastTurn) {
+          setTurnResult(currentSession, lastTurn.id, {
+            result
+          });
+        }
+      }
+    });
+    await send({
+      sessionId: options.id,
+      type: "complete"
+    });
+    await closeAdapter("complete");
+    speechDetected = false;
+    rewindFallbackTurnAudio();
+    await options.route.onComplete({
+      api,
+      context: options.context,
+      session
+    });
   };
   const handleError = async (event) => {
     await send({
@@ -379,18 +964,273 @@ var createVoiceSession = (options) => {
       type: "error"
     });
     if (!event.recoverable) {
-      await api.fail(event.error);
+      await failInternal(event.error);
     }
   };
   const handleClose = async (event) => {
     if (event.recoverable === false) {
-      await api.fail(new Error(event.reason ?? "Speech-to-text session closed"));
+      await failInternal(new Error(event.reason ?? "Speech-to-text session closed"));
+      return;
+    }
+    if (!event.reason) {
+      await closeAdapter("provider stream closed");
+      return;
+    }
+    await closeAdapter(event.reason);
+  };
+  const rewindFallbackTurnAudio = () => {
+    fallbackAttemptsForCurrentTurn = 0;
+    currentTurnAudio.length = 0;
+  };
+  const runFallbackTranscription = async (primaryText, primaryTranscripts) => {
+    if (!sttFallback?.adapter || fallbackAttemptsForCurrentTurn >= sttFallback.maxAttemptsPerTurn) {
+      return null;
+    }
+    const candidate = {
+      text: primaryText,
+      transcripts: primaryTranscripts
+    };
+    if (!isFallbackNeeded(candidate, sttFallback)) {
+      return null;
+    }
+    fallbackAttemptsForCurrentTurn += 1;
+    const replayAudio = getFallbackWindowAudio();
+    if (replayAudio.length === 0) {
+      return null;
+    }
+    let fallbackSession = null;
+    const fallbackTranscripts = [];
+    let fallbackClosed = false;
+    let fallbackEndOfTurnReceived = false;
+    let fallbackFinalReceived = false;
+    let lastFallbackTranscriptAt = 0;
+    try {
+      fallbackSession = await sttFallback.adapter.open({
+        format: DEFAULT_FORMAT,
+        phraseHints,
+        sessionId: `${options.id}:fallback:${fallbackAttemptsForCurrentTurn}`
+      });
+    } catch (error) {
+      logger.warn("voice stt fallback open failed", {
+        error: toError(error).message,
+        sessionId: options.id
+      });
+      return null;
+    }
+    const unsubscribers = [
+      fallbackSession.on("final", ({ transcript }) => {
+        fallbackFinalReceived = true;
+        lastFallbackTranscriptAt = Date.now();
+        fallbackTranscripts.push(cloneTranscript(transcript));
+      }),
+      fallbackSession.on("partial", ({ transcript }) => {
+        lastFallbackTranscriptAt = Date.now();
+        fallbackTranscripts.push(cloneTranscript(transcript));
+      }),
+      fallbackSession.on("endOfTurn", () => {
+        fallbackEndOfTurnReceived = true;
+      }),
+      fallbackSession.on("error", (event) => {
+        logger.warn("voice stt fallback error", {
+          error: toError(event.error).message,
+          sessionId: options.id
+        });
+      }),
+      fallbackSession.on("close", () => {
+        fallbackClosed = true;
+      })
+    ];
+    const closeFallback = async (reason) => {
+      if (!fallbackSession) {
+        return;
+      }
+      try {
+        await fallbackSession.close(reason);
+      } catch (error) {
+        logger.warn("voice stt fallback close failed", {
+          error: toError(error).message,
+          sessionId: options.id
+        });
+      } finally {
+        fallbackSession = null;
+      }
+    };
+    try {
+      for (const chunk of replayAudio) {
+        await fallbackSession.send(chunk);
+      }
+      const replayDurationMs = getBufferedAudioDurationMs(replayAudio);
+      const completionTimeoutMs = Math.max(sttFallback.completionTimeoutMs, Math.min(4000, Math.max(sttFallback.settleMs * 4, Math.round(replayDurationMs * 0.18))));
+      const waitStartedAt = Date.now();
+      while (Date.now() - waitStartedAt < completionTimeoutMs) {
+        const idleMs = lastFallbackTranscriptAt > 0 ? Date.now() - lastFallbackTranscriptAt : Date.now() - waitStartedAt;
+        if (fallbackEndOfTurnReceived && idleMs >= sttFallback.settleMs) {
+          break;
+        }
+        if (fallbackFinalReceived && idleMs >= sttFallback.settleMs) {
+          break;
+        }
+        if (fallbackClosed && (lastFallbackTranscriptAt === 0 || idleMs >= sttFallback.settleMs)) {
+          break;
+        }
+        await Bun.sleep(Math.min(75, Math.max(25, sttFallback.settleMs / 2)));
+      }
+    } catch (error) {
+      logger.warn("voice stt fallback failed", {
+        error: toError(error).message,
+        sessionId: options.id
+      });
+    } finally {
+      await closeFallback("fallback-complete");
+      for (const unsubscribe of unsubscribers) {
+        unsubscribe();
+      }
+    }
+    if (fallbackTranscripts.length === 0) {
+      return null;
+    }
+    const fallbackText = buildTurnText(fallbackTranscripts, "", {});
+    const fallbackConfidence = calculateMeanConfidence(fallbackTranscripts);
+    const fallbackCandidate = {
+      confidence: fallbackConfidence,
+      text: fallbackText,
+      wordCount: countWords2(normalizeText2(fallbackText))
+    };
+    const primaryCandidate = {
+      confidence: calculateMeanConfidence(primaryTranscripts),
+      text: primaryText,
+      wordCount: countWords2(normalizeText2(primaryText))
+    };
+    const selection = selectBetterTurnText(primaryCandidate, fallbackCandidate);
+    const diagnostics = {
+      attempted: true,
+      fallbackConfidence: fallbackCandidate.confidence,
+      fallbackText: fallbackCandidate.text,
+      fallbackWordCount: fallbackCandidate.wordCount,
+      primaryConfidence: primaryCandidate.confidence,
+      primaryText,
+      primaryWordCount: primaryCandidate.wordCount,
+      selected: selection.winner.text === fallbackCandidate.text,
+      selectionReason: selection.reason,
+      trigger: sttFallback.trigger
+    };
+    if (selection.winner.text === primaryCandidate.text) {
+      return {
+        diagnostics,
+        fallbackUsed: false,
+        source: "primary",
+        text: primaryText,
+        transcripts: primaryTranscripts.map((transcript) => ({
+          ...transcript,
+          isFinal: true
+        }))
+      };
+    }
+    const candidateTranscripts = fallbackText === fallbackCandidate.text ? fallbackTranscripts : [];
+    return {
+      diagnostics,
+      fallbackUsed: true,
+      source: "fallback",
+      text: selection.winner.text,
+      transcripts: candidateTranscripts.length > 0 ? candidateTranscripts.map((transcript) => ({
+        ...transcript,
+        isFinal: true
+      })) : [{ id: createId(), isFinal: false, text: selection.winner.text }]
+    };
+  };
+  const getFinalTranscriptIds = (transcripts) => {
+    const finalTranscriptIds = transcripts.filter((transcript) => transcript.isFinal).map((transcript) => transcript.id);
+    const fallbackIds = transcripts.map((transcript) => transcript.id);
+    return finalTranscriptIds.length > 0 ? finalTranscriptIds : fallbackIds;
+  };
+  const runTurnCorrection = async (input) => {
+    if (!options.route.correctTurn) {
+      return;
     }
+    const originalText = input.text;
+    const result = await options.route.correctTurn({
+      api,
+      context: options.context,
+      fallback: input.fallbackDiagnostics,
+      phraseHints,
+      session: input.session,
+      text: originalText,
+      transcripts: input.transcripts.map(cloneTranscript)
+    });
+    const nextText = typeof result === "string" ? result : typeof result?.text === "string" ? result.text : originalText;
+    const correctedText = normalizeCorrectionText(nextText);
+    const normalizedOriginal = normalizeCorrectionText(originalText);
+    return {
+      diagnostics: {
+        attempted: true,
+        changed: correctedText.length > 0 && correctedText !== normalizedOriginal,
+        correctedText: correctedText.length > 0 ? correctedText : normalizedOriginal,
+        metadata: typeof result === "object" ? result.metadata : undefined,
+        originalText,
+        provider: typeof result === "object" ? result.provider : undefined,
+        reason: typeof result === "object" ? result.reason : undefined
+      },
+      text: correctedText.length > 0 ? correctedText : originalText
+    };
+  };
+  const ensureCommittedTurnGuard = (session) => {
+    if (!session.lastCommittedTurn) {
+      session.lastCommittedTurn = {
+        committedAt: 0,
+        signature: "",
+        text: "",
+        transcriptIds: []
+      };
+    }
+    return session;
+  };
+  const buildTurnSignature = (session, finalText, transcriptIdsOverride) => {
+    const finalTranscriptIds = transcriptIdsOverride ?? getFinalTranscriptIds(session.currentTurn.transcripts);
+    return `${normalizeText2(finalText)}|${finalTranscriptIds.join(",")}`;
+  };
+  const isDuplicateTurnCommit = (session, finalText) => {
+    const signature = buildTurnSignature(session, finalText);
+    const committedTurn = session.lastCommittedTurn;
+    const isRecent = committedTurn && committedTurn.committedAt > 0 && Date.now() - committedTurn.committedAt < DEFAULT_DUPLICATE_TURN_WINDOW_MS;
+    const committedSignature = committedTurn?.signature ?? "";
+    const committedTranscriptIds = committedTurn?.transcriptIds ?? [];
+    const committedText = normalizeText2(committedTurn?.text ?? "");
+    const isSameText = normalizeText2(finalText) === committedText;
+    const hasNoNewAudioSinceCommit = (session.currentTurn.lastAudioAt ?? 0) <= (committedTurn?.committedAt ?? 0);
+    if (!isRecent) {
+      return false;
+    }
+    if (isSameText && hasNoNewAudioSinceCommit) {
+      return true;
+    }
+    if (signature !== committedSignature) {
+      return false;
+    }
+    const lastSignatureIds = new Set(committedTranscriptIds);
+    const hasNoNewFinalIds = session.currentTurn.transcripts.every((transcript) => !transcript.isFinal || lastSignatureIds.has(transcript.id));
+    return isRecent && hasNoNewFinalIds;
+  };
+  const markTurnCommitted = (session, finalText, committedTranscripts) => {
+    session.lastCommittedTurn = {
+      ...session.lastCommittedTurn ?? {},
+      committedAt: Date.now(),
+      signature: buildTurnSignature(session, finalText, getFinalTranscriptIds(committedTranscripts)),
+      text: normalizeText2(finalText),
+      transcriptIds: getFinalTranscriptIds(committedTranscripts)
+    };
   };
   const handlePartial = async (transcript) => {
     await writeSession((session) => {
-      session.currentTurn.lastAudioAt = Date.now();
-      session.currentTurn.partialText = buildTurnText(session.currentTurn.transcripts, transcript.text);
+      const nextPartialStartedAt = transcript.startedAtMs ?? session.currentTurn.partialStartedAt;
+      const nextPartialEndedAt = transcript.endedAtMs ?? session.currentTurn.partialEndedAt;
+      const preferredPartial = selectPreferredTranscriptText(session.currentTurn.partialText, transcript.text);
+      session.currentTurn.lastTranscriptAt = Date.now();
+      session.currentTurn.partialStartedAt = nextPartialStartedAt;
+      session.currentTurn.partialEndedAt = nextPartialEndedAt;
+      session.currentTurn.partialText = buildTurnText(session.currentTurn.transcripts, preferredPartial, {
+        partialEndedAtMs: nextPartialEndedAt,
+        partialStartedAtMs: nextPartialStartedAt
+      });
       session.lastActivityAt = Date.now();
       session.status = "active";
     });
@@ -412,8 +1252,11 @@ var createVoiceSession = (options) => {
           cloneTranscript(transcript)
         ];
       }
-      session.currentTurn.finalText = buildTurnText(session.currentTurn.transcripts, session.currentTurn.partialText);
-      session.currentTurn.lastAudioAt = Date.now();
+      session.currentTurn.finalText = buildTurnText(session.currentTurn.transcripts, session.currentTurn.partialText, {
+        partialEndedAtMs: session.currentTurn.partialEndedAt,
+        partialStartedAtMs: session.currentTurn.partialStartedAt
+      });
+      session.currentTurn.lastTranscriptAt = Date.now();
       session.lastActivityAt = Date.now();
       session.status = "active";
     });
@@ -422,36 +1265,60 @@ var createVoiceSession = (options) => {
       type: "final"
     });
   };
+  const resumePendingTurnCommit = (session) => {
+    const pendingText = buildTurnText(session.currentTurn.transcripts, session.currentTurn.partialText, {
+      partialEndedAtMs: session.currentTurn.partialEndedAt,
+      partialStartedAtMs: session.currentTurn.partialStartedAt
+    });
+    if (!pendingText) {
+      speechDetected = false;
+      return;
+    }
+    speechDetected = true;
+    const audioAge = session.currentTurn.silenceStartedAt !== undefined ? Date.now() - session.currentTurn.silenceStartedAt : session.currentTurn.lastSpeechAt !== undefined ? Date.now() - session.currentTurn.lastSpeechAt : 0;
+    const transcriptAge = session.currentTurn.lastTranscriptAt !== undefined ? Date.now() - session.currentTurn.lastTranscriptAt : turnDetection.transcriptStabilityMs;
+    const delayMs = Math.max(0, turnDetection.silenceMs - audioAge, turnDetection.transcriptStabilityMs - transcriptAge);
+    scheduleSilenceCommit(delayMs);
+  };
   const ensureAdapter = async () => {
     if (sttSession) {
       return sttSession;
     }
-    sttSession = await options.stt.open({
-      format: {
-        channels: 1,
-        container: "raw",
-        encoding: "pcm_s16le",
-        sampleRateHz: 16000
-      },
+    const openedSession = await options.stt.open({
+      format: DEFAULT_FORMAT,
+      phraseHints,
       sessionId: options.id
     });
-    sttSession.on("partial", ({ transcript }) => {
-      handlePartial(transcript);
+    const generation = ++adapterGenerationCounter;
+    sttSession = openedSession;
+    activeAdapterGeneration = generation;
+    const runAdapterEvent = (phase, handler) => {
+      runSerial(phase, async () => {
+        if (activeAdapterGeneration !== generation) {
+          return;
+        }
+        await handler();
+      });
+    };
+    openedSession.on("partial", ({ transcript }) => {
+      runAdapterEvent("adapter.partial", () => handlePartial(transcript));
     });
-    sttSession.on("final", ({ transcript }) => {
-      handleFinal(transcript);
+    openedSession.on("final", ({ transcript }) => {
+      runAdapterEvent("adapter.final", () => handleFinal(transcript));
     });
-    sttSession.on("endOfTurn", ({ reason }) => {
-      clearSilenceTimer();
-      api.commitTurn(reason);
+    openedSession.on("endOfTurn", ({ reason }) => {
+      runAdapterEvent("adapter.endOfTurn", async () => {
+        clearSilenceTimer();
+        await requestTurnCommit(reason);
+      });
     });
-    sttSession.on("error", (event) => {
-      handleError(event);
+    openedSession.on("error", (event) => {
+      runAdapterEvent("adapter.error", () => handleError(event));
     });
-    sttSession.on("close", (event) => {
-      handleClose(event);
+    openedSession.on("close", (event) => {
+      runAdapterEvent("adapter.close", () => handleClose(event));
     });
-    return sttSession;
+    return openedSession;
   };
   const completeTurn = async (session, turn) => {
     const output = await options.route.onTurn({
@@ -480,207 +1347,267 @@ var createVoiceSession = (options) => {
       });
     }
     if (output?.complete) {
-      await api.complete(output.result);
+      await completeInternal(output.result);
     }
   };
-  const api = {
-    id: options.id,
-    close: async (reason) => {
-      clearSilenceTimer();
-      await closeAdapter(reason);
-      await Promise.resolve(socket.close(1000, reason));
-    },
-    commitTurn: async (reason = "manual") => {
-      clearSilenceTimer();
-      const session = await readSession();
-      if (session.status === "completed" || session.status === "failed") {
-        return;
-      }
-      const text = buildTurnText(session.currentTurn.transcripts, session.currentTurn.partialText);
-      if (!text) {
-        return;
+  const commitTurnInternal = async (reason = "manual") => {
+    clearSilenceTimer();
+    const session = await readSession();
+    if (session.status === "completed" || session.status === "failed") {
+      return;
+    }
+    const text = buildTurnText(session.currentTurn.transcripts, session.currentTurn.partialText, {
+      partialEndedAtMs: session.currentTurn.partialEndedAt,
+      partialStartedAtMs: session.currentTurn.partialStartedAt
+    });
+    let transcripts = session.currentTurn.transcripts.length ? session.currentTurn.transcripts.map(cloneTranscript) : [];
+    let finalText = text;
+    const transcriptStabilityAge = session.currentTurn.lastTranscriptAt !== undefined ? Date.now() - session.currentTurn.lastTranscriptAt : undefined;
+    const fallbackSelection = await runFallbackTranscription(text, session.currentTurn.transcripts);
+    const source = fallbackSelection?.source ?? "primary";
+    const fallbackUsed = fallbackSelection?.fallbackUsed ?? false;
+    const fallbackDiagnostics = fallbackSelection?.diagnostics;
+    if (fallbackSelection) {
+      finalText = fallbackSelection.text;
+      transcripts = fallbackSelection.transcripts.length ? fallbackSelection.transcripts.map(cloneTranscript) : transcripts.length ? transcripts : [
+        {
+          id: createId(),
+          isFinal: false,
+          text: finalText
+        }
+      ];
+      if (fallbackSelection.fallbackUsed) {
+        logger.info("voice fallback turn selected", {
+          reason,
+          sessionId: options.id,
+          text: finalText
+        });
       }
-      const turn = {
-        committedAt: Date.now(),
-        id: createId(),
-        text,
-        transcripts: session.currentTurn.transcripts.length > 0 ? session.currentTurn.transcripts.map(cloneTranscript) : [
-          {
-            id: createId(),
-            isFinal: false,
-            text
-          }
-        ]
-      };
-      const updatedSession = await writeSession((currentSession) => {
-        currentSession.committedTurnIds = [
-          ...currentSession.committedTurnIds,
-          turn.id
-        ];
-        currentSession.currentTurn = createEmptyCurrentTurn();
-        currentSession.lastActivityAt = Date.now();
-        currentSession.status = "active";
-        currentSession.turns = [...currentSession.turns, turn];
-      });
-      speechDetected = false;
-      logger.info("voice turn committed", {
+    }
+    const correctionSelection = await runTurnCorrection({
+      fallbackDiagnostics,
+      fallbackUsed,
+      session,
+      source,
+      text: finalText,
+      transcripts
+    });
+    const correctionDiagnostics = correctionSelection?.diagnostics;
+    if (correctionSelection) {
+      finalText = correctionSelection.text;
+    }
+    if (!finalText) {
+      return;
+    }
+    if (isDuplicateTurnCommit(session, finalText)) {
+      logger.debug("voice turn commit deduped", {
         reason,
-        sessionId: options.id,
-        turnId: turn.id
-      });
-      await send({
-        turn,
-        type: "turn"
+        sessionId: options.id
       });
-      await completeTurn(updatedSession, turn);
-    },
-    complete: async (result) => {
-      clearSilenceTimer();
-      const session = await writeSession((currentSession) => {
-        if (currentSession.status === "completed") {
-          return;
-        }
-        currentSession.lastActivityAt = Date.now();
-        currentSession.status = "completed";
-        if (result !== undefined && currentSession.turns.length > 0) {
-          const lastTurn = currentSession.turns.at(-1);
-          if (lastTurn) {
-            setTurnResult(currentSession, lastTurn.id, {
-              result
-            });
-          }
+      return;
+    }
+    if (typeof transcriptStabilityAge === "number" && transcriptStabilityAge < turnDetection.transcriptStabilityMs && reason !== "manual") {
+      scheduleTurnCommit(turnDetection.transcriptStabilityMs - transcriptStabilityAge, reason, false);
+      return;
+    }
+    const turn = {
+      committedAt: Date.now(),
+      id: createId(),
+      text: finalText,
+      quality: createTurnQuality(transcripts, source, fallbackUsed, fallbackDiagnostics, correctionDiagnostics),
+      transcripts: transcripts.length > 0 ? transcripts : [
+        {
+          id: createId(),
+          isFinal: false,
+          text: finalText
         }
-      });
-      await send({
-        sessionId: options.id,
-        type: "complete"
-      });
-      await closeAdapter("complete");
-      speechDetected = false;
-      await options.route.onComplete({
+      ]
+    };
+    const updatedSession = await writeSession((currentSession) => {
+      currentSession.committedTurnIds = [
+        ...currentSession.committedTurnIds,
+        turn.id
+      ];
+      currentSession.currentTurn = createEmptyCurrentTurn();
+      currentSession.lastActivityAt = Date.now();
+      currentSession.status = "active";
+      currentSession.turns = [...currentSession.turns, turn];
+      markTurnCommitted(currentSession, finalText, transcripts);
+    });
+    speechDetected = false;
+    rewindFallbackTurnAudio();
+    logger.info("voice turn committed", {
+      reason,
+      sessionId: options.id,
+      turnId: turn.id
+    });
+    await send({
+      turn,
+      type: "turn"
+    });
+    if (options.sttLifecycle === "turn-scoped") {
+      await closeAdapter("turn-commit");
+    }
+    await completeTurn(updatedSession, turn);
+  };
+  const connectInternal = async (nextSocket) => {
+    socket = nextSocket;
+    const existingSession = await options.store.get(options.id);
+    let session = existingSession ?? createVoiceSessionRecord(options.id, options.scenarioId);
+    if (options.scenarioId && session.scenarioId !== options.scenarioId) {
+      session.scenarioId = options.scenarioId;
+    }
+    ensureCommittedTurnGuard(session);
+    let shouldFireOnSession = !existingSession;
+    if (existingSession?.scenarioId && options.scenarioId && existingSession.scenarioId !== options.scenarioId) {
+      session = resetVoiceSessionRecord(options.id, existingSession, options.scenarioId);
+      shouldFireOnSession = true;
+    }
+    rewindFallbackTurnAudio();
+    if (existingSession?.status === "reconnecting") {
+      const nextAttempts = existingSession.reconnect.attempts + 1;
+      const reconnectExpired = existingSession.reconnect.lastDisconnectAt !== undefined && Date.now() - existingSession.reconnect.lastDisconnectAt > reconnect.timeout;
+      const tooManyAttempts = nextAttempts > reconnect.maxAttempts;
+      if (reconnect.strategy === "fail" && (reconnectExpired || tooManyAttempts)) {
+        await failInternal(new Error("Voice session reconnect policy exhausted"));
+        return;
+      }
+      if (reconnect.strategy === "restart" && (reconnectExpired || tooManyAttempts)) {
+        session = resetVoiceSessionRecord(options.id, existingSession, options.scenarioId);
+        shouldFireOnSession = true;
+      } else {
+        session = {
+          ...existingSession,
+          reconnect: {
+            ...existingSession.reconnect,
+            attempts: nextAttempts
+          },
+          status: "active"
+        };
+      }
+    }
+    await options.store.set(options.id, session);
+    await send({
+      sessionId: options.id,
+      status: session.status,
+      scenarioId: session.scenarioId,
+      type: "session"
+    });
+    if (shouldFireOnSession) {
+      await options.route.onSession?.({
         api,
         context: options.context,
         session
       });
-    },
-    connect: async (nextSocket) => {
-      socket = nextSocket;
-      const existingSession = await options.store.get(options.id);
-      let session = existingSession ?? createVoiceSessionRecord(options.id);
-      let shouldFireOnSession = !existingSession;
-      if (existingSession?.status === "reconnecting") {
-        const nextAttempts = existingSession.reconnect.attempts + 1;
-        const reconnectExpired = existingSession.reconnect.lastDisconnectAt !== undefined && Date.now() - existingSession.reconnect.lastDisconnectAt > reconnect.timeout;
-        const tooManyAttempts = nextAttempts > reconnect.maxAttempts;
-        if (reconnect.strategy === "fail" && (reconnectExpired || tooManyAttempts)) {
-          await api.fail(new Error("Voice session reconnect policy exhausted"));
-          return;
-        }
-        if (reconnect.strategy === "restart" && (reconnectExpired || tooManyAttempts)) {
-          session = resetVoiceSessionRecord(options.id, existingSession);
-          shouldFireOnSession = true;
-        } else {
-          session = {
-            ...existingSession,
-            reconnect: {
-              ...existingSession.reconnect,
-              attempts: nextAttempts
-            },
-            status: "active"
-          };
-        }
-      }
-      await options.store.set(options.id, session);
+    }
+    if (session.status === "completed") {
       await send({
         sessionId: options.id,
-        status: session.status,
-        type: "session"
+        type: "complete"
       });
-      if (shouldFireOnSession) {
-        await options.route.onSession?.({
-          api,
-          context: options.context,
-          session
-        });
-      }
-      if (session.status === "completed") {
-        await send({
-          sessionId: options.id,
-          type: "complete"
-        });
+      return;
+    }
+    resumePendingTurnCommit(session);
+    await ensureAdapter();
+  };
+  const disconnectInternal = async (event) => {
+    clearSilenceTimer();
+    await closeAdapter(event?.reason);
+    rewindFallbackTurnAudio();
+    if (reconnect.strategy === "fail") {
+      await failInternal(new Error(event?.reason ?? "Voice socket disconnected"));
+      return;
+    }
+    await writeSession((session) => {
+      if (session.status === "completed" || session.status === "failed") {
         return;
       }
-      await ensureAdapter();
-    },
-    disconnect: async (event) => {
-      clearSilenceTimer();
-      await closeAdapter(event?.reason);
-      if (reconnect.strategy === "fail") {
-        await api.fail(new Error(event?.reason ?? "Voice socket disconnected"));
-        return;
+      session.lastActivityAt = Date.now();
+      session.reconnect.lastDisconnectAt = Date.now();
+      session.status = "reconnecting";
+    });
+    speechDetected = false;
+  };
+  const receiveAudioInternal = async (audio) => {
+    const session = await readSession();
+    if (session.status === "completed" || session.status === "failed") {
+      return;
+    }
+    const adapter = await ensureAdapter();
+    const conditionedAudio = conditionAudioChunk(audio, options.audioConditioning);
+    const audioLevel = measureAudioLevel(conditionedAudio);
+    const shouldStoreAudio = speechDetected || audioLevel >= turnDetection.speechThreshold;
+    await writeSession((currentSession) => {
+      currentSession.currentTurn.lastAudioAt = Date.now();
+      currentSession.lastActivityAt = Date.now();
+      currentSession.status = "active";
+      if (audioLevel >= turnDetection.speechThreshold) {
+        currentSession.currentTurn.lastSpeechAt = Date.now();
+        currentSession.currentTurn.silenceStartedAt = undefined;
+      } else if (speechDetected && currentSession.currentTurn.silenceStartedAt === undefined) {
+        currentSession.currentTurn.silenceStartedAt = Date.now();
       }
-      await writeSession((session) => {
-        if (session.status === "completed" || session.status === "failed") {
-          return;
-        }
-        session.lastActivityAt = Date.now();
-        session.reconnect.lastDisconnectAt = Date.now();
-        session.status = "reconnecting";
-      });
-      speechDetected = false;
-    },
-    fail: async (error) => {
+    });
+    if (shouldStoreAudio) {
+      pushTurnAudio(conditionedAudio);
+    }
+    if (audioLevel >= turnDetection.speechThreshold) {
+      speechDetected = true;
       clearSilenceTimer();
-      const session = await writeSession((currentSession) => {
-        currentSession.lastActivityAt = Date.now();
-        currentSession.status = "failed";
-      });
-      const resolvedError = toError(error);
-      await send({
-        message: resolvedError.message,
-        recoverable: false,
-        type: "error"
-      });
-      await closeAdapter("failed");
-      speechDetected = false;
-      await options.route.onError?.({
-        api,
-        context: options.context,
-        error: resolvedError,
-        session,
-        sessionId: options.id
-      });
-    },
-    receiveAudio: async (audio) => {
-      const session = await readSession();
-      if (session.status === "completed" || session.status === "failed") {
-        return;
+    } else if (speechDetected) {
+      const currentSession = await readSession();
+      const hasTurnText = Boolean(buildTurnText(currentSession.currentTurn.transcripts, currentSession.currentTurn.partialText, {
+        partialEndedAtMs: currentSession.currentTurn.partialEndedAt,
+        partialStartedAtMs: currentSession.currentTurn.partialStartedAt
+      }));
+      if (hasTurnText) {
+        scheduleSilenceCommit(turnDetection.silenceMs, false);
       }
-      const adapter = await ensureAdapter();
-      const audioLevel = measureAudioLevel(audio);
-      await writeSession((currentSession) => {
-        currentSession.currentTurn.lastAudioAt = Date.now();
-        currentSession.lastActivityAt = Date.now();
-        currentSession.status = "active";
-      });
-      if (audioLevel >= turnDetection.speechThreshold) {
-        speechDetected = true;
+    }
+    await adapter.send(conditionedAudio);
+  };
+  const api = {
+    id: options.id,
+    close: async (reason) => {
+      await runSerial("api.close", async () => {
         clearSilenceTimer();
-      } else if (speechDetected) {
-        const currentSession = await readSession();
-        const hasTurnText = Boolean(buildTurnText(currentSession.currentTurn.transcripts, currentSession.currentTurn.partialText));
-        if (hasTurnText) {
-          scheduleSilenceCommit();
-        }
-      }
-      await adapter.send(audio);
+        await closeAdapter(reason);
+        await Promise.resolve(socket.close(1000, reason));
+      });
     },
-    snapshot: async () => readSession()
+    commitTurn: async (reason = "manual") => runSerial("api.commitTurn", async () => {
+      await commitTurnInternal(reason);
+    }),
+    complete: async (result) => runSerial("api.complete", async () => {
+      await completeInternal(result);
+    }),
+    connect: async (nextSocket) => runSerial("api.connect", async () => {
+      await connectInternal(nextSocket);
+    }),
+    disconnect: async (event) => runSerial("api.disconnect", async () => {
+      await disconnectInternal(event);
+    }),
+    fail: async (error) => runSerial("api.fail", async () => {
+      await failInternal(error);
+    }),
+    receiveAudio: async (audio) => runSerial("api.receiveAudio", async () => {
+      await receiveAudioInternal(audio);
+    }),
+    snapshot: async () => runSerial("api.snapshot", async () => readSession())
   };
   return api;
 };
 
 // src/plugin.ts
+var resolveQueryScenario = (query) => {
+  if (typeof query?.scenarioId === "string" && query.scenarioId.trim()) {
+    return query.scenarioId.trim();
+  }
+  if (typeof query?.mode === "string" && query.mode.trim()) {
+    return query.mode.trim();
+  }
+  return null;
+};
 var HTMX_BOOTSTRAP_DIST_CANDIDATES = [
   resolve(import.meta.dir, "client", "htmxBootstrap.js"),
   resolve(import.meta.dir, "..", "dist", "client", "htmxBootstrap.js")
@@ -727,6 +1654,21 @@ ${log}` : ""}`);
   };
 })();
 var isArrayBufferView = (value) => typeof value === "object" && value !== null && ArrayBuffer.isView(value);
+var resolveSTTFallbackConfig = (config) => {
+  if (!config) {
+    return;
+  }
+  return {
+    adapter: config.adapter,
+    completionTimeoutMs: config.completionTimeoutMs ?? 2500,
+    confidenceThreshold: config.confidenceThreshold ?? 0.6,
+    maxAttemptsPerTurn: config.maxAttemptsPerTurn ?? 1,
+    minTextLength: config.minTextLength ?? 2,
+    replayWindowMs: config.replayWindowMs ?? 8000,
+    settleMs: config.settleMs ?? 220,
+    trigger: config.trigger ?? "empty-or-low-confidence"
+  };
+};
 var isVoiceClientMessage = (value) => {
   if (!value || typeof value !== "object" || !("type" in value)) {
     return false;
@@ -739,7 +1681,7 @@ var isVoiceClientMessage = (value) => {
     case "ping":
       return true;
     case "start":
-      return !("sessionId" in value) || typeof value.sessionId === "string";
+      return (!("sessionId" in value) || typeof value.sessionId === "string") && (!("scenarioId" in value) || typeof value.scenarioId === "string");
     default:
       return false;
   }
@@ -759,14 +1701,16 @@ var parseClientMessage = (raw) => {
   return null;
 };
 var resolveSessionId = (runtime, ws) => {
-  const existing = runtime.socketSessions.get(ws);
-  if (existing) {
-    return existing;
-  }
   const query = ws.data && typeof ws.data === "object" && "query" in ws.data ? ws.data.query : undefined;
-  const providedSessionId = typeof query?.sessionId === "string" && query.sessionId.trim() ? query.sessionId.trim() : createId();
-  runtime.socketSessions.set(ws, providedSessionId);
-  return providedSessionId;
+  const existing = runtime.socketSessions.get(ws);
+  const providedSessionId = typeof query?.sessionId === "string" && query.sessionId.trim() ? query.sessionId.trim() : existing?.sessionId ?? createId();
+  const scenarioId = resolveQueryScenario(query) ?? existing?.scenarioId ?? null;
+  const resolved = {
+    sessionId: providedSessionId,
+    scenarioId
+  };
+  runtime.socketSessions.set(ws, resolved);
+  return resolved;
 };
 var toAudioChunk = (raw) => {
   if (raw instanceof ArrayBuffer) {
@@ -792,6 +1736,38 @@ var normalizeOnTurn = (handler) => {
   }
   return handler;
 };
+var resolveSessionOptions = (config) => {
+  const preset = resolveVoiceRuntimePreset(config.preset);
+  return {
+    audioConditioning: config.audioConditioning !== undefined ? resolveAudioConditioningConfig(config.audioConditioning) : preset.audioConditioning,
+    sttFallback: resolveSTTFallbackConfig(config.sttFallback),
+    logger: config.logger,
+    reconnect: {
+      maxAttempts: config.reconnect?.maxAttempts ?? 10,
+      strategy: config.reconnect?.strategy ?? "resume-last-turn",
+      timeout: config.reconnect?.timeout ?? 30000
+    },
+    sttLifecycle: config.sttLifecycle ?? preset.sttLifecycle,
+    turnDetection: resolveTurnDetectionConfig({
+      ...preset.turnDetection,
+      ...config.turnDetection
+    })
+  };
+};
+var normalizePhraseHints = (hints) => (hints ?? []).map((hint) => ({
+  ...hint,
+  aliases: hint.aliases?.filter((value) => typeof value === "string" && value.trim().length > 0),
+  text: hint.text.trim()
+})).filter((hint) => hint.text.length > 0);
+var resolvePhraseHints = async (config, input) => {
+  if (!config.phraseHints) {
+    return [];
+  }
+  if (typeof config.phraseHints === "function") {
+    return normalizePhraseHints(await config.phraseHints(input));
+  }
+  return normalizePhraseHints(config.phraseHints);
+};
 var voice = (config) => {
   const runtime = {
     activeSessions: new Map,
@@ -799,11 +1775,42 @@ var voice = (config) => {
     socketSessions: new WeakMap
   };
   const onTurn = normalizeOnTurn(config.onTurn);
+  const sessionOptions = resolveSessionOptions(config);
   const htmxOptions = config.htmx && typeof config.htmx === "object" ? config.htmx : undefined;
   const htmxRoute = htmxOptions?.route ?? `${config.path}/htmx/session`;
   const htmxBootstrapRoute = htmxOptions?.bootstrapRoute ?? `${config.path}/htmx/bootstrap.js`;
   const htmxRenderers = resolveVoiceHTMXRenderers(config.htmx && config.htmx !== true ? config.htmx : undefined);
   const htmxTargets = resolveVoiceHTMXTargets(htmxOptions?.targets);
+  const createManagedSession = async (ws, sessionId, scenarioId) => {
+    const context = ws.data;
+    const phraseHints = await resolvePhraseHints(config, {
+      context,
+      scenarioId,
+      sessionId
+    });
+    return createVoiceSession({
+      audioConditioning: sessionOptions.audioConditioning,
+      context,
+      id: sessionId,
+      logger: sessionOptions.logger,
+      phraseHints,
+      reconnect: sessionOptions.reconnect,
+      route: {
+        correctTurn: config.correctTurn,
+        onComplete: config.onComplete,
+        onError: config.onError,
+        onSession: config.onSession,
+        onTurn
+      },
+      scenarioId,
+      socket: createSocketAdapter(ws),
+      store: config.session,
+      stt: config.stt,
+      sttFallback: sessionOptions.sttFallback,
+      sttLifecycle: sessionOptions.sttLifecycle,
+      turnDetection: sessionOptions.turnDetection
+    });
+  };
   const htmxRoutes = () => {
     if (!config.htmx) {
       return new Elysia;
@@ -833,12 +1840,12 @@ var voice = (config) => {
   };
   return new Elysia({ name: "absolutejs-voice" }).ws(config.path, {
     close: async (ws, code, reason) => {
-      const sessionId = runtime.socketSessions.get(ws);
-      if (!sessionId) {
+      const socketState = runtime.socketSessions.get(ws);
+      if (!socketState) {
         return;
       }
-      const session = runtime.activeSessions.get(sessionId);
-      runtime.activeSessions.delete(sessionId);
+      const session = runtime.activeSessions.get(socketState.sessionId);
+      runtime.activeSessions.delete(socketState.sessionId);
       if (session) {
         await session.disconnect({
           code,
@@ -849,8 +1856,8 @@ var voice = (config) => {
       }
     },
     message: async (ws, raw) => {
-      const sessionId = resolveSessionId(runtime, ws);
-      const current = runtime.activeSessions.get(sessionId);
+      const sessionState = resolveSessionId(runtime, ws);
+      const current = runtime.activeSessions.get(sessionState.sessionId);
       const message = parseClientMessage(raw);
       if (message) {
         if (message.type === "ping") {
@@ -861,10 +1868,27 @@ var voice = (config) => {
         }
         if (message.type === "close" && current) {
           await current.close(message.reason);
-          runtime.activeSessions.delete(sessionId);
+          runtime.activeSessions.delete(sessionState.sessionId);
+        }
+        if (message.type === "start" && message.sessionId && message.sessionId !== sessionState.sessionId) {
+          const currentSession = runtime.activeSessions.get(sessionState.sessionId);
+          if (currentSession) {
+            await currentSession.close("session-switch");
+            runtime.activeSessions.delete(sessionState.sessionId);
+          }
+          sessionState.sessionId = message.sessionId;
+          runtime.socketSessions.set(ws, {
+            ...sessionState,
+            sessionId: message.sessionId,
+            scenarioId: sessionState.scenarioId
+          });
         }
-        if (message.type === "start" && message.sessionId && message.sessionId !== sessionId) {
-          runtime.socketSessions.set(ws, message.sessionId);
+        if (message.type === "start" && message.scenarioId) {
+          sessionState.scenarioId = message.scenarioId;
+          runtime.socketSessions.set(ws, {
+            ...sessionState,
+            scenarioId: message.scenarioId
+          });
         }
         return;
       }
@@ -872,66 +1896,22 @@ var voice = (config) => {
       if (!audio) {
         return;
       }
-      const session = current ?? createVoiceSession({
-        context: ws.data,
-        id: sessionId,
-        logger: config.logger,
-        reconnect: {
-          maxAttempts: config.reconnect?.maxAttempts ?? 10,
-          strategy: config.reconnect?.strategy ?? "resume-last-turn",
-          timeout: config.reconnect?.timeout ?? 30000
-        },
-        route: {
-          onComplete: config.onComplete,
-          onError: config.onError,
-          onSession: config.onSession,
-          onTurn
-        },
-        socket: createSocketAdapter(ws),
-        store: config.session,
-        stt: config.stt,
-        turnDetection: {
-          silenceMs: config.turnDetection?.silenceMs ?? 700,
-          speechThreshold: config.turnDetection?.speechThreshold ?? 0.015
-        }
-      });
+      const session = current ?? await createManagedSession(ws, sessionState.sessionId, sessionState.scenarioId ?? undefined);
       if (!current) {
-        runtime.activeSessions.set(sessionId, session);
+        runtime.activeSessions.set(sessionState.sessionId, session);
         await session.connect(createSocketAdapter(ws));
       }
       await session.receiveAudio(audio);
     },
     open: async (ws) => {
-      const sessionId = resolveSessionId(runtime, ws);
-      const existing = runtime.activeSessions.get(sessionId);
+      const sessionState = resolveSessionId(runtime, ws);
+      const existing = runtime.activeSessions.get(sessionState.sessionId);
       if (existing) {
         await existing.close("superseded");
-        runtime.activeSessions.delete(sessionId);
+        runtime.activeSessions.delete(sessionState.sessionId);
       }
-      const session = createVoiceSession({
-        context: ws.data,
-        id: sessionId,
-        logger: config.logger,
-        reconnect: {
-          maxAttempts: config.reconnect?.maxAttempts ?? 10,
-          strategy: config.reconnect?.strategy ?? "resume-last-turn",
-          timeout: config.reconnect?.timeout ?? 30000
-        },
-        route: {
-          onComplete: config.onComplete,
-          onError: config.onError,
-          onSession: config.onSession,
-          onTurn
-        },
-        socket: createSocketAdapter(ws),
-        store: config.session,
-        stt: config.stt,
-        turnDetection: {
-          silenceMs: config.turnDetection?.silenceMs ?? 700,
-          speechThreshold: config.turnDetection?.speechThreshold ?? 0.015
-        }
-      });
-      runtime.activeSessions.set(sessionId, session);
+      const session = await createManagedSession(ws, sessionState.sessionId, sessionState.scenarioId ?? undefined);
+      runtime.activeSessions.set(sessionState.sessionId, session);
       await session.connect(createSocketAdapter(ws));
     }
   }).use(htmxRoutes());
@@ -957,10 +1937,61 @@ var createVoiceMemoryStore = () => {
   };
   return { get, getOrCreate, list, remove, set };
 };
+// src/correction.ts
+var escapeRegExp = (value) => value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+var normalizeHintAliases = (hint) => (hint.aliases ?? []).map((alias) => alias.trim()).filter((alias) => alias.length > 0).sort((left, right) => right.length - left.length);
+var applyPhraseHintCorrections = (text, phraseHints) => {
+  let corrected = text;
+  const matches = [];
+  for (const hint of phraseHints) {
+    for (const alias of normalizeHintAliases(hint)) {
+      const matcher = new RegExp(`\\b${escapeRegExp(alias)}\\b`, "gi");
+      if (!matcher.test(corrected)) {
+        continue;
+      }
+      corrected = corrected.replace(matcher, hint.text);
+      matches.push({
+        alias,
+        hint
+      });
+    }
+  }
+  return {
+    changed: corrected !== text,
+    matches,
+    text: corrected
+  };
+};
+var createPhraseHintCorrectionHandler = (options = {}) => {
+  const provider = options.provider ?? "@absolutejs/voice";
+  const reason = options.reason ?? "phrase-hint-correction";
+  return async ({ phraseHints, text }) => {
+    const result = applyPhraseHintCorrections(text, phraseHints);
+    if (!result.changed) {
+      return;
+    }
+    return {
+      metadata: result.matches.length > 0 ? {
+        matchedAliases: result.matches.map((match) => match.alias),
+        matchedHints: result.matches.map((match) => match.hint.text)
+      } : undefined,
+      provider,
+      reason,
+      text: result.text
+    };
+  };
+};
 export {
   voice,
+  resolveVoiceRuntimePreset,
+  resolveTurnDetectionConfig,
+  resolveAudioConditioningConfig,
   createVoiceSessionRecord,
   createVoiceSession,
   createVoiceMemoryStore,
-  createId
+  createPhraseHintCorrectionHandler,
+  createId,
+  conditionAudioChunk,
+  applyPhraseHintCorrections,
+  TURN_PROFILE_DEFAULTS
 };