@absolutejs/voice 0.0.22-beta.291 → 0.0.22-beta.292

package/README.md

@@ -3888,6 +3888,59 @@ Built-in policy presets:
 - `cost-cap`: rank by cost and reject providers above `maxCost`.
 - `balanced`: weighted score using cost, latency, quality, and priority.
 
+Use `createVoiceProviderOrchestrationProfile(...)` when one app has multiple provider surfaces with different tradeoffs. This is the Vapi-style "choose providers without glue" layer, but still code-owned: a live call can prefer low latency with a circuit breaker, while a background summary can prefer lower cost and stricter budget caps.
+
+```ts
+import {
+	createVoiceProviderOrchestrationProfile,
+	createVoiceProviderRouter
+} from '@absolutejs/voice';
+
+const providerProfile = createVoiceProviderOrchestrationProfile({
+	id: 'support-agent-providers',
+	defaultSurface: 'live-call',
+	surfaces: {
+		'live-call': {
+			policy: 'latency-first',
+			fallback: ['openai', 'anthropic', 'gemini'],
+			maxLatencyMs: 900,
+			providerHealth: {
+				failureThreshold: 1,
+				cooldownMs: 30_000,
+				rateLimitCooldownMs: 120_000
+			},
+			providerProfiles: {
+				openai: { cost: 6, latencyMs: 650, quality: 0.92, timeoutMs: 3500 },
+				anthropic: { cost: 7, latencyMs: 850, quality: 0.95, timeoutMs: 4500 },
+				gemini: { cost: 2, latencyMs: 700, quality: 0.86, timeoutMs: 3500 }
+			}
+		},
+		'background-summary': {
+			policy: 'cost-cap',
+			fallback: ['gemini', 'openai'],
+			maxCost: 3,
+			minQuality: 0.82,
+			providerProfiles: {
+				openai: { cost: 6, latencyMs: 650, quality: 0.92 },
+				gemini: { cost: 2, latencyMs: 700, quality: 0.86 }
+			}
+		}
+	}
+});
+
+const liveModel = createVoiceProviderRouter({
+	providers,
+	orchestrationProfile: providerProfile,
+	orchestrationSurface: 'live-call'
+});
+
+const summaryModel = createVoiceProviderRouter({
+	providers,
+	orchestrationProfile: providerProfile,
+	orchestrationSurface: 'background-summary'
+});
+```
+
 Budget filters are strict. If you pass `maxCost`, `maxLatencyMs`, or `minQuality`, providers outside those limits are removed before ranking, even if they were selected by the request.
 
 ```ts

package/dist/index.d.ts

@@ -46,7 +46,7 @@ export { applyVoiceTelephonyOutcome, assertVoiceTelephonyWebhookNormalizationEvi
 export { assertVoicePhoneCallControlEvidence, assertVoicePhoneAssistantEvidence, createVoicePhoneAgent, evaluateVoicePhoneCallControlEvidence, evaluateVoicePhoneAssistantEvidence } from './phoneAgent';
 export { createStoredVoiceCallReviewArtifact, createStoredVoiceExternalObjectMap, createStoredVoiceIntegrationEvent, createStoredVoiceOpsTask, createVoiceFileIncidentBundleStore, createVoiceFileExternalObjectMapStore, createVoiceFileAssistantMemoryStore, createVoiceFileAuditEventStore, createVoiceFileAuditSinkDeliveryStore, createVoiceFileCampaignStore, createVoiceFileIntegrationEventStore, createVoiceFileReviewStore, createVoiceFileRuntimeStorage, createVoiceFileSessionStore, createVoiceFileTaskStore, createVoiceFileTraceSinkDeliveryStore, createVoiceFileTraceEventStore } from './fileStore';
 export { createVoiceAssistantMemoryHandle, createVoiceAssistantMemoryRecord, createVoiceMemoryAssistantMemoryStore, resolveVoiceAssistantMemoryNamespace } from './assistantMemory';
-export { createAnthropicVoiceAssistantModel, createGeminiVoiceAssistantModel, createJSONVoiceAssistantModel, createOpenAIVoiceAssistantModel, resolveVoiceProviderRoutingPolicyPreset, createVoiceProviderRouter } from './modelAdapters';
+export { createAnthropicVoiceAssistantModel, createGeminiVoiceAssistantModel, createJSONVoiceAssistantModel, createOpenAIVoiceAssistantModel, createVoiceProviderOrchestrationProfile, resolveVoiceProviderRoutingPolicyPreset, createVoiceProviderRouter } from './modelAdapters';
 export { createOpenAIRealtimeAdapter } from './openaiRealtime';
 export { createOpenAIVoiceTTS } from './openaiTTS';
 export { createVoiceProviderHealthHTMLHandler, createVoiceProviderHealthJSONHandler, createVoiceProviderHealthRoutes, renderVoiceProviderHealthHTML, summarizeVoiceProviderHealth } from './providerHealth';
@@ -106,7 +106,7 @@ export type { VoiceEvalBaselineComparison, VoiceEvalBaselineComparisonOptions, V
 export type { VoiceSimulationSuiteAssertionInput, VoiceSimulationSuiteAssertionReport, VoiceSimulationSuiteEvalRoutesOptions, VoiceSimulationSuiteOptions, VoiceSimulationSuiteReport, VoiceSimulationSuiteRoutesOptions, VoiceSimulationSuiteSection, VoiceSimulationSuiteSectionSummary, VoiceSimulationSuiteStatus } from './simulationSuite';
 export type { VoiceWorkflowContract, VoiceWorkflowContractDefinition, VoiceWorkflowContractField, VoiceWorkflowContractFieldMatch, VoiceWorkflowContractPresetName, VoiceWorkflowContractPresetOptions, VoiceWorkflowContractTracePayload, VoiceWorkflowContractValidation, VoiceWorkflowContractValidationIssue, VoiceWorkflowOutcome } from './workflowContract';
 export type { VoiceSessionListHTMLHandlerOptions, VoiceSessionListItem, VoiceSessionListOptions, VoiceSessionListRoutesOptions, VoiceSessionListStatus, VoiceProviderFallbackRecoverySummary, VoiceSessionReplay, VoiceSessionReplayHTMLHandlerOptions, VoiceSessionReplayOptions, VoiceSessionReplayRoutesOptions, VoiceSessionReplayTurn } from './sessionReplay';
-export type { AnthropicVoiceAssistantModelOptions, GeminiVoiceAssistantModelOptions, OpenAIVoiceAssistantModelOptions, VoiceProviderRouterEvent, VoiceProviderRouterFallbackMode, VoiceProviderRouterHealthOptions, VoiceProviderRouterOptions, VoiceProviderRouterPolicy, VoiceProviderRouterPolicyPreset, VoiceProviderRouterPolicyWeights, VoiceProviderRouterProviderHealth, VoiceProviderRouterProviderProfile, VoiceProviderRouterStrategy, VoiceJSONAssistantModelHandler, VoiceJSONAssistantModelOptions } from './modelAdapters';
+export type { AnthropicVoiceAssistantModelOptions, GeminiVoiceAssistantModelOptions, OpenAIVoiceAssistantModelOptions, VoiceProviderRouterEvent, VoiceProviderRouterFallbackMode, VoiceProviderRouterHealthOptions, VoiceProviderRouterOptions, VoiceProviderOrchestrationProfile, VoiceProviderOrchestrationProfileOptions, VoiceProviderOrchestrationResolvedSurface, VoiceProviderOrchestrationSurface, VoiceProviderRouterPolicy, VoiceProviderRouterPolicyPreset, VoiceProviderRouterPolicyWeights, VoiceProviderRouterProviderHealth, VoiceProviderRouterProviderProfile, VoiceProviderRouterStrategy, VoiceJSONAssistantModelHandler, VoiceJSONAssistantModelOptions } from './modelAdapters';
 export type { OpenAIVoiceTTSOptions, OpenAIVoiceTTSVoice } from './openaiTTS';
 export type { OpenAIRealtimeAdapterOptions, OpenAIRealtimeModel, OpenAIRealtimeNoiseReduction, OpenAIRealtimeResponseMode, OpenAIRealtimeTranscriptionModel, OpenAIRealtimeVoice } from './openaiRealtime';
 export type { VoiceProviderHealthStatus, VoiceProviderHealthSummary, VoiceProviderHealthSummaryOptions } from './providerHealth';

package/dist/index.js

@@ -21650,6 +21650,7 @@ var createStoredVoiceExternalObjectMap = (mapping) => createVoiceExternalObjectM
   sourceType: mapping.sourceType
 });
 // src/modelAdapters.ts
+var isVoiceProviderRoutingPolicyPreset = (value) => value === "balanced" || value === "cost-cap" || value === "cost-first" || value === "latency-first" || value === "quality-first";
 var resolveVoiceProviderRoutingPolicyPreset = (preset, options = {}) => {
   switch (preset) {
     case "balanced":
@@ -21691,6 +21692,75 @@ var resolveVoiceProviderRoutingPolicyPreset = (preset, options = {}) => {
       };
   }
 };
+var resolveVoiceProviderRoutingPolicy = (policy) => {
+  if (!policy) {
+    return;
+  }
+  if (typeof policy === "string") {
+    return isVoiceProviderRoutingPolicyPreset(policy) ? resolveVoiceProviderRoutingPolicyPreset(policy) : {
+      strategy: policy
+    };
+  }
+  return policy;
+};
+var mergeDefinedProviderPolicyFields = (base, surface) => {
+  const next = {
+    ...base ?? {}
+  };
+  if (surface.allowProviders !== undefined) {
+    next.allowProviders = surface.allowProviders;
+  }
+  if (surface.fallbackMode !== undefined) {
+    next.fallbackMode = surface.fallbackMode;
+  }
+  if (surface.maxCost !== undefined) {
+    next.maxCost = surface.maxCost;
+  }
+  if (surface.maxLatencyMs !== undefined) {
+    next.maxLatencyMs = surface.maxLatencyMs;
+  }
+  if (surface.minQuality !== undefined) {
+    next.minQuality = surface.minQuality;
+  }
+  if (surface.strategy !== undefined) {
+    next.strategy = surface.strategy;
+  }
+  if (surface.weights !== undefined) {
+    next.weights = {
+      ...base?.weights ?? {},
+      ...surface.weights
+    };
+  }
+  return next;
+};
+var createVoiceProviderOrchestrationProfile = (options) => {
+  const surfaceNames = Object.keys(options.surfaces);
+  const defaultSurface = options.defaultSurface ?? surfaceNames[0];
+  if (!defaultSurface || !options.surfaces[defaultSurface]) {
+    throw new Error("Voice provider orchestration profile has no surfaces.");
+  }
+  return {
+    defaultSurface,
+    id: options.id,
+    resolve: (surface = defaultSurface) => {
+      const config = options.surfaces[surface];
+      if (!config) {
+        throw new Error(`Voice provider orchestration profile ${options.id} has no surface "${surface}".`);
+      }
+      const policy = mergeDefinedProviderPolicyFields(resolveVoiceProviderRoutingPolicy(config.policy), config);
+      return {
+        allowProviders: config.allowProviders,
+        fallback: config.fallback,
+        fallbackMode: config.fallbackMode,
+        policy,
+        providerHealth: config.providerHealth,
+        providerProfiles: config.providerProfiles,
+        timeoutMs: config.timeoutMs
+      };
+    },
+    surfaces: options.surfaces
+  };
+};
 var OUTPUT_SCHEMA = {
   additionalProperties: false,
   properties: {
@@ -21858,19 +21928,23 @@ var createJSONVoiceAssistantModel = (options) => ({
 var createVoiceProviderRouter = (options) => {
   const providerIds = Object.keys(options.providers);
   const firstProvider = providerIds[0];
-  const policy = typeof options.policy === "string" ? options.policy === "balanced" || options.policy === "cost-cap" || options.policy === "cost-first" || options.policy === "latency-first" || options.policy === "quality-first" ? resolveVoiceProviderRoutingPolicyPreset(options.policy) : {
-    strategy: options.policy
-  } : options.policy;
+  const orchestrationSurface = options.orchestrationProfile?.resolve(options.orchestrationSurface);
+  const policy = resolveVoiceProviderRoutingPolicy(options.policy) ?? resolveVoiceProviderRoutingPolicy(orchestrationSurface?.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 fallbackMode = policy?.fallbackMode ?? options.fallbackMode ?? orchestrationSurface?.fallbackMode ?? "provider-error";
+  const providerProfiles = {
+    ...orchestrationSurface?.providerProfiles ?? {},
+    ...options.providerProfiles ?? {}
+  };
+  const providerHealthOption = options.providerHealth ?? orchestrationSurface?.providerHealth;
+  const healthOptions = typeof providerHealthOption === "object" ? providerHealthOption : providerHealthOption ? {} : 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 getProviderTimeoutMs = (provider) => {
-    const timeoutMs = options.providerProfiles?.[provider]?.timeoutMs ?? options.timeoutMs;
+    const timeoutMs = providerProfiles[provider]?.timeoutMs ?? options.timeoutMs ?? orchestrationSurface?.timeoutMs;
     return typeof timeoutMs === "number" && Number.isFinite(timeoutMs) && timeoutMs > 0 ? timeoutMs : undefined;
   };
   const getHealth = (provider) => {
@@ -21936,12 +22010,12 @@ var createVoiceProviderRouter = (options) => {
     return cloneHealth(provider);
   };
   const resolveAllowedProviders = async (input) => {
-    const allowProviders = policy?.allowProviders ?? options.allowProviders;
+    const allowProviders = policy?.allowProviders ?? options.allowProviders ?? orchestrationSurface?.allowProviders;
     const allowed = typeof allowProviders === "function" ? await allowProviders(input) : allowProviders;
     return new Set(allowed ?? providerIds);
   };
   const passesBudgetFilters = (provider) => {
-    const profile = options.providerProfiles?.[provider];
+    const profile = providerProfiles[provider];
     if (typeof policy?.maxCost === "number" && typeof profile?.cost === "number" && profile.cost > policy.maxCost) {
       return false;
     }
@@ -21954,7 +22028,7 @@ var createVoiceProviderRouter = (options) => {
     return true;
   };
   const getBalancedScore = (provider) => {
-    const profile = options.providerProfiles?.[provider];
+    const profile = providerProfiles[provider];
     if (policy?.scoreProvider) {
       return policy.scoreProvider(provider, profile);
     }
@@ -21966,8 +22040,8 @@ var createVoiceProviderRouter = (options) => {
       return providers;
     }
     return [...providers].sort((left, right) => {
-      const leftProfile = options.providerProfiles?.[left];
-      const rightProfile = options.providerProfiles?.[right];
+      const leftProfile = providerProfiles[left];
+      const rightProfile = providerProfiles[right];
       if (strategy === "quality-first") {
         return (rightProfile?.quality ?? Number.MIN_SAFE_INTEGER) - (leftProfile?.quality ?? Number.MIN_SAFE_INTEGER) || (leftProfile?.priority ?? Number.MAX_SAFE_INTEGER) - (rightProfile?.priority ?? Number.MAX_SAFE_INTEGER) || (leftProfile?.latencyMs ?? Number.MAX_SAFE_INTEGER) - (rightProfile?.latencyMs ?? Number.MAX_SAFE_INTEGER) || (leftProfile?.cost ?? Number.MAX_SAFE_INTEGER) - (rightProfile?.cost ?? Number.MAX_SAFE_INTEGER);
       }
@@ -21982,7 +22056,8 @@ var createVoiceProviderRouter = (options) => {
   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 fallbackSource = options.fallback ?? orchestrationSurface?.fallback;
+    const fallbackOrder = typeof fallbackSource === "function" ? await fallbackSource(input) : fallbackSource;
     const allowedRankedProviders = sortProviders([
       ...fallbackOrder ?? providerIds
     ]).filter((provider) => allowedProviders.has(provider));
@@ -30823,11 +30898,11 @@ var withTimeout2 = async (input) => {
     }
   }
 };
-var isVoiceProviderRoutingPolicyPreset = (policy) => policy === "balanced" || policy === "cost-cap" || policy === "cost-first" || policy === "latency-first" || policy === "quality-first";
+var isVoiceProviderRoutingPolicyPreset2 = (policy) => policy === "balanced" || policy === "cost-cap" || policy === "cost-first" || policy === "latency-first" || policy === "quality-first";
 var createResolver = (options) => {
   const providerIds = Object.keys(options.adapters);
   const firstProvider = providerIds[0];
-  const policy = typeof options.policy === "string" ? isVoiceProviderRoutingPolicyPreset(options.policy) ? resolveVoiceProviderRoutingPolicyPreset(options.policy) : {
+  const policy = typeof options.policy === "string" ? isVoiceProviderRoutingPolicyPreset2(options.policy) ? resolveVoiceProviderRoutingPolicyPreset(options.policy) : {
     strategy: options.policy
   } : options.policy;
   const strategy = policy?.strategy ?? "prefer-selected";
@@ -33231,6 +33306,7 @@ export {
   createVoiceQualityRoutes,
   createVoiceProviderSloRoutes,
   createVoiceProviderRouter,
+  createVoiceProviderOrchestrationProfile,
   createVoiceProviderHealthRoutes,
   createVoiceProviderHealthJSONHandler,
   createVoiceProviderHealthHTMLHandler,

package/dist/modelAdapters.d.ts

@@ -92,6 +92,41 @@ export type VoiceProviderRouterProviderHealth<TProvider extends string = string>
     status: 'healthy' | 'suppressed';
     suppressedUntil?: number;
 };
+export type VoiceProviderOrchestrationSurface<TContext = unknown, TSession extends VoiceSessionRecord = VoiceSessionRecord, TProvider extends string = string> = {
+    allowProviders?: readonly TProvider[] | ((input: VoiceAgentModelInput<TContext, TSession>) => readonly TProvider[] | Promise<readonly TProvider[]>);
+    fallback?: readonly TProvider[] | ((input: VoiceAgentModelInput<TContext, TSession>) => readonly TProvider[] | Promise<readonly TProvider[]>);
+    fallbackMode?: VoiceProviderRouterFallbackMode;
+    maxCost?: number;
+    maxLatencyMs?: number;
+    minQuality?: number;
+    policy?: VoiceProviderRouterPolicy<TContext, TSession, TProvider>;
+    providerHealth?: boolean | VoiceProviderRouterHealthOptions;
+    providerProfiles?: Partial<Record<TProvider, VoiceProviderRouterProviderProfile>>;
+    strategy?: VoiceProviderRouterStrategy;
+    timeoutMs?: number;
+    weights?: VoiceProviderRouterPolicyWeights;
+};
+export type VoiceProviderOrchestrationProfile<TContext = unknown, TSession extends VoiceSessionRecord = VoiceSessionRecord, TProvider extends string = string, TSurface extends string = string> = {
+    defaultSurface?: TSurface;
+    id: string;
+    resolve: (surface?: TSurface) => VoiceProviderOrchestrationResolvedSurface<TContext, TSession, TProvider>;
+    surfaces: Record<TSurface, VoiceProviderOrchestrationSurface<TContext, TSession, TProvider>>;
+};
+export type VoiceProviderOrchestrationProfileOptions<TContext = unknown, TSession extends VoiceSessionRecord = VoiceSessionRecord, TProvider extends string = string, TSurface extends string = string> = {
+    defaultSurface?: TSurface;
+    id: string;
+    surfaces: Record<TSurface, VoiceProviderOrchestrationSurface<TContext, TSession, TProvider>>;
+};
+export type VoiceProviderOrchestrationResolvedSurface<TContext = unknown, TSession extends VoiceSessionRecord = VoiceSessionRecord, TProvider extends string = string> = {
+    allowProviders?: VoiceProviderOrchestrationSurface<TContext, TSession, TProvider>['allowProviders'];
+    fallback?: VoiceProviderOrchestrationSurface<TContext, TSession, TProvider>['fallback'];
+    fallbackMode?: VoiceProviderRouterFallbackMode;
+    policy?: VoiceProviderRouterPolicy<TContext, TSession, TProvider>;
+    providerHealth?: boolean | VoiceProviderRouterHealthOptions;
+    providerProfiles?: Partial<Record<TProvider, VoiceProviderRouterProviderProfile>>;
+    timeoutMs?: number;
+};
+export declare const createVoiceProviderOrchestrationProfile: <TContext = unknown, TSession extends VoiceSessionRecord = VoiceSessionRecord, TProvider extends string = string, TSurface extends string = string>(options: VoiceProviderOrchestrationProfileOptions<TContext, TSession, TProvider, TSurface>) => VoiceProviderOrchestrationProfile<TContext, TSession, TProvider, TSurface>;
 export type VoiceProviderRouterOptions<TContext = unknown, TSession extends VoiceSessionRecord = VoiceSessionRecord, TResult = unknown, TProvider extends string = string> = {
     allowProviders?: readonly TProvider[] | ((input: VoiceAgentModelInput<TContext, TSession>) => readonly TProvider[] | Promise<readonly TProvider[]>);
     fallback?: TProvider[] | ((input: VoiceAgentModelInput<TContext, TSession>) => readonly TProvider[] | Promise<readonly TProvider[]>);
@@ -100,6 +135,8 @@ export type VoiceProviderRouterOptions<TContext = unknown, TSession extends Voic
     isRateLimitError?: (error: unknown, provider: TProvider) => boolean;
     isTimeoutError?: (error: unknown, provider: TProvider) => boolean;
     onProviderEvent?: (event: VoiceProviderRouterEvent<TProvider>, input: VoiceAgentModelInput<TContext, TSession>) => Promise<void> | void;
+    orchestrationProfile?: VoiceProviderOrchestrationProfile<TContext, TSession, TProvider>;
+    orchestrationSurface?: string;
     policy?: VoiceProviderRouterPolicy<TContext, TSession, TProvider>;
     providerHealth?: boolean | VoiceProviderRouterHealthOptions;
     providerProfiles?: Partial<Record<TProvider, VoiceProviderRouterProviderProfile>>;

package/dist/testing/index.js

@@ -3791,6 +3791,7 @@ var createVoiceIOProviderFailureSimulator = (options) => {
   };
 };
 // src/modelAdapters.ts
+var isVoiceProviderRoutingPolicyPreset = (value) => value === "balanced" || value === "cost-cap" || value === "cost-first" || value === "latency-first" || value === "quality-first";
 var resolveVoiceProviderRoutingPolicyPreset = (preset, options = {}) => {
   switch (preset) {
     case "balanced":
@@ -3832,6 +3833,75 @@ var resolveVoiceProviderRoutingPolicyPreset = (preset, options = {}) => {
       };
   }
 };
+var resolveVoiceProviderRoutingPolicy = (policy) => {
+  if (!policy) {
+    return;
+  }
+  if (typeof policy === "string") {
+    return isVoiceProviderRoutingPolicyPreset(policy) ? resolveVoiceProviderRoutingPolicyPreset(policy) : {
+      strategy: policy
+    };
+  }
+  return policy;
+};
+var mergeDefinedProviderPolicyFields = (base, surface) => {
+  const next = {
+    ...base ?? {}
+  };
+  if (surface.allowProviders !== undefined) {
+    next.allowProviders = surface.allowProviders;
+  }
+  if (surface.fallbackMode !== undefined) {
+    next.fallbackMode = surface.fallbackMode;
+  }
+  if (surface.maxCost !== undefined) {
+    next.maxCost = surface.maxCost;
+  }
+  if (surface.maxLatencyMs !== undefined) {
+    next.maxLatencyMs = surface.maxLatencyMs;
+  }
+  if (surface.minQuality !== undefined) {
+    next.minQuality = surface.minQuality;
+  }
+  if (surface.strategy !== undefined) {
+    next.strategy = surface.strategy;
+  }
+  if (surface.weights !== undefined) {
+    next.weights = {
+      ...base?.weights ?? {},
+      ...surface.weights
+    };
+  }
+  return next;
+};
+var createVoiceProviderOrchestrationProfile = (options) => {
+  const surfaceNames = Object.keys(options.surfaces);
+  const defaultSurface = options.defaultSurface ?? surfaceNames[0];
+  if (!defaultSurface || !options.surfaces[defaultSurface]) {
+    throw new Error("Voice provider orchestration profile has no surfaces.");
+  }
+  return {
+    defaultSurface,
+    id: options.id,
+    resolve: (surface = defaultSurface) => {
+      const config = options.surfaces[surface];
+      if (!config) {
+        throw new Error(`Voice provider orchestration profile ${options.id} has no surface "${surface}".`);
+      }
+      const policy = mergeDefinedProviderPolicyFields(resolveVoiceProviderRoutingPolicy(config.policy), config);
+      return {
+        allowProviders: config.allowProviders,
+        fallback: config.fallback,
+        fallbackMode: config.fallbackMode,
+        policy,
+        providerHealth: config.providerHealth,
+        providerProfiles: config.providerProfiles,
+        timeoutMs: config.timeoutMs
+      };
+    },
+    surfaces: options.surfaces
+  };
+};
 var OUTPUT_SCHEMA = {
   additionalProperties: false,
   properties: {
@@ -3999,19 +4069,23 @@ var createJSONVoiceAssistantModel = (options) => ({
 var createVoiceProviderRouter = (options) => {
   const providerIds = Object.keys(options.providers);
   const firstProvider = providerIds[0];
-  const policy = typeof options.policy === "string" ? options.policy === "balanced" || options.policy === "cost-cap" || options.policy === "cost-first" || options.policy === "latency-first" || options.policy === "quality-first" ? resolveVoiceProviderRoutingPolicyPreset(options.policy) : {
-    strategy: options.policy
-  } : options.policy;
+  const orchestrationSurface = options.orchestrationProfile?.resolve(options.orchestrationSurface);
+  const policy = resolveVoiceProviderRoutingPolicy(options.policy) ?? resolveVoiceProviderRoutingPolicy(orchestrationSurface?.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 fallbackMode = policy?.fallbackMode ?? options.fallbackMode ?? orchestrationSurface?.fallbackMode ?? "provider-error";
+  const providerProfiles = {
+    ...orchestrationSurface?.providerProfiles ?? {},
+    ...options.providerProfiles ?? {}
+  };
+  const providerHealthOption = options.providerHealth ?? orchestrationSurface?.providerHealth;
+  const healthOptions = typeof providerHealthOption === "object" ? providerHealthOption : providerHealthOption ? {} : 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 getProviderTimeoutMs = (provider) => {
-    const timeoutMs = options.providerProfiles?.[provider]?.timeoutMs ?? options.timeoutMs;
+    const timeoutMs = providerProfiles[provider]?.timeoutMs ?? options.timeoutMs ?? orchestrationSurface?.timeoutMs;
     return typeof timeoutMs === "number" && Number.isFinite(timeoutMs) && timeoutMs > 0 ? timeoutMs : undefined;
   };
   const getHealth = (provider) => {
@@ -4077,12 +4151,12 @@ var createVoiceProviderRouter = (options) => {
     return cloneHealth(provider);
   };
   const resolveAllowedProviders = async (input) => {
-    const allowProviders = policy?.allowProviders ?? options.allowProviders;
+    const allowProviders = policy?.allowProviders ?? options.allowProviders ?? orchestrationSurface?.allowProviders;
     const allowed = typeof allowProviders === "function" ? await allowProviders(input) : allowProviders;
     return new Set(allowed ?? providerIds);
   };
   const passesBudgetFilters = (provider) => {
-    const profile = options.providerProfiles?.[provider];
+    const profile = providerProfiles[provider];
     if (typeof policy?.maxCost === "number" && typeof profile?.cost === "number" && profile.cost > policy.maxCost) {
       return false;
     }
@@ -4095,7 +4169,7 @@ var createVoiceProviderRouter = (options) => {
     return true;
   };
   const getBalancedScore = (provider) => {
-    const profile = options.providerProfiles?.[provider];
+    const profile = providerProfiles[provider];
     if (policy?.scoreProvider) {
       return policy.scoreProvider(provider, profile);
     }
@@ -4107,8 +4181,8 @@ var createVoiceProviderRouter = (options) => {
       return providers;
     }
     return [...providers].sort((left, right) => {
-      const leftProfile = options.providerProfiles?.[left];
-      const rightProfile = options.providerProfiles?.[right];
+      const leftProfile = providerProfiles[left];
+      const rightProfile = providerProfiles[right];
       if (strategy === "quality-first") {
         return (rightProfile?.quality ?? Number.MIN_SAFE_INTEGER) - (leftProfile?.quality ?? Number.MIN_SAFE_INTEGER) || (leftProfile?.priority ?? Number.MAX_SAFE_INTEGER) - (rightProfile?.priority ?? Number.MAX_SAFE_INTEGER) || (leftProfile?.latencyMs ?? Number.MAX_SAFE_INTEGER) - (rightProfile?.latencyMs ?? Number.MAX_SAFE_INTEGER) || (leftProfile?.cost ?? Number.MAX_SAFE_INTEGER) - (rightProfile?.cost ?? Number.MAX_SAFE_INTEGER);
       }
@@ -4123,7 +4197,8 @@ var createVoiceProviderRouter = (options) => {
   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 fallbackSource = options.fallback ?? orchestrationSurface?.fallback;
+    const fallbackOrder = typeof fallbackSource === "function" ? await fallbackSource(input) : fallbackSource;
     const allowedRankedProviders = sortProviders([
       ...fallbackOrder ?? providerIds
     ]).filter((provider) => allowedProviders.has(provider));

package/package.json

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