@absolutejs/voice 0.0.22-beta.31 → 0.0.22-beta.33

package/dist/index.d.ts

@@ -7,6 +7,7 @@ export { createStoredVoiceCallReviewArtifact, createStoredVoiceExternalObjectMap
 export { createVoiceAssistantMemoryHandle, createVoiceAssistantMemoryRecord, createVoiceMemoryAssistantMemoryStore, resolveVoiceAssistantMemoryNamespace } from './assistantMemory';
 export { createAnthropicVoiceAssistantModel, createGeminiVoiceAssistantModel, createJSONVoiceAssistantModel, createOpenAIVoiceAssistantModel, createVoiceProviderRouter } from './modelAdapters';
 export { createVoiceProviderHealthHTMLHandler, createVoiceProviderHealthJSONHandler, createVoiceProviderHealthRoutes, renderVoiceProviderHealthHTML, summarizeVoiceProviderHealth } from './providerHealth';
+export { createVoiceSTTProviderRouter, createVoiceTTSProviderRouter } from './providerAdapters';
 export { buildVoiceTraceReplay, createVoiceMemoryTraceSinkDeliveryStore, createVoiceTraceHTTPSink, createVoiceMemoryTraceEventStore, createVoiceTraceSinkDeliveryId, createVoiceTraceSinkDeliveryRecord, createVoiceTraceSinkStore, createVoiceTraceEvent, createVoiceTraceEventId, deliverVoiceTraceEventsToSinks, evaluateVoiceTrace, exportVoiceTrace, filterVoiceTraceEvents, pruneVoiceTraceEvents, redactVoiceTraceEvent, redactVoiceTraceEvents, redactVoiceTraceText, renderVoiceTraceHTML, renderVoiceTraceMarkdown, resolveVoiceTraceRedactionOptions, selectVoiceTraceEventsForPrune, summarizeVoiceTrace } from './trace';
 export { createVoiceSQLiteExternalObjectMapStore, createVoiceSQLiteIntegrationEventStore, createVoiceSQLiteReviewStore, createVoiceSQLiteRuntimeStorage, createVoiceSQLiteSessionStore, createVoiceSQLiteTaskStore, createVoiceSQLiteTraceSinkDeliveryStore, createVoiceSQLiteTraceEventStore } from './sqliteStore';
 export { createVoicePostgresExternalObjectMapStore, createVoicePostgresIntegrationEventStore, createVoicePostgresReviewStore, createVoicePostgresRuntimeStorage, createVoicePostgresSessionStore, createVoicePostgresTaskStore, createVoicePostgresTraceSinkDeliveryStore, createVoicePostgresTraceEventStore } from './postgresStore';
@@ -36,6 +37,7 @@ export type { VoiceAssistantMemoryBinding, VoiceAssistantMemoryHandle, VoiceAssi
 export type { VoiceSessionListHTMLHandlerOptions, VoiceSessionListItem, VoiceSessionListOptions, VoiceSessionListRoutesOptions, VoiceSessionListStatus, VoiceSessionReplay, VoiceSessionReplayHTMLHandlerOptions, VoiceSessionReplayOptions, VoiceSessionReplayRoutesOptions, VoiceSessionReplayTurn } from './sessionReplay';
 export type { AnthropicVoiceAssistantModelOptions, GeminiVoiceAssistantModelOptions, OpenAIVoiceAssistantModelOptions, VoiceProviderRouterEvent, VoiceProviderRouterFallbackMode, VoiceProviderRouterHealthOptions, VoiceProviderRouterOptions, VoiceProviderRouterPolicy, VoiceProviderRouterProviderHealth, VoiceProviderRouterProviderProfile, VoiceJSONAssistantModelHandler, VoiceJSONAssistantModelOptions } from './modelAdapters';
 export type { VoiceProviderHealthStatus, VoiceProviderHealthSummary, VoiceProviderHealthSummaryOptions } from './providerHealth';
+export type { VoiceIOProviderRouterEvent, VoiceSTTProviderRouterOptions, VoiceTTSProviderRouterOptions } from './providerAdapters';
 export type { VoiceAgent, VoiceAgentMessage, VoiceAgentMessageRole, VoiceAgentModel, VoiceAgentModelInput, VoiceAgentModelOutput, VoiceAgentOptions, VoiceAgentRunResult, VoiceAgentSquadOptions, VoiceAgentTool, VoiceAgentToolCall, VoiceAgentToolResult } from './agent';
 export type { VoiceOpsRuntime, VoiceOpsRuntimeConfig, VoiceOpsRuntimeSummary, VoiceOpsRuntimeSinkWorkerConfig, VoiceOpsRuntimeTaskWorkerConfig, VoiceOpsRuntimeTickResult, VoiceOpsRuntimeWebhookWorkerConfig } from './opsRuntime';
 export type { VoiceOpsPresetName, VoiceOpsPresetOverrides, VoiceResolvedOpsPreset } from './opsPresets';

package/dist/index.js

@@ -6552,7 +6552,8 @@ var summarizeVoiceProviderHealth = async (input) => {
       rateLimited: false,
       recommended: false,
       runCount: 0,
-      status: "idle"
+      status: "idle",
+      timeoutCount: 0
     };
     entries.set(provider, entry);
     return entry;
@@ -6629,6 +6630,9 @@ var summarizeVoiceProviderHealth = async (input) => {
     }
     const entry = applyProviderHealth();
     entry.errorCount += 1;
+    if (event.payload.timedOut === true) {
+      entry.timeoutCount += 1;
+    }
     entry.lastError = getString(event.payload.error);
     entry.lastErrorAt = event.at;
     entry.rateLimited ||= event.payload.rateLimited === true;
@@ -6653,7 +6657,8 @@ var summarizeVoiceProviderHealth = async (input) => {
       runCount: entry.runCount,
       status,
       suppressionRemainingMs: activeSuppression ? suppressionRemainingMs : undefined,
-      suppressedUntil: entry.suppressedUntil
+      suppressedUntil: entry.suppressedUntil,
+      timeoutCount: entry.timeoutCount
     };
   });
   const recommended = summaries.filter((entry) => entry.status === "healthy").sort((left, right) => (left.averageElapsedMs ?? Number.MAX_SAFE_INTEGER) - (right.averageElapsedMs ?? Number.MAX_SAFE_INTEGER))[0];
@@ -6677,6 +6682,7 @@ var renderVoiceProviderHealthHTML = (providers) => providers.length === 0 ? '<p
       `<div><dt>Runs</dt><dd>${String(provider.runCount)}</dd></div>`,
       `<div><dt>Avg latency</dt><dd>${String(provider.averageElapsedMs ?? 0)}ms</dd></div>`,
       `<div><dt>Errors</dt><dd>${String(provider.errorCount)}</dd></div>`,
+      `<div><dt>Timeouts</dt><dd>${String(provider.timeoutCount)}</dd></div>`,
       `<div><dt>Fallbacks</dt><dd>${String(provider.fallbackCount)}</dd></div>`,
       "</dl>",
       suppressionSeconds ? `<p>Temporarily suppressed for ${String(suppressionSeconds)}s.</p>` : "",
@@ -8132,6 +8138,17 @@ var parseJSONValue = (value) => {
     return value;
   }
 };
+
+class VoiceProviderTimeoutError extends Error {
+  provider;
+  timeoutMs;
+  constructor(provider, timeoutMs) {
+    super(`Voice provider ${provider} exceeded ${timeoutMs}ms latency budget.`);
+    this.name = "VoiceProviderTimeoutError";
+    this.provider = provider;
+    this.timeoutMs = timeoutMs;
+  }
+}
 var getMessageToolCalls = (message) => {
   const toolCalls = message.metadata?.toolCalls;
   return Array.isArray(toolCalls) ? toolCalls.filter((toolCall) => toolCall && typeof toolCall === "object" && typeof toolCall.name === "string") : [];
@@ -8209,6 +8226,10 @@ var createVoiceProviderRouter = (options) => {
   const failureThreshold = Math.max(1, healthOptions?.failureThreshold ?? 1);
   const cooldownMs = Math.max(0, healthOptions?.cooldownMs ?? 30000);
   const rateLimitCooldownMs = Math.max(0, healthOptions?.rateLimitCooldownMs ?? 60000);
+  const getProviderTimeoutMs = (provider) => {
+    const timeoutMs = options.providerProfiles?.[provider]?.timeoutMs ?? options.timeoutMs;
+    return typeof timeoutMs === "number" && Number.isFinite(timeoutMs) && timeoutMs > 0 ? timeoutMs : undefined;
+  };
   const getHealth = (provider) => {
     const existing = healthState.get(provider);
     if (existing) {
@@ -8320,6 +8341,25 @@ var createVoiceProviderRouter = (options) => {
   const emit = async (event, input) => {
     await options.onProviderEvent?.(event, input);
   };
+  const runProvider = async (provider, model, input) => {
+    const timeoutMs = getProviderTimeoutMs(provider);
+    if (!timeoutMs) {
+      return model.generate(input);
+    }
+    let timeout;
+    try {
+      return await Promise.race([
+        model.generate(input),
+        new Promise((_, reject) => {
+          timeout = setTimeout(() => reject(new VoiceProviderTimeoutError(provider, timeoutMs)), timeoutMs);
+        })
+      ]);
+    } finally {
+      if (timeout) {
+        clearTimeout(timeout);
+      }
+    }
+  };
   return {
     generate: async (input) => {
       const { order, selectedProvider } = await resolveOrder(input);
@@ -8334,12 +8374,14 @@ var createVoiceProviderRouter = (options) => {
         }
         const startedAt = Date.now();
         try {
-          const output = await model.generate(input);
+          const output = await runProvider(provider, model, input);
           const providerHealth = recordProviderSuccess(provider);
           await emit({
             at: Date.now(),
+            attempt: index + 1,
             elapsedMs: Date.now() - startedAt,
             fallbackProvider: provider === selectedProvider ? undefined : provider,
+            latencyBudgetMs: getProviderTimeoutMs(provider),
             provider,
             providerHealth,
             recovered: provider !== selectedProvider,
@@ -8351,22 +8393,26 @@ var createVoiceProviderRouter = (options) => {
           lastError = error;
           const hasNextProvider = index < order.length - 1;
           const isProviderError = options.isProviderError?.(error, provider) ?? true;
+          const timedOut = options.isTimeoutError?.(error, provider) ?? error instanceof VoiceProviderTimeoutError;
           const rateLimited = options.isRateLimitError?.(error, provider) ?? defaultIsRateLimitError(error);
           const shouldFallback = fallbackMode === "provider-error" ? isProviderError : fallbackMode === "rate-limit" ? isProviderError && rateLimited : false;
           const providerHealth = recordProviderError(provider, isProviderError, rateLimited);
           const nextProvider = hasNextProvider ? order[index + 1] : undefined;
           await emit({
             at: Date.now(),
+            attempt: index + 1,
             elapsedMs: Date.now() - startedAt,
             error: errorMessage(error),
             fallbackProvider: shouldFallback ? nextProvider : undefined,
+            latencyBudgetMs: getProviderTimeoutMs(provider),
             provider,
             providerHealth,
             rateLimited,
             selectedProvider,
             suppressionRemainingMs: getSuppressionRemainingMs(provider),
             suppressedUntil: providerHealth?.suppressedUntil,
-            status: "error"
+            status: "error",
+            timedOut
           }, input);
           if (!hasNextProvider || !shouldFallback) {
             throw error;
@@ -8812,6 +8858,288 @@ var createGeminiVoiceAssistantModel = (options) => {
     }
   };
 };
+// src/providerAdapters.ts
+class VoiceIOProviderTimeoutError extends Error {
+  provider;
+  timeoutMs;
+  constructor(kind, provider, timeoutMs) {
+    super(`Voice ${kind} provider ${provider} exceeded ${timeoutMs}ms latency budget.`);
+    this.name = "VoiceIOProviderTimeoutError";
+    this.provider = provider;
+    this.timeoutMs = timeoutMs;
+  }
+}
+var errorMessage2 = (error) => error instanceof Error ? error.message : String(error);
+var createEmitter = () => {
+  const listeners = new Map;
+  return {
+    emit: async (event, payload) => {
+      await Promise.all([...listeners.get(event) ?? []].map((handler) => Promise.resolve(handler(payload))));
+    },
+    on: (event, handler) => {
+      const set = listeners.get(event) ?? new Set;
+      set.add(handler);
+      listeners.set(event, set);
+      return () => {
+        set.delete(handler);
+      };
+    }
+  };
+};
+var getTimeoutMs = (options, provider) => {
+  const timeoutMs = options.providerProfiles?.[provider]?.timeoutMs ?? options.timeoutMs;
+  return typeof timeoutMs === "number" && Number.isFinite(timeoutMs) && timeoutMs > 0 ? timeoutMs : undefined;
+};
+var withTimeout = async (input) => {
+  if (!input.timeoutMs) {
+    return input.run();
+  }
+  let timeout;
+  try {
+    return await Promise.race([
+      Promise.resolve(input.run()),
+      new Promise((_, reject) => {
+        timeout = setTimeout(() => reject(new VoiceIOProviderTimeoutError(input.kind, input.provider, input.timeoutMs)), input.timeoutMs);
+      })
+    ]);
+  } finally {
+    if (timeout) {
+      clearTimeout(timeout);
+    }
+  }
+};
+var createResolver = (options) => {
+  const providerIds = Object.keys(options.adapters);
+  const firstProvider = providerIds[0];
+  const resolveOrder = async (input) => {
+    const selectedProvider = await options.selectProvider?.(input) ?? firstProvider;
+    const fallbackOrder = typeof options.fallback === "function" ? await options.fallback(input) : options.fallback;
+    const candidates = [selectedProvider, ...fallbackOrder ?? providerIds];
+    const seen = new Set;
+    const order = candidates.filter((provider) => {
+      if (!provider || seen.has(provider) || !options.adapters[provider]) {
+        return false;
+      }
+      seen.add(provider);
+      return true;
+    });
+    return {
+      order,
+      selectedProvider
+    };
+  };
+  const emit = async (event, input) => {
+    await options.onProviderEvent?.(event, input);
+  };
+  return {
+    emit,
+    providerIds,
+    resolveOrder
+  };
+};
+var createVoiceSTTProviderRouter = (options) => {
+  const resolver = createResolver(options);
+  return {
+    kind: "stt",
+    open: async (input) => {
+      const { order, selectedProvider } = await resolver.resolveOrder(input);
+      if (!selectedProvider || order.length === 0) {
+        throw new Error("Voice STT provider router has no available providers.");
+      }
+      let lastError;
+      for (const [index, provider] of order.entries()) {
+        const adapter = options.adapters[provider];
+        if (!adapter) {
+          continue;
+        }
+        const startedAt = Date.now();
+        try {
+          const session = await withTimeout({
+            kind: "stt",
+            operation: "open",
+            provider,
+            run: () => adapter.open(input),
+            timeoutMs: getTimeoutMs(options, provider)
+          });
+          await resolver.emit({
+            at: Date.now(),
+            attempt: index + 1,
+            elapsedMs: Date.now() - startedAt,
+            fallbackProvider: provider === selectedProvider ? undefined : provider,
+            kind: "stt",
+            latencyBudgetMs: getTimeoutMs(options, provider),
+            operation: "open",
+            provider,
+            selectedProvider,
+            status: provider === selectedProvider ? "success" : "fallback"
+          }, input);
+          return session;
+        } catch (error) {
+          lastError = error;
+          const hasNextProvider = index < order.length - 1;
+          const shouldFallback = options.isProviderError?.(error, provider) ?? true;
+          await resolver.emit({
+            at: Date.now(),
+            attempt: index + 1,
+            elapsedMs: Date.now() - startedAt,
+            error: errorMessage2(error),
+            fallbackProvider: shouldFallback ? order[index + 1] : undefined,
+            kind: "stt",
+            latencyBudgetMs: getTimeoutMs(options, provider),
+            operation: "open",
+            provider,
+            selectedProvider,
+            status: "error",
+            timedOut: error instanceof VoiceIOProviderTimeoutError
+          }, input);
+          if (!hasNextProvider || !shouldFallback) {
+            throw error;
+          }
+        }
+      }
+      throw lastError ?? new Error("Voice STT provider router did not open a provider.");
+    }
+  };
+};
+var createVoiceTTSProviderRouter = (options) => {
+  const resolver = createResolver(options);
+  return {
+    kind: "tts",
+    open: async (input) => {
+      const { order, selectedProvider } = await resolver.resolveOrder(input);
+      if (!selectedProvider || order.length === 0) {
+        throw new Error("Voice TTS provider router has no available providers.");
+      }
+      const emitter = createEmitter();
+      let activeSession;
+      let activeProvider;
+      let nextProviderIndex = 0;
+      const attach = (session) => {
+        session.on("audio", (event) => emitter.emit("audio", event));
+        session.on("error", (event) => emitter.emit("error", event));
+        session.on("close", (event) => emitter.emit("close", event));
+      };
+      const openProvider = async (provider, attempt) => {
+        const adapter = options.adapters[provider];
+        if (!adapter) {
+          throw new Error(`Voice TTS provider ${provider} is not configured.`);
+        }
+        const startedAt = Date.now();
+        const session = await withTimeout({
+          kind: "tts",
+          operation: "open",
+          provider,
+          run: () => adapter.open(input),
+          timeoutMs: getTimeoutMs(options, provider)
+        });
+        attach(session);
+        activeSession = session;
+        activeProvider = provider;
+        await resolver.emit({
+          at: Date.now(),
+          attempt,
+          elapsedMs: Date.now() - startedAt,
+          fallbackProvider: provider === selectedProvider ? undefined : provider,
+          kind: "tts",
+          latencyBudgetMs: getTimeoutMs(options, provider),
+          operation: "open",
+          provider,
+          selectedProvider,
+          status: provider === selectedProvider ? "success" : "fallback"
+        }, input);
+        return session;
+      };
+      const failProvider = async (inputEvent) => {
+        const shouldFallback = options.isProviderError?.(inputEvent.error, inputEvent.provider) ?? true;
+        await resolver.emit({
+          at: Date.now(),
+          attempt: inputEvent.attempt,
+          elapsedMs: Date.now() - inputEvent.startedAt,
+          error: errorMessage2(inputEvent.error),
+          fallbackProvider: shouldFallback ? order[nextProviderIndex] : undefined,
+          kind: "tts",
+          latencyBudgetMs: getTimeoutMs(options, inputEvent.provider),
+          operation: inputEvent.operation,
+          provider: inputEvent.provider,
+          selectedProvider,
+          status: "error",
+          timedOut: inputEvent.error instanceof VoiceIOProviderTimeoutError
+        }, input);
+        return shouldFallback;
+      };
+      for (const [index, provider] of order.entries()) {
+        nextProviderIndex = index + 1;
+        const startedAt = Date.now();
+        try {
+          await openProvider(provider, index + 1);
+          break;
+        } catch (error) {
+          const shouldFallback = await failProvider({
+            attempt: index + 1,
+            error,
+            operation: "open",
+            provider,
+            startedAt
+          });
+          if (!shouldFallback || index >= order.length - 1) {
+            throw error;
+          }
+        }
+      }
+      if (!activeSession || !activeProvider) {
+        throw new Error("Voice TTS provider router did not open a provider.");
+      }
+      const sendWithFallback = async (text) => {
+        for (;; ) {
+          const session = activeSession;
+          const provider = activeProvider;
+          if (!session || !provider) {
+            throw new Error("Voice TTS provider router has no active provider.");
+          }
+          const startedAt = Date.now();
+          try {
+            await withTimeout({
+              kind: "tts",
+              operation: "send",
+              provider,
+              run: () => session.send(text),
+              timeoutMs: getTimeoutMs(options, provider)
+            });
+            return;
+          } catch (error) {
+            const shouldFallback = await failProvider({
+              attempt: nextProviderIndex,
+              error,
+              operation: "send",
+              provider,
+              startedAt
+            });
+            const nextProvider = order[nextProviderIndex];
+            if (!shouldFallback || !nextProvider) {
+              throw error;
+            }
+            nextProviderIndex += 1;
+            await session.close("tts-provider-fallback").catch(() => {});
+            await openProvider(nextProvider, nextProviderIndex);
+          }
+        }
+      };
+      return {
+        close: async (reason) => {
+          await activeSession?.close(reason);
+          activeSession = undefined;
+          activeProvider = undefined;
+          await emitter.emit("close", {
+            reason,
+            type: "close"
+          });
+        },
+        on: emitter.on,
+        send: sendWithFallback
+      };
+    }
+  };
+};
 // src/sqliteStore.ts
 import { Database } from "bun:sqlite";
 var normalizeTableNameSegment = (value) => value.trim().replace(/[^a-zA-Z0-9_]+/g, "_").replace(/^_+|_+$/g, "") || "voice";
@@ -10510,10 +10838,10 @@ var createVoiceOpsTaskProcessorWorker = (options) => ({
         result.completed += 1;
       } catch (error) {
         await options.onError?.(error, task);
-        const errorMessage2 = error instanceof Error ? error.message : String(error);
+        const errorMessage3 = error instanceof Error ? error.message : String(error);
         const failedTask = failVoiceOpsTask(task, {
           actor: task.claimedBy ?? "ops-worker",
-          error: errorMessage2
+          error: errorMessage3
         });
         if (shouldDeadLetterTask(failedTask, options.maxFailures)) {
           const deadLetterTask = deadLetterVoiceOpsTask(failedTask, {
@@ -11840,6 +12168,7 @@ export {
   createVoiceTaskUpdatedEvent,
   createVoiceTaskSLABreachedEvent,
   createVoiceTaskCreatedEvent,
+  createVoiceTTSProviderRouter,
   createVoiceSessionsJSONHandler,
   createVoiceSessionsHTMLHandler,
   createVoiceSessionReplayRoutes,
@@ -11849,6 +12178,7 @@ export {
   createVoiceSessionListRoutes,
   createVoiceSession,
   createVoiceSTTRoutingCorrectionHandler,
+  createVoiceSTTProviderRouter,
   createVoiceSQLiteTraceSinkDeliveryStore,
   createVoiceSQLiteTraceEventStore,
   createVoiceSQLiteTaskStore,

package/dist/modelAdapters.d.ts

@@ -36,9 +36,11 @@ export type GeminiVoiceAssistantModelOptions = {
 };
 export type VoiceProviderRouterEvent<TProvider extends string = string> = {
     at: number;
+    attempt: number;
     elapsedMs: number;
     error?: string;
     fallbackProvider?: TProvider;
+    latencyBudgetMs?: number;
     provider: TProvider;
     providerHealth?: VoiceProviderRouterProviderHealth<TProvider>;
     rateLimited?: boolean;
@@ -47,6 +49,7 @@ export type VoiceProviderRouterEvent<TProvider extends string = string> = {
     suppressionRemainingMs?: number;
     suppressedUntil?: number;
     status: 'error' | 'fallback' | 'success';
+    timedOut?: boolean;
 };
 export type VoiceProviderRouterFallbackMode = 'never' | 'provider-error' | 'rate-limit';
 export type VoiceProviderRouterPolicy<TContext = unknown, TSession extends VoiceSessionRecord = VoiceSessionRecord, TProvider extends string = string> = 'ordered' | 'prefer-cheapest' | 'prefer-fastest' | 'prefer-selected' | {
@@ -58,6 +61,7 @@ export type VoiceProviderRouterProviderProfile = {
     cost?: number;
     latencyMs?: number;
     priority?: number;
+    timeoutMs?: number;
 };
 export type VoiceProviderRouterHealthOptions = {
     cooldownMs?: number;
@@ -79,10 +83,12 @@ export type VoiceProviderRouterOptions<TContext = unknown, TSession extends Voic
     fallbackMode?: VoiceProviderRouterFallbackMode;
     isProviderError?: (error: unknown, provider: TProvider) => boolean;
     isRateLimitError?: (error: unknown, provider: TProvider) => boolean;
+    isTimeoutError?: (error: unknown, provider: TProvider) => boolean;
     onProviderEvent?: (event: VoiceProviderRouterEvent<TProvider>, input: VoiceAgentModelInput<TContext, TSession>) => Promise<void> | void;
     policy?: VoiceProviderRouterPolicy<TContext, TSession, TProvider>;
     providerHealth?: boolean | VoiceProviderRouterHealthOptions;
     providerProfiles?: Partial<Record<TProvider, VoiceProviderRouterProviderProfile>>;
+    timeoutMs?: number;
     providers: Partial<Record<TProvider, VoiceAgentModel<TContext, TSession, TResult>>>;
     selectProvider?: (input: VoiceAgentModelInput<TContext, TSession>) => TProvider | undefined | Promise<TProvider | undefined>;
 };

package/dist/providerAdapters.d.ts

@@ -0,0 +1,33 @@
+import type { STTAdapter, STTAdapterOpenOptions, TTSAdapter, TTSAdapterOpenOptions } from './types';
+import type { VoiceProviderRouterProviderProfile } from './modelAdapters';
+type MaybePromise<T> = T | Promise<T>;
+type VoiceIOProviderKind = 'stt' | 'tts';
+type VoiceIOProviderStatus = 'error' | 'fallback' | 'success';
+export type VoiceIOProviderRouterEvent<TProvider extends string = string> = {
+    at: number;
+    attempt: number;
+    elapsedMs: number;
+    error?: string;
+    fallbackProvider?: TProvider;
+    kind: VoiceIOProviderKind;
+    latencyBudgetMs?: number;
+    operation: 'open' | 'send';
+    provider: TProvider;
+    selectedProvider: TProvider;
+    status: VoiceIOProviderStatus;
+    timedOut?: boolean;
+};
+export type VoiceIOProviderRouterOptions<TProvider extends string, TAdapter, TOpenOptions> = {
+    adapters: Partial<Record<TProvider, TAdapter>>;
+    fallback?: readonly TProvider[] | ((input: TOpenOptions) => MaybePromise<readonly TProvider[]>);
+    isProviderError?: (error: unknown, provider: TProvider) => boolean;
+    onProviderEvent?: (event: VoiceIOProviderRouterEvent<TProvider>, input: TOpenOptions) => Promise<void> | void;
+    providerProfiles?: Partial<Record<TProvider, VoiceProviderRouterProviderProfile>>;
+    selectProvider?: (input: TOpenOptions) => MaybePromise<TProvider | undefined>;
+    timeoutMs?: number;
+};
+export type VoiceSTTProviderRouterOptions<TProvider extends string = string, TOptions extends STTAdapterOpenOptions = STTAdapterOpenOptions> = VoiceIOProviderRouterOptions<TProvider, STTAdapter<TOptions>, TOptions>;
+export type VoiceTTSProviderRouterOptions<TProvider extends string = string, TOptions extends TTSAdapterOpenOptions = TTSAdapterOpenOptions> = VoiceIOProviderRouterOptions<TProvider, TTSAdapter<TOptions>, TOptions>;
+export declare const createVoiceSTTProviderRouter: <TProvider extends string = string, TOptions extends STTAdapterOpenOptions = STTAdapterOpenOptions>(options: VoiceSTTProviderRouterOptions<TProvider, TOptions>) => STTAdapter<TOptions>;
+export declare const createVoiceTTSProviderRouter: <TProvider extends string = string, TOptions extends TTSAdapterOpenOptions = TTSAdapterOpenOptions>(options: VoiceTTSProviderRouterOptions<TProvider, TOptions>) => TTSAdapter<TOptions>;
+export {};

package/dist/providerHealth.d.ts

@@ -15,6 +15,7 @@ export type VoiceProviderHealthSummary<TProvider extends string = string> = {
     status: VoiceProviderHealthStatus;
     suppressionRemainingMs?: number;
     suppressedUntil?: number;
+    timeoutCount: number;
 };
 export type VoiceProviderHealthSummaryOptions<TProvider extends string = string> = {
     events?: StoredVoiceTraceEvent[];

package/dist/testing/index.js

@@ -3601,6 +3601,17 @@ var parseJSONValue = (value) => {
     return value;
   }
 };
+
+class VoiceProviderTimeoutError extends Error {
+  provider;
+  timeoutMs;
+  constructor(provider, timeoutMs) {
+    super(`Voice provider ${provider} exceeded ${timeoutMs}ms latency budget.`);
+    this.name = "VoiceProviderTimeoutError";
+    this.provider = provider;
+    this.timeoutMs = timeoutMs;
+  }
+}
 var getMessageToolCalls = (message) => {
   const toolCalls = message.metadata?.toolCalls;
   return Array.isArray(toolCalls) ? toolCalls.filter((toolCall) => toolCall && typeof toolCall === "object" && typeof toolCall.name === "string") : [];
@@ -3678,6 +3689,10 @@ var createVoiceProviderRouter = (options) => {
   const failureThreshold = Math.max(1, healthOptions?.failureThreshold ?? 1);
   const cooldownMs = Math.max(0, healthOptions?.cooldownMs ?? 30000);
   const rateLimitCooldownMs = Math.max(0, healthOptions?.rateLimitCooldownMs ?? 60000);
+  const getProviderTimeoutMs = (provider) => {
+    const timeoutMs = options.providerProfiles?.[provider]?.timeoutMs ?? options.timeoutMs;
+    return typeof timeoutMs === "number" && Number.isFinite(timeoutMs) && timeoutMs > 0 ? timeoutMs : undefined;
+  };
   const getHealth = (provider) => {
     const existing = healthState.get(provider);
     if (existing) {
@@ -3789,6 +3804,25 @@ var createVoiceProviderRouter = (options) => {
   const emit = async (event, input) => {
     await options.onProviderEvent?.(event, input);
   };
+  const runProvider = async (provider, model, input) => {
+    const timeoutMs = getProviderTimeoutMs(provider);
+    if (!timeoutMs) {
+      return model.generate(input);
+    }
+    let timeout;
+    try {
+      return await Promise.race([
+        model.generate(input),
+        new Promise((_, reject) => {
+          timeout = setTimeout(() => reject(new VoiceProviderTimeoutError(provider, timeoutMs)), timeoutMs);
+        })
+      ]);
+    } finally {
+      if (timeout) {
+        clearTimeout(timeout);
+      }
+    }
+  };
   return {
     generate: async (input) => {
       const { order, selectedProvider } = await resolveOrder(input);
@@ -3803,12 +3837,14 @@ var createVoiceProviderRouter = (options) => {
         }
         const startedAt = Date.now();
         try {
-          const output = await model.generate(input);
+          const output = await runProvider(provider, model, input);
           const providerHealth = recordProviderSuccess(provider);
           await emit({
             at: Date.now(),
+            attempt: index + 1,
             elapsedMs: Date.now() - startedAt,
             fallbackProvider: provider === selectedProvider ? undefined : provider,
+            latencyBudgetMs: getProviderTimeoutMs(provider),
             provider,
             providerHealth,
             recovered: provider !== selectedProvider,
@@ -3820,22 +3856,26 @@ var createVoiceProviderRouter = (options) => {
           lastError = error;
           const hasNextProvider = index < order.length - 1;
           const isProviderError = options.isProviderError?.(error, provider) ?? true;
+          const timedOut = options.isTimeoutError?.(error, provider) ?? error instanceof VoiceProviderTimeoutError;
           const rateLimited = options.isRateLimitError?.(error, provider) ?? defaultIsRateLimitError(error);
           const shouldFallback = fallbackMode === "provider-error" ? isProviderError : fallbackMode === "rate-limit" ? isProviderError && rateLimited : false;
           const providerHealth = recordProviderError(provider, isProviderError, rateLimited);
           const nextProvider = hasNextProvider ? order[index + 1] : undefined;
           await emit({
             at: Date.now(),
+            attempt: index + 1,
             elapsedMs: Date.now() - startedAt,
             error: errorMessage(error),
             fallbackProvider: shouldFallback ? nextProvider : undefined,
+            latencyBudgetMs: getProviderTimeoutMs(provider),
             provider,
             providerHealth,
             rateLimited,
             selectedProvider,
             suppressionRemainingMs: getSuppressionRemainingMs(provider),
             suppressedUntil: providerHealth?.suppressedUntil,
-            status: "error"
+            status: "error",
+            timedOut
           }, input);
           if (!hasNextProvider || !shouldFallback) {
             throw error;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@absolutejs/voice",
-	"version": "0.0.22-beta.31",
+	"version": "0.0.22-beta.33",
 	"description": "Voice primitives and Elysia plugin for AbsoluteJS",
 	"repository": {
 		"type": "git",