@absolutejs/voice 0.0.22-beta.121 → 0.0.22-beta.123

package/README.md

@@ -224,9 +224,9 @@ app.use(
 
 The suite rolls up session quality, scenario evals, fixture simulations, tool contracts, and outcome contracts into one pass/fail report. It is the code-owned equivalent of "test this voice flow before production" without requiring a hosted voice-agent dashboard.
 
-## Phone Voice Agent Path
+## Phone Voice Agent In 20 Minutes
 
-Use the telephony primitives when the agent needs to answer or place calls through your own carrier account:
+Use `createVoicePhoneAgent(...)` when the agent needs to answer or place calls through your own Twilio, Telnyx, or Plivo account. This is the self-hosted alternative to a hosted phone-agent dashboard: your app owns the carrier routes, stream URLs, webhooks, traces, readiness checks, and lifecycle outcomes.
 
 ```ts
 import {
@@ -242,6 +242,10 @@ const outcomePolicy = createVoiceTelephonyOutcomePolicy({
 app
 	.use(
 		createVoicePhoneAgent({
+			setup: {
+				path: '/api/voice/phone/setup',
+				title: 'Support Phone Agent'
+			},
 			matrix: {
 				path: '/api/carriers',
 				title: 'AbsoluteJS Voice Carrier Matrix'
@@ -274,7 +278,42 @@ app
 	);
 ```
 
-The wrapper mounts selected carrier routes and a readiness matrix. Telnyx and Plivo use the same wrapper with `{ provider: 'telnyx', options: ... }` or `{ provider: 'plivo', options: ... }`. The lower-level `createTwilioVoiceRoutes(...)`, `createTelnyxVoiceRoutes(...)`, and `createPlivoVoiceRoutes(...)` helpers remain available when you need carrier-specific control.
+The wrapper mounts selected carrier routes plus two proof surfaces:
+
+- `/api/voice/phone/setup`: one setup report with carrier URLs, smoke links, lifecycle stages, and readiness.
+- `/api/voice/phone/setup?format=html`: copy/paste setup page for carrier dashboards.
+- `/api/carriers`: carrier matrix JSON for Twilio, Telnyx, and Plivo.
+- `/api/carriers?format=html`: side-by-side carrier readiness matrix.
+
+The setup page tells you exactly what to copy into the carrier dashboard:
+
+- Twilio: set the phone number voice webhook/TwiML URL to the reported TwiML URL, set the status callback to the reported webhook URL, and allow the reported `wss://` media stream.
+- Telnyx: set the connection TeXML URL to the reported TeXML URL, set the status webhook to the reported webhook URL, and allow the reported `wss://` media stream.
+- Plivo: set the answer URL to the reported answer URL, set the status callback to the reported webhook URL, and allow the reported `wss://` media stream.
+
+Each configured carrier can also expose its own setup and smoke pages, for example:
+
+- `/api/voice/twilio/setup?format=html`
+- `/api/voice/twilio/smoke?format=html`
+- `/api/voice/telnyx/setup?format=html`
+- `/api/voice/telnyx/smoke?format=html`
+- `/api/voice/plivo/setup?format=html`
+- `/api/voice/plivo/smoke?format=html`
+
+The phone-agent report normalizes the lifecycle schema across carriers:
+
+- `ringing`
+- `answered`
+- `media-started`
+- `transcript`
+- `assistant-response`
+- `transfer`
+- `voicemail`
+- `no-answer`
+- `completed`
+- `failed`
+
+That is the important Vapi/Retell/Bland gap this primitive closes: a team can mount one phone-agent entrypoint, bring its own carrier account, verify readiness before live calls, and keep call traces and lifecycle outcomes inside its own AbsoluteJS app. Telnyx and Plivo use the same wrapper with `{ provider: 'telnyx', options: ... }` or `{ provider: 'plivo', options: ... }`. The lower-level `createTwilioVoiceRoutes(...)`, `createTelnyxVoiceRoutes(...)`, and `createPlivoVoiceRoutes(...)` helpers remain available when you need carrier-specific control.
 
 ## App Kit And Status Widgets
 
@@ -524,7 +563,21 @@ const billingAgent = createVoiceAgent({
 const frontDesk = createVoiceAgentSquad({
 	id: 'front-desk',
 	defaultAgentId: 'support',
-	agents: [supportAgent, billingAgent]
+	agents: [supportAgent, billingAgent],
+	handoffPolicy: ({ handoff }) => {
+		if (handoff.targetAgentId === 'billing') {
+			return {
+				summary: 'Route verified billing requests to the billing specialist.',
+				metadata: { queue: 'billing' }
+			};
+		}
+
+		return {
+			allow: false,
+			reason: `No approved route for ${handoff.targetAgentId}.`,
+			escalate: { reason: 'unsupported-specialist' }
+		};
+	}
 });
 
 voice({
@@ -538,6 +591,8 @@ voice({
 
 `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`.
 
+For production call centers, pass `handoffPolicy` to keep routing code-owned instead of dashboard-owned. The policy can allow a handoff, reroute it to a different specialist, merge handoff metadata, summarize the reason for the target agent, or block the handoff and return an escalation. Squad traces mark each handoff as `allowed`, `blocked`, `unknown-target`, or `max-exceeded`, so support teams can audit why a caller moved between specialists.
+
 ## 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.

package/dist/agent.d.ts

@@ -66,6 +66,14 @@ export type VoiceAgentRunResult<TResult = unknown> = VoiceRouteResult<TResult> &
     messages: VoiceAgentMessage[];
     toolResults: VoiceAgentToolResult[];
 };
+export type VoiceAgentSquadHandoffPolicyResult<TResult = unknown> = {
+    allow?: boolean;
+    escalate?: VoiceRouteResult<TResult>['escalate'];
+    metadata?: Record<string, unknown>;
+    reason?: string;
+    summary?: string;
+    targetAgentId?: string;
+};
 export type VoiceAgent<TContext = unknown, TSession extends VoiceSessionRecord = VoiceSessionRecord, TResult = unknown> = {
     id: string;
     onTurn: VoiceOnTurnObjectHandler<TContext, TSession, TResult>;
@@ -93,6 +101,15 @@ export type VoiceAgentOptions<TContext = unknown, TSession extends VoiceSessionR
 export type VoiceAgentSquadOptions<TContext = unknown, TSession extends VoiceSessionRecord = VoiceSessionRecord, TResult = unknown> = {
     agents: Array<VoiceAgent<TContext, TSession, TResult>>;
     defaultAgentId: string;
+    handoffPolicy?: (input: {
+        context: TContext;
+        fromAgentId: string;
+        handoff: NonNullable<VoiceAgentModelOutput<TResult>['handoff']>;
+        messages: VoiceAgentMessage[];
+        session: TSession;
+        targetAgent?: VoiceAgent<TContext, TSession, TResult>;
+        turn: VoiceTurnRecord;
+    }) => Promise<VoiceAgentSquadHandoffPolicyResult<TResult> | void> | VoiceAgentSquadHandoffPolicyResult<TResult> | void;
     id: string;
     maxHandoffsPerTurn?: number;
     onHandoff?: (input: {

package/dist/index.d.ts

@@ -81,7 +81,7 @@ export type { VoiceProductionReadinessAction, VoiceProductionReadinessCheck, Voi
 export type { VoiceQualityLink, VoiceQualityMetric, VoiceQualityReport, VoiceQualityRoutesOptions, VoiceQualityStatus, VoiceQualityThresholds } from './qualityRoutes';
 export type { VoiceResilienceIOSimulator, VoiceResilienceLink, VoiceResiliencePageData, VoiceResilienceRoutesOptions, VoiceResilienceSimulationProvider, VoiceRoutingKindSummary, VoiceRoutingDecisionSummary, VoiceRoutingDecisionSummaryOptions, VoiceRoutingEvent, VoiceRoutingEventKind, VoiceRoutingSessionSummary, VoiceRoutingSessionSummaryOptions } from './resilienceRoutes';
 export type { VoiceIOProviderRouterEvent, VoiceIOProviderRouterOptions, VoiceIOProviderRouterPolicy, VoiceIOProviderRouterPolicyConfig, VoiceSTTProviderRouterOptions, VoiceTTSProviderRouterOptions } from './providerAdapters';
-export type { VoiceAgent, VoiceAgentMessage, VoiceAgentMessageRole, VoiceAgentModel, VoiceAgentModelInput, VoiceAgentModelOutput, VoiceAgentOptions, VoiceAgentRunResult, VoiceAgentSquadOptions, VoiceAgentTool, VoiceAgentToolCall, VoiceAgentToolResult } from './agent';
+export type { VoiceAgent, VoiceAgentMessage, VoiceAgentMessageRole, VoiceAgentModel, VoiceAgentModelInput, VoiceAgentModelOutput, VoiceAgentOptions, VoiceAgentRunResult, VoiceAgentSquadHandoffPolicyResult, VoiceAgentSquadOptions, VoiceAgentTool, VoiceAgentToolCall, VoiceAgentToolResult } from './agent';
 export type { VoiceToolRetryDelay, VoiceToolRuntime, VoiceToolRuntimeExecuteInput, VoiceToolRuntimeOptions, VoiceToolRuntimeResult } from './toolRuntime';
 export type { VoiceToolContractCase, VoiceToolContractCaseReport, VoiceToolContractDefinition, VoiceToolContractExpectation, VoiceToolContractHandlerOptions, VoiceToolContractHTMLHandlerOptions, VoiceToolContractIssue, VoiceToolContractReport, VoiceToolContractRoutesOptions, VoiceToolContractSuiteReport } from './toolContract';
 export type { VoiceOpsRuntime, VoiceOpsRuntimeConfig, VoiceOpsRuntimeSummary, VoiceOpsRuntimeSinkWorkerConfig, VoiceOpsRuntimeTaskWorkerConfig, VoiceOpsRuntimeTickResult, VoiceOpsRuntimeWebhookWorkerConfig } from './opsRuntime';

package/dist/index.js

@@ -5827,21 +5827,80 @@ var createVoiceAgentSquad = (options) => {
     });
     toolResults.push(...result.toolResults);
     for (let handoffCount = 0;result.handoff && handoffCount < maxHandoffs; handoffCount += 1) {
-      const nextAgent = agents.get(result.handoff.targetAgentId);
+      const originalTargetAgentId = result.handoff.targetAgentId;
+      const policy = await options.handoffPolicy?.({
+        context: input.context,
+        fromAgentId: agent.id,
+        handoff: result.handoff,
+        messages,
+        session: input.session,
+        targetAgent: agents.get(originalTargetAgentId),
+        turn: input.turn
+      });
+      const targetAgentId = normalizeText3(policy?.targetAgentId) || originalTargetAgentId;
+      const nextAgent = agents.get(targetAgentId);
+      const handoffReason = policy?.summary ?? policy?.reason ?? result.handoff.reason;
+      const handoffMetadata = {
+        ...result.handoff.metadata,
+        ...policy?.metadata
+      };
+      const metadata = Object.keys(handoffMetadata).length > 0 ? handoffMetadata : undefined;
+      if (policy?.allow === false) {
+        await appendVoiceAgentTrace({
+          agentId: options.id,
+          event: {
+            fromAgentId: agent.id,
+            metadata,
+            originalTargetAgentId,
+            reason: handoffReason,
+            status: "blocked",
+            targetAgentId
+          },
+          session: input.session,
+          trace: options.trace,
+          turn: input.turn,
+          type: "agent.handoff"
+        });
+        return {
+          ...result,
+          escalate: result.escalate ?? policy.escalate ?? {
+            metadata,
+            reason: handoffReason ?? `Blocked handoff to ${targetAgentId}`
+          },
+          handoff: undefined,
+          toolResults
+        };
+      }
       if (!nextAgent) {
+        await appendVoiceAgentTrace({
+          agentId: options.id,
+          event: {
+            fromAgentId: agent.id,
+            metadata,
+            originalTargetAgentId,
+            reason: handoffReason,
+            status: "unknown-target",
+            targetAgentId
+          },
+          session: input.session,
+          trace: options.trace,
+          turn: input.turn,
+          type: "agent.handoff"
+        });
         return {
           ...result,
           escalate: result.escalate ?? {
-            metadata: result.handoff.metadata,
-            reason: `Unknown handoff target: ${result.handoff.targetAgentId}`
+            metadata,
+            reason: `Unknown handoff target: ${targetAgentId}`
           },
+          handoff: undefined,
           toolResults
         };
       }
       await options.onHandoff?.({
         context: input.context,
         fromAgentId: agent.id,
-        reason: result.handoff.reason,
+        reason: handoffReason,
         session: input.session,
         targetAgentId: nextAgent.id,
         turn: input.turn
@@ -5850,7 +5909,10 @@ var createVoiceAgentSquad = (options) => {
         agentId: options.id,
         event: {
           fromAgentId: agent.id,
-          reason: result.handoff.reason,
+          metadata,
+          originalTargetAgentId: originalTargetAgentId === nextAgent.id ? undefined : originalTargetAgentId,
+          reason: handoffReason,
+          status: "allowed",
           targetAgentId: nextAgent.id
         },
         session: input.session,
@@ -5859,8 +5921,8 @@ var createVoiceAgentSquad = (options) => {
         type: "agent.handoff"
       });
       messages.push({
-        content: result.handoff.reason ?? `Handoff to ${nextAgent.id}`,
-        metadata: result.handoff.metadata,
+        content: handoffReason ?? `Handoff to ${nextAgent.id}`,
+        metadata,
         name: nextAgent.id,
         role: "system"
       });
@@ -5872,6 +5934,31 @@ var createVoiceAgentSquad = (options) => {
       });
       toolResults.push(...result.toolResults);
     }
+    if (result.handoff) {
+      await appendVoiceAgentTrace({
+        agentId: options.id,
+        event: {
+          fromAgentId: agent.id,
+          metadata: result.handoff.metadata,
+          reason: result.handoff.reason,
+          status: "max-exceeded",
+          targetAgentId: result.handoff.targetAgentId
+        },
+        session: input.session,
+        trace: options.trace,
+        turn: input.turn,
+        type: "agent.handoff"
+      });
+      return {
+        ...result,
+        escalate: result.escalate ?? {
+          metadata: result.handoff.metadata,
+          reason: `Max handoffs exceeded: ${maxHandoffs}`
+        },
+        handoff: undefined,
+        toolResults
+      };
+    }
     return {
       ...result,
       agentId,

package/package.json

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