@absolutejs/voice 0.0.22-beta.181 → 0.0.22-beta.182

package/dist/agent.d.ts

@@ -61,10 +61,30 @@ export type VoiceAgentModelOutput<TResult = unknown> = VoiceRouteResult<TResult>
 export type VoiceAgentModel<TContext = unknown, TSession extends VoiceSessionRecord = VoiceSessionRecord, TResult = unknown> = {
     generate: (input: VoiceAgentModelInput<TContext, TSession>) => Promise<VoiceAgentModelOutput<TResult>> | VoiceAgentModelOutput<TResult>;
 };
+export type VoiceAgentSquadHandoffStatus = 'allowed' | 'blocked' | 'max-exceeded' | 'unknown-target';
+export type VoiceAgentSquadStateHandoff = {
+    at: number;
+    fromAgentId: string;
+    metadata?: Record<string, unknown>;
+    originalTargetAgentId?: string;
+    reason?: string;
+    status: VoiceAgentSquadHandoffStatus;
+    summary?: string;
+    targetAgentId: string;
+    turnId: string;
+};
+export type VoiceAgentSquadState = {
+    agentId: string;
+    handoffCount: number;
+    handoffs: VoiceAgentSquadStateHandoff[];
+    lastHandoff?: VoiceAgentSquadStateHandoff;
+    previousAgentId?: string;
+};
 export type VoiceAgentRunResult<TResult = unknown> = VoiceRouteResult<TResult> & {
     agentId: string;
     handoff?: VoiceAgentModelOutput<TResult>['handoff'];
     messages: VoiceAgentMessage[];
+    squad?: VoiceAgentSquadState;
     toolResults: VoiceAgentToolResult[];
 };
 export type VoiceAgentSquadHandoffPolicyResult<TResult = unknown> = {
@@ -120,8 +140,10 @@ export type VoiceAgentSquadOptions<TContext = unknown, TSession extends VoiceSes
     onHandoff?: (input: {
         context: TContext;
         fromAgentId: string;
+        metadata?: Record<string, unknown>;
         reason?: string;
         session: TSession;
+        summary?: string;
         targetAgentId: string;
         turn: VoiceTurnRecord;
     }) => Promise<void> | void;

package/dist/agentSquadContract.d.ts

@@ -1,10 +1,15 @@
-import type { VoiceAgent, VoiceAgentRunResult } from './agent';
+import type { VoiceAgent, VoiceAgentRunResult, VoiceAgentSquadHandoffStatus } from './agent';
 import type { VoiceTraceEventStore } from './trace';
 import type { VoiceRouteResult, VoiceSessionHandle, VoiceSessionRecord } from './types';
 export type VoiceAgentSquadContractOutcome = 'assistant' | 'complete' | 'escalate' | 'no-answer' | 'transfer' | 'voicemail';
 export type VoiceAgentSquadHandoffExpectation = {
     fromAgentId?: string;
-    status?: 'allowed' | 'blocked' | 'max-exceeded' | 'unknown-target';
+    metadata?: Record<string, unknown>;
+    reason?: string;
+    reasonIncludes?: string[];
+    status?: VoiceAgentSquadHandoffStatus;
+    summary?: string;
+    summaryIncludes?: string[];
     targetAgentId?: string;
 };
 export type VoiceAgentSquadTurnExpectation<TResult = unknown> = {

package/dist/index.d.ts

@@ -110,7 +110,7 @@ export type { VoiceProviderStackChoice, VoiceProviderStackCapabilities, VoicePro
 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, VoiceAgentSquadHandoffPolicyResult, VoiceAgentSquadOptions, VoiceAgentTool, VoiceAgentToolCall, VoiceAgentToolResult } from './agent';
+export type { VoiceAgent, VoiceAgentMessage, VoiceAgentMessageRole, VoiceAgentModel, VoiceAgentModelInput, VoiceAgentModelOutput, VoiceAgentOptions, VoiceAgentRunResult, VoiceAgentSquadHandoffPolicyResult, VoiceAgentSquadHandoffStatus, VoiceAgentSquadOptions, VoiceAgentSquadState, VoiceAgentSquadStateHandoff, VoiceAgentTool, VoiceAgentToolCall, VoiceAgentToolResult } from './agent';
 export type { VoiceAgentSquadContractDefinition, VoiceAgentSquadContractIssue, VoiceAgentSquadContractOutcome, VoiceAgentSquadContractReport, VoiceAgentSquadContractRunOptions, VoiceAgentSquadContractTurn, VoiceAgentSquadContractTurnReport, VoiceAgentSquadHandoffExpectation, VoiceAgentSquadTurnExpectation } from './agentSquadContract';
 export type { VoiceToolRetryDelay, VoiceToolRuntime, VoiceToolRuntimeExecuteInput, VoiceToolRuntimeOptions, VoiceToolRuntimeResult } from './toolRuntime';
 export type { VoiceToolContractCase, VoiceToolContractCaseReport, VoiceToolContractDefinition, VoiceToolContractExpectation, VoiceToolContractHandlerOptions, VoiceToolContractHTMLHandlerOptions, VoiceToolContractIssue, VoiceToolContractReport, VoiceToolContractRoutesOptions, VoiceToolContractSuiteReport } from './toolContract';

package/dist/index.js

@@ -6887,6 +6887,47 @@ var resolveVoiceAgentAuditLogger = (audit) => {
   return "append" in audit ? createVoiceAuditLogger(audit) : audit;
 };
 var toAuditOutcome = (status) => status === "allowed" ? "success" : status === "blocked" ? "skipped" : "error";
+var createVoiceAgentSquadState = (input) => {
+  const lastHandoff = input.handoffs.at(-1);
+  return {
+    agentId: input.agentId,
+    handoffCount: input.handoffs.length,
+    handoffs: [...input.handoffs],
+    lastHandoff,
+    previousAgentId: lastHandoff?.status === "allowed" ? lastHandoff.fromAgentId : undefined
+  };
+};
+var appendVoiceAgentSquadHandoff = async (input) => {
+  const handoff = {
+    at: Date.now(),
+    fromAgentId: input.fromAgentId,
+    metadata: input.metadata,
+    originalTargetAgentId: input.originalTargetAgentId,
+    reason: input.reason,
+    status: input.status,
+    summary: input.summary,
+    targetAgentId: input.targetAgentId,
+    turnId: input.turn.id
+  };
+  input.handoffs.push(handoff);
+  await appendVoiceAgentTrace({
+    agentId: input.agentId,
+    event: {
+      fromAgentId: handoff.fromAgentId,
+      metadata: handoff.metadata,
+      originalTargetAgentId: handoff.originalTargetAgentId,
+      reason: handoff.reason,
+      status: handoff.status,
+      summary: handoff.summary,
+      targetAgentId: handoff.targetAgentId
+    },
+    session: input.session,
+    trace: input.trace,
+    turn: input.turn,
+    type: "agent.handoff"
+  });
+  return handoff;
+};
 var createVoiceAgentTool = (tool) => tool;
 var createVoiceAgent = (options) => {
   const toolMap = new Map(options.tools?.map((tool) => [tool.name, tool]) ?? []);
@@ -7187,6 +7228,7 @@ var createVoiceAgentSquad = (options) => {
     let agent = agents.get(agentId) ?? defaultAgent;
     const messages = input.messages ?? createHistoryMessages(input.session, input.turn);
     const toolResults = [];
+    const handoffs = [];
     const maxHandoffs = Math.max(0, options.maxHandoffsPerTurn ?? 2);
     let result = await agent.run({
       ...input,
@@ -7207,26 +7249,26 @@ var createVoiceAgentSquad = (options) => {
       const targetAgentId = normalizeText3(policy?.targetAgentId) || originalTargetAgentId;
       const nextAgent = agents.get(targetAgentId);
       const handoffReason = policy?.summary ?? policy?.reason ?? result.handoff.reason;
+      const handoffSummary = policy?.summary ?? result.handoff.reason ?? policy?.reason;
       const handoffMetadata = {
         ...result.handoff.metadata,
         ...policy?.metadata
       };
       const metadata = Object.keys(handoffMetadata).length > 0 ? handoffMetadata : undefined;
       if (policy?.allow === false) {
-        await appendVoiceAgentTrace({
+        await appendVoiceAgentSquadHandoff({
           agentId: options.id,
-          event: {
-            fromAgentId: agent.id,
-            metadata,
-            originalTargetAgentId,
-            reason: handoffReason,
-            status: "blocked",
-            targetAgentId
-          },
+          fromAgentId: agent.id,
+          handoffs,
+          metadata,
+          originalTargetAgentId: originalTargetAgentId === targetAgentId ? undefined : originalTargetAgentId,
+          reason: handoffReason,
           session: input.session,
+          status: "blocked",
+          summary: handoffSummary,
+          targetAgentId,
           trace: options.trace,
-          turn: input.turn,
-          type: "agent.handoff"
+          turn: input.turn
         });
         await audit?.handoff({
           actor: {
@@ -7247,24 +7289,27 @@ var createVoiceAgentSquad = (options) => {
             reason: handoffReason ?? `Blocked handoff to ${targetAgentId}`
           },
           handoff: undefined,
+          squad: createVoiceAgentSquadState({
+            agentId: agent.id,
+            handoffs
+          }),
           toolResults
         };
       }
       if (!nextAgent) {
-        await appendVoiceAgentTrace({
+        await appendVoiceAgentSquadHandoff({
           agentId: options.id,
-          event: {
-            fromAgentId: agent.id,
-            metadata,
-            originalTargetAgentId,
-            reason: handoffReason,
-            status: "unknown-target",
-            targetAgentId
-          },
+          fromAgentId: agent.id,
+          handoffs,
+          metadata,
+          originalTargetAgentId: originalTargetAgentId === targetAgentId ? undefined : originalTargetAgentId,
+          reason: handoffReason,
           session: input.session,
+          status: "unknown-target",
+          summary: handoffSummary,
+          targetAgentId,
           trace: options.trace,
-          turn: input.turn,
-          type: "agent.handoff"
+          turn: input.turn
         });
         await audit?.handoff({
           actor: {
@@ -7285,31 +7330,36 @@ var createVoiceAgentSquad = (options) => {
             reason: `Unknown handoff target: ${targetAgentId}`
           },
           handoff: undefined,
+          squad: createVoiceAgentSquadState({
+            agentId: agent.id,
+            handoffs
+          }),
           toolResults
         };
       }
       await options.onHandoff?.({
         context: input.context,
         fromAgentId: agent.id,
+        metadata,
         reason: handoffReason,
         session: input.session,
+        summary: handoffSummary,
         targetAgentId: nextAgent.id,
         turn: input.turn
       });
-      await appendVoiceAgentTrace({
+      await appendVoiceAgentSquadHandoff({
         agentId: options.id,
-        event: {
-          fromAgentId: agent.id,
-          metadata,
-          originalTargetAgentId: originalTargetAgentId === nextAgent.id ? undefined : originalTargetAgentId,
-          reason: handoffReason,
-          status: "allowed",
-          targetAgentId: nextAgent.id
-        },
+        fromAgentId: agent.id,
+        handoffs,
+        metadata,
+        originalTargetAgentId: originalTargetAgentId === nextAgent.id ? undefined : originalTargetAgentId,
+        reason: handoffReason,
         session: input.session,
+        status: "allowed",
+        summary: handoffSummary,
+        targetAgentId: nextAgent.id,
         trace: options.trace,
-        turn: input.turn,
-        type: "agent.handoff"
+        turn: input.turn
       });
       await audit?.handoff({
         actor: {
@@ -7324,7 +7374,7 @@ var createVoiceAgentSquad = (options) => {
         toAgentId: nextAgent.id
       });
       messages.push({
-        content: handoffReason ?? `Handoff to ${nextAgent.id}`,
+        content: handoffSummary ?? handoffReason ?? `Handoff to ${nextAgent.id}`,
         metadata,
         name: nextAgent.id,
         role: "system"
@@ -7338,19 +7388,18 @@ var createVoiceAgentSquad = (options) => {
       toolResults.push(...result.toolResults);
     }
     if (result.handoff) {
-      await appendVoiceAgentTrace({
+      await appendVoiceAgentSquadHandoff({
         agentId: options.id,
-        event: {
-          fromAgentId: agent.id,
-          metadata: result.handoff.metadata,
-          reason: result.handoff.reason,
-          status: "max-exceeded",
-          targetAgentId: result.handoff.targetAgentId
-        },
+        fromAgentId: agent.id,
+        handoffs,
+        metadata: result.handoff.metadata,
+        reason: result.handoff.reason,
         session: input.session,
+        status: "max-exceeded",
+        summary: result.handoff.reason,
+        targetAgentId: result.handoff.targetAgentId,
         trace: options.trace,
-        turn: input.turn,
-        type: "agent.handoff"
+        turn: input.turn
       });
       await audit?.handoff({
         actor: {
@@ -7371,12 +7420,20 @@ var createVoiceAgentSquad = (options) => {
           reason: `Max handoffs exceeded: ${maxHandoffs}`
         },
         handoff: undefined,
+        squad: createVoiceAgentSquadState({
+          agentId: agent.id,
+          handoffs
+        }),
         toolResults
       };
     }
     return {
       ...result,
       agentId,
+      squad: createVoiceAgentSquadState({
+        agentId,
+        handoffs
+      }),
       toolResults
     };
   };
@@ -14433,9 +14490,16 @@ var getPayloadString2 = (event, key) => {
   const value = event.payload[key];
   return typeof value === "string" ? value : undefined;
 };
+var getPayloadRecord = (event, key) => {
+  const value = event.payload[key];
+  return value && typeof value === "object" && !Array.isArray(value) ? value : undefined;
+};
 var toHandoffExpectation = (event) => ({
   fromAgentId: getPayloadString2(event, "fromAgentId"),
+  metadata: getPayloadRecord(event, "metadata"),
+  reason: getPayloadString2(event, "reason"),
   status: getPayloadString2(event, "status"),
+  summary: getPayloadString2(event, "summary"),
   targetAgentId: getPayloadString2(event, "targetAgentId")
 });
 var createContractApi = (session) => ({
@@ -14465,6 +14529,28 @@ var appendIssue = (issues, issue, turnId) => {
     turnId: issue.turnId ?? turnId
   });
 };
+var assertIncludes = (input) => {
+  const actual = normalizeIncludes(input.actual?.join(" ") ?? "");
+  for (const expected of input.expected ?? []) {
+    if (!actual.includes(normalizeIncludes(expected))) {
+      appendIssue(input.issues, {
+        code: input.code,
+        message: `Expected handoff ${input.handoffIndex + 1} ${input.label} to include: ${expected}`
+      }, input.turnId);
+    }
+  }
+};
+var assertMetadata = (input) => {
+  for (const [key, expectedValue] of Object.entries(input.expected ?? {})) {
+    const actualValue = input.actual?.[key];
+    if (actualValue !== expectedValue) {
+      appendIssue(input.issues, {
+        code: "agent_squad.handoff_metadata_mismatch",
+        message: `Expected handoff ${input.handoffIndex + 1} metadata ${key} ${String(expectedValue)}, saw ${String(actualValue ?? "none")}.`
+      }, input.turnId);
+    }
+  }
+};
 var runVoiceAgentSquadContract = async (options) => {
   const session = options.session ?? createVoiceSessionRecord(`agent-squad-contract-${options.contract.id}`, options.contract.scenarioId ?? options.contract.id);
   const api = options.api ?? createContractApi(session);
@@ -14531,6 +14617,39 @@ var runVoiceAgentSquadContract = async (options) => {
           }, turn.id);
         }
       }
+      for (const key of ["reason", "summary"]) {
+        if (expectedHandoff[key] && actual[key] !== expectedHandoff[key]) {
+          appendIssue(turnIssues, {
+            code: `agent_squad.handoff_${key}_mismatch`,
+            message: `Expected handoff ${handoffIndex + 1} ${key} ${expectedHandoff[key]}, saw ${actual[key] ?? "none"}.`
+          }, turn.id);
+        }
+      }
+      assertIncludes({
+        actual: actual.reason ? [actual.reason] : undefined,
+        code: "agent_squad.handoff_reason_missing",
+        expected: expectedHandoff.reasonIncludes,
+        handoffIndex,
+        issues: turnIssues,
+        label: "reason",
+        turnId: turn.id
+      });
+      assertIncludes({
+        actual: actual.summary ? [actual.summary] : undefined,
+        code: "agent_squad.handoff_summary_missing",
+        expected: expectedHandoff.summaryIncludes,
+        handoffIndex,
+        issues: turnIssues,
+        label: "summary",
+        turnId: turn.id
+      });
+      assertMetadata({
+        actual: actual.metadata,
+        expected: expectedHandoff.metadata,
+        handoffIndex,
+        issues: turnIssues,
+        turnId: turn.id
+      });
     }
     for (const issue of expected?.result?.({
       result: result.result,

package/package.json

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