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

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/productionReadiness.d.ts

@@ -15,6 +15,7 @@ import type { VoiceAuditEventStore, VoiceAuditEventType, VoiceAuditOutcome } fro
 import { type VoiceAuditSinkDeliveryStore } from './auditSinks';
 import type { VoiceProviderContractMatrixReport, VoiceProviderStackCapabilityGapReport } from './providerStackRecommendations';
 import { type VoiceProviderSloReport, type VoiceProviderSloReportOptions } from './providerSlo';
+import type { VoiceProviderOrchestrationReport } from './providerOrchestration';
 import type { VoiceCampaignReadinessProofReport } from './campaign';
 import { type VoiceOpsRecoveryReport } from './opsRecovery';
 import { type VoiceObservabilityExportDeliveryHistory, type VoiceObservabilityExportDeliveryReceiptStore, type VoiceObservabilityExportReplayReport, type VoiceObservabilityExportReplaySource, type VoiceObservabilityExportReport } from './observabilityExport';
@@ -136,6 +137,7 @@ export type VoiceProductionReadinessReport = {
         phoneAgentSmoke?: string;
         telephonyWebhookSecurity?: string;
         providerContracts?: string;
+        providerOrchestration?: string;
         providerRoutingContracts?: string;
         providerSlo?: string;
         quality?: string;
@@ -243,6 +245,15 @@ export type VoiceProductionReadinessReport = {
         };
         providerStack?: VoiceProviderStackCapabilityGapReport;
         providerContractMatrix?: VoiceProviderContractMatrixReport;
+        providerOrchestration?: {
+            failed: number;
+            issues: number;
+            passed: number;
+            providers: number;
+            status: VoiceProductionReadinessStatus;
+            surfaces: number;
+            warned: number;
+        };
         providerRecovery: VoiceProviderFallbackRecoverySummary;
         phoneAgentSmokes?: {
             failed: number;
@@ -469,6 +480,10 @@ export type VoiceProductionReadinessRoutesOptions = {
         query: Record<string, unknown>;
         request: Request;
     }) => Promise<VoiceProviderSloReport | VoiceProviderSloReportOptions> | VoiceProviderSloReport | VoiceProviderSloReportOptions);
+    providerOrchestration?: false | VoiceProviderOrchestrationReport | ((input: {
+        query: Record<string, unknown>;
+        request: Request;
+    }) => Promise<VoiceProviderOrchestrationReport> | VoiceProviderOrchestrationReport);
     providerStack?: false | VoiceProviderStackCapabilityGapReport | ((input: {
         query: Record<string, unknown>;
         request: Request;

package/dist/providerOrchestration.d.ts

@@ -0,0 +1,109 @@
+import { Elysia } from 'elysia';
+import type { VoiceProviderOrchestrationProfile, VoiceProviderRouterProviderProfile } from './modelAdapters';
+import type { VoiceSessionRecord } from './types';
+export type VoiceProviderOrchestrationStatus = 'fail' | 'pass' | 'warn';
+export type VoiceProviderOrchestrationRequirement = {
+    minProviders?: number;
+    requireBudgetPolicy?: boolean;
+    requireCircuitBreaker?: boolean;
+    requireFallback?: boolean;
+    requireTimeoutBudget?: boolean;
+};
+export type VoiceProviderOrchestrationIssue = {
+    code: string;
+    message: string;
+    status: Exclude<VoiceProviderOrchestrationStatus, 'pass'>;
+    surface?: string;
+};
+export type VoiceProviderOrchestrationSurfaceReport = {
+    allowProviders: string[];
+    budgetPolicy: {
+        maxCost?: number;
+        maxLatencyMs?: number;
+        minQuality?: number;
+    };
+    circuitBreaker: boolean;
+    fallbackMode?: string;
+    fallbackProviders: string[];
+    issues: VoiceProviderOrchestrationIssue[];
+    providerProfiles: Record<string, VoiceProviderRouterProviderProfile>;
+    providers: string[];
+    status: VoiceProviderOrchestrationStatus;
+    strategy?: string;
+    surface: string;
+    timeoutBudget: boolean;
+    timeoutMs?: number;
+};
+export type VoiceProviderOrchestrationReport = {
+    checkedAt: number;
+    issues: VoiceProviderOrchestrationIssue[];
+    profileId: string;
+    status: VoiceProviderOrchestrationStatus;
+    summary: {
+        failed: number;
+        passed: number;
+        providers: number;
+        surfaces: number;
+        warned: number;
+    };
+    surfaces: VoiceProviderOrchestrationSurfaceReport[];
+};
+export type VoiceProviderOrchestrationReportOptions<TProvider extends string = string, TSurface extends string = string> = {
+    defaultRequirement?: VoiceProviderOrchestrationRequirement;
+    profile: VoiceProviderOrchestrationProfile<unknown, VoiceSessionRecord, TProvider, TSurface>;
+    requirements?: Partial<Record<TSurface, VoiceProviderOrchestrationRequirement>>;
+};
+export type VoiceProviderOrchestrationRoutesOptions<TProvider extends string = string, TSurface extends string = string> = VoiceProviderOrchestrationReportOptions<TProvider, TSurface> & {
+    headers?: HeadersInit;
+    htmlPath?: false | string;
+    markdownPath?: false | string;
+    name?: string;
+    path?: string;
+    render?: (report: VoiceProviderOrchestrationReport) => string | Promise<string>;
+    title?: string;
+};
+export declare const buildVoiceProviderOrchestrationReport: <TProvider extends string = string, TSurface extends string = string>(options: VoiceProviderOrchestrationReportOptions<TProvider, TSurface>) => VoiceProviderOrchestrationReport;
+export declare const renderVoiceProviderOrchestrationMarkdown: (report: VoiceProviderOrchestrationReport) => string;
+export declare const renderVoiceProviderOrchestrationHTML: (report: VoiceProviderOrchestrationReport, options?: {
+    title?: string;
+}) => string;
+export declare const createVoiceProviderOrchestrationRoutes: <TProvider extends string = string, TSurface extends string = string>(options: VoiceProviderOrchestrationRoutesOptions<TProvider, TSurface>) => Elysia<"", {
+    decorator: {};
+    store: {};
+    derive: {};
+    resolve: {};
+}, {
+    typebox: {};
+    error: {};
+}, {
+    schema: {};
+    standaloneSchema: {};
+    macro: {};
+    macroFn: {};
+    parser: {};
+    response: {};
+}, {
+    [x: string]: {
+        get: {
+            body: unknown;
+            params: {};
+            query: unknown;
+            headers: unknown;
+            response: {
+                200: VoiceProviderOrchestrationReport;
+            };
+        };
+    };
+}, {
+    derive: {};
+    resolve: {};
+    schema: {};
+    standaloneSchema: {};
+    response: {};
+}, {
+    derive: {};
+    resolve: {};
+    schema: {};
+    standaloneSchema: {};
+    response: {};
+}>;

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/dist/vue/useVoiceReadinessFailures.d.ts

@@ -56,6 +56,7 @@ export declare const useVoiceReadinessFailures: (path?: string, options?: VoiceR
             readonly phoneAgentSmoke?: string | undefined;
             readonly telephonyWebhookSecurity?: string | undefined;
             readonly providerContracts?: string | undefined;
+            readonly providerOrchestration?: string | undefined;
             readonly providerRoutingContracts?: string | undefined;
             readonly providerSlo?: string | undefined;
             readonly quality?: string | undefined;
@@ -310,6 +311,15 @@ export declare const useVoiceReadinessFailures: (path?: string, options?: VoiceR
                 readonly total: number;
                 readonly warned: number;
             } | undefined;
+            readonly providerOrchestration?: {
+                readonly failed: number;
+                readonly issues: number;
+                readonly passed: number;
+                readonly providers: number;
+                readonly status: import("..").VoiceProductionReadinessStatus;
+                readonly surfaces: number;
+                readonly warned: number;
+            } | undefined;
             readonly providerRecovery: {
                 readonly recovered: number;
                 readonly recoveredSessions: number;
@@ -429,6 +439,7 @@ export declare const useVoiceReadinessFailures: (path?: string, options?: VoiceR
             readonly phoneAgentSmoke?: string | undefined;
             readonly telephonyWebhookSecurity?: string | undefined;
             readonly providerContracts?: string | undefined;
+            readonly providerOrchestration?: string | undefined;
             readonly providerRoutingContracts?: string | undefined;
             readonly providerSlo?: string | undefined;
             readonly quality?: string | undefined;
@@ -683,6 +694,15 @@ export declare const useVoiceReadinessFailures: (path?: string, options?: VoiceR
                 readonly total: number;
                 readonly warned: number;
             } | undefined;
+            readonly providerOrchestration?: {
+                readonly failed: number;
+                readonly issues: number;
+                readonly passed: number;
+                readonly providers: number;
+                readonly status: import("..").VoiceProductionReadinessStatus;
+                readonly surfaces: number;
+                readonly warned: number;
+            } | undefined;
             readonly providerRecovery: {
                 readonly recovered: number;
                 readonly recoveredSessions: number;

package/package.json

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