@absolutejs/voice 0.0.22-beta.204 → 0.0.22-beta.205

package/README.md

@@ -41,6 +41,51 @@ AbsoluteJS Voice is strongest when voice is part of your own product and you nee
 
 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.
 
+## Default Debug Path
+
+Hosted platforms usually make the call log the center of debugging. AbsoluteJS Voice makes the operations record that center, while keeping the data and routes inside your app.
+
+Mount `createVoiceOperationsRecordRoutes(...)` early in any serious voice app and use `/voice-operations/:sessionId` as the first support link for failed calls, bad transcripts, provider fallback, slow turns, handoff failures, campaign attempts, and post-call workflow issues.
+
+The recommended investigation path is:
+
+1. Open `/production-readiness`, `/ops-recovery`, `/voice/simulations`, a tool contract report, or an outcome contract report.
+2. Follow the linked `/voice-operations/:sessionId` record for the impacted call or session.
+3. Inspect the transcript, trace timeline, replay links, provider decisions, tool calls, handoffs, reviews, tasks, audit events, integration events, and sink delivery attempts from one page.
+4. Use `/voice-operations/:sessionId/incident.md` when support, engineering, or a customer-facing handoff needs copyable incident context.
+
+That is the Vapi-style call-log workflow without a vendor dashboard becoming the source of truth.
+
+## Switching From Vapi
+
+If a team is already evaluating Vapi, map the dashboard concepts to AbsoluteJS primitives this way:
+
+| Hosted voice-platform concept | AbsoluteJS Voice primitive |
+| --- | --- |
+| Assistant | `createVoiceAssistant(...)`, `createVoiceAgent(...)`, or `voice({ onTurn })` |
+| Web call | `voice(...)` plus React, Vue, Svelte, Angular, HTML, HTMX, or client helpers |
+| Phone call | `createVoicePhoneAgent(...)` with Twilio, Telnyx, or Plivo routes |
+| Squads / multi-assistant routing | `createVoiceAgentSquad(...)` with `handoffPolicy`, `contextPolicy`, specialist tools, traces, and squad contracts |
+| Tools / functions | Agent tools, tool runtime, `runVoiceToolContract(...)`, audit events, and integration events |
+| Call logs | `/voice-operations/:sessionId`, trace timelines, replay links, reviews, tasks, audit, provider decisions, and delivery queues |
+| Post-call analysis | reviews, outcomes, ops tasks, handoff deliveries, integration events, webhook/audit sinks, and outcome contracts |
+| Simulation testing | `createVoiceSimulationSuiteRoutes(...)` with scenarios, fixtures, tool contracts, outcome contracts, and baseline comparison |
+| Production monitoring | `createVoiceProductionReadinessRoutes(...)`, `createVoiceOpsRecoveryRoutes(...)`, ops status, latency SLO gates, provider health, and delivery runtime proof |
+| Campaigns | `createVoiceCampaignRoutes(...)`, recipient import, scheduling controls, carrier dialer proof, and campaign readiness |
+| Compliance controls | self-hosted storage, redaction defaults, retention plans, audit exports, data-control routes, and provider-key ownership |
+
+The practical difference is ownership. In Vapi-style systems, the assistant, call log, tool execution, and operational dashboard live primarily in the vendor platform. With AbsoluteJS Voice, those same surfaces are route handlers, stores, reports, hooks, and contracts inside the AbsoluteJS app.
+
+Use `createVoiceAssistant(...)` when you want a product-level assistant surface with tools, guardrails, experiments, tracing, reviews, tasks, and ops recipes. Drop down to `createVoiceAgent(...)` when you want a provider-neutral model/tool loop. Use raw `voice({ onTurn })` when you want the smallest possible browser voice route.
+
+Use `createVoiceAgentSquad(...)` for Vapi Squads-style specialist routing without moving routing policy into a hosted dashboard. Each specialist owns its tools, `handoffPolicy` decides whether to allow, reroute, block, or escalate transfers, and `contextPolicy` decides what conversation context the next specialist receives. Squad traces and contracts make the handoff graph testable before production.
+
+Use `createVoicePhoneAgent(...)` when the hosted-platform feature you need is "call this assistant by phone." The wrapper mounts carrier routes, setup pages, carrier matrix proof, and smoke-contract routes while still letting your app own Twilio, Telnyx, or Plivo credentials, webhooks, stream URLs, traces, and lifecycle outcomes.
+
+Use operations records instead of hosted call logs. A proof failure should link to `/voice-operations/:sessionId`; the record then links the transcript, replay, provider choices, tool calls, handoffs, audit events, reviews, tasks, integration events, and delivery attempts. When someone needs a support handoff, send `/voice-operations/:sessionId/incident.md`.
+
+Use simulation and contracts before live traffic. The simulation suite, tool contracts, outcome contracts, provider routing contracts, phone-agent smoke contracts, and production-readiness gates turn dashboard-only confidence into code-owned deploy evidence.
+
 ## Install
 
 ```bash
@@ -65,6 +110,178 @@ Common optional adapters:
 - `@absolutejs/voice-deepgram`
 - `@absolutejs/voice-assemblyai`
 
+## Fastest First Success
+
+Use these paths when you want the smallest useful setup that still proves the app is production-shaped. The point is not to hide primitives; it is to mount the voice route plus the debug surfaces a real team needs immediately.
+
+### Browser Agent In 10 Minutes
+
+```ts
+import { Elysia } from 'elysia';
+import {
+	createVoiceFileRuntimeStorage,
+	createVoiceOperationsRecordRoutes,
+	createVoiceOpsStatusRoutes,
+	createVoiceProductionReadinessRoutes,
+	createVoiceTraceTimelineRoutes,
+	voice
+} from '@absolutejs/voice';
+import { deepgram } from '@absolutejs/voice-deepgram';
+
+const runtime = createVoiceFileRuntimeStorage({
+	directory: '.voice-runtime/support'
+});
+
+export const app = new Elysia()
+	.use(
+		voice({
+			path: '/voice',
+			session: runtime.session,
+			trace: runtime.traces,
+			stt: deepgram({ apiKey: process.env.DEEPGRAM_API_KEY! }),
+			async onTurn({ turn }) {
+				return { assistantText: `I heard: ${turn.text}` };
+			},
+			onComplete: async () => {}
+		})
+	)
+	.use(
+		createVoiceOpsStatusRoutes({
+			path: '/api/voice/ops-status',
+			store: runtime.traces,
+			sttProviders: ['deepgram']
+		})
+	)
+	.use(
+		createVoiceTraceTimelineRoutes({
+			htmlPath: '/traces',
+			path: '/api/voice-traces',
+			store: runtime.traces
+		})
+	)
+	.use(
+		createVoiceOperationsRecordRoutes({
+			audit: runtime.audit,
+			htmlPath: '/voice-operations/:sessionId',
+			path: '/api/voice-operations/:sessionId',
+			store: runtime.traces
+		})
+	)
+	.use(
+		createVoiceProductionReadinessRoutes({
+			links: {
+				operationsRecords: '/voice-operations/:sessionId'
+			},
+			path: '/api/production-readiness',
+			htmlPath: '/production-readiness',
+			store: runtime.traces
+		})
+	);
+```
+
+After one browser call, open:
+
+- `/api/voice/ops-status`: compact health signal for UI/widgets.
+- `/traces`: trace timeline by session.
+- `/voice-operations/:sessionId`: call-log/debug record for the session.
+- `/voice-operations/:sessionId/incident.md`: copyable incident handoff.
+- `/production-readiness`: deploy gate summary.
+
+### Phone Agent In 20 Minutes
+
+```ts
+import { Elysia } from 'elysia';
+import {
+	createVoiceFileRuntimeStorage,
+	createVoiceOperationsRecordRoutes,
+	createVoicePhoneAgent,
+	createVoiceProductionReadinessRoutes,
+	createVoiceReadinessProfile,
+	createVoiceTelephonyOutcomePolicy
+} from '@absolutejs/voice';
+import { deepgram } from '@absolutejs/voice-deepgram';
+
+const runtime = createVoiceFileRuntimeStorage({
+	directory: '.voice-runtime/support'
+});
+const outcomePolicy = createVoiceTelephonyOutcomePolicy({
+	transferTarget: process.env.VOICE_TRANSFER_TARGET
+});
+
+export const app = new Elysia()
+	.use(
+		createVoicePhoneAgent({
+			setup: { path: '/api/voice/phone/setup' },
+			matrix: { path: '/api/carriers' },
+			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
+	)
+	.use(
+		createVoiceOperationsRecordRoutes({
+			audit: runtime.audit,
+			htmlPath: '/voice-operations/:sessionId',
+			path: '/api/voice-operations/:sessionId',
+			store: runtime.traces
+		})
+	)
+	.use(
+		createVoiceProductionReadinessRoutes({
+			...createVoiceReadinessProfile('phone-agent', {
+				explain: true
+			}),
+			links: {
+				operationsRecords: '/voice-operations/:sessionId'
+			},
+			path: '/api/production-readiness',
+			htmlPath: '/production-readiness',
+			store: runtime.traces
+		})
+	);
+```
+
+Open `/api/voice/phone/setup?format=html`, copy the reported Twilio URLs into the carrier dashboard, run one smoke call, then inspect:
+
+- `/api/carriers?format=html`: carrier setup matrix.
+- `/voice/phone/smoke-contract?sessionId=...`: trace-backed phone smoke proof.
+- `/voice-operations/:sessionId`: call-log/debug record.
+- `/production-readiness`: phone-agent readiness gate.
+
 ## Browser Voice Agent
 
 ```ts
@@ -208,6 +425,8 @@ Recommended proof routes:
 - `/api/voice/ops-status/html`: HTML status card for quick internal review.
 - `/demo-ready`: customer-facing demo readiness checklist.
 - `/production-readiness`: production gate summary.
+- `/voice-operations/:sessionId`: default call-log/debug record for one problematic session.
+- `/voice-operations/:sessionId/incident.md`: copyable incident handoff for support and engineering.
 - `/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.
@@ -906,6 +1125,119 @@ For HTML or HTMX pages:
 </script>
 ```
 
+## Live Operator Workflows
+
+Use live-ops primitives when an operator needs to intervene during an active session without taking voice orchestration out of your app. The supported actions are:
+
+- `pause-assistant`: keep committing caller turns, but skip assistant generation.
+- `resume-assistant`: let automation continue.
+- `operator-takeover`: keep the session open while a human handles the caller.
+- `inject-instruction`: add an operator instruction to the next assistant turn.
+- `force-handoff`: mark the session for a specific handoff target.
+- `escalate`, `assign`, `tag`, and `create-task`: record operational intent and make it auditable.
+
+Mount the live-ops control routes beside your voice route:
+
+```ts
+import {
+	createVoiceLiveOpsRoutes,
+	createVoiceMemoryLiveOpsControlStore,
+	voice
+} from '@absolutejs/voice';
+import { deepgram } from '@absolutejs/voice-deepgram';
+
+const liveOps = createVoiceMemoryLiveOpsControlStore();
+
+app
+	.use(
+		createVoiceLiveOpsRoutes({
+			audit: runtimeStorage.audit,
+			store: liveOps,
+			trace: runtimeStorage.traces
+		})
+	)
+	.use(
+		voice({
+			path: '/voice',
+			liveOps: {
+				getControl: (sessionId) => liveOps.get(sessionId)
+			},
+			session: runtimeStorage.session,
+			stt: deepgram({ apiKey: process.env.DEEPGRAM_API_KEY! }),
+			async onTurn({ turn }) {
+				return { assistantText: `I heard: ${turn.text}` };
+			},
+			onComplete: async () => {}
+		})
+	);
+```
+
+The default route accepts `POST /api/voice/live-ops/action`:
+
+```ts
+await fetch('/api/voice/live-ops/action', {
+	body: JSON.stringify({
+		action: 'pause-assistant',
+		assignee: 'operator-123',
+		detail: 'Caller is upset; pause automation while support reviews.',
+		sessionId: 'session-123',
+		tag: 'priority-support'
+	}),
+	headers: { 'content-type': 'application/json' },
+	method: 'POST'
+});
+```
+
+Every action updates the control store and can write both `operator.action` audit events and `operator.action` trace events. The voice runtime checks the control state before assistant generation. When `assistantPaused` or `operatorTakeover` is active, it commits the user transcript, records a skipped-turn trace, and does not call the assistant. When `injectedInstruction` is present, the next assistant turn receives that instruction.
+
+The safe operator runbook is:
+
+1. Open the session's operations record or trace timeline before intervening.
+2. Use `pause-assistant` when the bot should stop responding but the transcript should continue.
+3. Use `inject-instruction` when the bot should continue with human guidance, such as "apologize and offer transfer."
+4. Use `operator-takeover` when a human is now handling the caller and automation must stay silent.
+5. Use `force-handoff` or `escalate` when the session needs a specialist, supervisor, or external queue.
+6. Use `resume-assistant` only after the operator has verified the session state and any handoff context.
+7. Review `/api/voice/live-ops/control/:sessionId`, `/voice-operations/:sessionId`, `/api/voice/ops-actions/history`, or `/audit` when you need proof of who intervened and why.
+
+Framework and HTML clients can run the same actions without a custom dashboard:
+
+```tsx
+import { useVoiceLiveOps } from '@absolutejs/voice/react';
+
+export function LiveOperatorPanel({ sessionId }: { sessionId: string }) {
+	const liveOps = useVoiceLiveOps();
+
+	return (
+		<button
+			onClick={() =>
+				liveOps.run({
+					action: 'operator-takeover',
+					assignee: 'operator-123',
+					detail: 'Human support took over the call.',
+					sessionId,
+					tag: 'human-takeover'
+				})
+			}
+		>
+			Take over
+		</button>
+	);
+}
+```
+
+For HTML or HTMX pages:
+
+```html
+<absolute-voice-live-ops session-id="session-123"></absolute-voice-live-ops>
+<script type="module">
+	import { defineVoiceLiveOpsElement } from '@absolutejs/voice/client';
+	defineVoiceLiveOpsElement();
+</script>
+```
+
+Live-ops is intentionally a primitive layer: the package records controls, audit evidence, and trace evidence, while your app decides which operators are allowed to run actions and how those controls appear in the product UI.
+
 ## 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(...)`.
@@ -1092,6 +1424,44 @@ Pass `contextPolicy` when a specialist should receive a controlled context windo
 
 Each specialist owns its own `tools`, so tool permissions stay explicit per agent. For example, support can have `lookup_order`, billing can have `refund_invoice`, and scheduling can have `book_appointment`. The squad only routes; it does not give every specialist every tool by default.
 
+Make the current specialist visible in your UI by mounting trace timelines and using the squad status primitives. They derive current specialist state from `agent.handoff`, `agent.context`, `agent.model`, and `agent.result` traces, so the UI stays tied to the same proof source used by readiness and operations records.
+
+```tsx
+import { VoiceAgentSquadStatus } from '@absolutejs/voice/react';
+
+export function SpecialistBadge({ sessionId }: { sessionId: string }) {
+	return (
+		<VoiceAgentSquadStatus
+			path="/api/voice-traces"
+			sessionId={sessionId}
+			title="Current specialist"
+		/>
+	);
+}
+```
+
+Framework equivalents are available without a dashboard:
+
+```ts
+import { useVoiceAgentSquadStatus } from '@absolutejs/voice/vue';
+import { createVoiceAgentSquadStatus } from '@absolutejs/voice/svelte';
+import { VoiceAgentSquadStatusService } from '@absolutejs/voice/angular';
+```
+
+For HTML or HTMX pages:
+
+```html
+<absolute-voice-agent-squad-status
+	path="/api/voice-traces"
+	session-id="session-123"
+	title="Current specialist"
+></absolute-voice-agent-squad-status>
+<script type="module">
+	import { defineVoiceAgentSquadStatusElement } from '@absolutejs/voice/client';
+	defineVoiceAgentSquadStatusElement();
+</script>
+```
+
 Use `runVoiceAgentSquadContract(...)` in tests or readiness checks when you need proof that a specialist graph still routes correctly:
 
 ```ts
@@ -1380,6 +1750,10 @@ app.use(
 
 `createVoiceOperationsRecordRoutes(...)` links the call/session timeline, transcript, replay, provider decisions, tools, handoffs, audit, reviews, ops tasks, integration events, and sink delivery attempts into one debuggable object. Use `/voice-operations/:sessionId` as the first place to investigate failed calls, provider failures, handoff failures, slow turns, and campaign attempts. The same mount also exposes incident handoff Markdown at `/voice-operations/:sessionId/incident.md` and `/api/voice-operations/:sessionId/incident.md` for support tooling.
 
+Most proof surfaces can link to the same record by passing an operations-record URL template such as `/voice-operations/:sessionId`. Use that template anywhere a report emits session-level failures: production readiness, ops recovery, trace timelines, session lists, reviews, campaign attempts, eval reports, simulation-suite actions, tool-contract cases, and outcome-contract matched sessions. The goal is that no operator has to guess which trace, review, task, or delivery queue belongs to the failing call.
+
+If a customer asks for "the call log," send the operations-record URL. If engineering needs reproducible context, send the incident Markdown URL. If a deploy gate fails, start at readiness or ops recovery and follow the linked operations record instead of searching storage manually.
+
 Mount `createVoiceOpsRecoveryRoutes(...)` beside it when operators need one deploy-checkable recovery signal:
 
 ```ts

package/dist/angular/index.d.ts

@@ -10,6 +10,7 @@ export { VoiceProviderContractsService } from './voice-provider-contracts.servic
 export { VoiceProviderStatusService } from './voice-provider-status.service';
 export { VoiceRoutingStatusService } from './voice-routing-status.service';
 export { VoiceTraceTimelineService } from './voice-trace-timeline.service';
+export { VoiceAgentSquadStatusService } from './voice-agent-squad-status.service';
 export { VoiceTurnLatencyService } from './voice-turn-latency.service';
 export { VoiceTurnQualityService } from './voice-turn-quality.service';
 export { VoiceWorkflowStatusService } from './voice-workflow-status.service';