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

package/README.md

@@ -593,6 +593,54 @@ voice({
 
 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.
 
+Use `runVoiceAgentSquadContract(...)` in tests or readiness checks when you need proof that a specialist graph still routes correctly:
+
+```ts
+import {
+	createVoiceMemoryTraceEventStore,
+	runVoiceAgentSquadContract
+} from '@absolutejs/voice';
+
+const trace = createVoiceMemoryTraceEventStore();
+const frontDesk = createVoiceAgentSquad({
+	id: 'front-desk',
+	defaultAgentId: 'support',
+	agents: [supportAgent, billingAgent],
+	trace
+});
+
+const report = await runVoiceAgentSquadContract({
+	context: {},
+	squad: frontDesk,
+	trace,
+	contract: {
+		id: 'billing-route',
+		scenarioId: 'billing-route',
+		turns: [
+			{
+				text: 'I have a billing question.',
+				expect: {
+					finalAgentId: 'billing',
+					outcome: 'assistant',
+					assistantIncludes: ['billing'],
+					handoffs: [
+						{
+							fromAgentId: 'support',
+							targetAgentId: 'billing',
+							status: 'allowed'
+						}
+					]
+				}
+			}
+		]
+	}
+});
+
+if (!report.pass) {
+	throw new Error(report.issues.map((issue) => issue.message).join('\n'));
+}
+```
+
 ## 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/agentSquadContract.d.ts

@@ -0,0 +1,64 @@
+import type { VoiceAgent, VoiceAgentRunResult } 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';
+    targetAgentId?: string;
+};
+export type VoiceAgentSquadTurnExpectation<TResult = unknown> = {
+    assistantIncludes?: string[];
+    finalAgentId?: string;
+    handoffs?: VoiceAgentSquadHandoffExpectation[];
+    outcome?: VoiceAgentSquadContractOutcome;
+    result?: (input: {
+        result: TResult | undefined;
+        routeResult: VoiceRouteResult<TResult>;
+    }) => VoiceAgentSquadContractIssue[];
+    transferTarget?: string;
+};
+export type VoiceAgentSquadContractTurn<TResult = unknown> = {
+    expect?: VoiceAgentSquadTurnExpectation<TResult>;
+    id?: string;
+    text: string;
+};
+export type VoiceAgentSquadContractDefinition<TResult = unknown> = {
+    description?: string;
+    id: string;
+    label?: string;
+    scenarioId?: string;
+    turns: Array<VoiceAgentSquadContractTurn<TResult>>;
+};
+export type VoiceAgentSquadContractIssue = {
+    code: string;
+    message: string;
+    turnId?: string;
+};
+export type VoiceAgentSquadContractTurnReport<TResult = unknown> = {
+    agentId: string;
+    handoffs: VoiceAgentSquadHandoffExpectation[];
+    issues: VoiceAgentSquadContractIssue[];
+    outcome?: VoiceAgentSquadContractOutcome;
+    pass: boolean;
+    result: VoiceAgentRunResult<TResult>;
+    turnId: string;
+};
+export type VoiceAgentSquadContractReport<TResult = unknown> = {
+    contractId: string;
+    issues: VoiceAgentSquadContractIssue[];
+    pass: boolean;
+    scenarioId?: string;
+    sessionId: string;
+    turns: Array<VoiceAgentSquadContractTurnReport<TResult>>;
+};
+export type VoiceAgentSquadContractRunOptions<TContext = unknown, TSession extends VoiceSessionRecord = VoiceSessionRecord, TResult = unknown> = {
+    api?: VoiceSessionHandle<TContext, TSession, TResult>;
+    context: TContext;
+    contract: VoiceAgentSquadContractDefinition<TResult>;
+    session?: TSession;
+    squad: VoiceAgent<TContext, TSession, TResult>;
+    trace?: VoiceTraceEventStore;
+};
+export declare const runVoiceAgentSquadContract: <TContext = unknown, TSession extends VoiceSessionRecord = VoiceSessionRecord, TResult = unknown>(options: VoiceAgentSquadContractRunOptions<TContext, TSession, TResult>) => Promise<VoiceAgentSquadContractReport<TResult>>;
+export declare const assertVoiceAgentSquadContract: <TContext = unknown, TSession extends VoiceSessionRecord = VoiceSessionRecord, TResult = unknown>(options: VoiceAgentSquadContractRunOptions<TContext, TSession, TResult>) => Promise<VoiceAgentSquadContractReport<TResult>>;

package/dist/index.d.ts

@@ -11,6 +11,7 @@ export { createVoiceSimulationSuiteRoutes, renderVoiceSimulationSuiteHTML, runVo
 export { createVoiceWorkflowContract, createVoiceWorkflowContractHandler, createVoiceWorkflowContractPreset, createVoiceWorkflowScenario, recordVoiceWorkflowContractTrace, validateVoiceWorkflowRouteResult } from './workflowContract';
 export { createVoiceSessionListRoutes, createVoiceSessionReplayHTMLHandler, createVoiceSessionReplayJSONHandler, createVoiceSessionReplayRoutes, createVoiceSessionsHTMLHandler, createVoiceSessionsJSONHandler, renderVoiceSessionsHTML, summarizeVoiceSessions, summarizeVoiceSessionReplay } from './sessionReplay';
 export { createVoiceAgent, createVoiceAgentSquad, createVoiceAgentTool } from './agent';
+export { assertVoiceAgentSquadContract, runVoiceAgentSquadContract } from './agentSquadContract';
 export { createVoiceToolIdempotencyKey, createVoiceToolRuntime } from './toolRuntime';
 export { createVoiceToolContract, createVoiceToolContractHTMLHandler, createVoiceToolContractJSONHandler, createVoiceToolContractRoutes, createVoiceToolRuntimeContractDefaults, renderVoiceToolContractHTML, runVoiceToolContractSuite, runVoiceToolContract } from './toolContract';
 export { createVoiceTurnLatencyHTMLHandler, createVoiceTurnLatencyJSONHandler, createVoiceTurnLatencyRoutes, renderVoiceTurnLatencyHTML, summarizeVoiceTurnLatency } from './turnLatency';
@@ -82,6 +83,7 @@ export type { VoiceQualityLink, VoiceQualityMetric, VoiceQualityReport, VoiceQua
 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 { 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';
 export type { VoiceOpsRuntime, VoiceOpsRuntimeConfig, VoiceOpsRuntimeSummary, VoiceOpsRuntimeSinkWorkerConfig, VoiceOpsRuntimeTaskWorkerConfig, VoiceOpsRuntimeTickResult, VoiceOpsRuntimeWebhookWorkerConfig } from './opsRuntime';

package/dist/index.js

@@ -9831,6 +9831,12 @@ var resolveCarriers = async (options, input) => {
     providers: [...providers]
   });
 };
+var resolveAgentSquadContracts = async (options, input) => {
+  if (options.agentSquadContracts === false || options.agentSquadContracts === undefined) {
+    return;
+  }
+  return typeof options.agentSquadContracts === "function" ? await options.agentSquadContracts(input) : options.agentSquadContracts;
+};
 var summarizeLiveLatency = (events, options) => {
   const warnAfterMs = options.liveLatencyWarnAfterMs ?? 1800;
   const failAfterMs = options.liveLatencyFailAfterMs ?? 3200;
@@ -9853,7 +9859,7 @@ var buildVoiceProductionReadinessReport = async (options, input = {}) => {
   const routingEvents = listVoiceRoutingEvents(events);
   const routingSessions = summarizeVoiceRoutingSessions(routingEvents);
   const liveLatency = summarizeLiveLatency(events, options);
-  const [quality, providers, sessions, handoffs, carriers] = await Promise.all([
+  const [quality, providers, sessions, handoffs, carriers, agentSquadContracts] = await Promise.all([
     evaluateVoiceQuality({ events }),
     Promise.all([
       summarizeVoiceProviderHealth({
@@ -9871,7 +9877,8 @@ var buildVoiceProductionReadinessReport = async (options, input = {}) => {
     ]).then((groups) => groups.flat()),
     summarizeVoiceSessions({ events, status: "all" }),
     summarizeVoiceHandoffHealth({ events }),
-    resolveCarriers(options, { query, request })
+    resolveCarriers(options, { query, request }),
+    resolveAgentSquadContracts(options, { query, request })
   ]);
   const degradedProviders = providers.filter((provider) => provider.status === "degraded" || provider.status === "rate-limited" || provider.status === "suppressed").length;
   const failedSessions = sessions.filter((session) => session.status === "failed").length;
@@ -9980,6 +9987,28 @@ var buildVoiceProductionReadinessReport = async (options, input = {}) => {
     status: carrierStatus(carriers),
     warnings: carriers.summary.warnings
   } : undefined;
+  const agentSquadContractSummary = agentSquadContracts ? {
+    failed: agentSquadContracts.filter((report) => !report.pass).length,
+    passed: agentSquadContracts.filter((report) => report.pass).length,
+    status: agentSquadContracts.some((report) => !report.pass) ? "fail" : agentSquadContracts.length === 0 ? "warn" : "pass",
+    total: agentSquadContracts.length
+  } : undefined;
+  if (agentSquadContractSummary) {
+    checks.push({
+      detail: agentSquadContractSummary.status === "pass" ? `${agentSquadContractSummary.passed} agent squad contract(s) are passing.` : agentSquadContractSummary.total === 0 ? "No agent squad contracts are configured." : `${agentSquadContractSummary.failed} agent squad contract(s) failed.`,
+      href: options.links?.agentSquadContracts ?? "/agent-squad-contract",
+      label: "Agent squad contracts",
+      status: agentSquadContractSummary.status,
+      value: `${agentSquadContractSummary.passed}/${agentSquadContractSummary.total}`,
+      actions: agentSquadContractSummary.status === "pass" ? [] : [
+        {
+          description: "Open the specialist routing contract report and inspect failing handoff paths.",
+          href: options.links?.agentSquadContracts ?? "/agent-squad-contract",
+          label: "Open squad contracts"
+        }
+      ]
+    });
+  }
   if (carriers && carrierSummary) {
     checks.push({
       detail: carrierSummary.status === "pass" ? "Configured carrier setup and contract checks are passing." : `${carrierSummary.failing} carrier(s) failing, ${carrierSummary.warnings} warning(s).`,
@@ -10000,6 +10029,7 @@ var buildVoiceProductionReadinessReport = async (options, input = {}) => {
     checkedAt: Date.now(),
     checks,
     links: {
+      agentSquadContracts: "/agent-squad-contract",
       carriers: "/carriers",
       handoffs: "/handoffs",
       handoffRetry: "/api/voice-handoffs/retry",
@@ -10011,6 +10041,7 @@ var buildVoiceProductionReadinessReport = async (options, input = {}) => {
     },
     status: rollupStatus(checks),
     summary: {
+      agentSquadContracts: agentSquadContractSummary,
       carriers: carrierSummary,
       handoffs: {
         failed: handoffs.failed,
@@ -12733,6 +12764,164 @@ var createVoiceWorkflowContractHandler = (input) => {
     return result;
   };
 };
+// src/agentSquadContract.ts
+var normalizeIncludes = (value) => value.trim().toLowerCase();
+var resolveOutcome3 = (result) => {
+  if (result.complete)
+    return "complete";
+  if (result.transfer)
+    return "transfer";
+  if (result.escalate)
+    return "escalate";
+  if (result.voicemail)
+    return "voicemail";
+  if (result.noAnswer)
+    return "no-answer";
+  if (result.assistantText?.trim())
+    return "assistant";
+  return;
+};
+var getPayloadString2 = (event, key) => {
+  const value = event.payload[key];
+  return typeof value === "string" ? value : undefined;
+};
+var toHandoffExpectation = (event) => ({
+  fromAgentId: getPayloadString2(event, "fromAgentId"),
+  status: getPayloadString2(event, "status"),
+  targetAgentId: getPayloadString2(event, "targetAgentId")
+});
+var createContractApi = (session) => ({
+  close: async () => {},
+  commitTurn: async () => {},
+  complete: async () => {},
+  connect: async () => {},
+  disconnect: async () => {},
+  escalate: async () => {},
+  fail: async () => {},
+  id: session.id,
+  markNoAnswer: async () => {},
+  markVoicemail: async () => {},
+  receiveAudio: async () => {},
+  snapshot: async () => session,
+  transfer: async () => {}
+});
+var createContractTurn = (turn, index) => ({
+  committedAt: Date.now(),
+  id: turn.id ?? `turn-${index + 1}`,
+  text: turn.text,
+  transcripts: []
+});
+var appendIssue = (issues, issue, turnId) => {
+  issues.push({
+    ...issue,
+    turnId: issue.turnId ?? 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);
+  const turnReports = [];
+  const issues = [];
+  for (const [index, contractTurn] of options.contract.turns.entries()) {
+    const turn = createContractTurn(contractTurn, index);
+    const result = await options.squad.run({
+      api,
+      context: options.context,
+      session,
+      turn
+    });
+    const handoffEvents = await options.trace?.list({
+      sessionId: session.id,
+      turnId: turn.id,
+      type: "agent.handoff"
+    }) ?? [];
+    const handoffs = handoffEvents.map(toHandoffExpectation);
+    const turnIssues = [];
+    const expected = contractTurn.expect;
+    const outcome = resolveOutcome3(result);
+    if (expected?.finalAgentId && result.agentId !== expected.finalAgentId) {
+      appendIssue(turnIssues, {
+        code: "agent_squad.final_agent_mismatch",
+        message: `Expected final agent ${expected.finalAgentId}, saw ${result.agentId}.`
+      }, turn.id);
+    }
+    if (expected?.outcome && outcome !== expected.outcome) {
+      appendIssue(turnIssues, {
+        code: "agent_squad.outcome_mismatch",
+        message: `Expected outcome ${expected.outcome}, saw ${outcome ?? "none"}.`
+      }, turn.id);
+    }
+    if (expected?.transferTarget && result.transfer?.target !== expected.transferTarget) {
+      appendIssue(turnIssues, {
+        code: "agent_squad.transfer_target_mismatch",
+        message: `Expected transfer target ${expected.transferTarget}, saw ${result.transfer?.target ?? "none"}.`
+      }, turn.id);
+    }
+    const assistantText = normalizeIncludes(result.assistantText ?? "");
+    for (const expectedText of expected?.assistantIncludes ?? []) {
+      if (!assistantText.includes(normalizeIncludes(expectedText))) {
+        appendIssue(turnIssues, {
+          code: "agent_squad.assistant_text_missing",
+          message: `Expected assistant text to include: ${expectedText}`
+        }, turn.id);
+      }
+    }
+    for (const [handoffIndex, expectedHandoff] of (expected?.handoffs ?? []).entries()) {
+      const actual = handoffs[handoffIndex];
+      if (!actual) {
+        appendIssue(turnIssues, {
+          code: "agent_squad.handoff_missing",
+          message: `Expected handoff ${handoffIndex + 1}, but no trace event was recorded.`
+        }, turn.id);
+        continue;
+      }
+      for (const key of ["fromAgentId", "status", "targetAgentId"]) {
+        if (expectedHandoff[key] && actual[key] !== expectedHandoff[key]) {
+          appendIssue(turnIssues, {
+            code: "agent_squad.handoff_mismatch",
+            message: `Expected handoff ${handoffIndex + 1} ${key} ${expectedHandoff[key]}, saw ${actual[key] ?? "none"}.`
+          }, turn.id);
+        }
+      }
+    }
+    for (const issue of expected?.result?.({
+      result: result.result,
+      routeResult: result
+    }) ?? []) {
+      appendIssue(turnIssues, issue, turn.id);
+    }
+    issues.push(...turnIssues);
+    turnReports.push({
+      agentId: result.agentId,
+      handoffs,
+      issues: turnIssues,
+      outcome,
+      pass: turnIssues.length === 0,
+      result,
+      turnId: turn.id
+    });
+    session.turns.push({
+      ...turn,
+      assistantText: result.assistantText,
+      result: result.result
+    });
+  }
+  return {
+    contractId: options.contract.id,
+    issues,
+    pass: issues.length === 0,
+    scenarioId: options.contract.scenarioId,
+    sessionId: session.id,
+    turns: turnReports
+  };
+};
+var assertVoiceAgentSquadContract = async (options) => {
+  const report = await runVoiceAgentSquadContract(options);
+  if (!report.pass) {
+    throw new Error(`Voice agent squad contract ${report.contractId} failed: ${report.issues.map((issue) => issue.message).join(" ")}`);
+  }
+  return report;
+};
 // src/turnLatency.ts
 import { Elysia as Elysia21 } from "elysia";
 var DEFAULT_WARN_AFTER_MS = 1800;
@@ -19779,6 +19968,7 @@ export {
   runVoiceOutcomeContractSuite,
   runVoiceCampaignProof,
   runVoiceCampaignDialerProof,
+  runVoiceAgentSquadContract,
   resolveVoiceTraceRedactionOptions,
   resolveVoiceTelephonyOutcome,
   resolveVoiceSTTRoutingStrategy,
@@ -20056,6 +20246,7 @@ export {
   buildVoiceDiagnosticsMarkdown,
   buildVoiceCampaignObservabilityReport,
   assignVoiceOpsTask,
+  assertVoiceAgentSquadContract,
   applyVoiceTelephonyOutcome,
   applyVoiceOpsTaskPolicy,
   applyVoiceOpsTaskAssignmentRule,

package/dist/productionReadiness.d.ts

@@ -1,6 +1,7 @@
 import { Elysia } from 'elysia';
 import { type VoiceTelephonyCarrierMatrixInput } from './telephony/matrix';
 import type { VoiceTraceEventStore } from './trace';
+import type { VoiceAgentSquadContractReport } from './agentSquadContract';
 export type VoiceProductionReadinessStatus = 'fail' | 'pass' | 'warn';
 export type VoiceProductionReadinessAction = {
     description?: string;
@@ -20,6 +21,7 @@ export type VoiceProductionReadinessReport = {
     checkedAt: number;
     checks: VoiceProductionReadinessCheck[];
     links: {
+        agentSquadContracts?: string;
         carriers?: string;
         handoffs?: string;
         handoffRetry?: string;
@@ -30,6 +32,12 @@ export type VoiceProductionReadinessReport = {
     };
     status: VoiceProductionReadinessStatus;
     summary: {
+        agentSquadContracts?: {
+            failed: number;
+            passed: number;
+            status: VoiceProductionReadinessStatus;
+            total: number;
+        };
         carriers?: {
             failing: number;
             providers: number;
@@ -66,6 +74,10 @@ export type VoiceProductionReadinessReport = {
     };
 };
 export type VoiceProductionReadinessRoutesOptions = {
+    agentSquadContracts?: false | readonly VoiceAgentSquadContractReport[] | ((input: {
+        query: Record<string, unknown>;
+        request: Request;
+    }) => Promise<readonly VoiceAgentSquadContractReport[]> | readonly VoiceAgentSquadContractReport[]);
     carriers?: false | readonly VoiceTelephonyCarrierMatrixInput[] | ((input: {
         query: Record<string, unknown>;
         request: Request;

package/package.json

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