@absolutejs/voice 0.0.22-beta.329 → 0.0.22-beta.330

package/dist/index.d.ts

@@ -109,6 +109,7 @@ export { conditionAudioChunk, resolveAudioConditioningConfig } from './audioCond
 export { resolveVoiceRuntimePreset } from './presets';
 export { resolveTurnDetectionConfig, TURN_PROFILE_DEFAULTS } from './turnProfiles';
 export { createVoiceCallReviewFromLiveTelephonyReport, createVoiceCallReviewRecorder, renderVoiceCallReviewHTML, renderVoiceCallReviewMarkdown } from './testing/review';
+export { getDefaultVoiceTelephonyBenchmarkScenarios, runVoiceTelephonyBenchmark, runVoiceTelephonyBenchmarkScenario, runVoiceTelephonyMediaOperationsSmoke, summarizeVoiceTelephonyBenchmark } from './testing/telephony';
 export type { VoiceCampaign, VoiceCampaignAttempt, VoiceCampaignAttemptResultInput, VoiceCampaignAttemptStatus, VoiceCampaignCreateInput, VoiceCampaignDialer, VoiceCampaignDialerInput, VoiceCampaignDialerResult, VoiceCampaignProofOptions, VoiceCampaignProofReport, VoiceCampaignReadinessAssertionInput, VoiceCampaignReadinessAssertionReport, VoiceCampaignReadinessCheck, VoiceCampaignReadinessProofOptions, VoiceCampaignReadinessProofReport, VoiceCampaignRecipient, VoiceCampaignRecipientImportIssue, VoiceCampaignRecipientImportIssueCode, VoiceCampaignRecipientImportOptions, VoiceCampaignRecipientImportResult, VoiceCampaignRecipientImportRow, VoiceCampaignRecipientInput, VoiceCampaignRecipientStatus, VoiceCampaignRecord, VoiceCampaignRoutesOptions, VoiceCampaignRuntime, VoiceCampaignRuntimeOptions, VoiceCampaignRateLimit, VoiceCampaignRetryPolicy, VoiceCampaignSchedule, VoiceCampaignStatus, VoiceCampaignStore, VoiceCampaignSummary, VoiceCampaignTimeWindow, VoiceCampaignTickResult } from './campaign';
 export type { VoiceCampaignDialerProofAssertionInput, VoiceCampaignDialerProofAssertionReport, VoiceCampaignDialerProofCarrierRequest, VoiceCampaignDialerProofOptions, VoiceCampaignDialerProofProvider, VoiceCampaignDialerProofProviderResult, VoiceCampaignDialerProofReport, VoiceCampaignDialerProofStatus, VoicePlivoCampaignDialerOptions, VoiceTelnyxCampaignDialerOptions, VoiceTwilioCampaignDialerOptions } from './campaignDialers';
 export type { VoiceBargeInReport, VoiceBargeInRoutesOptions } from './bargeInRoutes';
@@ -162,6 +163,7 @@ export type { VoiceOpsWebhookEnvelope, VoiceOpsWebhookEntity, VoiceOpsWebhookLin
 export type { VoiceHandoffDelivery, VoiceHandoffDeliveryRecord, VoiceHandoffDeliveryRecordInput, VoiceHandoffFanoutResult, VoiceQueuedHandoffDeliveryOptions, VoiceTwilioRedirectHandoffAdapterOptions, VoiceWebhookHandoffAdapterOptions } from './handoff';
 export type { VoiceHandoffHealthDelivery, VoiceHandoffHealthEvent, VoiceHandoffHealthHTMLHandlerOptions, VoiceHandoffHealthRoutesOptions, VoiceHandoffHealthStatus, VoiceHandoffHealthSummary, VoiceHandoffHealthSummaryOptions } from './handoffHealth';
 export type { StoredVoiceCallReviewArtifact, VoiceCallReviewArtifact, VoiceCallReviewConfig, VoiceCallReviewPostCallSummary, VoiceCallReviewRecorder, VoiceCallReviewRecorderOptions, VoiceCallReviewStore, VoiceCallReviewSummary, VoiceCallReviewTimelineEvent } from './testing/review';
+export type { VoiceTelephonyBenchmarkReport, VoiceTelephonyBenchmarkScenario, VoiceTelephonyBenchmarkScenarioResult, VoiceTelephonyBenchmarkSummary, VoiceTelephonyMediaOperationsSmokeOptions, VoiceTelephonyMediaOperationsSmokeReport } from './testing/telephony';
 export type { StoredVoiceAuditEvent, VoiceAuditActor, VoiceAuditEvent, VoiceAuditEventFilter, VoiceAuditEventStore, VoiceAuditEventType, VoiceAuditLogger, VoiceAuditOutcome, VoiceAuditResource, VoiceHandoffAuditEventInput, VoiceOperatorAuditEventInput, VoiceProviderAuditEventInput, VoiceRetentionAuditEventInput, VoiceToolAuditEventInput } from './audit';
 export type { VoiceAuditTrailOptions, VoiceAuditTrailReport, VoiceAuditTrailRoutesOptions, VoiceAuditTrailSummary } from './auditRoutes';
 export type { VoiceAuditExport } from './auditExport';

package/dist/index.js

@@ -35510,6 +35510,367 @@ var createVoiceSTTRoutingCorrectionHandler = (mode = "generic") => {
   }
   return createPhraseHintCorrectionHandler();
 };
+// src/testing/telephony.ts
+var DEFAULT_PCM16_FORMAT = {
+  channels: 1,
+  container: "raw",
+  encoding: "pcm_s16le",
+  sampleRateHz: 16000
+};
+var DEFAULT_SCENARIOS = [
+  {
+    expectClear: false,
+    expectMark: true,
+    expectOutboundMedia: true,
+    id: "telephony-turn",
+    title: "Telephony bridge streams assistant audio and mark"
+  },
+  {
+    expectClear: true,
+    expectMark: true,
+    expectOutboundMedia: true,
+    id: "telephony-barge-in",
+    secondInboundDelayMs: 5,
+    title: "Telephony bridge clears queued outbound audio on barge-in"
+  },
+  {
+    expectClear: true,
+    expectMark: true,
+    expectOutboundMedia: true,
+    id: "telephony-streaming",
+    secondInboundDelayMs: 8,
+    title: "Telephony bridge keeps streaming chunks and still clears on re-entry",
+    ttsChunkCount: 3,
+    ttsChunkDelayMs: 4
+  }
+];
+var waitFor = async (check, timeoutMs, intervalMs = 5) => {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if (check()) {
+      return true;
+    }
+    await Bun.sleep(intervalMs);
+  }
+  return check();
+};
+var toUint8Array2 = (audio) => audio instanceof Uint8Array ? audio : audio instanceof ArrayBuffer ? new Uint8Array(audio) : new Uint8Array(audio.buffer, audio.byteOffset, audio.byteLength);
+var createFakeSTTAdapter = (inputSpy, sttDelayMs) => ({
+  kind: "stt",
+  open: (_options) => {
+    const listeners = {
+      close: new Set,
+      endOfTurn: new Set,
+      error: new Set,
+      final: new Set,
+      partial: new Set
+    };
+    let delivered = false;
+    return {
+      close: async () => {
+        for (const handler of listeners.close) {
+          handler({ type: "close" });
+        }
+      },
+      on: (event, handler) => {
+        listeners[event].add(handler);
+        return () => {
+          listeners[event].delete(handler);
+        };
+      },
+      send: async (audio) => {
+        inputSpy.push(toUint8Array2(audio));
+        if (delivered) {
+          return;
+        }
+        delivered = true;
+        if (sttDelayMs > 0) {
+          await Bun.sleep(sttDelayMs);
+        }
+        const receivedAt = Date.now();
+        for (const handler of listeners.final) {
+          handler({
+            receivedAt,
+            transcript: {
+              id: "telephony-benchmark-final",
+              isFinal: true,
+              text: "hello from twilio"
+            },
+            type: "final"
+          });
+        }
+        for (const handler of listeners.endOfTurn) {
+          handler({
+            receivedAt,
+            reason: "vendor",
+            type: "endOfTurn"
+          });
+        }
+      }
+    };
+  }
+});
+var createFakeTTSAdapter = (chunkCount, chunkDelayMs) => ({
+  kind: "tts",
+  open: () => {
+    const listeners = {
+      audio: new Set,
+      close: new Set,
+      error: new Set
+    };
+    return {
+      close: async () => {
+        for (const handler of listeners.close) {
+          handler({ type: "close" });
+        }
+      },
+      on: (event, handler) => {
+        listeners[event].add(handler);
+        return () => {
+          listeners[event].delete(handler);
+        };
+      },
+      send: async () => {
+        for (let index = 0;index < chunkCount; index += 1) {
+          if (chunkDelayMs > 0) {
+            await Bun.sleep(chunkDelayMs);
+          }
+          const chunk = new Uint8Array(320);
+          for (let byteIndex = 0;byteIndex < chunk.length; byteIndex += 2) {
+            chunk[byteIndex] = 255;
+            chunk[byteIndex + 1] = 31;
+          }
+          for (const handler of listeners.audio) {
+            handler({
+              chunk,
+              format: DEFAULT_PCM16_FORMAT,
+              receivedAt: Date.now(),
+              type: "audio"
+            });
+          }
+        }
+      }
+    };
+  }
+});
+var defaultOperationsRecordHref = ({
+  sessionId
+}) => `/voice-operations/${encodeURIComponent(sessionId)}`;
+var resolveOperationsRecordHref = (href, input) => typeof href === "function" ? href(input) : href === undefined ? defaultOperationsRecordHref(input) : href;
+var runVoiceTelephonyMediaOperationsSmoke = async (options = {}) => {
+  const timeoutMs = options.timeoutMs ?? 5000;
+  const sessionId = options.sessionId ?? `telephony-media-ops-${Date.now()}`;
+  const streamSid = options.streamSid ?? "telephony-media-ops-stream";
+  const callSid = options.callSid ?? "telephony-media-ops-call";
+  const scenarioId = options.scenarioId ?? "telephony-media-operations-smoke";
+  const trace = options.store ?? createVoiceMemoryTraceEventStore();
+  const sentEvents = [];
+  const receivedAudio = [];
+  const bridge = createTwilioMediaStreamBridge({
+    close: () => {},
+    send: (data) => {
+      sentEvents.push(JSON.parse(data));
+    }
+  }, {
+    context: {},
+    onComplete: async () => {},
+    onTurn: async () => ({
+      assistantText: "Confirmed. Two way carrier media is visible."
+    }),
+    session: createVoiceMemoryStore(),
+    stt: createFakeSTTAdapter(receivedAudio, 0),
+    trace,
+    tts: createFakeTTSAdapter(1, 0),
+    turnDetection: {
+      transcriptStabilityMs: 0
+    }
+  });
+  const payload = encodeTwilioMulawBase64(new Int16Array([500, -500, 1500, -1500, 2500, -2500]));
+  await bridge.handleMessage({
+    event: "start",
+    start: {
+      callSid,
+      customParameters: {
+        scenarioId,
+        sessionId
+      },
+      streamSid
+    },
+    streamSid
+  });
+  await bridge.handleMessage({
+    event: "media",
+    media: {
+      payload,
+      track: "inbound"
+    },
+    streamSid
+  });
+  await waitFor(() => sentEvents.some((message) => message.event === "media"), timeoutMs);
+  await bridge.handleMessage({
+    event: "media",
+    media: {
+      payload,
+      track: "inbound"
+    },
+    streamSid
+  });
+  await waitFor(() => sentEvents.some((message) => message.event === "clear"), timeoutMs);
+  await bridge.handleMessage({
+    event: "stop",
+    stop: {
+      callSid
+    },
+    streamSid
+  });
+  await bridge.close("telephony-media-operations-smoke-complete");
+  const operationsRecord = await buildVoiceOperationsRecord({
+    sessionId,
+    store: trace
+  });
+  const media = operationsRecord.telephonyMedia;
+  const issues = [
+    media.starts < 1 ? "Missing telephony media start event." : undefined,
+    media.stops < 1 ? "Missing telephony media stop event." : undefined,
+    media.inbound < 2 ? "Expected at least two inbound telephony media events." : undefined,
+    media.outbound < 2 ? "Expected outbound assistant media/control evidence." : undefined,
+    media.media < 3 ? "Expected inbound and outbound telephony media packet evidence." : undefined,
+    media.clears < 1 ? "Missing outbound clear evidence." : undefined,
+    media.audioBytes <= 0 ? "Missing telephony media audio bytes." : undefined,
+    media.carriers.includes("twilio") ? undefined : "Missing Twilio carrier evidence.",
+    media.streamIds.includes(streamSid) ? undefined : "Missing telephony media stream ID evidence."
+  ].filter((issue) => typeof issue === "string");
+  return {
+    issues,
+    ok: issues.length === 0,
+    operationsRecord,
+    operationsRecordHref: resolveOperationsRecordHref(options.operationsRecordHref, { sessionId, streamSid }),
+    sentEvents: sentEvents.map((message) => message.event).filter((event) => typeof event === "string"),
+    sessionId,
+    streamSid,
+    telephonyMedia: media
+  };
+};
+var getDefaultVoiceTelephonyBenchmarkScenarios = () => DEFAULT_SCENARIOS.map((scenario) => ({ ...scenario }));
+var runVoiceTelephonyBenchmarkScenario = async (scenario, options = {}) => {
+  const timeoutMs = options.timeoutMs ?? 1000;
+  const sentEvents = [];
+  const receivedAudio = [];
+  const bridge = createTwilioMediaStreamBridge({
+    close: () => {},
+    send: (data) => {
+      sentEvents.push({
+        at: Date.now(),
+        event: JSON.parse(data)
+      });
+    }
+  }, {
+    context: {},
+    onComplete: async () => {},
+    onTurn: async () => ({
+      assistantText: "Copy that."
+    }),
+    session: createVoiceMemoryStore(),
+    stt: createFakeSTTAdapter(receivedAudio, scenario.sttDelayMs ?? 0),
+    tts: createFakeTTSAdapter(scenario.ttsChunkCount ?? 2, scenario.ttsChunkDelayMs ?? 0),
+    turnDetection: {
+      transcriptStabilityMs: 0
+    }
+  });
+  const startedAt = Date.now();
+  let secondInboundAt;
+  try {
+    await bridge.handleMessage({
+      event: "start",
+      start: {
+        callSid: "CA-benchmark",
+        customParameters: {
+          scenarioId: scenario.id,
+          sessionId: `phone-${scenario.id}`
+        },
+        streamSid: "MZ-benchmark"
+      },
+      streamSid: "MZ-benchmark"
+    });
+    await bridge.handleMessage({
+      event: "media",
+      media: {
+        payload: encodeTwilioMulawBase64(new Int16Array([500, -500, 1500, -1500, 2500, -2500])),
+        track: "inbound"
+      },
+      streamSid: "MZ-benchmark"
+    });
+    const sawOutboundMedia = await waitFor(() => sentEvents.some((entry) => entry.event.event === "media"), timeoutMs);
+    if (scenario.expectClear) {
+      if (scenario.secondInboundDelayMs) {
+        await Bun.sleep(scenario.secondInboundDelayMs);
+      }
+      secondInboundAt = Date.now();
+      await bridge.handleMessage({
+        event: "media",
+        media: {
+          payload: encodeTwilioMulawBase64(new Int16Array([200, -200, 200, -200])),
+          track: "inbound"
+        },
+        streamSid: "MZ-benchmark"
+      });
+    }
+    await waitFor(() => (!scenario.expectOutboundMedia || sawOutboundMedia) && (!scenario.expectMark || sentEvents.some((entry) => entry.event.event === "mark")) && (!scenario.expectClear || sentEvents.some((entry) => entry.event.event === "clear")), timeoutMs);
+  } finally {
+    await bridge.close("telephony-benchmark");
+  }
+  const outboundMediaEvents = sentEvents.filter((entry) => entry.event.event === "media");
+  const markEvents = sentEvents.filter((entry) => entry.event.event === "mark");
+  const clearEvents = sentEvents.filter((entry) => entry.event.event === "clear");
+  const firstOutboundMediaAt = outboundMediaEvents[0]?.at;
+  const firstMarkAt = markEvents[0]?.at;
+  const firstClearAt = clearEvents[0]?.at;
+  const passes = (!scenario.expectOutboundMedia || outboundMediaEvents.length > 0) && (!scenario.expectMark || markEvents.length > 0) && (!scenario.expectClear || clearEvents.length > 0);
+  return {
+    clearCount: clearEvents.length,
+    clearLatencyMs: secondInboundAt !== undefined && firstClearAt !== undefined ? firstClearAt - secondInboundAt : undefined,
+    elapsedMs: Date.now() - startedAt,
+    expectClear: scenario.expectClear,
+    expectMark: scenario.expectMark,
+    expectOutboundMedia: scenario.expectOutboundMedia,
+    fixtureId: scenario.id,
+    firstOutboundMediaLatencyMs: firstOutboundMediaAt !== undefined ? firstOutboundMediaAt - startedAt : undefined,
+    markCount: markEvents.length,
+    markLatencyMs: firstMarkAt !== undefined ? firstMarkAt - startedAt : undefined,
+    outboundMediaCount: outboundMediaEvents.length,
+    passes,
+    receivedAudioBytes: receivedAudio.reduce((sum, chunk) => sum + chunk.byteLength, 0),
+    title: scenario.title
+  };
+};
+var summarizeVoiceTelephonyBenchmark = (fixtures) => {
+  const scenarioCount = fixtures.length;
+  const firstMediaSamples = fixtures.filter((fixture) => typeof fixture.firstOutboundMediaLatencyMs === "number");
+  const markSamples = fixtures.filter((fixture) => typeof fixture.markLatencyMs === "number");
+  const clearSamples = fixtures.filter((fixture) => typeof fixture.clearLatencyMs === "number");
+  const passCount = fixtures.filter((fixture) => fixture.passes).length;
+  return {
+    averageClearLatencyMs: clearSamples.length > 0 ? clearSamples.reduce((sum, fixture) => sum + fixture.clearLatencyMs, 0) / clearSamples.length : undefined,
+    averageElapsedMs: scenarioCount > 0 ? fixtures.reduce((sum, fixture) => sum + fixture.elapsedMs, 0) / scenarioCount : 0,
+    averageFirstOutboundMediaLatencyMs: firstMediaSamples.length > 0 ? firstMediaSamples.reduce((sum, fixture) => sum + fixture.firstOutboundMediaLatencyMs, 0) / firstMediaSamples.length : undefined,
+    averageMarkLatencyMs: markSamples.length > 0 ? markSamples.reduce((sum, fixture) => sum + fixture.markLatencyMs, 0) / markSamples.length : undefined,
+    passCount,
+    passRate: scenarioCount > 0 ? passCount / scenarioCount : 0,
+    scenarioCount,
+    totalOutboundMediaCount: fixtures.reduce((sum, fixture) => sum + fixture.outboundMediaCount, 0)
+  };
+};
+var runVoiceTelephonyBenchmark = async (scenarios = getDefaultVoiceTelephonyBenchmarkScenarios(), options = {}) => {
+  const fixtures = [];
+  for (const scenario of scenarios) {
+    fixtures.push(await runVoiceTelephonyBenchmarkScenario(scenario, options));
+  }
+  return {
+    fixtures,
+    generatedAt: Date.now(),
+    summary: summarizeVoiceTelephonyBenchmark(fixtures)
+  };
+};
 // src/telephony/response.ts
 var normalizeWhitespace = (value) => value.replace(/\s+/g, " ").trim();
 var DEFAULT_MAX_WORDS = 12;
@@ -35584,6 +35945,7 @@ export {
   summarizeVoiceTraceTimeline,
   summarizeVoiceTraceSinkDeliveries,
   summarizeVoiceTrace,
+  summarizeVoiceTelephonyBenchmark,
   summarizeVoiceSessions,
   summarizeVoiceSessionReplay,
   summarizeVoiceRoutingSessions,
@@ -35616,6 +35978,9 @@ export {
   saveVoiceIncidentBundleArtifact,
   runVoiceToolContractSuite,
   runVoiceToolContract,
+  runVoiceTelephonyMediaOperationsSmoke,
+  runVoiceTelephonyBenchmarkScenario,
+  runVoiceTelephonyBenchmark,
   runVoiceSimulationSuite,
   runVoiceSessionEvals,
   runVoiceScenarioFixtureEvals,
@@ -35759,6 +36124,7 @@ export {
   getVoiceCampaignDialerProofStatus,
   getLatestVoiceTelephonyMediaReport,
   getLatestVoiceBrowserMediaReport,
+  getDefaultVoiceTelephonyBenchmarkScenarios,
   formatVoiceProofTrendAge,
   filterVoiceTraceEvents,
   filterVoiceAuditEvents,