@absolutejs/voice 0.0.22-beta.15 → 0.0.22-beta.151

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: ops status, 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 the status and proof primitives you need, such as `createVoiceOpsStatusRoutes(...)`, `createVoiceProductionReadinessRoutes(...)`, quality routes, trace routes, eval routes, and smoke contracts.
+- 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,532 @@ 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 proof routes you need. These give you the self-hosted operational surfaces that hosted platforms usually make mandatory, without forcing a bundled app kit:
+
+```ts
+import {
+	createVoiceAuditDeliveryRoutes,
+	createVoiceDemoReadyRoutes,
+	createVoiceFileRuntimeStorage,
+	createVoiceLiveLatencyRoutes,
+	createVoiceOpsStatusRoutes,
+	createVoiceProductionReadinessRoutes,
+	createVoiceTraceDeliveryRoutes,
+	createVoiceTraceTimelineRoutes,
+	createVoiceTurnLatencyRoutes,
+	createVoiceTurnQualityRoutes
+} from '@absolutejs/voice';
+
+const runtime = createVoiceFileRuntimeStorage({
+	directory: '.voice-runtime/support'
+});
+
+app
+	.use(
+		createVoiceOpsStatusRoutes({
+			store: runtime.traces,
+			llmProviders: ['openai', 'anthropic', 'gemini'],
+			sttProviders: ['deepgram', 'assemblyai']
+		})
+	)
+	.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({
+			audit: runtime.audit,
+			auditDeliveries: runtime.auditDeliveries,
+			htmlPath: '/production-readiness',
+			path: '/api/production-readiness',
+			store: runtime.traces,
+			traceDeliveries: runtime.traceDeliveries
+		})
+	)
+	.use(
+		createVoiceAuditDeliveryRoutes({
+			htmlPath: '/audit/deliveries',
+			path: '/api/voice-audit-deliveries',
+			store: runtime.auditDeliveries
+		})
+	)
+	.use(
+		createVoiceTraceDeliveryRoutes({
+			htmlPath: '/traces/deliveries',
+			path: '/api/voice-trace-deliveries',
+			store: runtime.traceDeliveries
+		})
+	);
+```
+
+Recommended proof routes:
+
+- `/api/voice/ops-status`: compact status for hooks, widgets, and customer-facing demos.
+- `/api/voice/ops-status/html`: HTML status card for quick internal review.
+- `/demo-ready`: customer-facing demo readiness checklist.
+- `/production-readiness`: production gate summary.
+- `/audit/deliveries`: audit sink export queue and failed delivery details.
+- `/voice/phone/smoke-contract`: trace-backed phone-agent production smoke proof.
+- `/traces`: per-session trace timelines.
+- `/traces/deliveries`: trace sink export queue and failed delivery details.
+- `/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.
+
+## Delivery Runtime Presets
+
+Use `createVoiceDeliveryRuntimePresetConfig(...)` when you want one primitive to create paired audit and trace delivery workers for the same target. The preset returns a normal `VoiceDeliveryRuntimeConfig`, so you can still inspect or override worker options before passing it to `createVoiceDeliveryRuntime(...)`.
+
+### File Delivery
+
+Use file delivery for local demos, dev environments, or self-hosted deployments that collect exports from disk.
+
+```ts
+import {
+	createVoiceDeliveryRuntime,
+	createVoiceDeliveryRuntimePresetConfig,
+	createVoiceDeliveryRuntimeRoutes,
+	createVoiceFileRuntimeStorage
+} from '@absolutejs/voice';
+
+const runtimeStorage = createVoiceFileRuntimeStorage({
+	directory: '.voice-runtime/support'
+});
+
+const deliveryRuntime = createVoiceDeliveryRuntime(
+	createVoiceDeliveryRuntimePresetConfig({
+		auditDeliveries: runtimeStorage.auditDeliveries,
+		directory: '.voice-runtime/support/delivery-exports',
+		leases: createLeaseCoordinator(),
+		mode: 'file',
+		traceDeliveries: runtimeStorage.traceDeliveries
+	})
+);
+
+app.use(
+	createVoiceDeliveryRuntimeRoutes({
+		runtime: deliveryRuntime
+	})
+);
+```
+
+### Webhook Delivery
+
+Use webhook delivery when audit and trace exports should go to your own ingestion service, SIEM bridge, warehouse collector, or internal ops backend. The built-in HTTP sinks support retries, optional HMAC signing, custom headers, timeouts, and custom envelope bodies.
+
+```ts
+const deliveryRuntime = createVoiceDeliveryRuntime(
+	createVoiceDeliveryRuntimePresetConfig({
+		auditDeliveries: runtimeStorage.auditDeliveries,
+		auditSinkId: 'support-audit-webhook',
+		body: {
+			audit: ({ events }) => ({
+				eventCount: events.length,
+				events,
+				source: 'support-app',
+				surface: 'audit-deliveries'
+			}),
+			trace: ({ events }) => ({
+				eventCount: events.length,
+				events,
+				source: 'support-app',
+				surface: 'trace-deliveries'
+			})
+		},
+		failures: {
+			maxFailures: 3
+		},
+		leases: {
+			audit: createLeaseCoordinator(),
+			trace: createLeaseCoordinator()
+		},
+		mode: 'webhook',
+		signingSecret: process.env.VOICE_DELIVERY_WEBHOOK_SECRET,
+		traceDeliveries: runtimeStorage.traceDeliveries,
+		traceSinkId: 'support-trace-webhook',
+		url: process.env.VOICE_DELIVERY_WEBHOOK_URL!
+	})
+);
+```
+
+### S3 Delivery
+
+Use S3 delivery when exports should land directly in object storage through Bun's native S3 client. Set `bucket` and `keyPrefix`; the preset writes audit and trace exports under separate prefixes.
+
+```ts
+const deliveryRuntime = createVoiceDeliveryRuntime(
+	createVoiceDeliveryRuntimePresetConfig({
+		auditDeliveries: runtimeStorage.auditDeliveries,
+		auditSinkId: 'support-audit-s3',
+		bucket: process.env.VOICE_DELIVERY_S3_BUCKET,
+		failures: {
+			maxFailures: 3
+		},
+		keyPrefix: 'support/voice-deliveries',
+		leases: {
+			audit: createLeaseCoordinator(),
+			trace: createLeaseCoordinator()
+		},
+		mode: 's3',
+		traceDeliveries: runtimeStorage.traceDeliveries,
+		traceSinkId: 'support-trace-s3'
+	})
+);
+```
+
+Mount `createVoiceDeliveryRuntimeRoutes({ runtime: deliveryRuntime })` to expose:
+
+- `/api/voice-delivery-runtime`: combined audit and trace worker summary.
+- `/api/voice-delivery-runtime/tick`: manual tick for both workers.
+- `/delivery-runtime`: HTML worker control plane.
+
+Pass the same runtime to production readiness so failed, dead-lettered, or pending export queues become deploy-blocking evidence:
+
+```ts
+app.use(
+	createVoiceProductionReadinessRoutes({
+		auditDeliveries: runtimeStorage.auditDeliveries,
+		deliveryRuntime,
+		links: {
+			deliveryRuntime: '/delivery-runtime'
+		},
+		store: runtimeStorage.traces,
+		traceDeliveries: runtimeStorage.traceDeliveries
+	})
+);
+```
+
+## 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 In 20 Minutes
+
+Use `createVoicePhoneAgent(...)` when the agent needs to answer or place calls through your own Twilio, Telnyx, or Plivo account. This is the self-hosted alternative to a hosted phone-agent dashboard: your app owns the carrier routes, stream URLs, webhooks, traces, readiness checks, and lifecycle outcomes.
+
+```ts
+import {
+	createVoicePhoneAgent,
+	createVoiceTelephonyOutcomePolicy,
+	runVoicePhoneAgentProductionSmokeContract
+} from '@absolutejs/voice';
+import { deepgram } from '@absolutejs/voice-deepgram';
+
+const outcomePolicy = createVoiceTelephonyOutcomePolicy({
+	transferTarget: '+15551234567'
+});
+
+app
+	.use(
+		createVoicePhoneAgent({
+			setup: {
+				path: '/api/voice/phone/setup',
+				title: 'Support Phone Agent'
+			},
+			matrix: {
+				path: '/api/carriers',
+				title: 'AbsoluteJS Voice Carrier Matrix'
+			},
+			productionSmoke: {
+				maxAgeMs: 24 * 60 * 60 * 1000,
+				required: [
+					'carrier-contract',
+					'media-started',
+					'transcript',
+					'assistant-response',
+					'lifecycle-outcome',
+					'no-session-error',
+					'fresh-trace'
+				],
+				store: runtime.traces
+			},
+			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 plus two proof surfaces:
+
+- `/api/voice/phone/setup`: one setup report with carrier URLs, smoke links, lifecycle stages, and readiness.
+- `/api/voice/phone/setup?format=html`: copy/paste setup page for carrier dashboards.
+- `/api/carriers`: carrier matrix JSON for Twilio, Telnyx, and Plivo.
+- `/api/carriers?format=html`: side-by-side carrier readiness matrix.
+- `/api/voice/phone/smoke-contract?sessionId=...`: trace-backed production smoke contract.
+- `/voice/phone/smoke-contract?sessionId=...`: HTML production smoke contract.
+
+The setup page tells you exactly what to copy into the carrier dashboard:
+
+- Twilio: set the phone number voice webhook/TwiML URL to the reported TwiML URL, set the status callback to the reported webhook URL, and allow the reported `wss://` media stream.
+- Telnyx: set the connection TeXML URL to the reported TeXML URL, set the status webhook to the reported webhook URL, and allow the reported `wss://` media stream.
+- Plivo: set the answer URL to the reported answer URL, set the status callback to the reported webhook URL, and allow the reported `wss://` media stream.
+
+Each configured carrier can also expose its own setup and smoke pages, for example:
+
+- `/api/voice/twilio/setup?format=html`
+- `/api/voice/twilio/smoke?format=html`
+- `/api/voice/telnyx/setup?format=html`
+- `/api/voice/telnyx/smoke?format=html`
+- `/api/voice/plivo/setup?format=html`
+- `/api/voice/plivo/smoke?format=html`
+
+The phone-agent report normalizes the lifecycle schema across carriers:
+
+- `ringing`
+- `answered`
+- `media-started`
+- `transcript`
+- `assistant-response`
+- `transfer`
+- `voicemail`
+- `no-answer`
+- `completed`
+- `failed`
+
+That is the important Vapi/Retell/Bland gap this primitive closes: a team can mount one phone-agent entrypoint, bring its own carrier account, verify readiness before live calls, and keep call traces and lifecycle outcomes inside its own AbsoluteJS app. 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.
+
+After running a real smoke call, certify the phone-agent path from traces:
+
+```ts
+const smoke = await runVoicePhoneAgentProductionSmokeContract({
+	maxAgeMs: 24 * 60 * 60 * 1000,
+	required: [
+		'media-started',
+		'transcript',
+		'assistant-response',
+		'lifecycle-outcome',
+		'no-session-error',
+		'fresh-trace'
+	],
+	sessionId: 'phone-smoke-session',
+	store: runtime.traces
+});
+
+if (!smoke.pass) {
+	throw new Error(smoke.issues.map((issue) => issue.message).join('\n'));
+}
+```
+
+Pass those reports into production readiness through `phoneAgentSmokes`. This makes deployment fail when the carrier setup exists but the actual phone-agent call path did not produce media start, transcript, assistant response, terminal lifecycle outcome, and clean trace evidence.
+
+When `productionSmoke` is enabled on `createVoicePhoneAgent(...)`, the wrapper mounts `/api/voice/phone/smoke-contract?sessionId=...` for JSON and `/voice/phone/smoke-contract?sessionId=...` for HTML. It also derives carrier contract evidence from the existing carrier matrix unless you provide a custom `getContract`.
+
+## Ops Status Hooks And Widgets
+
+Use `createVoiceOpsStatusRoutes(...)` when you want a small status endpoint for demos, admin pages, and framework widgets. It is intentionally not a route bundle: mount quality gates, eval routes, provider health, session replay, phone-agent smoke proof, handoff health, and diagnostics explicitly when your app needs them.
+
+```ts
+import {
+	createVoiceDemoReadyRoutes,
+	createVoiceFileRuntimeStorage,
+	createVoiceOpsStatusRoutes,
+	summarizeVoiceOpsStatus
+} from '@absolutejs/voice';
+
+const runtime = createVoiceFileRuntimeStorage({ directory: '.voice-runtime/support' });
+
+app.use(
+	createVoiceOpsStatusRoutes({
+		store: runtime.traces,
+		llmProviders: ['openai', 'anthropic', 'gemini'],
+		sttProviders: ['deepgram', 'assemblyai']
+	})
+);
+```
+
+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 proof routes you mount separately.
+
+For a single demo page that rolls up ops status, production readiness, phone setup, and phone smoke proof, mount `createVoiceDemoReadyRoutes(...)` with the same reports you already expose elsewhere:
+
+```ts
+app.use(
+	createVoiceDemoReadyRoutes({
+		opsStatus: {
+			href: '/api/voice/ops-status',
+			load: () => summarizeVoiceOpsStatus(opsStatusOptions)
+		},
+		phoneSetup: {
+			href: '/api/voice/phone/setup?format=html',
+			load: () => phoneAgentSetupReport
+		},
+		phoneSmoke: {
+			href: '/voice/phone/smoke-contract',
+			load: () => phoneSmokeReport
+		},
+		productionReadiness: {
+			href: '/production-readiness',
+			load: () => productionReadinessReport
+		}
+	})
+);
+```
+
+```ts
+app.use(
+	createVoiceOpsStatusRoutes({
+		include: { quality: false, sessions: false },
+		preferFixtureWorkflows: true,
+		store: runtime.traces
+	})
+);
+```
+
+### 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('/api/voice/ops-status', { intervalMs: 5000 });
+	let html = '';
+	onMount(() => status.subscribe(() => (html = status.getHTML())));
+	onDestroy(() => status.close());
+</script>
+
+{@html html}
+```
+
+### Angular Status Widget
+
+```ts
+import { VoiceOpsStatusService } from '@absolutejs/voice/angular';
+
+status = inject(VoiceOpsStatusService).connect('/api/voice/ops-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'), '/api/voice/ops-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(...)`.
@@ -212,7 +780,21 @@ const billingAgent = createVoiceAgent({
 const frontDesk = createVoiceAgentSquad({
 	id: 'front-desk',
 	defaultAgentId: 'support',
-	agents: [supportAgent, billingAgent]
+	agents: [supportAgent, billingAgent],
+	handoffPolicy: ({ handoff }) => {
+		if (handoff.targetAgentId === 'billing') {
+			return {
+				summary: 'Route verified billing requests to the billing specialist.',
+				metadata: { queue: 'billing' }
+			};
+		}
+
+		return {
+			allow: false,
+			reason: `No approved route for ${handoff.targetAgentId}.`,
+			escalate: { reason: 'unsupported-specialist' }
+		};
+	}
 });
 
 voice({
@@ -226,6 +808,56 @@ voice({
 
 `createVoiceAgentSquad(...)` gives you squad-style specialization without locking your app into a hosted voice platform. An agent can return `handoff: { targetAgentId: 'billing' }`; the squad records the handoff, runs the target agent on the same turn, and still returns a standard `VoiceRouteResult`.
 
+For production call centers, pass `handoffPolicy` to keep routing code-owned instead of dashboard-owned. The policy can allow a handoff, reroute it to a different specialist, merge handoff metadata, summarize the reason for the target agent, or block the handoff and return an escalation. Squad traces mark each handoff as `allowed`, `blocked`, `unknown-target`, or `max-exceeded`, so support teams can audit why a caller moved between specialists.
+
+Use `runVoiceAgentSquadContract(...)` in tests or readiness checks when you need proof that a specialist graph still routes correctly:
+
+```ts
+import {
+	createVoiceMemoryTraceEventStore,
+	runVoiceAgentSquadContract
+} from '@absolutejs/voice';
+
+const trace = createVoiceMemoryTraceEventStore();
+const frontDesk = createVoiceAgentSquad({
+	id: 'front-desk',
+	defaultAgentId: 'support',
+	agents: [supportAgent, billingAgent],
+	trace
+});
+
+const report = await runVoiceAgentSquadContract({
+	context: {},
+	squad: frontDesk,
+	trace,
+	contract: {
+		id: 'billing-route',
+		scenarioId: 'billing-route',
+		turns: [
+			{
+				text: 'I have a billing question.',
+				expect: {
+					finalAgentId: 'billing',
+					outcome: 'assistant',
+					assistantIncludes: ['billing'],
+					handoffs: [
+						{
+							fromAgentId: 'support',
+							targetAgentId: 'billing',
+							status: 'allowed'
+						}
+					]
+				}
+			}
+		]
+	}
+});
+
+if (!report.pass) {
+	throw new Error(report.issues.map((issue) => issue.message).join('\n'));
+}
+```
+
 ## Traces And Replay
 
 Use trace stores when you want every call to be inspectable outside a hosted platform. Trace events are append-only records for model passes, tool calls, handoffs, agent results, call lifecycle, turn timing, errors, and cost telemetry.
@@ -233,13 +865,22 @@ Use trace stores when you want every call to be inspectable outside a hosted pla
 ```ts
 import {
 	buildVoiceTraceReplay,
+	buildVoiceAuditExport,
+	createVoiceAuditHTTPSink,
+	createVoiceAuditLogger,
+	createVoiceAuditSinkDeliveryWorker,
+	createVoiceAuditSinkStore,
+	createVoiceAuditTrailRoutes,
 	createVoiceAgent,
 	createVoiceFileRuntimeStorage,
 	createVoiceRedisTaskLeaseCoordinator,
+	createVoiceTraceDeliveryRoutes,
 	createVoiceTraceHTTPSink,
 	createVoiceTraceSinkStore,
 	createVoiceTraceSinkDeliveryWorker,
+	buildVoiceDataRetentionPlan,
 	exportVoiceTrace,
+	applyVoiceDataRetentionPolicy,
 	pruneVoiceTraceEvents,
 	voice
 } from '@absolutejs/voice';
@@ -251,6 +892,30 @@ const runtimeStorage = createVoiceFileRuntimeStorage({
 const redisLeases = createVoiceRedisTaskLeaseCoordinator({
 	url: process.env.REDIS_URL
 });
+const auditStore = createVoiceAuditSinkStore({
+	store: runtimeStorage.audit,
+	deliveryQueue: runtimeStorage.auditDeliveries,
+	sinks: [
+		createVoiceAuditHTTPSink({
+			id: 'security-warehouse',
+			signingSecret: process.env.VOICE_AUDIT_SINK_SECRET,
+			url: process.env.VOICE_AUDIT_SINK_URL!
+		})
+	]
+});
+const audit = createVoiceAuditLogger(auditStore);
+const auditSinkWorker = createVoiceAuditSinkDeliveryWorker({
+	deliveries: runtimeStorage.auditDeliveries,
+	leases: redisLeases,
+	sinks: [
+		createVoiceAuditHTTPSink({
+			id: 'security-warehouse',
+			signingSecret: process.env.VOICE_AUDIT_SINK_SECRET,
+			url: process.env.VOICE_AUDIT_SINK_URL!
+		})
+	],
+	workerId: 'audit-sink-worker'
+});
 const trace = createVoiceTraceSinkStore({
 	store: runtimeStorage.traces,
 	deliveryQueue: runtimeStorage.traceDeliveries,
@@ -277,6 +942,9 @@ const traceSinkWorker = createVoiceTraceSinkDeliveryWorker({
 
 const supportAgent = createVoiceAgent({
 	id: 'support',
+	audit,
+	auditProvider: 'openai',
+	auditModel: 'gpt-4.1',
 	trace,
 	model: {
 		async generate() {
@@ -293,6 +961,17 @@ voice({
 	onTurn: supportAgent.onTurn,
 	onComplete: async () => {}
 });
+app.use(
+	createVoiceAuditTrailRoutes({
+		store: runtimeStorage.audit
+	})
+);
+app.use(
+	createVoiceTraceDeliveryRoutes({
+		store: runtimeStorage.traceDeliveries,
+		worker: traceSinkWorker
+	})
+);
 
 const replay = await exportVoiceTrace({
 	store: runtimeStorage.traces,
@@ -314,18 +993,53 @@ await pruneVoiceTraceEvents({
 	store: runtimeStorage.traces,
 	before: Date.now() - 30 * 24 * 60 * 60 * 1000
 });
+
+await audit.operatorAction({
+	action: 'review.approve',
+	actor: { id: 'operator-123', kind: 'operator' },
+	resource: { id: 'review-123', type: 'review' }
+});
 ```
 
 `createVoiceMemoryTraceEventStore(...)`, `createVoiceFileTraceEventStore(...)`, `createVoiceSQLiteTraceEventStore(...)`, and `createVoicePostgresTraceEventStore(...)` all implement the same `VoiceTraceEventStore` contract. File, SQLite, and Postgres runtime storage expose `runtimeStorage.traces` and `runtimeStorage.traceDeliveries` alongside sessions, reviews, tasks, events, and external object mappings. Passing `trace` to `voice(...)` records session lifecycle, transcript, committed-turn, assistant, cost, and error events; passing it to agents records model passes, tools, results, and handoffs.
 
 For self-hosted QA and support workflows, use `summarizeVoiceTrace(...)`, `evaluateVoiceTrace(...)`, `renderVoiceTraceMarkdown(...)`, `renderVoiceTraceHTML(...)`, or `buildVoiceTraceReplay(...)`. They turn raw trace events into portable artifacts you can attach to tickets, inspect locally, or fail in CI when a call has missing transcripts, missing turns, tool errors, session errors, or excessive handoffs.
 
-For observability pipelines, wrap any trace store with `createVoiceTraceSinkStore(...)` and pass sinks such as `createVoiceTraceHTTPSink(...)`. The wrapper still writes to your normal file, SQLite, or Postgres store, then fans out appended events to your warehouse, logs, S3 bridge, or analytics endpoint. Use `awaitDelivery: true` only when you want trace delivery to block append completion. For durable delivery, pass `deliveryQueue` and run `createVoiceTraceSinkDeliveryWorker(...)` or `createVoiceTraceSinkDeliveryWorkerLoop(...)`; the worker uses the same Redis lease/idempotency primitives as ops workers and supports retries plus dead-letter stores.
+For observability pipelines, wrap any trace store with `createVoiceTraceSinkStore(...)` and pass sinks such as `createVoiceTraceHTTPSink(...)`. The wrapper still writes to your normal file, SQLite, or Postgres store, then fans out appended events to your warehouse, logs, S3 bridge, or analytics endpoint. Use `awaitDelivery: true` only when you want trace delivery to block append completion. For durable delivery, pass `deliveryQueue` and run `createVoiceTraceSinkDeliveryWorker(...)` or `createVoiceTraceSinkDeliveryWorkerLoop(...)`; the worker uses the same Redis lease/idempotency primitives as ops workers and supports retries plus dead-letter stores. Mount `createVoiceTraceDeliveryRoutes({ store: runtimeStorage.traceDeliveries, worker })` to expose `/traces/deliveries`, `/api/voice-trace-deliveries`, and an explicit `POST /api/voice-trace-deliveries/drain` retry path.
 
 When traces may leave your private runtime, pass `redact: true` or a redaction config to `exportVoiceTrace(...)`, `renderVoiceTraceMarkdown(...)`, `renderVoiceTraceHTML(...)`, or `buildVoiceTraceReplay(...)`. The built-in redactor scrubs common email addresses, phone numbers, and sensitive keys like `token`, `secret`, `password`, `apiKey`, `authorization`, `phone`, and `email`; you can pass custom keys or replacement text for stricter policies.
 
 For retention jobs, `pruneVoiceTraceEvents(...)` works against any trace store. Use `dryRun: true` before deleting, filter by session, trace, scenario, turn, or event type, cap each run with `limit`, or keep only the newest N matching events with `keepNewest`.
 
+For whole-runtime data control, use `buildVoiceDataRetentionPlan(...)` first and then `applyVoiceDataRetentionPolicy(...)` when the deletion set is correct. The policy works across stores exposed by file, SQLite, or Postgres runtime storage, including sessions, traces, trace deliveries, audit deliveries, reviews, ops tasks, integration events, and campaigns. A cutoff or per-scope `keepNewest` selector is required before anything is deleted, so an empty policy reports skipped scopes instead of wiping data.
+
+```ts
+const plan = await buildVoiceDataRetentionPlan({
+	before: Date.now() - 30 * 24 * 60 * 60 * 1000,
+	...runtimeStorage
+});
+
+console.log(plan.scopes);
+
+await applyVoiceDataRetentionPolicy({
+	audit: runtimeStorage.audit,
+	before: Date.now() - 30 * 24 * 60 * 60 * 1000,
+	...runtimeStorage
+});
+```
+
+Use `createVoiceAuditLogger(...)` when you need append-only compliance evidence outside call traces. The logger records provider calls, tool calls, handoffs, retention runs, and operator actions into `runtimeStorage.audit`, so self-hosted teams can prove who changed what, which provider ran, which tool fired, and what data-control policy deleted.
+
+Pass `audit` directly to `createVoiceAgent(...)` to record model calls as provider-call audit events and tool executions as tool-call audit events. Pass it to `createVoiceAgentSquad(...)` to record squad handoffs automatically. Use `auditProvider` and `auditModel` on agents when you want readiness and compliance reports to show the actual model provider instead of the agent id.
+
+For compliance pipelines, wrap any audit store with `createVoiceAuditSinkStore(...)` and pass sinks such as `createVoiceAuditHTTPSink(...)`. Audit sinks redact by default, support HMAC signing, retries, event-type filters, optional blocking delivery, durable delivery queues through `runtimeStorage.auditDeliveries`, and background workers through `createVoiceAuditSinkDeliveryWorker(...)` or `createVoiceAuditSinkDeliveryWorkerLoop(...)`. File, SQLite, and Postgres runtime storage all expose `auditDeliveries`, so teams can ship evidence to a SIEM, warehouse, or internal security service without a hosted dashboard. Mount `createVoiceAuditDeliveryRoutes({ store: runtimeStorage.auditDeliveries, worker })` to expose `/audit/deliveries`, `/api/voice-audit-deliveries`, and an explicit `POST /api/voice-audit-deliveries/drain` retry path.
+
+Pass `audit: runtimeStorage.audit` into production readiness when audit coverage should block deploys. By default readiness requires provider-call, retention-policy, and operator-action audit evidence; retention-policy evidence must be from the last 7 days so a stale one-time audit event does not certify an active retention job. Override required event types or freshness with `audit: { store: runtimeStorage.audit, require: [{ type: 'retention.policy', maxAgeMs: ... }] }` when a deployment has different compliance gates. Pass `auditDeliveries: runtimeStorage.auditDeliveries` and `traceDeliveries: runtimeStorage.traceDeliveries` when sink export health should also block deploys; failed or dead-lettered deliveries fail readiness, pending deliveries warn, and pending deliveries older than the configured fail window fail readiness.
+
+Mount `createVoiceAuditTrailRoutes(...)` to expose `/api/voice-audit` and `/audit` over the same store. File, SQLite, and Postgres runtime storage all expose `runtimeStorage.audit`. The JSON and HTML surfaces support filters like `type`, `outcome`, `actorId`, `resourceType`, `resourceId`, `sessionId`, `traceId`, and `limit`, so operators can search audit evidence without writing a custom viewer first.
+
+Use `exportVoiceAuditTrail(...)` or `buildVoiceAuditExport(...)` when audit evidence needs to leave the app. Pass `redact: true` to scrub sensitive keys plus common email and phone patterns from payloads and metadata before generating JSON, Markdown, or HTML. Audit trail routes also expose redacted exports at `/api/voice-audit/export`, `/api/voice-audit/export?format=markdown`, `/api/voice-audit/export?format=html`, and `/audit/export`; export routes redact by default unless `redact=false` is passed.
+
 ## Production Voice Ops
 
 The recommended production pattern is:
@@ -733,6 +1447,59 @@ app.use(
 
 Client state now exposes `assistantAudio` on the stream/controller helpers, so apps can buffer or play synthesized chunks without inventing a second transport.
 
+## OpenAI Realtime
+
+Use `createOpenAIRealtimeAdapter(...)` when you want a direct OpenAI Realtime speech-to-speech output path for live smoke tests, duplex benchmarks, or custom realtime orchestration. It implements the same `RealtimeAdapter` contract used by the benchmark harness, so the provider can stream `response.output_audio.delta` audio chunks into AbsoluteJS voice events while still emitting normalized transcript, error, and close events.
+
+```ts
+import { createOpenAIRealtimeAdapter } from '@absolutejs/voice';
+import { runTTSAdapterFixture } from '@absolutejs/voice/testing';
+
+const realtime = createOpenAIRealtimeAdapter({
+	apiKey: process.env.OPENAI_API_KEY!,
+	instructions: 'Answer in one concise sentence.',
+	model: 'gpt-realtime',
+	voice: 'marin'
+});
+
+app.use(
+	voice({
+		path: '/voice',
+		realtime,
+		realtimeInputFormat: {
+			channels: 1,
+			container: 'raw',
+			encoding: 'pcm_s16le',
+			sampleRateHz: 24000
+		},
+		session,
+		onTurn: async ({ turn }) => ({
+			assistantText: `You said: ${turn.text}`
+		}),
+		onComplete: async () => {}
+	})
+);
+
+const report = await runTTSAdapterFixture(
+	realtime,
+	{
+		id: 'openai-realtime-smoke',
+		text: 'Say exactly: AbsoluteJS realtime is online.',
+		title: 'OpenAI Realtime smoke'
+	},
+	{
+		realtimeFormat: {
+			channels: 1,
+			container: 'raw',
+			encoding: 'pcm_s16le',
+			sampleRateHz: 24000
+		}
+	}
+);
+```
+
+For server-to-server use, the adapter opens a WebSocket to OpenAI, sends `session.update`, streams text or base64 PCM input, and emits raw 24kHz mono `pcm_s16le` assistant audio. It requires raw 24kHz mono PCM input because that is the OpenAI Realtime PCM format. The main `voice(...)` route can now run in cascaded mode with `stt` plus optional `tts`, or direct realtime mode with `realtime`. Browser demos should make sure the captured PCM format matches `realtimeInputFormat` or resample before sending audio.
+
 If you want a minimal browser playback path, use the client audio player:
 
 ```ts
@@ -1069,6 +1836,136 @@ 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
+});
+```
+
+Use `runVoiceProviderRoutingContract(...)` when provider fallback needs to be certified before production. The contract reads provider routing trace events and verifies the expected selected provider, fallback provider, status, and kind in order.
+
+```ts
+import { runVoiceProviderRoutingContract } from '@absolutejs/voice';
+
+const report = await runVoiceProviderRoutingContract({
+	store: runtime.traces,
+	contract: {
+		id: 'openai-to-anthropic-fallback',
+		expect: [
+			{
+				kind: 'llm',
+				provider: 'openai',
+				selectedProvider: 'openai',
+				fallbackProvider: 'anthropic',
+				status: 'error'
+			},
+			{
+				kind: 'llm',
+				provider: 'anthropic',
+				selectedProvider: 'openai',
+				status: 'fallback'
+			}
+		]
+	}
+});
+
+if (!report.pass) {
+	throw new Error(report.issues.map((issue) => issue.message).join('\n'));
+}
+```
+
+Pass provider routing contract reports into production readiness through `providerRoutingContracts`. Readiness fails when a fallback contract fails, so model-routing regressions become deploy blockers instead of dashboard-only surprises.
+
+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.
@@ -1566,6 +2463,8 @@ Default reconnect strategy is `resume-last-turn`.
 
 If an adapter does not emit native end-of-turn events, core falls back to silence detection with a default `700ms` threshold.
 
+For browser/client proof, use `runVoiceReconnectContract(...)` or mount `createVoiceReconnectContractRoutes(...)` with captured reconnect snapshots. The contract verifies that a reconnect was observed, the stream resumed before exhaustion, and replayed state did not duplicate committed turn IDs.
+
 ## STT Fallback
 
 You can pair a primary vendor with an optional fallback vendor per route when you need extra reliability for accents, edge environments, or short commands.