@absolutejs/voice 0.0.22-beta.11 → 0.0.22-beta.111

package/README.md

@@ -1,11 +1,48 @@
 # `@absolutejs/voice`
 
-`@absolutejs/voice` is the voice session layer for AbsoluteJS. It owns the duplex WebSocket lifecycle, transcript buffering, turn commits, reconnect behavior, and client primitives, while keeping speech vendors and session storage pluggable.
+`@absolutejs/voice` is the self-hosted voice operations layer for AbsoluteJS.
+
+It gives your app the primitives hosted voice platforms usually keep behind their dashboards: browser voice sessions, phone-call routes, provider routing, assistant tools, handoffs, traces, evals, production-readiness checks, latency proof, storage adapters, and framework-native UI helpers.
+
+Use it when you want Vapi/Retell/Bland-style voice-agent capability, but you want the orchestration, data, traces, storage, and UI to live inside the AbsoluteJS server you already operate.
+
+## Why AbsoluteJS Voice
+
+- Self-hosted by default: your app owns sessions, traces, reviews, tasks, handoffs, retention, and provider keys.
+- Provider-neutral: use Deepgram, AssemblyAI, OpenAI, Anthropic, Gemini, ElevenLabs-style TTS, or your own adapters without rewriting app workflow code.
+- Browser and phone surfaces: mount browser WebSocket voice routes plus Twilio, Telnyx, and Plivo telephony routes from the same package.
+- Production proof: App Kit, production readiness, turn quality, turn latency, live browser p50/p95 latency, trace timelines, evals, fixtures, and contracts are package primitives.
+- Framework parity: React, Vue, Svelte, Angular, HTML, HTMX, and plain client entrypoints share the same core behavior.
+- No hosted platform tax: AbsoluteJS Voice does not add a mandatory per-minute orchestration fee between your app and your providers.
+
+## Start Here
+
+Pick the path that matches what you are building:
+
+- Browser voice agent: mount `voice(...)`, choose an STT adapter, and use the React/Vue/Svelte/Angular/HTML/HTMX client helpers for mic, transcript, reconnect, and status UI.
+- Phone voice agent: mount Twilio, Telnyx, or Plivo routes, normalize carrier outcomes, inspect carrier readiness, and persist call lifecycle traces.
+- Production readiness: mount `createVoiceAppKitRoutes(...)` to get ops console/status, quality, evals, provider health, sessions, handoffs, diagnostics, and readiness gates.
+- Provider routing and fallback: use LLM/STT/TTS provider routers, provider health, provider simulation controls, and cost/latency-aware routing policies.
+- Evals and simulation: mount `createVoiceSimulationSuiteRoutes(...)` to run scenario fixtures, workflow contracts, tool contracts, outcome contracts, baseline comparisons, and saved benchmark artifacts before live traffic.
+
+## How This Differs From Hosted Voice Platforms
+
+Hosted voice-agent platforms are strongest when you want a managed dashboard, phone-number provisioning, hosted orchestration, and campaign tooling out of the box.
+
+AbsoluteJS Voice is strongest when voice is part of your own product and you need code-owned primitives:
+
+- Your app stores the call data instead of a vendor dashboard being the source of truth.
+- Your app controls provider routing, fallback, retries, handoffs, and retention.
+- Your team can inspect and extend every primitive.
+- Your framework UI can render first-class voice state without iframe/dashboard handoffs.
+- Your production checks and evals can run in CI, smoke tests, or your own admin UI.
+
+The goal is not to clone a hosted platform. The goal is to make AbsoluteJS the best place to build and operate self-hosted voice products.
 
 ## Install
 
 ```bash
-bun add @absolutejs/voice
+bun add @absolutejs/voice @absolutejs/voice-deepgram
 ```
 
 Peer dependencies:
@@ -21,7 +58,12 @@ Optional framework entrypoints:
 - `@absolutejs/voice/angular`
 - `@absolutejs/voice/client`
 
-## Route Setup
+Common optional adapters:
+
+- `@absolutejs/voice-deepgram`
+- `@absolutejs/voice-assemblyai`
+
+## Browser Voice Agent
 
 ```ts
 import { Elysia } from 'elysia';
@@ -73,6 +115,276 @@ const app = new Elysia()
 
 `createVoiceMemoryStore()` is dev-only. Real deployments should provide a shared store backed by Redis, Postgres, or equivalent.
 
+## Production Readiness Path
+
+Once the basic route works, mount the App Kit. This gives you the self-hosted operational surface that hosted platforms usually make mandatory:
+
+```ts
+import {
+	createVoiceAppKitRoutes,
+	createVoiceFileRuntimeStorage,
+	createVoiceLiveLatencyRoutes,
+	createVoiceProductionReadinessRoutes,
+	createVoiceTraceTimelineRoutes,
+	createVoiceTurnLatencyRoutes,
+	createVoiceTurnQualityRoutes
+} from '@absolutejs/voice';
+
+const runtime = createVoiceFileRuntimeStorage({
+	directory: '.voice-runtime/support'
+});
+
+app
+	.use(
+		createVoiceAppKitRoutes({
+			store: runtime.traces,
+			llmProviders: ['openai', 'anthropic', 'gemini'],
+			sttProviders: ['deepgram', 'assemblyai']
+		}).routes
+	)
+	.use(
+		createVoiceTurnLatencyRoutes({
+			htmlPath: '/turn-latency',
+			path: '/api/turn-latency',
+			store: runtime.session,
+			traceStore: runtime.traces
+		})
+	)
+	.use(
+		createVoiceLiveLatencyRoutes({
+			htmlPath: '/live-latency',
+			path: '/api/live-latency',
+			store: runtime.traces
+		})
+	)
+	.use(
+		createVoiceTurnQualityRoutes({
+			htmlPath: '/turn-quality',
+			path: '/api/turn-quality',
+			store: runtime.session
+		})
+	)
+	.use(
+		createVoiceTraceTimelineRoutes({
+			htmlPath: '/traces',
+			path: '/api/voice-traces',
+			store: runtime.traces
+		})
+	)
+	.use(
+		createVoiceProductionReadinessRoutes({
+			htmlPath: '/production-readiness',
+			path: '/api/production-readiness',
+			store: runtime.traces
+		})
+	);
+```
+
+Recommended proof routes:
+
+- `/app-kit/status`: compact customer-facing app status.
+- `/production-readiness`: production gate summary.
+- `/traces`: per-session trace timelines.
+- `/turn-latency`: server-side turn-stage latency.
+- `/live-latency`: browser-measured speech-to-assistant p50/p95 latency.
+- `/turn-quality`: STT confidence, correction, fallback, and transcript diagnostics.
+
+## Simulation Suite Path
+
+Use `createVoiceSimulationSuiteRoutes(...)` when you want one pre-production proof surface for the things that usually live in separate dashboards or scripts:
+
+```ts
+import {
+	createVoiceSimulationSuiteRoutes,
+	createVoiceFileRuntimeStorage
+} from '@absolutejs/voice';
+
+const runtime = createVoiceFileRuntimeStorage({
+	directory: '.voice-runtime/support'
+});
+
+app.use(
+	createVoiceSimulationSuiteRoutes({
+		htmlPath: '/voice/simulations',
+		path: '/api/voice/simulations',
+		store: runtime.traces,
+		scenarios: workflowScenarios,
+		fixtureStore: scenarioFixtureStore,
+		tools: toolContracts,
+		outcomes: {
+			contracts: outcomeContracts,
+			events: runtime.events,
+			reviews: runtime.reviews,
+			sessions: runtime.session,
+			tasks: runtime.tasks
+		}
+	})
+);
+```
+
+The suite rolls up session quality, scenario evals, fixture simulations, tool contracts, and outcome contracts into one pass/fail report. It is the code-owned equivalent of "test this voice flow before production" without requiring a hosted voice-agent dashboard.
+
+## Phone Voice Agent Path
+
+Use the telephony primitives when the agent needs to answer or place calls through your own carrier account:
+
+```ts
+import {
+	createVoicePhoneAgent,
+	createVoiceTelephonyOutcomePolicy
+} from '@absolutejs/voice';
+import { deepgram } from '@absolutejs/voice-deepgram';
+
+const outcomePolicy = createVoiceTelephonyOutcomePolicy({
+	transferTarget: '+15551234567'
+});
+
+app
+	.use(
+		createVoicePhoneAgent({
+			matrix: {
+				path: '/api/carriers',
+				title: 'AbsoluteJS Voice Carrier Matrix'
+			},
+			carriers: [
+				{
+					provider: 'twilio',
+					options: {
+						context: {},
+						outcomePolicy,
+						session: runtime.session,
+						stt: deepgram({ apiKey: process.env.DEEPGRAM_API_KEY! }),
+						streamPath: '/api/voice/twilio/stream',
+						twiml: {
+							path: '/api/voice/twilio',
+							streamUrl: process.env.TWILIO_STREAM_URL
+						},
+						webhook: {
+							path: '/api/voice/twilio/webhook',
+							signingSecret: process.env.TWILIO_AUTH_TOKEN
+						},
+						async onTurn({ turn }) {
+							return { assistantText: `I heard: ${turn.text}` };
+						},
+						onComplete: async () => {}
+					}
+				}
+			]
+		}).routes
+	);
+```
+
+The wrapper mounts selected carrier routes and a readiness matrix. Telnyx and Plivo use the same wrapper with `{ provider: 'telnyx', options: ... }` or `{ provider: 'plivo', options: ... }`. The lower-level `createTwilioVoiceRoutes(...)`, `createTelnyxVoiceRoutes(...)`, and `createPlivoVoiceRoutes(...)` helpers remain available when you need carrier-specific control.
+
+## App Kit And Status Widgets
+
+Use `createVoiceAppKitRoutes(...)` when you want a self-hosted operations surface without hand-wiring every dashboard route. It adds the ops console, quality gates, eval routes, provider health, session replay, handoff health, diagnostics, and `GET /app-kit/status`.
+
+```ts
+import { createVoiceAppKitRoutes, createVoiceFileRuntimeStorage } from '@absolutejs/voice';
+
+const runtime = createVoiceFileRuntimeStorage({ directory: '.voice-runtime/support' });
+
+app.use(
+	createVoiceAppKitRoutes({
+		store: runtime.traces,
+		llmProviders: ['openai', 'anthropic', 'gemini'],
+		sttProviders: ['deepgram', 'assemblyai']
+	}).routes
+);
+```
+
+The status endpoint is intentionally small enough for customer-facing demos. It can report fixture-backed workflow readiness while leaving deeper live quality/session failures visible on the ops pages.
+
+```ts
+app.use(
+	createVoiceAppKitRoutes({
+		appStatus: {
+			include: { quality: false, sessions: false },
+			preferFixtureWorkflows: true
+		},
+		evals: { fixtures: certificationFixtures, scenarios: workflowScenarios },
+		store: runtime.traces
+	}).routes
+);
+```
+
+### React Status Widget
+
+```tsx
+import { VoiceOpsStatus } from '@absolutejs/voice/react';
+
+export function OpsBadge() {
+	return <VoiceOpsStatus intervalMs={5000} />;
+}
+```
+
+### Vue Status Widget
+
+```vue
+<script setup lang="ts">
+import { VoiceOpsStatus } from '@absolutejs/voice/vue';
+</script>
+
+<template>
+	<VoiceOpsStatus :interval-ms="5000" />
+</template>
+```
+
+### Svelte Status Widget
+
+```svelte
+<script lang="ts">
+	import { onDestroy, onMount } from 'svelte';
+	import { createVoiceOpsStatus } from '@absolutejs/voice/svelte';
+
+	const status = createVoiceOpsStatus('/app-kit/status', { intervalMs: 5000 });
+	let html = '';
+	onMount(() => status.subscribe(() => (html = status.getHTML())));
+	onDestroy(() => status.close());
+</script>
+
+{@html html}
+```
+
+### Angular Status Widget
+
+```ts
+import { VoiceAppKitStatusService } from '@absolutejs/voice/angular';
+
+status = inject(VoiceAppKitStatusService).connect('/app-kit/status', {
+	intervalMs: 5000
+});
+```
+
+```html
+<h2>{{ status.report()?.status === 'pass' ? 'Passing' : 'Needs attention' }}</h2>
+<p>{{ status.report()?.passed ?? 0 }} passing checks</p>
+```
+
+### HTML Or HTMX Status Widget
+
+```html
+<div id="voice-ops-status"></div>
+<script type="module">
+	import { mountVoiceOpsStatus } from '@absolutejs/voice/client';
+
+	mountVoiceOpsStatus(document.querySelector('#voice-ops-status'), '/app-kit/status', {
+		intervalMs: 5000
+	});
+</script>
+```
+
+For custom elements:
+
+```html
+<absolute-voice-ops-status interval-ms="5000"></absolute-voice-ops-status>
+<script type="module">
+	import { defineVoiceOpsStatusElement } from '@absolutejs/voice/client';
+	defineVoiceOpsStatusElement();
+</script>
+```
+
 ## Voice Assistants
 
 Use `createVoiceAssistant(...)` when you want one product-level surface for a voice agent instead of wiring tools, guardrails, experiments, traces, and ops recipes separately. It returns a standard `onTurn` handler, plus an `ops` object you can pass to `voice(...)`.
@@ -1069,6 +1381,102 @@ app.use(
   - `benchmark-results/sessions-cheap-stt-runs-3.json`
   - `benchmark-results/stt-routing-run-manifest.json`
 
+## LLM Provider Routing
+
+Use `createVoiceProviderRouter(...)` when your assistant can run on more than one LLM provider. The router keeps provider choice inside your app: you define the available model adapters, profile each provider, and choose a policy.
+
+```ts
+import {
+	createAnthropicVoiceAssistantModel,
+	createGeminiVoiceAssistantModel,
+	createOpenAIVoiceAssistantModel,
+	createVoiceProviderRouter,
+	resolveVoiceProviderRoutingPolicyPreset
+} from '@absolutejs/voice';
+
+const model = createVoiceProviderRouter({
+	providers: {
+		openai: createOpenAIVoiceAssistantModel({ apiKey: process.env.OPENAI_API_KEY! }),
+		anthropic: createAnthropicVoiceAssistantModel({ apiKey: process.env.ANTHROPIC_API_KEY! }),
+		gemini: createGeminiVoiceAssistantModel({ apiKey: process.env.GEMINI_API_KEY! })
+	},
+	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 }
+	},
+	policy: resolveVoiceProviderRoutingPolicyPreset('balanced')
+});
+```
+
+Built-in policy presets:
+
+- `quality-first`: rank by `providerProfiles[provider].quality`, then priority, latency, and cost.
+- `latency-first`: rank by expected latency.
+- `cost-first`: rank by expected cost.
+- `cost-cap`: rank by cost and reject providers above `maxCost`.
+- `balanced`: weighted score using cost, latency, quality, and priority.
+
+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
+const policy = resolveVoiceProviderRoutingPolicyPreset('cost-cap', {
+	maxCost: 3,
+	minQuality: 0.82
+});
+```
+
+For full control, pass an object policy:
+
+```ts
+const model = createVoiceProviderRouter({
+	providers,
+	providerProfiles,
+	policy: {
+		strategy: 'balanced',
+		maxLatencyMs: 1000,
+		weights: { cost: 1, latencyMs: 0.004, quality: 12 }
+	}
+});
+```
+
+The same profile and policy shape also works for STT and TTS provider routers, so a self-hosted app can choose the fastest provider for live calls, cap cost for background work, or require a minimum quality score without hard-coding provider branches.
+
+```ts
+const stt = createVoiceSTTProviderRouter({
+	adapters: {
+		deepgram,
+		assemblyai
+	},
+	providerHealth: { cooldownMs: 30_000 },
+	providerProfiles: {
+		deepgram: { cost: 4, latencyMs: 180, quality: 0.93, timeoutMs: 1500 },
+		assemblyai: { cost: 2, latencyMs: 650, quality: 0.88, timeoutMs: 3000 }
+	},
+	policy: resolveVoiceProviderRoutingPolicyPreset('latency-first')
+});
+
+const tts = createVoiceTTSProviderRouter({
+	adapters: {
+		elevenlabs,
+		openai
+	},
+	providerProfiles: {
+		elevenlabs: { cost: 5, latencyMs: 220, quality: 0.94 },
+		openai: { cost: 2, latencyMs: 320, quality: 0.87 }
+	},
+	policy: resolveVoiceProviderRoutingPolicyPreset('cost-cap', {
+		maxCost: 3,
+		minQuality: 0.85
+	})
+});
+```
+
 ## Presets
 
 Voice now ships named runtime presets so apps can start from a useful baseline instead of hand-tuning silence and capture settings every time.

package/dist/agent.d.ts

@@ -1,5 +1,6 @@
 import type { VoiceOnTurnObjectHandler, VoiceRouteResult, VoiceSessionHandle, VoiceSessionRecord, VoiceTurnRecord } from './types';
 import type { VoiceTraceEventStore } from './trace';
+import type { VoiceToolRuntime } from './toolRuntime';
 export type VoiceAgentMessageRole = 'assistant' | 'system' | 'tool' | 'user';
 export type VoiceAgentMessage = {
     content: string;
@@ -86,6 +87,7 @@ export type VoiceAgentOptions<TContext = unknown, TSession extends VoiceSessionR
         turn: VoiceTurnRecord;
     }) => Promise<string | undefined> | string | undefined);
     trace?: VoiceTraceEventStore;
+    toolRuntime?: VoiceToolRuntime<TContext, TSession, TResult>;
     tools?: Array<VoiceAgentTool<TContext, TSession, Record<string, unknown>, unknown, TResult>>;
 };
 export type VoiceAgentSquadOptions<TContext = unknown, TSession extends VoiceSessionRecord = VoiceSessionRecord, TResult = unknown> = {

package/dist/angular/index.d.ts

@@ -1,2 +1,10 @@
+export { VoiceAppKitStatusService } from './voice-app-kit-status.service';
 export { VoiceStreamService } from './voice-stream.service';
 export { VoiceControllerService } from './voice-controller.service';
+export { VoiceProviderCapabilitiesService } from './voice-provider-capabilities.service';
+export { VoiceProviderStatusService } from './voice-provider-status.service';
+export { VoiceRoutingStatusService } from './voice-routing-status.service';
+export { VoiceTraceTimelineService } from './voice-trace-timeline.service';
+export { VoiceTurnLatencyService } from './voice-turn-latency.service';
+export { VoiceTurnQualityService } from './voice-turn-quality.service';
+export { VoiceWorkflowStatusService } from './voice-workflow-status.service';