@absolutejs/voice 0.0.22-beta.0 → 0.0.22-beta.2

package/README.md

@@ -73,6 +73,635 @@ const app = new Elysia()
 
 `createVoiceMemoryStore()` is dev-only. Real deployments should provide a shared store backed by Redis, Postgres, or equivalent.
 
+## 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(...)`.
+
+```ts
+import {
+	createVoiceAssistant,
+	createVoiceExperiment,
+	createVoiceFileRuntimeStorage,
+	createVoiceMemoryStore,
+	createVoiceAgentTool,
+	voice
+} from '@absolutejs/voice';
+import { deepgram } from '@absolutejs/voice-deepgram';
+
+const runtimeStorage = createVoiceFileRuntimeStorage({
+	directory: '.voice-runtime/support'
+});
+
+const lookupOrder = createVoiceAgentTool({
+	name: 'lookup_order',
+	description: 'Look up an order by id.',
+	execute: async ({ args }) => ({ orderId: args.orderId, status: 'shipped' })
+});
+
+const assistant = createVoiceAssistant({
+	id: 'support',
+	artifactPlan: {
+		ops: {
+			events: runtimeStorage.events,
+			reviews: runtimeStorage.reviews,
+			tasks: runtimeStorage.tasks
+		},
+		preset: {
+			name: 'support-triage',
+			options: {
+				queue: 'support-triage'
+			}
+		}
+	},
+	experiment: createVoiceExperiment({
+		id: 'support-prompt',
+		variants: [
+			{ id: 'baseline', weight: 1 },
+			{
+				id: 'direct',
+				weight: 1,
+				system: 'You are concise, practical, and resolve the caller quickly.'
+			}
+		]
+	}),
+	guardrails: {
+		beforeTurn: ({ turn }) =>
+			turn.text.toLowerCase().includes('human')
+				? { escalate: { reason: 'caller requested a human' } }
+				: undefined
+	},
+	model: {
+		async generate({ messages, tools }) {
+			return {
+				assistantText: `I can help. Available tools: ${tools.map((tool) => tool.name).join(', ')}`
+			};
+		}
+	},
+	system: 'You are a support voice assistant.',
+	tools: [lookupOrder],
+	trace: runtimeStorage.traces
+});
+
+voice({
+	path: '/voice',
+	session: createVoiceMemoryStore(),
+	stt: deepgram({ apiKey: process.env.DEEPGRAM_API_KEY! }),
+	trace: runtimeStorage.traces,
+	ops: assistant.ops,
+	onTurn: assistant.onTurn,
+	onComplete: async () => {}
+});
+```
+
+Assistant experiments are deterministic by session id, so a caller stays on the same variant for a call. Variants can change the model, system prompt, tools, and tool-round budget; guardrails can block a turn before model execution or rewrite the returned `VoiceRouteResult`.
+
+## 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.