@absolutejs/voice 0.0.21 → 0.0.22-beta.1

package/README.md

@@ -37,6 +37,13 @@ const app = new Elysia()
 		voice({
 			path: '/voice',
 			preset: 'guided-intake',
+			lexicon: [
+				{
+					text: 'AbsoluteJS',
+					aliases: ['absoloot js'],
+					pronunciation: 'ab-so-lute jay ess'
+				}
+			],
 			phraseHints: [
 				{ text: 'AbsoluteJS', aliases: ['absolute js'] },
 				{ text: 'Joe Johnston', aliases: ['joe johnson'] }
@@ -66,11 +73,830 @@ const app = new Elysia()
 
 `createVoiceMemoryStore()` is dev-only. Real deployments should provide a shared store backed by Redis, Postgres, or equivalent.
 
+## Agent Tools And Squads
+
+For assistant-style products, use `createVoiceAgent(...)` as the `onTurn` handler. The agent layer is provider-neutral: plug in any model adapter, register server-side tools, and return normal voice route results like `assistantText`, `transfer`, `escalate`, or `complete`.
+
+```ts
+import {
+	createVoiceAgent,
+	createVoiceAgentSquad,
+	createVoiceAgentTool,
+	createVoiceMemoryStore,
+	voice
+} from '@absolutejs/voice';
+import { deepgram } from '@absolutejs/voice-deepgram';
+
+const lookupOrder = createVoiceAgentTool({
+	name: 'lookup_order',
+	description: 'Look up an order by id.',
+	parameters: {
+		type: 'object',
+		properties: {
+			orderId: { type: 'string' }
+		},
+		required: ['orderId']
+	},
+	execute: async ({ args }) => {
+		return { orderId: args.orderId, status: 'shipped' };
+	}
+});
+
+const supportAgent = createVoiceAgent({
+	id: 'support',
+	system: 'You are a concise support voice agent.',
+	tools: [lookupOrder],
+	model: {
+		async generate({ messages, tools }) {
+			// Call your LLM provider here. If it returns tool calls, AbsoluteJS
+			// executes them and calls the model again with tool results.
+			return {
+				assistantText: `I can help. Available tools: ${tools.map((tool) => tool.name).join(', ')}`
+			};
+		}
+	}
+});
+
+const billingAgent = createVoiceAgent({
+	id: 'billing',
+	system: 'You handle billing questions.',
+	model: {
+		async generate() {
+			return { assistantText: 'I can help with billing.' };
+		}
+	}
+});
+
+const frontDesk = createVoiceAgentSquad({
+	id: 'front-desk',
+	defaultAgentId: 'support',
+	agents: [supportAgent, billingAgent]
+});
+
+voice({
+	path: '/voice',
+	session: createVoiceMemoryStore(),
+	stt: deepgram({ apiKey: process.env.DEEPGRAM_API_KEY! }),
+	onTurn: frontDesk.onTurn,
+	onComplete: async () => {}
+});
+```
+
+`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`.
+
+## 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.
+
+```ts
+import {
+	buildVoiceTraceReplay,
+	createVoiceAgent,
+	createVoiceFileRuntimeStorage,
+	createVoiceRedisTaskLeaseCoordinator,
+	createVoiceTraceHTTPSink,
+	createVoiceTraceSinkStore,
+	createVoiceTraceSinkDeliveryWorker,
+	exportVoiceTrace,
+	pruneVoiceTraceEvents,
+	voice
+} from '@absolutejs/voice';
+import { deepgram } from '@absolutejs/voice-deepgram';
+
+const runtimeStorage = createVoiceFileRuntimeStorage({
+	directory: '.voice-runtime/support'
+});
+const redisLeases = createVoiceRedisTaskLeaseCoordinator({
+	url: process.env.REDIS_URL
+});
+const trace = createVoiceTraceSinkStore({
+	store: runtimeStorage.traces,
+	deliveryQueue: runtimeStorage.traceDeliveries,
+	redact: true,
+	sinks: [
+		createVoiceTraceHTTPSink({
+			id: 'warehouse',
+			url: process.env.TRACE_WAREHOUSE_URL!
+		})
+	]
+});
+const traceSinkWorker = createVoiceTraceSinkDeliveryWorker({
+	deliveries: runtimeStorage.traceDeliveries,
+	leases: redisLeases,
+	redact: true,
+	sinks: [
+		createVoiceTraceHTTPSink({
+			id: 'warehouse',
+			url: process.env.TRACE_WAREHOUSE_URL!
+		})
+	],
+	workerId: 'trace-sink-worker'
+});
+
+const supportAgent = createVoiceAgent({
+	id: 'support',
+	trace,
+	model: {
+		async generate() {
+			return { assistantText: 'How can I help?' };
+		}
+	}
+});
+
+voice({
+	path: '/voice',
+	session: runtimeStorage.session,
+	stt: deepgram({ apiKey: process.env.DEEPGRAM_API_KEY! }),
+	trace,
+	onTurn: supportAgent.onTurn,
+	onComplete: async () => {}
+});
+
+const replay = await exportVoiceTrace({
+	store: runtimeStorage.traces,
+	filter: {
+		sessionId: 'session-123'
+	}
+});
+
+const report = buildVoiceTraceReplay(replay.events, {
+	redact: true,
+	title: 'Support call session-123'
+});
+
+console.log(report.summary);
+console.log(report.evaluation.pass);
+await Bun.write('trace.html', report.html);
+
+await pruneVoiceTraceEvents({
+	store: runtimeStorage.traces,
+	before: Date.now() - 30 * 24 * 60 * 60 * 1000
+});
+```
+
+`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.
+
+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`.
+
+## Production Voice Ops
+
+The recommended production pattern is:
+
+- persistent session storage
+- built-in review recording
+- built-in task creation from call outcomes
+- built-in integration event recording
+
+The simplest durable local setup uses `createVoiceFileRuntimeStorage(...)` plus `voice({ ops })`:
+
+```ts
+import { Elysia } from 'elysia';
+import {
+	createVoiceCRMActivitySink,
+	createVoiceFileRuntimeStorage,
+	createVoiceHelpdeskTicketSink,
+	resolveVoiceOutcomeRecipe,
+	voice
+} from '@absolutejs/voice';
+import { deepgram } from '@absolutejs/voice-deepgram';
+
+const runtimeStorage = createVoiceFileRuntimeStorage({
+	directory: '.voice-runtime/support'
+});
+
+const app = new Elysia().use(
+	voice({
+		path: '/voice',
+		preset: 'reliability',
+		session: runtimeStorage.session,
+		stt: deepgram({
+			apiKey: process.env.DEEPGRAM_API_KEY!,
+			model: 'flux-general-en'
+		}),
+		async onTurn({ turn }) {
+			if (turn.text.toLowerCase().includes('billing')) {
+				return {
+					assistantText: 'Transferring to billing.',
+					transfer: {
+						reason: 'caller-requested-transfer',
+						target: 'billing'
+					}
+				};
+			}
+
+			return {
+				assistantText: `You said: ${turn.text}`
+			};
+		},
+		onComplete: async () => {},
+		ops: {
+			...resolveVoiceOutcomeRecipe('support-triage', {
+				assignee: 'support-oncall',
+				queue: 'support-triage'
+			}),
+			reviews: runtimeStorage.reviews,
+			tasks: runtimeStorage.tasks,
+			events: runtimeStorage.events,
+			webhook: {
+				url: process.env.VOICE_OPS_WEBHOOK_URL!,
+				retries: 2,
+				backoffMs: 500,
+				signingSecret: process.env.VOICE_OPS_WEBHOOK_SECRET
+			},
+			sinks: [
+				createVoiceHelpdeskTicketSink({
+					id: 'helpdesk',
+					url: process.env.HELPDESK_SYNC_URL!
+				}),
+				createVoiceCRMActivitySink({
+					id: 'crm',
+					url: process.env.CRM_SYNC_URL!
+				})
+			]
+		}
+	})
+);
+```
+
+That gives you:
+
+- persisted sessions under `runtimeStorage.session`
+- persisted review artifacts under `runtimeStorage.reviews`
+- persisted follow-up tasks under `runtimeStorage.tasks`
+- persisted integration events under `runtimeStorage.events`
+- persisted vendor object mappings under `runtimeStorage.externalObjects`
+- built-in webhook delivery with persisted delivery status on each event
+- built-in sink fanout with per-sink delivery metadata on each event
+
+If you need richer review artifacts, pass `ops.buildReview(...)`. If you need custom task routing, pass `ops.createTaskFromReview(...)`. If you need external sync side effects inside your app, use `ops.onEvent(...)`. If you want built-in outbound delivery, use `ops.webhook`. If you want core-managed CRM/helpdesk fanout, use `ops.sinks` with `createVoiceIntegrationHTTPSink(...)`, `createVoiceHelpdeskTicketSink(...)`, or `createVoiceCRMActivitySink(...)`.
+
+For fast production defaults, spread `resolveVoiceOutcomeRecipe(...)` into `ops`. Built-in recipes cover `appointment-booking`, `lead-qualification`, `support-triage`, `voicemail-callback`, and `warm-transfer`; each returns task creation, SLA policies, and urgent routing rules while staying fully self-hosted.
+
+For packaged external systems, core now also includes:
+
+- `createVoiceZendeskTicketSink(...)`
+- `createVoiceZendeskTicketUpdateSink(...)`
+- `createVoiceZendeskTicketSyncSinks(...)`
+- `createVoiceHubSpotTaskSink(...)`
+- `createVoiceHubSpotTaskUpdateSink(...)`
+- `createVoiceHubSpotTaskSyncSinks(...)`
+- `createVoiceLinearIssueSink(...)`
+- `createVoiceLinearIssueUpdateSink(...)`
+- `createVoiceLinearIssueSyncSinks(...)`
+
+Those adapters stick to the documented-safe request shapes:
+
+- Zendesk: `POST /api/v2/tickets`
+- Zendesk updates: `PUT /api/v2/tickets/{ticketId}`
+- HubSpot: `POST /crm/v3/objects/tasks`
+- HubSpot updates: `PATCH /crm/v3/objects/tasks/{taskId}`
+- Linear: `issueCreate` over `https://api.linear.app/graphql`
+- Linear updates: `issueUpdate` over `https://api.linear.app/graphql`
+
+Create sinks can persist vendor object ids into `runtimeStorage.externalObjects` when you pass `externalObjects` to the adapter. Update sinks first check explicit event payload ids like `zendeskTicketId`, `hubspotTaskId`, or `linearIssueId`, then resolver callbacks like `ticketId`, `taskId`, or `issueId`, then the external object map. If no external id can be resolved, the sink records a skipped delivery instead of accidentally treating an internal AbsoluteJS task id as a vendor object id.
+
+Use the `*SyncSinks(...)` helpers when you want create/update parity without hand-wiring two adapters. They return a pair of sinks: a create sink for creation events and an update sink for `task.updated` / `task.sla_breached`, sharing the same credentials, fetch options, and `externalObjects` mapping store.
+
+If you want durable non-file runtime storage under Bun, use `createVoiceSQLiteRuntimeStorage(...)` with the same `ops` shape:
+
+```ts
+import { createVoiceSQLiteRuntimeStorage, voice } from '@absolutejs/voice';
+
+const runtimeStorage = createVoiceSQLiteRuntimeStorage({
+	path: '.voice-runtime/support.sqlite'
+});
+```
+
+This uses Bun's native `bun:sqlite` driver directly.
+
+If you want production-friendly shared storage, use `createVoicePostgresRuntimeStorage(...)`:
+
+```ts
+import { createVoicePostgresRuntimeStorage, voice } from '@absolutejs/voice';
+
+const runtimeStorage = createVoicePostgresRuntimeStorage({
+	connectionString: process.env.DATABASE_URL!,
+	schemaName: 'voice_ops',
+	tablePrefix: 'support'
+});
+```
+
+This uses Bun's native `Bun.SQL` client for PostgreSQL.
+
+File, SQLite, and Postgres runtime storage expose the same core surfaces: `session`, `reviews`, `tasks`, `events`, and `externalObjects`. Vendor create/update sink mapping works the same way across local demos and production deployments.
+
+If you need worker coordination for follow-up tasks, use Bun's native Redis client through `createVoiceRedisTaskLeaseCoordinator(...)`:
+
+```ts
+import { createVoiceRedisTaskLeaseCoordinator } from '@absolutejs/voice';
+
+const leases = createVoiceRedisTaskLeaseCoordinator({
+	url: process.env.REDIS_URL,
+	keyPrefix: 'voice:ops'
+});
+
+const claimed = await leases.claim({
+	taskId: 'task-123',
+	workerId: 'worker-a',
+	leaseMs: 30_000
+});
+```
+
+For durable redelivery and idempotent event processing, combine that with `createVoiceRedisIdempotencyStore(...)` and `createVoiceWebhookDeliveryWorker(...)`.
+
+If you want a long-running worker loop, use `createVoiceWebhookDeliveryWorkerLoop(...)` and attach a dead-letter store for repeatedly failing events.
+
+If you need operator task workers in core, use `createVoiceOpsTaskWorker(...)` for lease-backed claim/heartbeat/complete/requeue flows, or `createVoiceOpsTaskProcessorWorker(...)` when you want a handler-driven queue that records failures, requeues retries, and dead-letters tasks after repeated errors.
+
+For task queue observability, use `summarizeVoiceOpsTaskQueue(...)` to report claimed/unclaimed counts, retry-eligible tasks, overdue work, assignee/claim ownership, and dead-letter totals from the same persisted task stores.
+
+If you want assignee and worker throughput metrics directly from stored task history, use `summarizeVoiceOpsTaskAnalytics(...)`. It derives:
+
+- aging buckets (`fresh`, `aging`, `due-soon`, `overdue`, `stale`)
+- assignee backlog and average completion time
+- worker claim / heartbeat / failure / completion counts
+- total overdue and completed workload
+
+If you want outcome-driven SLAs in core, set `ops.taskPolicies` or `ops.resolveTaskPolicy(...)`. Tasks can now carry:
+
+- `priority`
+- `dueAt`
+- `policyName`
+- `processingAttempts`
+- `processingError`
+- `deadLetteredAt`
+
+The built-in default policies already bias toward real ops behavior:
+
+- `escalated` -> urgent, short SLA
+- `failed` -> high priority review
+- `voicemail` -> callback SLA
+- `no-answer` -> retry SLA
+- `transferred` -> verification SLA
+
+Policies can also set:
+
+- `assignee`
+- `queue`
+- `priority`
+- `dueInMs`
+- `recommendedAction`
+
+If you need routing beyond static outcome policies, use `ops.taskAssignmentRules` or `ops.resolveTaskAssignment(...)`. Assignment rules run after task policy resolution, so you can do things like:
+
+- route urgent tasks to an on-call queue
+- move high-priority callbacks into a fast-lane pool
+- escalate specific policy lanes to supervisor ownership
+
+If you want SLA follow-up automation in core, use `createVoiceOpsRuntime(...).checkSLA()` or configure `sla.followUpTask` on the runtime. Overdue tasks can now:
+
+- be marked once with `slaBreachedAt`
+- emit a portable `task.sla_breached` integration event
+- create a secondary follow-up task for supervisors or escalation queues
+
+If you want one higher-level core surface instead of wiring review recording, webhook workers, task processors, and queue summaries by hand, use `createVoiceOpsRuntime(...)`:
+
+```ts
+import {
+	createVoiceCRMActivitySink,
+	createVoiceFileRuntimeStorage,
+	createVoiceHelpdeskTicketSink,
+	createVoiceOpsRuntime,
+	createVoiceRedisTaskLeaseCoordinator,
+	voice
+} from '@absolutejs/voice';
+
+const runtimeStorage = createVoiceFileRuntimeStorage({
+	dir: '.voice-runtime/support'
+});
+
+const ops = {
+	reviews: runtimeStorage.reviews,
+	tasks: runtimeStorage.tasks,
+	events: runtimeStorage.events,
+	sinks: [
+		createVoiceHelpdeskTicketSink({
+			id: 'helpdesk',
+			url: process.env.HELPDESK_SYNC_URL!
+		}),
+		createVoiceCRMActivitySink({
+			id: 'crm',
+			url: process.env.CRM_SYNC_URL!
+		})
+	]
+} as const;
+
+const opsRuntime = createVoiceOpsRuntime({
+	ops,
+	sinks: {
+		autoStart: true,
+		leases: createVoiceRedisTaskLeaseCoordinator({
+			url: process.env.REDIS_URL,
+			keyPrefix: 'voice:ops:sinks'
+		}),
+		maxFailures: 3,
+		workerId: 'ops-sink-worker'
+	},
+	tasks: {
+		autoStart: true,
+		leases: createVoiceRedisTaskLeaseCoordinator({
+			url: process.env.REDIS_URL,
+			keyPrefix: 'voice:ops:tasks'
+		}),
+		maxFailures: 3,
+		process: async (task) => {
+			if (task.kind === 'callback') {
+				// hand off to CRM / dialer / queue
+				return { action: 'complete' };
+			}
+
+			return { action: 'requeue', detail: 'Waiting for a downstream system.' };
+		},
+		workerId: 'ops-task-worker'
+	},
+	webhooks: {
+		autoStart: true,
+		leases: createVoiceRedisTaskLeaseCoordinator({
+			url: process.env.REDIS_URL,
+			keyPrefix: 'voice:ops:events'
+		}),
+		retries: 2,
+		signingSecret: process.env.VOICE_OPS_WEBHOOK_SECRET,
+		url: process.env.VOICE_OPS_WEBHOOK_URL!,
+		workerId: 'ops-webhook-worker'
+	}
+});
+
+opsRuntime.start();
+
+app.use(
+	voice({
+		path: '/voice',
+		ops
+	})
+);
+```
+
+That gives you:
+
+- one portable `ops` config for review/task/event recording
+- built-in sink fanout plus sink redelivery workers
+- built-in webhook delivery workers
+- built-in task processor workers
+- unified `tick()`, `start()`, `stop()`, and `summarize()` controls
+- one queue/runtime surface to test and operate
+
+If you want opinionated queue routing without handcrafting every assignee/queue/SLA rule, start from `resolveVoiceOpsPreset(...)` and spread the result into your ops runtime:
+
+```ts
+import { resolveVoiceOpsPreset } from '@absolutejs/voice';
+
+const opsPreset = resolveVoiceOpsPreset('support-default');
+
+const opsRuntime = createVoiceOpsRuntime({
+	ops: {
+		reviews: runtimeStorage.reviews,
+		tasks: runtimeStorage.tasks,
+		events: runtimeStorage.events,
+		taskPolicies: opsPreset.taskPolicies
+	},
+	sla: opsPreset.sla
+});
+```
+
+Built-in presets:
+
+- `support-default`
+- `sales-default`
+- `collections-default`
+
+Those presets include both:
+
+- `taskPolicies`
+- `assignmentRules`
+
+If you want larger review artifacts in object storage instead of a local or SQL store, use Bun's native S3 client through `createVoiceS3ReviewStore(...)`.
+
+## Production Checklist
+
+Use this as the default deployment checklist for a real voice app:
+
+- Storage:
+  use a shared session store for `session`
+- Runtime ops:
+  enable `ops.reviews`, `ops.tasks`, and `ops.events`
+- Review path:
+  make stored review artifacts visible somewhere operators can inspect quickly
+- Task path:
+  turn non-happy outcomes like `transferred`, `escalated`, `voicemail`, `no-answer`, and `failed` into follow-up work
+- Task policy:
+  set `ops.taskPolicies` or `ops.resolveTaskPolicy(...)` so follow-up work gets real priorities and deadlines instead of ad hoc app rules
+- Worker path:
+  run Redis-leased task workers for follow-up ops and keep dead-letter queues for tasks that repeatedly fail downstream processing
+- Event path:
+  persist `ops.events`, enable `ops.webhook` for outbound delivery, and reserve `ops.onEvent(...)` for app-local side effects
+- STT:
+  use the adapter/model pair you have actually benchmarked for the channel you are shipping
+- PSTN:
+  prefer the telephony path you have validated live, and keep channel-specific settings in presets instead of ad hoc script overrides
+- Correction:
+  keep correction deterministic and domain-safe; do not ship benchmark-shaped seeded aliases as your default public path
+- Observability:
+  capture first partial, first commit, first outbound audio, barge-in stop, disposition, and per-turn errors
+- QA:
+  run repeated live benchmarks for the channel you care about, not just single-pass smoke checks
+
+For the local file-backed starter path, the minimum production-shaped stack is:
+
+- `createVoiceFileRuntimeStorage(...)`
+- `voice({ session: runtimeStorage.session, ops: { reviews, tasks, events } })`
+- one review UI
+- one task queue UI
+- one integration-event sink
+
+## TTS
+
+`@absolutejs/voice` now supports optional assistant audio streaming on the same session path. If you provide a `tts` adapter, `assistantText` responses are still sent as text, and the synthesized PCM chunks are streamed as `audio` messages alongside them.
+
+```ts
+import { voice, createVoiceMemoryStore } from '@absolutejs/voice';
+import { deepgram } from '@absolutejs/voice-deepgram';
+import { elevenlabs } from '@absolutejs/voice-elevenlabs';
+
+app.use(
+	voice({
+		path: '/voice',
+		session: createVoiceMemoryStore(),
+		stt: deepgram({
+			apiKey: process.env.DEEPGRAM_API_KEY!,
+			model: 'flux-general-en'
+		}),
+		tts: elevenlabs({
+			apiKey: process.env.ELEVENLABS_API_KEY!,
+			voiceId: process.env.ELEVENLABS_VOICE_ID!
+		}),
+		onTurn: async ({ turn }) => ({
+			assistantText: `You said: ${turn.text}`
+		}),
+		onComplete: async () => {}
+	})
+);
+```
+
+Client state now exposes `assistantAudio` on the stream/controller helpers, so apps can buffer or play synthesized chunks without inventing a second transport.
+
+If you want a minimal browser playback path, use the client audio player:
+
+```ts
+import {
+	createVoiceAudioPlayer,
+	createVoiceController
+} from '@absolutejs/voice/client';
+
+const voice = createVoiceController('/voice', {
+	preset: 'chat'
+});
+const player = createVoiceAudioPlayer(voice);
+
+await player.start(); // call from a user gesture
+await player.interrupt(); // flush queued assistant playback for barge-in
+```
+
+`createVoiceAudioPlayer()` subscribes to `assistantAudio`, decodes raw `pcm_s16le` chunks, and queues them in WebAudio. It also exposes `interrupt()`, `lastInterruptLatencyMs`, and `lastPlaybackStopLatencyMs` so apps can flush assistant playback during barge-in and inspect how long it took for queued playback to fully stop.
+
+For a higher-level client path, use the duplex helper:
+
+```ts
+import { createVoiceDuplexController } from '@absolutejs/voice/client';
+
+const voice = createVoiceDuplexController('/voice', {
+	bargeIn: {
+		interruptThreshold: 0.08
+	},
+	preset: 'chat'
+});
+
+await voice.audioPlayer.start();
+await voice.startRecording();
+```
+
+`createVoiceDuplexController()` composes the controller and audio player and automatically interrupts assistant playback when:
+
+- microphone input crosses the configured barge-in threshold
+- partial user speech starts arriving
+- manual `sendAudio(...)` is called while assistant audio is playing
+
+## Duplex Benchmarks
+
+The first duplex benchmark lane measures package-level barge-in interruption on the client path. It records scenario pass/fail plus local interruption latency for:
+
+- manual `sendAudio(...)`
+- partial transcript start
+- input-level threshold crossing
+
+Run it with:
+
+```bash
+bun run bench:duplex
+```
+
+That writes:
+
+- `benchmark-results/duplex-barge-in.json`
+
+## Telephony
+
+`@absolutejs/voice` now includes a first PSTN bridge layer for Twilio Media Streams. It converts inbound `audio/x-mulaw` 8 kHz frames into the PCM format the voice session expects, and converts assistant PCM audio back into outbound Twilio media events.
+
+Minimal usage:
+
+```ts
+import { createTwilioMediaStreamBridge, createTwilioVoiceResponse } from '@absolutejs/voice';
+import { deepgram } from '@absolutejs/voice-deepgram';
+import { elevenlabs } from '@absolutejs/voice-elevenlabs';
+
+const twiml = createTwilioVoiceResponse({
+  streamUrl: 'wss://example.com/voice/twilio',
+  parameters: {
+    sessionId: 'call-123',
+    scenarioId: 'phone-intake'
+  },
+  track: 'both_tracks'
+});
+
+const bridge = createTwilioMediaStreamBridge(twilioSocket, {
+  context: {},
+  onComplete: async () => {},
+  onTurn: async ({ turn }) => ({
+    assistantText: `You said: ${turn.text}`
+  }),
+  session: createVoiceMemoryStore(),
+  stt: deepgram({
+    apiKey: process.env.DEEPGRAM_API_KEY!,
+    model: 'flux-general-en'
+  }),
+  tts: elevenlabs({
+    apiKey: process.env.ELEVENLABS_API_KEY!,
+    voiceId: process.env.ELEVENLABS_VOICE_ID!
+  })
+});
+
+await bridge.handleMessage(startMessageFromTwilio);
+await bridge.handleMessage(mediaMessageFromTwilio);
+```
+
+The bridge also sends Twilio `clear` events on new inbound media after assistant audio has started streaming, so telephony barge-in can stop queued outbound playback.
+
+You can benchmark the package-level Twilio bridge path with:
+
+```bash
+bun run bench:telephony:run
+```
+
+That writes:
+- `benchmark-results/telephony-twilio-bridge.json`
+- `benchmark-results/telephony-run-manifest.json`
+
+For a live vendor-backed duplex smoke benchmark on the real TTS adapters, run:
+
+```bash
+bun run bench:duplex:live:run
+```
+
+That writes fresh results to:
+
+For a live vendor-backed telephony smoke benchmark through the Twilio bridge path, run:
+
+```bash
+bun run bench:telephony:live:run
+```
+
+That writes:
+- `benchmark-results/telephony-live-deepgram-elevenlabs.json`
+- `benchmark-results/telephony-live-run-manifest.json`
+
+For a repeated live telephony stability read, run:
+
+```bash
+bun run bench:telephony:live:series
+```
+
+That writes:
+- `benchmark-results/telephony-live-series-summary-runs-3.json`
+
+For a live Deepgram telephony model shootout on the same PSTN path, run:
+
+```bash
+bun run bench:telephony:live:shootout
+```
+
+That writes:
+- `benchmark-results/telephony-live-flux-general-en.json`
+- `benchmark-results/telephony-live-nova-3-phone.json`
+- `benchmark-results/telephony-live-shootout-manifest.json`
+
+- `benchmark-results/duplex-live-elevenlabs.json`
+- `benchmark-results/duplex-live-openai.json`
+- `benchmark-results/duplex-live-all.json`
+- `benchmark-results/duplex-live-run-manifest.json`
+
+For a browser-run duplex benchmark that uses a real headless Chrome `AudioContext` instead of the fake Node-side playback context, run:
+
+```bash
+bun run bench:duplex:browser:run
+```
+
+That writes fresh results to:
+
+- `benchmark-results/duplex-browser-elevenlabs.json`
+- `benchmark-results/duplex-browser-openai.json`
+- `benchmark-results/duplex-browser-all.json`
+- `benchmark-results/duplex-browser-run-manifest.json`
+
+To measure browser duplex stability across repeated runs, use:
+
+```bash
+bun run bench:duplex:browser:series
+```
+
+That writes:
+
+- `benchmark-results/duplex-browser-series-summary-runs-3.json`
+- per-run provider artifacts like `benchmark-results/duplex-browser-elevenlabs-series-run-1.json`
+
+For repeated interrupt-and-resume across several consecutive assistant turns, run:
+
+```bash
+bun run bench:duplex:browser:overlap:run
+```
+
+That writes:
+
+- `benchmark-results/duplex-browser-overlap-elevenlabs.json`
+- `benchmark-results/duplex-browser-overlap-openai.json`
+- `benchmark-results/duplex-browser-overlap-all.json`
+- `benchmark-results/duplex-browser-overlap-run-manifest.json`
+
+To measure overlap stability across repeated live browser runs, use:
+
+```bash
+bun run bench:duplex:browser:overlap:series
+```
+
+That writes:
+
+- `benchmark-results/duplex-browser-overlap-series-summary-runs-3.json`
+- per-run provider artifacts like `benchmark-results/duplex-browser-overlap-elevenlabs-series-run-1.json`
+
+## TTS Benchmarks
+
+`@absolutejs/voice` now includes a first TTS benchmark harness for streaming output adapters. The initial metrics are:
+
+- `firstAudioLatencyMs`
+- `elapsedMs`
+- `audioChunkCount`
+- `totalAudioBytes`
+- estimated PCM `audioDurationMs`
+- interruption responsiveness via `interruptionLatencyMs`
+
+Run the full TTS suite with one command:
+
+```bash
+bun run bench:tts:run
+```
+
+That writes fresh results to:
+
+- `benchmark-results/tts-all.json`
+- `benchmark-results/tts-elevenlabs.json`
+- `benchmark-results/tts-openai.json`
+- `benchmark-results/tts-run-manifest.json`
+
+To measure interruption/cancel responsiveness separately:
+
+```bash
+bun run bench:tts:interrupt:run
+```
+
+That writes fresh interruption results to:
+
+- `benchmark-results/tts-all-interrupt.json`
+- `benchmark-results/tts-elevenlabs-interrupt.json`
+- `benchmark-results/tts-openai-interrupt.json`
+- `benchmark-results/tts-interrupt-run-manifest.json`
+
 ## Recommended Production Path
 
 The current best-performing path in the bundled benchmarks is:
 
 - `deepgram-flux` as primary STT
+- route-level `lexicon` for pronunciation/domain entries
 - route-level `phraseHints`
 - route-level `correctTurn` using `createPhraseHintCorrectionHandler()`
 
@@ -80,7 +906,9 @@ Minimal production-oriented example:
 
 ```ts
 import {
+	createVoiceSTTRoutingCorrectionHandler,
 	createPhraseHintCorrectionHandler,
+	resolveVoiceSTTRoutingStrategy,
 	voice
 } from '@absolutejs/voice';
 import { deepgram } from '@absolutejs/voice-deepgram';
@@ -89,6 +917,13 @@ app.use(
 	voice({
 		path: '/voice/intake',
 		preset: 'reliability',
+		lexicon: [
+			{
+				text: 'AbsoluteJS',
+				aliases: ['absoloot js'],
+				pronunciation: 'ab-so-lute jay ess'
+			}
+		],
 		phraseHints: [
 			{ text: 'AbsoluteJS', aliases: ['absolute js'] },
 			{ text: 'Joe Johnston', aliases: ['joe johnson'] },
@@ -113,6 +948,45 @@ app.use(
 
 `phraseHints` are user-controlled route config, not hidden framework magic. They are there so the app can teach the voice route its domain vocabulary.
 
+## Best Vs Cheap STT
+
+`@absolutejs/voice` now exposes an explicit package-level routing split so apps can choose between the strongest benchmarked path and a cheaper/raw path without inventing their own policy layer.
+
+```ts
+import {
+	createVoiceMemoryStore,
+	createVoiceSTTRoutingCorrectionHandler,
+	resolveVoiceSTTRoutingStrategy,
+	voice
+} from '@absolutejs/voice';
+import { deepgram } from '@absolutejs/voice-deepgram';
+
+const strategy = resolveVoiceSTTRoutingStrategy('best');
+
+app.use(
+	voice({
+		path: '/voice/stt',
+		preset: strategy.preset,
+		phraseHints: [{ text: 'Joe Johnston', aliases: ['joe johnson'] }],
+		correctTurn: createVoiceSTTRoutingCorrectionHandler(strategy.correctionMode),
+		session: createVoiceMemoryStore(),
+		sttLifecycle: strategy.sttLifecycle,
+		stt: deepgram({
+			apiKey: process.env.DEEPGRAM_API_KEY!,
+			model: 'flux-general-en'
+		})
+	})
+);
+```
+
+- `best` maps to the current strongest in-package path: Deepgram Flux plus generic deterministic correction.
+- `low-cost` maps to a cheaper/raw package path: one primary STT pass with no correction hook.
+- session benchmarks now include per-turn cost telemetry fields like `averageRelativeCostUnits`, `averagePrimaryAudioMs`, and `averageFallbackReplayAudioMs`.
+- use `bun run bench:stt:routing:run` to benchmark both in parallel and write fresh:
+  - `benchmark-results/sessions-best-stt-runs-3.json`
+  - `benchmark-results/sessions-cheap-stt-runs-3.json`
+  - `benchmark-results/stt-routing-run-manifest.json`
+
 ## 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.
@@ -161,11 +1035,13 @@ Presets are still overridable. If you need to tune for a specific route, layer `
 Presets are not the same thing as phrase hints:
 
 - presets tune framework-owned behavior like silence windows, reconnect defaults, and audio conditioning
+- `lexicon` tunes pronunciation-aware domain entries that should reach STT/TTS adapters directly
 - `phraseHints` tune app/domain vocabulary like company names, product names, legal phrases, or subscriber-specific jargon
 
 In practice:
 
 - use a preset to choose the runtime shape (`guided-intake`, `reliability`, `noisy-room`)
+- use `lexicon` when pronunciation matters and you want adapter-consumable entries
 - use `phraseHints` to teach the route what words matter for your business
 - use `correctTurn` when you want deterministic post-STT repair before the turn is committed
 
@@ -199,9 +1075,51 @@ The controller helpers abstract the common browser boilerplate:
 
 They do not hide the underlying transport. You still choose the route path and preset explicitly.
 
-## Phrase Hints And Correction
+## Lexicon, Phrase Hints, And Correction
 
-`phraseHints` are a route-level input that the application owns.
+`lexicon` is a route-level input for pronunciation-aware domain entries.
+
+It can be:
+
+- a static array for known names, products, and jargon
+- a resolver function when entries depend on the tenant, subscriber, or scenario
+
+```ts
+voice({
+	path: '/voice/intake',
+	lexicon: async ({ context }) => {
+		return [
+			{
+				text: 'AbsoluteJS',
+				aliases: ['absoloot js'],
+				pronunciation: 'ab-so-lute jay ess'
+			},
+			{
+				text: 'Eden Treaty',
+				aliases: ['eden tree tea'],
+				pronunciation: 'ee-den tree-tee'
+			}
+		];
+	},
+	session: createVoiceMemoryStore(),
+	stt: deepgram({
+		apiKey: process.env.DEEPGRAM_API_KEY!,
+		model: 'flux-general-en'
+	}),
+	onTurn: async ({ turn }) => ({
+		assistantText: turn.text
+	}),
+	onComplete: async () => {}
+});
+```
+
+How the package uses it:
+
+- adapters receive `lexicon` at open time and translate it into vendor-native hinting surfaces when possible
+- STT adapters can use the canonical text plus aliases to bias recognition
+- future TTS adapters can use the same entries for pronunciation-aware speech output
+
+`phraseHints` are a separate route-level input that the application owns.
 
 They can be:
 
@@ -234,6 +1152,7 @@ voice({
 
 How the package uses them:
 
+- adapters receive `lexicon` and `phraseHints` at open time
 - adapters receive `phraseHints` at open time and can translate them into vendor-native hinting surfaces
 - the correction layer can use the same hints after STT to repair domain terms before commit
 
@@ -361,6 +1280,11 @@ Use profiles to focus where you want to win:
 
 - `bun run bench:vs all` (default)
 - `bun run bench:vs all accents`
+- `bun run bench:vs all code-switch`
+- `bun run bench:vs all jargon`
+- `bun run bench:vs all multilingual`
+- `bun run bench:vs all multi-speaker`
+- `bun run bench:vs all telephony`
 - `bun run bench:vs all clean`
 - `bun run bench:vs all noisy`
 - `bun run bench:vs deepgram accents`
@@ -387,6 +1311,21 @@ DEEPGRAM_MODEL=flux-general-en bun run bench:deepgram:accents
 DEEPGRAM_MODEL=nova-3 bun run bench:deepgram:accents
 ```
 
+To stress the STT path with synthesized narrowband phone audio:
+
+```bash
+bun run bench:telephony
+bun run bench:telephony:run
+bun run bench:deepgram:telephony
+bun run bench:deepgram:corrected:telephony
+bun run bench:jargon
+bun run bench:deepgram:jargon
+bun run bench:deepgram:corrected:audit:jargon
+bun run bench:multi-speaker:run
+bun run bench:multi-speaker:analyze
+bun run bench:deepgram:multi-speaker
+```
+
 To compare against Vapi or other providers, provide a baseline JSON file:
 
 ```bash
@@ -427,20 +1366,31 @@ The harness prints:
 - pass rate and recall deltas per adapter
 - weighted scorecard (`passRate`, term recall, word accuracy)
 - optional competitor deltas (Vapi)
+- a markdown report beside the JSON output, for example:
+  - `benchmark-results/vs-all-telephony.json`
+  - `benchmark-results/vs-all-telephony.md`
 
 For package-level multi-turn behavior, use the session benchmark harness instead of raw STT-only benchmarking:
 
 ```bash
 bun run bench:sessions
 bun run bench:deepgram:sessions
+bun run bench:deepgram:soak:sessions
 bun run bench:deepgram:hybrid:sessions
 bun run bench:deepgram:corrected:sessions
+bun run bench:deepgram:corrected:soak:sessions
+bun run bench:stt:routing:run
 bun run bench:assemblyai:sessions
 bun run bench:openai:sessions
+bun run bench:soak:run
 ```
 
 That harness runs the adapter through `VoiceSession` itself, so the output reflects reconnect handling, turn commit stability, and duplicate-turn protection rather than only raw transcript quality.
 
+`bench:soak:run` is the STT-5 runner. It executes the long-session soak lane for raw Deepgram Flux, corrected Deepgram, and the reconnect resilience suite in parallel, then writes fresh JSON into `benchmark-results/` without the runs deleting each other.
+
+`bench:stt:routing:run` is the STT-7 runner. It benchmarks the package’s current `best` vs `low-cost` session strategies in parallel, clears stale outputs first, and writes a manifest so the cost-aware summaries are guaranteed fresh.
+
 `bench:deepgram:corrected:sessions` exercises the current recommended package-level production path:
 
 - Deepgram Flux as primary STT
@@ -568,6 +1518,100 @@ Fallback triggers are evaluated at commit time:
 
 The fallback adapter receives the same window of turn audio as the primary (default `8s`, configurable with `replayWindowMs`) and can only run `maxAttemptsPerTurn` times per turn.
 
+## Benchmark Fixture Sources
+
+Bundled fixtures cover the current in-repo English benchmark suite. For multilingual and code-switch evaluation, add external fixture directories and let the benchmark scripts merge them automatically.
+
+The public corpus builder currently assembles:
+
+- FLEURS multilingual dev clips
+- BSC Catalan-Spanish code-switch evaluation clips
+- CoSHE Hindi-English code-switch evaluation clips
+
+Set either:
+
+- `VOICE_FIXTURE_DIR=/abs/path/to/fixtures`
+- `VOICE_FIXTURE_DIRS=/abs/path/one,/abs/path/two`
+
+Each fixture directory must include:
+
+- `manifest.json`
+- `pcm/*.pcm`
+
+Each manifest entry can include:
+
+- `language`
+- `tags`
+  Use `multilingual`, `bilingual`, or `code-switch` to route fixtures into the multilingual benchmark lane.
+
+Benchmark commands:
+
+```bash
+bun run bench:multilingual
+bun run bench:code-switch
+bun run bench:code-switch:series
+bun run bench:code-switch:ca-es
+bun run bench:code-switch:ca-es:series
+bun run bench:code-switch:ca-es:corts:series
+bun run bench:code-switch:ca-es:parlament:series
+bun run bench:code-switch:hi-en
+bun run bench:code-switch:hi-en:series
+bun run bench:deepgram:multilingual
+bun run bench:deepgram:code-switch
+bun run bench:deepgram:code-switch:series
+bun run bench:deepgram:code-switch:ca-es
+bun run bench:deepgram:code-switch:ca-es:series
+bun run bench:deepgram:code-switch:ca-es:corts:series
+bun run bench:deepgram:code-switch:ca-es:parlament:series
+bun run bench:deepgram:code-switch:ca-es:nova3-multi:series
+bun run bench:deepgram:code-switch:ca-es:nova3-ca:series
+bun run bench:deepgram:code-switch:ca-es:nova3-es:series
+bun run bench:deepgram:code-switch:ca-es:nova2-ca:series
+bun run bench:deepgram:code-switch:ca-es:nova2-es:series
+bun run bench:deepgram:code-switch:ca-es:best:corrected:series
+bun run bench:deepgram:code-switch:ca-es:parlament:debug
+bun run bench:deepgram:code-switch:corrected:ca-es
+bun run bench:deepgram:code-switch:corrected:ca-es:series
+bun run bench:deepgram:code-switch:corrected:ca-es:corts:series
+bun run bench:deepgram:code-switch:corrected:ca-es:parlament:series
+bun run bench:deepgram:code-switch:hi-en
+bun run bench:deepgram:code-switch:hi-en:series
+bun run bench:deepgram:code-switch:corrected:hi-en
+bun run bench:deepgram:code-switch:corrected:hi-en:series
+bun run bench:deepgram:code-switch:corrected
+bun run bench:deepgram:code-switch:corrected:series
+bun run bench:assemblyai:multilingual
+bun run bench:assemblyai:code-switch
+bun run bench:openai:multilingual
+bun run bench:openai:code-switch
+bun run bench:openai:code-switch:series
+bun run bench:openai:code-switch:ca-es
+bun run bench:openai:code-switch:ca-es:series
+bun run bench:openai:code-switch:corrected:ca-es
+bun run bench:openai:code-switch:corrected:ca-es:series
+bun run bench:openai:code-switch:hi-en
+bun run bench:openai:code-switch:hi-en:series
+bun run bench:openai:code-switch:corrected:hi-en
+bun run bench:openai:code-switch:corrected:hi-en:series
+bun run bench:openai:code-switch:corrected
+bun run bench:openai:code-switch:corrected:series
+```
+
+Current benchmark direction:
+
+- `openai` is the strongest adapter on the current public multilingual corpus
+- `deepgram` remains the strongest browser-English path
+- raw code-switch remains a weaker surface for every adapter and should be benchmarked separately with `bench:code-switch`
+- jargon-heavy/domain-heavy English terms now have their own profile; use `bench:jargon` for the cross-adapter read and `bench:deepgram:corrected:audit:jargon` to compare `raw` vs `generic` vs `experimental` vs `benchmarkSeeded`
+- code-switch should be treated as language-pair-specific, not one universal lane; `ca-es` and `hi-en` now have dedicated series commands
+- `ca-es` also has a dedicated Deepgram model/language shootout lane so you can compare `nova-3`/`nova-2` with `multi`, `ca`, and `es` routing without overwriting results
+- current best `ca-es` base path is `deepgram` `nova-3` with `language=ca`; the short runner script uses that path for corrected series
+- `ca-es` is also split by source now: `corts_valencianes` and `parlament_parla` can be benchmarked independently, and `parlament_parla` has a dedicated transcript dump script
+- corrected code-switch runs now have dedicated lexicon-driven series commands so raw and corrected stability can be compared directly
+- multi-speaker diarization is now its own benchmark surface; use `bench:multi-speaker:run` for the parallel cross-adapter plus Deepgram-specific read
+- when tuning diarization specifically, use `bench:multi-speaker:analyze` to split Deepgram into clean vs noisy handoff lanes, include a corrected noisy read, and emit a speaker-pattern debug dump
+- use the `:series` commands when you need stability rather than a single-pass snapshot
+
 ## Client Primitives
 
 Browser and framework helpers sit on top of the same connection core: