@absolutejs/voice 0.0.22-beta.207 → 0.0.22-beta.209

package/README.md

@@ -27,6 +27,228 @@ Pick the path that matches what you are building:
 - 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.
 
+## Buyer Paths
+
+These are the primitive-first paths a Vapi-style buyer usually needs. Each path stays inside your AbsoluteJS app; the package gives you route handlers, stores, reports, hooks, composables, services, widgets, and contracts instead of a hosted dashboard.
+
+| If you need | Start with | Add proof with | UI entrypoints |
+| --- | --- | --- | --- |
+| Web voice assistant | `voice(...)` or `createVoiceAssistant(...)` | trace timeline, turn quality, live latency, reconnect contract, operations record | React/Vue/Svelte/Angular voice stream helpers, HTML/HTMX/client helpers |
+| Phone voice assistant | `createVoicePhoneAgent(...)` | carrier matrix, setup instructions, phone smoke contract, production readiness, operations record | phone setup HTML/JSON, smoke HTML/JSON, framework status UI |
+| Multi-specialist support flow | `createVoiceAgentSquad(...)` | squad contract, handoff traces, context traces, operations record | Agent Squad status hooks/composables/services/widgets |
+| Business actions and tools | `createVoiceAgentTool(...)` plus agent tool runtime | tool contracts, audit events, integration events, outcome contracts | operations record, action center, contract routes |
+| Provider routing and fallback | provider routers, health checks, simulation controls | provider contract matrix, provider-stage traces, latency SLO reports | provider contract hooks/composables/services/widgets |
+| Production operations | ops status, ops recovery, production readiness, delivery runtime | readiness gates, recovery report, incident Markdown, delivery queues | ops action center, delivery runtime UI, operations record |
+| Outbound campaigns | `createVoiceCampaignRoutes(...)` | recipient validation, consent/dedupe, carrier dry-run, campaign readiness | campaign routes and operations-record-linked attempt proof |
+| Simulation before launch | `createVoiceSimulationSuiteRoutes(...)` | scenarios, evals, tool contracts, outcome contracts, baselines | simulation-suite HTML/JSON and linked operations records |
+| Compliance controls | runtime storage, audit logger, data-control routes | retention dry-run, redacted audit export, zero-retention policy, deploy gate | data-control HTML/JSON and audit/export routes |
+
+## Capability Matrix
+
+| Surface | Core package | Example/demo role | Not our lane |
+| --- | --- | --- | --- |
+| Browser voice | WebSocket voice route, client stream/controller/store primitives, reconnect, barge-in, latency, framework helpers | Prove the same mic/transcript/status workflow across React, Vue, Svelte, Angular, HTML, and HTMX | Hosted iframe widget that owns app UX |
+| Telephony | Twilio, Telnyx, Plivo route bridges, phone-agent wrapper, setup instructions, smoke contracts, carrier outcomes | Show setup/smoke/proof surfaces and call lifecycle debugging | Buying/provisioning phone numbers for the user |
+| Agents and tools | assistant, agent, tools, squads, handoff/context policies, contracts, audit hooks | Demonstrate realistic support/sales/workflow flows | Dashboard-only visual bot builder |
+| Provider layer | OpenAI/Anthropic/Gemini model paths, STT/TTS adapter seams, routing, fallback, health, simulation | Show provider switching and health in UI | Reselling provider minutes or hiding provider accounts |
+| Observability | traces, timelines, replay, operations records, incident Markdown, ops recovery, readiness | Make every failing proof link to a call/session record | Vendor dashboard as source of truth |
+| Evals and simulation | fixtures, eval routes, simulation suite, workflow/tool/outcome contracts, baselines | Prove flows before live traffic | Opaque hosted test runner |
+| Data and compliance controls | file/SQLite/Postgres/S3 storage paths, redaction, retention, audit exports, guarded deletion | Show customer-owned storage and export proof | Legal certification or compliance attestation |
+
+## Use-Case Recipe: Support Triage
+
+Use this path when you want a Vapi-style support assistant that can answer web or phone calls, look up customer context, route billing issues to a specialist, create follow-up work, and leave one debuggable call record. It is a recipe over primitives, not a support app kit.
+
+The production shape is:
+
+1. Persist sessions, traces, reviews, tasks, integration events, and audit events in app-owned runtime storage.
+2. Define server-side tools with idempotency and contract proof.
+3. Compose support and billing specialists with `createVoiceAgentSquad(...)`.
+4. Mount a browser route with `voice(...)` and optionally a phone route with `createVoicePhoneAgent(...)`.
+5. Add outcome, readiness, simulation, audit, and operations-record routes so every failed proof links back to the call.
+
+```ts
+import { Elysia } from 'elysia';
+import {
+	createVoiceAgent,
+	createVoiceAgentSquad,
+	createVoiceAgentTool,
+	createVoiceFileRuntimeStorage,
+	createVoiceOperationsRecordRoutes,
+	createVoiceProductionReadinessRoutes,
+	createVoiceSimulationSuiteRoutes,
+	createVoiceToolContractRoutes,
+	createVoiceToolRuntimeContractDefaults,
+	resolveVoiceOutcomeRecipe,
+	voice
+} from '@absolutejs/voice';
+import { deepgram } from '@absolutejs/voice-deepgram';
+
+const runtime = createVoiceFileRuntimeStorage({
+	directory: '.voice-runtime/support-triage'
+});
+
+const lookupCustomer = createVoiceAgentTool({
+	name: 'lookup_customer',
+	description: 'Look up a customer and their open support state.',
+	parameters: {
+		type: 'object',
+		properties: {
+			customerId: { type: 'string' }
+		},
+		required: ['customerId']
+	},
+	execute: async ({ args }) => ({
+		customerId: args.customerId,
+		plan: 'business',
+		openTickets: 1,
+		status: 'active'
+	})
+});
+
+const support = createVoiceAgent({
+	id: 'support',
+	system: 'Triage the caller, use tools for account context, and hand billing questions to billing.',
+	tools: [lookupCustomer],
+	trace: runtime.traces,
+	model: {
+		async generate({ messages, tools }) {
+			const latest = messages.at(-1)?.content.toLowerCase() ?? '';
+			if (latest.includes('billing')) {
+				return {
+					assistantText: 'I am routing you to billing with the context so far.',
+					handoff: { reason: 'billing-request', targetAgentId: 'billing' }
+				};
+			}
+
+			return {
+				assistantText: `I can help with that. I can also use ${tools.map((tool) => tool.name).join(', ')} when I need account context.`
+			};
+		}
+	}
+});
+
+const billing = createVoiceAgent({
+	id: 'billing',
+	system: 'Handle billing questions and escalate refund or cancellation risk.',
+	trace: runtime.traces,
+	model: {
+		async generate() {
+			return {
+				assistantText: 'I can help with billing. I have the handoff context from support.'
+			};
+		}
+	}
+});
+
+const supportDesk = createVoiceAgentSquad({
+	id: 'support-desk',
+	defaultAgentId: 'support',
+	agents: [support, billing],
+	trace: runtime.traces,
+	handoffPolicy: ({ handoff }) =>
+		handoff.targetAgentId === 'billing'
+			? {
+					summary: 'Billing specialist receives the support summary and current caller intent.',
+					metadata: { queue: 'billing' }
+				}
+			: {
+					allow: false,
+					reason: 'Only billing handoffs are approved in this recipe.',
+					escalate: { reason: 'unsupported-specialist' }
+				}
+});
+
+const toolContractDefinitions = [
+	{
+		id: 'lookup-customer-contract',
+		label: 'Lookup customer returns support state',
+		tool: lookupCustomer,
+		cases: [
+			{
+				id: 'active-business-customer',
+				args: { customerId: 'cus_123' },
+				expect: {
+					expectedResult: {
+						customerId: 'cus_123',
+						openTickets: 1,
+						plan: 'business',
+						status: 'active'
+					},
+					expectStatus: 'ok'
+				}
+			}
+		],
+		defaultRuntime: createVoiceToolRuntimeContractDefaults()
+	}
+];
+
+const app = new Elysia()
+	.use(
+		voice({
+			path: '/voice/support',
+			preset: 'reliability',
+			session: runtime.session,
+			stt: deepgram({
+				apiKey: process.env.DEEPGRAM_API_KEY!,
+				model: 'flux-general-en'
+			}),
+			trace: runtime.traces,
+			onTurn: supportDesk.onTurn,
+			onComplete: async () => {},
+			ops: {
+				...resolveVoiceOutcomeRecipe('support-triage', {
+					assignee: 'support-oncall',
+					queue: 'support-triage'
+				}),
+				events: runtime.events,
+				reviews: runtime.reviews,
+				tasks: runtime.tasks
+			}
+		})
+	)
+	.use(
+		createVoiceToolContractRoutes({
+			contracts: toolContractDefinitions,
+			htmlPath: '/voice/support/tool-contracts',
+			path: '/api/voice/support/tool-contracts'
+		})
+	)
+	.use(
+		createVoiceSimulationSuiteRoutes({
+			htmlPath: '/voice/support/simulations',
+			path: '/api/voice/support/simulations',
+			tools: toolContractDefinitions,
+			operationsRecordHref: '/voice-operations/:sessionId'
+		})
+	)
+	.use(
+		createVoiceOperationsRecordRoutes({
+			htmlPath: '/voice-operations/:sessionId',
+			path: '/api/voice-operations/:sessionId',
+			store: runtime.traces,
+			reviews: runtime.reviews,
+			tasks: runtime.tasks,
+			integrationEvents: runtime.events
+		})
+	)
+	.use(
+		createVoiceProductionReadinessRoutes({
+			htmlPath: '/production-readiness',
+			path: '/api/production-readiness',
+			store: runtime.traces,
+			links: {
+				operationsRecords: '/voice-operations/:sessionId',
+				simulations: '/voice/support/simulations'
+			}
+		})
+	);
+```
+
+The demo UI should show a mic button, transcript, current specialist badge, readiness link, simulation link, and operations-record link. Use the framework helpers for that surface instead of embedding a dashboard: `VoiceAgentSquadStatus` in React, `useVoiceAgentSquadStatus(...)` in Vue, `createVoiceAgentSquadStatus(...)` in Svelte, `VoiceAgentSquadStatusService` in Angular, or `<absolute-voice-agent-squad-status>` for HTML/HTMX.
+
+This recipe covers the hosted-platform expectations that matter for support triage: assistant entrypoint, business tools, specialist handoff, post-call task creation, simulation proof, tool contract proof, production readiness, audit-compatible runtime storage, and a call-log replacement at `/voice-operations/:sessionId`.
+
 ## 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.

package/package.json

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