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

package/README.md

@@ -563,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({
@@ -577,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.122",
+	"version": "0.0.22-beta.123",
 	"description": "Voice primitives and Elysia plugin for AbsoluteJS",
 	"repository": {
 		"type": "git",