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

package/README.md

@@ -55,6 +55,200 @@ These are the primitive-first paths a Vapi-style buyer usually needs. Each path
 | 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.208",
+	"version": "0.0.22-beta.209",
 	"description": "Voice primitives and Elysia plugin for AbsoluteJS",
 	"repository": {
 		"type": "git",