@absolutejs/voice 0.0.22-beta.16 → 0.0.22-beta.17

package/dist/testing/index.d.ts

@@ -3,6 +3,7 @@ export * from './benchmark';
 export * from './corrected';
 export * from './duplex';
 export * from './fixtures';
+export * from './providerSimulator';
 export * from './resilience';
 export * from './review';
 export * from './sessionBenchmark';

package/dist/testing/index.js

@@ -3468,6 +3468,778 @@ var loadVoiceTestFixtures = async (fixtureDirectory) => {
   }
   return fixtures;
 };
+// src/modelAdapters.ts
+var OUTPUT_SCHEMA = {
+  additionalProperties: false,
+  properties: {
+    assistantText: {
+      type: "string"
+    },
+    complete: {
+      type: "boolean"
+    },
+    escalate: {
+      additionalProperties: false,
+      properties: {
+        metadata: {
+          additionalProperties: true,
+          type: "object"
+        },
+        reason: {
+          type: "string"
+        }
+      },
+      required: ["reason"],
+      type: "object"
+    },
+    noAnswer: {
+      additionalProperties: false,
+      properties: {
+        metadata: {
+          additionalProperties: true,
+          type: "object"
+        }
+      },
+      type: "object"
+    },
+    result: {
+      additionalProperties: true,
+      type: "object"
+    },
+    transfer: {
+      additionalProperties: false,
+      properties: {
+        metadata: {
+          additionalProperties: true,
+          type: "object"
+        },
+        reason: {
+          type: "string"
+        },
+        target: {
+          type: "string"
+        }
+      },
+      required: ["target"],
+      type: "object"
+    },
+    voicemail: {
+      additionalProperties: false,
+      properties: {
+        metadata: {
+          additionalProperties: true,
+          type: "object"
+        }
+      },
+      type: "object"
+    }
+  },
+  type: "object"
+};
+var ROUTE_RESULT_INSTRUCTION = "Return only a JSON object with assistantText, complete, transfer, escalate, voicemail, noAnswer, and result when you are not calling tools. Only set transfer, escalate, voicemail, or noAnswer when the user explicitly asks for that lifecycle outcome or a tool result says that exact outcome. Do not infer voicemail from generic words like voice, voice app, or voice integration.";
+var stripJSONCodeFence = (value) => {
+  const trimmed = value.trim();
+  const match = trimmed.match(/^```(?:json)?\s*([\s\S]*?)\s*```$/i);
+  return match?.[1]?.trim() ?? value;
+};
+var parseJSON = (value) => {
+  try {
+    const parsed = JSON.parse(stripJSONCodeFence(value));
+    return parsed && typeof parsed === "object" ? parsed : {};
+  } catch {
+    return {
+      assistantText: value
+    };
+  }
+};
+var parseJSONValue = (value) => {
+  try {
+    return JSON.parse(value);
+  } catch {
+    return value;
+  }
+};
+var getMessageToolCalls = (message) => {
+  const toolCalls = message.metadata?.toolCalls;
+  return Array.isArray(toolCalls) ? toolCalls.filter((toolCall) => toolCall && typeof toolCall === "object" && typeof toolCall.name === "string") : [];
+};
+var createHTTPError = (provider, response) => new Error(`${provider} voice assistant model failed: HTTP ${response.status}`);
+var sleep = (ms) => new Promise((resolve2) => {
+  setTimeout(resolve2, ms);
+});
+var errorMessage = (error) => error instanceof Error ? error.message : String(error);
+var defaultIsRateLimitError = (error) => /(\b429\b|rate limit|quota|too many requests)/i.test(errorMessage(error));
+var normalizeRouteOutput = (output) => {
+  const result = {};
+  if (typeof output.assistantText === "string") {
+    result.assistantText = output.assistantText;
+  }
+  if (typeof output.complete === "boolean") {
+    result.complete = output.complete;
+  }
+  if (output.result !== undefined) {
+    result.result = output.result;
+  }
+  if (output.transfer && typeof output.transfer === "object") {
+    const transfer = output.transfer;
+    if (typeof transfer.target === "string") {
+      result.transfer = {
+        metadata: transfer.metadata && typeof transfer.metadata === "object" ? transfer.metadata : undefined,
+        reason: typeof transfer.reason === "string" ? transfer.reason : undefined,
+        target: transfer.target
+      };
+    }
+  }
+  if (output.escalate && typeof output.escalate === "object") {
+    const escalate = output.escalate;
+    if (typeof escalate.reason === "string") {
+      result.escalate = {
+        metadata: escalate.metadata && typeof escalate.metadata === "object" ? escalate.metadata : undefined,
+        reason: escalate.reason
+      };
+    }
+  }
+  if (output.voicemail && typeof output.voicemail === "object") {
+    const voicemail = output.voicemail;
+    result.voicemail = {
+      metadata: voicemail.metadata && typeof voicemail.metadata === "object" ? voicemail.metadata : undefined
+    };
+  }
+  if (output.noAnswer && typeof output.noAnswer === "object") {
+    const noAnswer = output.noAnswer;
+    result.noAnswer = {
+      metadata: noAnswer.metadata && typeof noAnswer.metadata === "object" ? noAnswer.metadata : undefined
+    };
+  }
+  return result;
+};
+var createJSONVoiceAssistantModel = (options) => ({
+  generate: async (input) => {
+    const output = await options.generate(input);
+    if ("assistantText" in output || "toolCalls" in output || "complete" in output || "transfer" in output || "escalate" in output) {
+      return output;
+    }
+    return options.mapOutput?.(output) ?? normalizeRouteOutput(output);
+  }
+});
+var createVoiceProviderRouter = (options) => {
+  const providerIds = Object.keys(options.providers);
+  const firstProvider = providerIds[0];
+  const policy = typeof options.policy === "string" ? {
+    strategy: options.policy
+  } : options.policy;
+  const strategy = policy?.strategy ?? "prefer-selected";
+  const fallbackMode = policy?.fallbackMode ?? options.fallbackMode ?? "provider-error";
+  const healthOptions = typeof options.providerHealth === "object" ? options.providerHealth : options.providerHealth ? {} : undefined;
+  const healthState = new Map;
+  const now = () => healthOptions?.now?.() ?? Date.now();
+  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 getHealth = (provider) => {
+    const existing = healthState.get(provider);
+    if (existing) {
+      return existing;
+    }
+    const next = {
+      consecutiveFailures: 0,
+      provider,
+      status: "healthy"
+    };
+    healthState.set(provider, next);
+    return next;
+  };
+  const cloneHealth = (provider) => {
+    if (!healthOptions) {
+      return;
+    }
+    return {
+      ...getHealth(provider)
+    };
+  };
+  const getSuppressionRemainingMs = (provider) => {
+    if (!healthOptions) {
+      return;
+    }
+    const suppressedUntil = getHealth(provider).suppressedUntil;
+    return typeof suppressedUntil === "number" ? Math.max(0, suppressedUntil - now()) : undefined;
+  };
+  const isSuppressed = (provider) => {
+    if (!healthOptions) {
+      return false;
+    }
+    const health = getHealth(provider);
+    return typeof health.suppressedUntil === "number" && health.suppressedUntil > now();
+  };
+  const recordProviderSuccess = (provider) => {
+    if (!healthOptions) {
+      return;
+    }
+    const health = getHealth(provider);
+    health.consecutiveFailures = 0;
+    health.status = "healthy";
+    health.suppressedUntil = undefined;
+    return cloneHealth(provider);
+  };
+  const recordProviderError = (provider, isProviderError, rateLimited) => {
+    if (!healthOptions || !isProviderError) {
+      return cloneHealth(provider);
+    }
+    const currentTime = now();
+    const health = getHealth(provider);
+    health.consecutiveFailures += 1;
+    health.lastFailureAt = currentTime;
+    if (rateLimited) {
+      health.lastRateLimitedAt = currentTime;
+    }
+    if (rateLimited || health.consecutiveFailures >= failureThreshold) {
+      health.status = "suppressed";
+      health.suppressedUntil = currentTime + (rateLimited ? rateLimitCooldownMs : cooldownMs);
+    }
+    return cloneHealth(provider);
+  };
+  const resolveAllowedProviders = async (input) => {
+    const allowProviders = policy?.allowProviders ?? options.allowProviders;
+    const allowed = typeof allowProviders === "function" ? await allowProviders(input) : allowProviders;
+    return new Set(allowed ?? providerIds);
+  };
+  const sortProviders = (providers) => {
+    if (strategy !== "prefer-cheapest" && strategy !== "prefer-fastest") {
+      return providers;
+    }
+    return [...providers].sort((left, right) => {
+      const leftProfile = options.providerProfiles?.[left];
+      const rightProfile = options.providerProfiles?.[right];
+      const leftValue = strategy === "prefer-cheapest" ? leftProfile?.cost ?? Number.MAX_SAFE_INTEGER : leftProfile?.latencyMs ?? Number.MAX_SAFE_INTEGER;
+      const rightValue = strategy === "prefer-cheapest" ? rightProfile?.cost ?? Number.MAX_SAFE_INTEGER : rightProfile?.latencyMs ?? Number.MAX_SAFE_INTEGER;
+      return leftValue - rightValue || (leftProfile?.priority ?? Number.MAX_SAFE_INTEGER) - (rightProfile?.priority ?? Number.MAX_SAFE_INTEGER);
+    });
+  };
+  const resolveOrder = async (input) => {
+    const selectedProvider = await options.selectProvider?.(input);
+    const allowedProviders = await resolveAllowedProviders(input);
+    const fallbackOrder = typeof options.fallback === "function" ? await options.fallback(input) : options.fallback;
+    const rankedProviders = sortProviders([
+      ...fallbackOrder ?? providerIds
+    ]).filter((provider) => allowedProviders.has(provider));
+    const healthyRankedProviders = healthOptions ? rankedProviders.filter((provider) => !isSuppressed(provider)) : rankedProviders;
+    const candidateRankedProviders = healthyRankedProviders.length ? healthyRankedProviders : rankedProviders;
+    const preferred = selectedProvider && allowedProviders.has(selectedProvider) && (!healthOptions || !isSuppressed(selectedProvider)) ? selectedProvider : candidateRankedProviders[0] ?? firstProvider;
+    const seen = new Set;
+    const order = [];
+    const candidates = strategy === "ordered" ? candidateRankedProviders : [
+      preferred,
+      ...candidateRankedProviders,
+      ...providerIds.filter((provider) => !healthOptions || !isSuppressed(provider))
+    ];
+    for (const provider of candidates) {
+      if (!provider || seen.has(provider) || !allowedProviders.has(provider) || !options.providers[provider]) {
+        continue;
+      }
+      seen.add(provider);
+      order.push(provider);
+    }
+    return {
+      order,
+      selectedProvider: preferred
+    };
+  };
+  const emit = async (event, input) => {
+    await options.onProviderEvent?.(event, input);
+  };
+  return {
+    generate: async (input) => {
+      const { order, selectedProvider } = await resolveOrder(input);
+      if (!selectedProvider || order.length === 0) {
+        throw new Error("Voice provider router has no available providers.");
+      }
+      let lastError;
+      for (const [index, provider] of order.entries()) {
+        const model = options.providers[provider];
+        if (!model) {
+          continue;
+        }
+        const startedAt = Date.now();
+        try {
+          const output = await model.generate(input);
+          const providerHealth = recordProviderSuccess(provider);
+          await emit({
+            at: Date.now(),
+            elapsedMs: Date.now() - startedAt,
+            fallbackProvider: provider === selectedProvider ? undefined : provider,
+            provider,
+            providerHealth,
+            recovered: provider !== selectedProvider,
+            selectedProvider,
+            status: provider === selectedProvider ? "success" : "fallback"
+          }, input);
+          return output;
+        } catch (error) {
+          lastError = error;
+          const hasNextProvider = index < order.length - 1;
+          const isProviderError = options.isProviderError?.(error, provider) ?? true;
+          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(),
+            elapsedMs: Date.now() - startedAt,
+            error: errorMessage(error),
+            fallbackProvider: shouldFallback ? nextProvider : undefined,
+            provider,
+            providerHealth,
+            rateLimited,
+            selectedProvider,
+            suppressionRemainingMs: getSuppressionRemainingMs(provider),
+            suppressedUntil: providerHealth?.suppressedUntil,
+            status: "error"
+          }, input);
+          if (!hasNextProvider || !shouldFallback) {
+            throw error;
+          }
+        }
+      }
+      throw lastError ?? new Error("Voice provider router did not run a provider.");
+    }
+  };
+};
+var messageToOpenAIInput = (message) => {
+  if (message.role === "tool") {
+    return [
+      {
+        call_id: message.toolCallId ?? message.name ?? crypto.randomUUID(),
+        output: message.content,
+        type: "function_call_output"
+      }
+    ];
+  }
+  const toolCalls = getMessageToolCalls(message);
+  if (message.role === "assistant" && toolCalls.length) {
+    return toolCalls.map((toolCall) => ({
+      arguments: JSON.stringify(toolCall.args),
+      call_id: toolCall.id ?? crypto.randomUUID(),
+      name: toolCall.name,
+      type: "function_call"
+    }));
+  }
+  return [
+    {
+      content: message.content,
+      role: message.role === "system" ? "developer" : message.role
+    }
+  ];
+};
+var messagesToOpenAIInput = (messages) => messages.flatMap(messageToOpenAIInput);
+var messageToAnthropicMessage = (message) => {
+  if (message.role === "system") {
+    return;
+  }
+  if (message.role === "tool") {
+    if (!message.toolCallId) {
+      return {
+        content: `Tool result from ${message.name ?? "tool"}: ${message.content}`,
+        role: "user"
+      };
+    }
+    return {
+      content: [
+        {
+          content: message.content,
+          tool_use_id: message.toolCallId,
+          type: "tool_result"
+        }
+      ],
+      role: "user"
+    };
+  }
+  const toolCalls = getMessageToolCalls(message);
+  if (message.role === "assistant" && toolCalls.length) {
+    return {
+      content: [
+        ...message.content ? [
+          {
+            text: message.content,
+            type: "text"
+          }
+        ] : [],
+        ...toolCalls.map((toolCall) => ({
+          id: toolCall.id ?? crypto.randomUUID(),
+          input: toolCall.args,
+          name: toolCall.name,
+          type: "tool_use"
+        }))
+      ],
+      role: "assistant"
+    };
+  }
+  return {
+    content: message.content,
+    role: message.role
+  };
+};
+var toGeminiSchema = (schema) => {
+  const next = {};
+  for (const [key, value] of Object.entries(schema)) {
+    if (key === "additionalProperties") {
+      continue;
+    }
+    if (key === "type" && typeof value === "string") {
+      next[key] = value.toUpperCase();
+      continue;
+    }
+    if (Array.isArray(value)) {
+      next[key] = value.map((item) => item && typeof item === "object" ? toGeminiSchema(item) : item);
+      continue;
+    }
+    if (value && typeof value === "object") {
+      next[key] = toGeminiSchema(value);
+      continue;
+    }
+    next[key] = value;
+  }
+  return next;
+};
+var messageToGeminiContent = (message) => {
+  if (message.role === "system") {
+    return;
+  }
+  if (message.role === "tool") {
+    return {
+      parts: [
+        {
+          functionResponse: {
+            id: message.toolCallId,
+            name: message.name ?? "tool",
+            response: {
+              result: parseJSONValue(message.content)
+            }
+          }
+        }
+      ],
+      role: "user"
+    };
+  }
+  const toolCalls = getMessageToolCalls(message);
+  if (message.role === "assistant" && toolCalls.length) {
+    return {
+      parts: [
+        ...message.content ? [
+          {
+            text: message.content
+          }
+        ] : [],
+        ...toolCalls.map((toolCall) => ({
+          functionCall: {
+            args: toolCall.args,
+            id: toolCall.id,
+            name: toolCall.name
+          }
+        }))
+      ],
+      role: "model"
+    };
+  }
+  return {
+    parts: [
+      {
+        text: message.content
+      }
+    ],
+    role: message.role === "assistant" ? "model" : "user"
+  };
+};
+var extractText = (response) => {
+  if (typeof response.output_text === "string") {
+    return response.output_text;
+  }
+  const output = Array.isArray(response.output) ? response.output : [];
+  for (const item of output) {
+    if (!item || typeof item !== "object") {
+      continue;
+    }
+    const record = item;
+    const content = Array.isArray(record.content) ? record.content : [];
+    for (const contentItem of content) {
+      if (!contentItem || typeof contentItem !== "object") {
+        continue;
+      }
+      const contentRecord = contentItem;
+      if (typeof contentRecord.text === "string") {
+        return contentRecord.text;
+      }
+    }
+  }
+  return "";
+};
+var extractToolCalls = (response) => {
+  const output = Array.isArray(response.output) ? response.output : [];
+  const toolCalls = [];
+  for (const item of output) {
+    if (!item || typeof item !== "object") {
+      continue;
+    }
+    const record = item;
+    if (record.type !== "function_call" || typeof record.name !== "string") {
+      continue;
+    }
+    const args = typeof record.arguments === "string" ? parseJSON(record.arguments) : {};
+    toolCalls.push({
+      args,
+      id: typeof record.call_id === "string" ? record.call_id : typeof record.id === "string" ? record.id : undefined,
+      name: record.name
+    });
+  }
+  return toolCalls;
+};
+var createOpenAIVoiceAssistantModel = (options) => {
+  const fetchImpl = options.fetch ?? globalThis.fetch;
+  const baseUrl = options.baseUrl ?? "https://api.openai.com/v1";
+  const model = options.model ?? "gpt-4.1-mini";
+  return {
+    generate: async (input) => {
+      const response = await fetchImpl(`${baseUrl.replace(/\/$/, "")}/responses`, {
+        body: JSON.stringify({
+          input: messagesToOpenAIInput(input.messages),
+          instructions: [
+            input.system,
+            "Return a JSON object with assistantText, complete, transfer, escalate, voicemail, noAnswer, and result when you are not calling tools."
+          ].filter(Boolean).join(`
+
+`),
+          max_output_tokens: options.maxOutputTokens,
+          model,
+          temperature: options.temperature,
+          text: {
+            format: {
+              name: "voice_route_result",
+              schema: OUTPUT_SCHEMA,
+              strict: false,
+              type: "json_schema"
+            }
+          },
+          tool_choice: input.tools.length ? "auto" : "none",
+          tools: input.tools.map((tool) => ({
+            description: tool.description,
+            name: tool.name,
+            parameters: tool.parameters ?? {
+              additionalProperties: true,
+              type: "object"
+            },
+            strict: false,
+            type: "function"
+          }))
+        }),
+        headers: {
+          authorization: `Bearer ${options.apiKey}`,
+          "content-type": "application/json"
+        },
+        method: "POST"
+      });
+      if (!response.ok) {
+        throw createHTTPError("OpenAI", response);
+      }
+      const body = await response.json();
+      if (body.usage && typeof body.usage === "object") {
+        await options.onUsage?.(body.usage);
+      }
+      const toolCalls = extractToolCalls(body);
+      if (toolCalls.length) {
+        return {
+          toolCalls
+        };
+      }
+      return normalizeRouteOutput(parseJSON(extractText(body)));
+    }
+  };
+};
+var extractAnthropicText = (response) => {
+  const content = Array.isArray(response.content) ? response.content : [];
+  return content.map((item) => item && typeof item === "object" && item.type === "text" && typeof item.text === "string" ? item.text : "").filter(Boolean).join(`
+`);
+};
+var extractAnthropicToolCalls = (response) => {
+  const content = Array.isArray(response.content) ? response.content : [];
+  const toolCalls = [];
+  for (const item of content) {
+    if (!item || typeof item !== "object") {
+      continue;
+    }
+    const record = item;
+    if (record.type !== "tool_use" || typeof record.name !== "string") {
+      continue;
+    }
+    toolCalls.push({
+      args: record.input && typeof record.input === "object" ? record.input : {},
+      id: typeof record.id === "string" ? record.id : undefined,
+      name: record.name
+    });
+  }
+  return toolCalls;
+};
+var createAnthropicVoiceAssistantModel = (options) => {
+  const fetchImpl = options.fetch ?? globalThis.fetch;
+  const baseUrl = options.baseUrl ?? "https://api.anthropic.com/v1";
+  const model = options.model ?? "claude-sonnet-4-5";
+  return {
+    generate: async (input) => {
+      const response = await fetchImpl(`${baseUrl.replace(/\/$/, "")}/messages`, {
+        body: JSON.stringify({
+          max_tokens: options.maxOutputTokens ?? 1024,
+          messages: input.messages.map(messageToAnthropicMessage).filter(Boolean),
+          model,
+          system: [input.system, ROUTE_RESULT_INSTRUCTION].filter(Boolean).join(`
+
+`),
+          temperature: options.temperature,
+          tool_choice: input.tools.length ? { type: "auto" } : { type: "none" },
+          tools: input.tools.map((tool) => ({
+            description: tool.description,
+            input_schema: tool.parameters ?? {
+              additionalProperties: true,
+              type: "object"
+            },
+            name: tool.name
+          }))
+        }),
+        headers: {
+          "anthropic-version": options.version ?? "2023-06-01",
+          "content-type": "application/json",
+          "x-api-key": options.apiKey
+        },
+        method: "POST"
+      });
+      if (!response.ok) {
+        throw createHTTPError("Anthropic", response);
+      }
+      const body = await response.json();
+      if (body.usage && typeof body.usage === "object") {
+        await options.onUsage?.(body.usage);
+      }
+      const toolCalls = extractAnthropicToolCalls(body);
+      if (toolCalls.length) {
+        return {
+          assistantText: extractAnthropicText(body) || undefined,
+          toolCalls
+        };
+      }
+      return normalizeRouteOutput(parseJSON(extractAnthropicText(body)));
+    }
+  };
+};
+var extractGeminiCandidateParts = (response) => {
+  const candidates = Array.isArray(response.candidates) ? response.candidates : [];
+  const first = candidates[0];
+  if (!first || typeof first !== "object") {
+    return [];
+  }
+  const content = first.content;
+  if (!content || typeof content !== "object") {
+    return [];
+  }
+  const parts = content.parts;
+  return Array.isArray(parts) ? parts : [];
+};
+var extractGeminiText = (response) => extractGeminiCandidateParts(response).map((part) => part && typeof part === "object" && typeof part.text === "string" ? part.text : "").filter(Boolean).join(`
+`);
+var extractGeminiToolCalls = (response) => {
+  const toolCalls = [];
+  for (const part of extractGeminiCandidateParts(response)) {
+    if (!part || typeof part !== "object") {
+      continue;
+    }
+    const functionCall = part.functionCall;
+    if (!functionCall || typeof functionCall !== "object") {
+      continue;
+    }
+    const record = functionCall;
+    if (typeof record.name !== "string") {
+      continue;
+    }
+    toolCalls.push({
+      args: record.args && typeof record.args === "object" ? record.args : {},
+      id: typeof record.id === "string" ? record.id : undefined,
+      name: record.name
+    });
+  }
+  return toolCalls;
+};
+var createGeminiVoiceAssistantModel = (options) => {
+  const fetchImpl = options.fetch ?? globalThis.fetch;
+  const baseUrl = options.baseUrl ?? "https://generativelanguage.googleapis.com/v1beta";
+  const model = options.model ?? "gemini-2.5-flash";
+  const maxRetries = Math.max(0, options.maxRetries ?? 2);
+  return {
+    generate: async (input) => {
+      const endpoint = `${baseUrl.replace(/\/$/, "")}/models/${encodeURIComponent(model)}:generateContent?key=${encodeURIComponent(options.apiKey)}`;
+      let response;
+      for (let attempt = 0;attempt <= maxRetries; attempt += 1) {
+        response = await fetchImpl(endpoint, {
+          body: JSON.stringify({
+            contents: input.messages.map(messageToGeminiContent).filter(Boolean),
+            generationConfig: {
+              maxOutputTokens: options.maxOutputTokens,
+              ...input.tools.length ? {} : {
+                responseMimeType: "application/json",
+                responseSchema: toGeminiSchema(OUTPUT_SCHEMA)
+              },
+              temperature: options.temperature
+            },
+            systemInstruction: {
+              parts: [
+                {
+                  text: [input.system, ROUTE_RESULT_INSTRUCTION].filter(Boolean).join(`
+
+`)
+                }
+              ]
+            },
+            tools: input.tools.length ? [
+              {
+                functionDeclarations: input.tools.map((tool) => ({
+                  description: tool.description,
+                  name: tool.name,
+                  parameters: toGeminiSchema(tool.parameters ?? {
+                    additionalProperties: true,
+                    type: "object"
+                  })
+                }))
+              }
+            ] : undefined
+          }),
+          headers: {
+            "content-type": "application/json"
+          },
+          method: "POST"
+        });
+        if (response.ok || response.status !== 429 && response.status < 500 || attempt === maxRetries) {
+          break;
+        }
+        const retryAfter = Number(response.headers.get("retry-after"));
+        await sleep(Number.isFinite(retryAfter) && retryAfter > 0 ? retryAfter * 1000 : 500 * 2 ** attempt);
+      }
+      if (!response) {
+        throw new Error("Gemini voice assistant model failed: no response");
+      }
+      if (!response.ok) {
+        throw createHTTPError("Gemini", response);
+      }
+      const body = await response.json();
+      if (body.usageMetadata && typeof body.usageMetadata === "object") {
+        await options.onUsage?.(body.usageMetadata);
+      }
+      const toolCalls = extractGeminiToolCalls(body);
+      if (toolCalls.length) {
+        return {
+          assistantText: extractGeminiText(body) || undefined,
+          toolCalls
+        };
+      }
+      return normalizeRouteOutput(parseJSON(extractGeminiText(body)));
+    }
+  };
+};
+
 // src/store.ts
 var createId = () => crypto.randomUUID();
 var createVoiceSessionRecord = (id, scenarioId) => ({
@@ -3508,6 +4280,111 @@ var toVoiceSessionSummary = (session) => ({
   turnCount: session.turns.length
 });
 
+// src/testing/providerSimulator.ts
+var getContextQuery = (context) => context.query;
+var titleCaseProvider = (provider) => provider.split(/[-_\s]+/).filter(Boolean).map((part) => part[0]?.toUpperCase() + part.slice(1)).join(" ");
+var resolveRequestedProvider = (context, providers) => {
+  const provider = getContextQuery(context).provider;
+  return providers.includes(provider) ? provider : providers[0];
+};
+var createVoiceProviderFailureSimulator = (options) => {
+  if (options.providers.length === 0) {
+    throw new Error("At least one provider is required.");
+  }
+  const providerModels = Object.fromEntries(options.providers.map((provider) => [
+    provider,
+    {
+      generate: async (input) => {
+        const query = getContextQuery(input.context);
+        if (provider === query.simulateFailureProvider) {
+          const label = options.providerLabel?.(provider) ?? titleCaseProvider(provider);
+          throw new Error(`${label} voice assistant model failed: HTTP 429`);
+        }
+        if (options.response) {
+          return options.response({
+            ...input,
+            mode: query.recoverProvider === provider ? "recovery" : "failure",
+            provider
+          });
+        }
+        return {
+          assistantText: `Simulated ${provider} provider recovered.`
+        };
+      }
+    }
+  ]));
+  const router = createVoiceProviderRouter({
+    allowProviders: async (input) => {
+      const recoverProvider = getContextQuery(input.context).recoverProvider;
+      if (recoverProvider) {
+        return [recoverProvider];
+      }
+      if (typeof options.allowProviders === "function") {
+        return options.allowProviders(input);
+      }
+      return options.allowProviders ?? options.providers;
+    },
+    fallback: async (input) => {
+      const selectedProvider = resolveRequestedProvider(input.context, options.providers);
+      if (typeof options.fallback === "function") {
+        return options.fallback(selectedProvider, input);
+      }
+      return options.fallback ?? options.providers.filter((provider) => provider !== selectedProvider);
+    },
+    fallbackMode: "provider-error",
+    isProviderError: options.isProviderError,
+    isRateLimitError: options.isRateLimitError,
+    onProviderEvent: options.onProviderEvent,
+    policy: "prefer-selected",
+    providerHealth: options.providerHealth ?? {
+      cooldownMs: 30000,
+      failureThreshold: 1,
+      rateLimitCooldownMs: 120000
+    },
+    providers: providerModels,
+    selectProvider: ({ context }) => resolveRequestedProvider(context, options.providers)
+  });
+  const run = async (provider, mode) => {
+    const now = Date.now();
+    const session = createVoiceSessionRecord(`provider-sim-${now}`, "provider-simulation");
+    const turn = {
+      committedAt: now,
+      id: `provider-sim-turn-${now}`,
+      text: mode === "failure" ? `Simulate ${provider} provider failure.` : `Simulate ${provider} provider recovery.`,
+      transcripts: []
+    };
+    const context = {
+      query: {
+        provider,
+        ...mode === "recovery" ? { recoverProvider: provider } : {},
+        ...mode === "failure" ? { simulateFailureProvider: provider } : {}
+      }
+    };
+    const result = await router.generate({
+      agentId: "provider-simulator",
+      context,
+      messages: [
+        {
+          content: turn.text,
+          role: "user"
+        }
+      ],
+      session,
+      system: "Simulate provider routing without calling external APIs.",
+      tools: [],
+      turn
+    });
+    return {
+      mode,
+      provider,
+      result,
+      status: "simulated"
+    };
+  };
+  return {
+    run
+  };
+};
 // src/memoryStore.ts
 var createVoiceMemoryStore = () => {
   const sessions = new Map;
@@ -7208,6 +8085,7 @@ export {
   getDefaultVoiceDuplexBenchmarkScenarios,
   getDefaultTTSBenchmarkFixtures,
   evaluateSTTBenchmarkAcceptance,
+  createVoiceProviderFailureSimulator,
   createVoiceCallReviewRecorder,
   createVoiceCallReviewFromLiveTelephonyReport,
   createTelephonyVoiceTestFixtures,

package/dist/testing/providerSimulator.d.ts

@@ -0,0 +1,36 @@
+import type { VoiceAgentModelInput, VoiceAgentModelOutput } from '../agent';
+import type { VoiceSessionRecord } from '../types';
+import type { VoiceProviderRouterEvent, VoiceProviderRouterHealthOptions } from '../modelAdapters';
+export type VoiceProviderFailureSimulationMode = 'failure' | 'recovery';
+export type VoiceProviderFailureSimulationContext<TProvider extends string = string> = {
+    query: {
+        provider: TProvider;
+        recoverProvider?: TProvider;
+        simulateFailureProvider?: TProvider;
+    };
+};
+export type VoiceProviderFailureSimulationResult<TProvider extends string = string, TResult = unknown> = {
+    mode: VoiceProviderFailureSimulationMode;
+    provider: TProvider;
+    result: VoiceAgentModelOutput<TResult>;
+    status: 'simulated';
+};
+type ProviderListResolver<TContext, TSession extends VoiceSessionRecord, TProvider extends string> = readonly TProvider[] | ((input: VoiceAgentModelInput<TContext, TSession>) => readonly TProvider[] | Promise<readonly TProvider[]>);
+export type VoiceProviderFailureSimulatorOptions<TContext extends VoiceProviderFailureSimulationContext<TProvider>, TSession extends VoiceSessionRecord = VoiceSessionRecord, TResult = unknown, TProvider extends string = string> = {
+    allowProviders?: ProviderListResolver<TContext, TSession, TProvider>;
+    fallback?: readonly TProvider[] | ((provider: TProvider, input: VoiceAgentModelInput<TContext, TSession>) => readonly TProvider[] | Promise<readonly TProvider[]>);
+    isProviderError?: (error: unknown, provider: TProvider) => boolean;
+    isRateLimitError?: (error: unknown, provider: TProvider) => boolean;
+    onProviderEvent?: (event: VoiceProviderRouterEvent<TProvider>, input: VoiceAgentModelInput<TContext, TSession>) => Promise<void> | void;
+    providerHealth?: boolean | VoiceProviderRouterHealthOptions;
+    providerLabel?: (provider: TProvider) => string;
+    providers: readonly TProvider[];
+    response?: (input: {
+        mode: VoiceProviderFailureSimulationMode;
+        provider: TProvider;
+    } & VoiceAgentModelInput<TContext, TSession>) => VoiceAgentModelOutput<TResult> | Promise<VoiceAgentModelOutput<TResult>>;
+};
+export declare const createVoiceProviderFailureSimulator: <TProvider extends string, TResult = unknown, TSession extends VoiceSessionRecord = VoiceSessionRecord, TContext extends VoiceProviderFailureSimulationContext<TProvider> = VoiceProviderFailureSimulationContext<TProvider>>(options: VoiceProviderFailureSimulatorOptions<TContext, TSession, TResult, TProvider>) => {
+    run: (provider: TProvider, mode: VoiceProviderFailureSimulationMode) => Promise<VoiceProviderFailureSimulationResult<TProvider, TResult>>;
+};
+export {};

package/package.json

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