@absolutejs/voice 0.0.22-beta.27 → 0.0.22-beta.29

package/dist/angular/index.js

@@ -596,6 +596,7 @@ class VoiceStreamService {
     const stream = createVoiceStream(path, options);
     const assistantAudioSignal = signal([]);
     const assistantTextsSignal = signal([]);
+    const callSignal = signal(null);
     const errorSignal = signal(null);
     const isConnectedSignal = signal(false);
     const partialSignal = signal("");
@@ -605,6 +606,7 @@ class VoiceStreamService {
     const sync = () => {
       assistantAudioSignal.set([...stream.assistantAudio]);
       assistantTextsSignal.set([...stream.assistantTexts]);
+      callSignal.set(stream.call);
       errorSignal.set(stream.error);
       isConnectedSignal.set(stream.isConnected);
       partialSignal.set(stream.partial);
@@ -617,6 +619,8 @@ class VoiceStreamService {
     return {
       assistantAudio: computed(() => assistantAudioSignal()),
       assistantTexts: computed(() => assistantTextsSignal()),
+      call: computed(() => callSignal()),
+      callControl: (message) => stream.callControl(message),
       close: () => {
         unsubscribe();
         stream.close();

package/dist/angular/voice-stream.service.d.ts

@@ -8,6 +8,8 @@ export declare class VoiceStreamService {
             turnId?: string;
         }[]>;
         assistantTexts: import("@angular/core").Signal<string[]>;
+        call: import("@angular/core").Signal<import("..").VoiceCallLifecycleState | null>;
+        callControl: (message: Parameters<(message: Omit<import("..").VoiceClientCallControlMessage, "type">) => void>[0]) => void;
         close: () => void;
         endTurn: () => void;
         error: import("@angular/core").Signal<string | null>;

package/dist/handoff.d.ts

@@ -0,0 +1,40 @@
+import type { VoiceHandoffAction, VoiceHandoffAdapter, VoiceHandoffConfig, VoiceHandoffInput, VoiceHandoffResult, VoiceSessionRecord } from './types';
+type MaybePromise<T> = T | Promise<T>;
+export type VoiceHandoffDelivery = VoiceHandoffResult & {
+    adapterId: string;
+    adapterKind?: string;
+};
+export type VoiceHandoffFanoutResult = {
+    action: VoiceHandoffAction;
+    deliveries: Record<string, VoiceHandoffDelivery>;
+    status: VoiceHandoffResult['status'];
+};
+export type VoiceWebhookHandoffAdapterOptions<TContext = unknown, TSession extends VoiceSessionRecord = VoiceSessionRecord, TResult = unknown> = {
+    actions?: VoiceHandoffAction[];
+    body?: (input: VoiceHandoffInput<TContext, TSession, TResult>) => MaybePromise<Record<string, unknown>>;
+    fetch?: typeof fetch;
+    headers?: Record<string, string>;
+    id: string;
+    kind?: string;
+    method?: 'POST' | 'PUT' | 'PATCH';
+    signingSecret?: string;
+    timeoutMs?: number;
+    url: string;
+};
+export type VoiceTwilioRedirectHandoffAdapterOptions<TContext = unknown, TSession extends VoiceSessionRecord = VoiceSessionRecord, TResult = unknown> = {
+    accountSid: string;
+    actions?: VoiceHandoffAction[];
+    authToken: string;
+    buildTwiML?: (input: VoiceHandoffInput<TContext, TSession, TResult>) => MaybePromise<string>;
+    callSid?: string | ((input: VoiceHandoffInput<TContext, TSession, TResult>) => MaybePromise<string | undefined>);
+    fetch?: typeof fetch;
+    id?: string;
+    timeoutMs?: number;
+};
+export declare const deliverVoiceHandoff: <TContext, TSession extends VoiceSessionRecord, TResult>(input: {
+    config?: VoiceHandoffConfig<TContext, TSession, TResult>;
+    handoff: VoiceHandoffInput<TContext, TSession, TResult>;
+}) => Promise<VoiceHandoffFanoutResult | undefined>;
+export declare const createVoiceWebhookHandoffAdapter: <TContext = unknown, TSession extends VoiceSessionRecord = VoiceSessionRecord, TResult = unknown>(options: VoiceWebhookHandoffAdapterOptions<TContext, TSession, TResult>) => VoiceHandoffAdapter<TContext, TSession, TResult>;
+export declare const createVoiceTwilioRedirectHandoffAdapter: <TContext = unknown, TSession extends VoiceSessionRecord = VoiceSessionRecord, TResult = unknown>(options: VoiceTwilioRedirectHandoffAdapterOptions<TContext, TSession, TResult>) => VoiceHandoffAdapter<TContext, TSession, TResult>;
+export {};

package/dist/index.d.ts

@@ -14,6 +14,7 @@ export { createVoiceS3ReviewStore } from './s3Store';
 export { createVoiceMemoryStore } from './memoryStore';
 export { createVoiceCRMActivitySink, createVoiceHelpdeskTicketSink, createVoiceIntegrationHTTPSink, createVoiceHubSpotTaskSink, createVoiceHubSpotTaskSyncSinks, createVoiceHubSpotTaskUpdateSink, createVoiceLinearIssueSink, createVoiceLinearIssueSyncSinks, createVoiceLinearIssueUpdateSink, createVoiceZendeskTicketSink, createVoiceZendeskTicketSyncSinks, createVoiceZendeskTicketUpdateSink, deliverVoiceIntegrationEventToSinks } from './opsSinks';
 export { createVoiceOpsWebhookEnvelope, createVoiceOpsWebhookReceiverRoutes, createVoiceOpsWebhookSink, verifyVoiceOpsWebhookSignature } from './opsWebhook';
+export { createVoiceTwilioRedirectHandoffAdapter, createVoiceWebhookHandoffAdapter, deliverVoiceHandoff } from './handoff';
 export { createVoiceIntegrationSinkWorker, createVoiceIntegrationSinkWorkerLoop, createVoiceOpsTaskWorker, createVoiceOpsTaskProcessorWorker, createVoiceOpsTaskProcessorWorkerLoop, createVoiceRedisIdempotencyStore, createVoiceRedisTaskLeaseCoordinator, createVoiceTraceSinkDeliveryWorker, createVoiceTraceSinkDeliveryWorkerLoop, createVoiceWebhookDeliveryWorker, createVoiceWebhookDeliveryWorkerLoop, summarizeVoiceTraceSinkDeliveries, summarizeVoiceOpsTaskQueue, summarizeVoiceIntegrationEvents } from './queue';
 export { assignVoiceOpsTask, applyVoiceOpsTaskAssignmentRule, applyVoiceOpsTaskPolicy, buildVoiceOpsTaskFromReview, buildVoiceOpsTaskFromSLABreach, claimVoiceOpsTask, completeVoiceOpsTask, createVoiceExternalObjectMap, createVoiceExternalObjectMapId, createVoiceCallCompletedEvent, createVoiceTaskSLABreachedEvent, deadLetterVoiceOpsTask, deliverVoiceIntegrationEvent, failVoiceOpsTask, hasVoiceOpsTaskSLABreach, heartbeatVoiceOpsTask, isVoiceOpsTaskOverdue, markVoiceOpsTaskSLABreached, matchesVoiceOpsTaskAssignmentRule, resolveVoiceOpsTaskAgeBucket, createVoiceIntegrationEvent, createVoiceReviewSavedEvent, resolveVoiceOpsTaskAssignment, resolveVoiceOpsTaskPolicy, requeueVoiceOpsTask, createVoiceTaskCreatedEvent, createVoiceTaskUpdatedEvent, listVoiceOpsTasks, reopenVoiceOpsTask, startVoiceOpsTask, summarizeVoiceOpsTaskAnalytics, summarizeVoiceOpsTasks, withVoiceIntegrationEventId, withVoiceOpsTaskId } from './ops';
 export { createVoiceSession } from './session';
@@ -40,6 +41,7 @@ export type { VoiceOpsPresetName, VoiceOpsPresetOverrides, VoiceResolvedOpsPrese
 export type { VoiceOutcomeRecipe, VoiceOutcomeRecipeName, VoiceOutcomeRecipeOptions } from './outcomeRecipes';
 export type { VoiceCRMActivitySinkOptions, VoiceHubSpotTaskSinkOptions, VoiceHubSpotTaskUpdateSinkOptions, VoiceHelpdeskTicketSinkOptions, VoiceIntegrationHTTPSinkOptions, VoiceIntegrationSink, VoiceIntegrationSinkDeliveryResult, VoiceLinearIssueSinkOptions, VoiceLinearIssueUpdateSinkOptions, VoiceZendeskTicketSinkOptions, VoiceZendeskTicketUpdateSinkOptions } from './opsSinks';
 export type { VoiceOpsWebhookEnvelope, VoiceOpsWebhookEntity, VoiceOpsWebhookLinkResolver, VoiceOpsWebhookReceiverRoutesOptions, VoiceOpsWebhookSinkOptions, VoiceOpsWebhookVerificationResult } from './opsWebhook';
+export type { VoiceHandoffDelivery, VoiceHandoffFanoutResult, VoiceTwilioRedirectHandoffAdapterOptions, VoiceWebhookHandoffAdapterOptions } from './handoff';
 export type { StoredVoiceCallReviewArtifact, VoiceCallReviewArtifact, VoiceCallReviewConfig, VoiceCallReviewPostCallSummary, VoiceCallReviewRecorder, VoiceCallReviewRecorderOptions, VoiceCallReviewStore, VoiceCallReviewSummary, VoiceCallReviewTimelineEvent } from './testing/review';
 export type { VoiceFileRuntimeStorage, VoiceFileStoreOptions } from './fileStore';
 export type { StoredVoiceTraceEvent, VoiceTraceEvaluation, VoiceTraceEvaluationOptions, VoiceTraceEvent, VoiceTraceEventFilter, VoiceTraceEventStore, VoiceTraceEventType, VoiceTraceIssue, VoiceTraceIssueSeverity, VoiceTraceHTTPSinkOptions, VoiceTracePruneFilter, VoiceTracePruneOptions, VoiceTracePruneResult, VoiceTraceRedactionConfig, VoiceTraceRedactionOptions, VoiceTraceRedactionReplacement, VoiceResolvedTraceRedactionOptions, VoiceTraceSink, VoiceTraceSinkDeliveryQueueStatus, VoiceTraceSinkDeliveryRecord, VoiceTraceSinkDeliveryResult, VoiceTraceSinkDeliveryStatus, VoiceTraceSinkDeliveryStore, VoiceTraceSinkFanoutResult, VoiceTraceSinkStoreOptions, VoiceTraceSummary } from './trace';

package/dist/index.js

@@ -2992,6 +2992,214 @@ var toVoiceSessionSummary = (session) => ({
 // src/session.ts
 import { Buffer } from "buffer";
 
+// src/handoff.ts
+var toHex3 = (bytes) => Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
+var signHandoffBody = async (input) => {
+  const encoder = new TextEncoder;
+  const key = await crypto.subtle.importKey("raw", encoder.encode(input.secret), {
+    hash: "SHA-256",
+    name: "HMAC"
+  }, false, ["sign"]);
+  const signature = await crypto.subtle.sign("HMAC", key, encoder.encode(`${input.timestamp}.${input.body}`));
+  return `sha256=${toHex3(new Uint8Array(signature))}`;
+};
+var toErrorMessage2 = (error) => error instanceof Error ? error.message : String(error);
+var createSkippedDelivery = (adapter) => ({
+  adapterId: adapter.id,
+  adapterKind: adapter.kind,
+  status: "skipped"
+});
+var aggregateHandoffStatus = (deliveries) => {
+  const statuses = Object.values(deliveries).map((delivery) => delivery.status);
+  if (statuses.some((status) => status === "failed")) {
+    return "failed";
+  }
+  if (statuses.some((status) => status === "delivered")) {
+    return "delivered";
+  }
+  return "skipped";
+};
+var defaultWebhookBody = (input) => ({
+  action: input.action,
+  metadata: input.metadata,
+  reason: input.reason,
+  result: input.result,
+  session: {
+    id: input.session.id,
+    scenarioId: input.session.scenarioId,
+    status: input.session.status
+  },
+  source: "absolutejs-voice",
+  target: input.target
+});
+var deliverVoiceHandoff = async (input) => {
+  if (!input.config || input.config.adapters.length === 0) {
+    return;
+  }
+  const deliveries = {};
+  for (const adapter of input.config.adapters) {
+    if (adapter.actions && !adapter.actions.includes(input.handoff.action)) {
+      deliveries[adapter.id] = createSkippedDelivery(adapter);
+      continue;
+    }
+    try {
+      const result = await adapter.handoff(input.handoff);
+      deliveries[adapter.id] = {
+        ...result,
+        adapterId: adapter.id,
+        adapterKind: adapter.kind
+      };
+    } catch (error) {
+      deliveries[adapter.id] = {
+        adapterId: adapter.id,
+        adapterKind: adapter.kind,
+        error: toErrorMessage2(error),
+        status: "failed"
+      };
+      if (input.config.failMode === "throw") {
+        throw error;
+      }
+    }
+  }
+  return {
+    action: input.handoff.action,
+    deliveries,
+    status: aggregateHandoffStatus(deliveries)
+  };
+};
+var createVoiceWebhookHandoffAdapter = (options) => ({
+  actions: options.actions,
+  handoff: async (input) => {
+    const fetchImpl = options.fetch ?? globalThis.fetch;
+    if (typeof fetchImpl !== "function") {
+      return {
+        deliveredTo: options.url,
+        error: "Handoff delivery failed: fetch is not available in this runtime.",
+        status: "failed"
+      };
+    }
+    const body = JSON.stringify(await options.body?.(input) ?? defaultWebhookBody(input));
+    const headers = {
+      "content-type": "application/json",
+      ...options.headers
+    };
+    if (options.signingSecret) {
+      const timestamp = String(Date.now());
+      headers["x-absolutejs-timestamp"] = timestamp;
+      headers["x-absolutejs-signature"] = await signHandoffBody({
+        body,
+        secret: options.signingSecret,
+        timestamp
+      });
+    }
+    const controller = options.timeoutMs && options.timeoutMs > 0 ? new AbortController : undefined;
+    const timeout = controller && options.timeoutMs ? setTimeout(() => controller.abort(), options.timeoutMs) : undefined;
+    try {
+      const response = await fetchImpl(options.url, {
+        body,
+        headers,
+        method: options.method ?? "POST",
+        signal: controller?.signal
+      });
+      if (!response.ok) {
+        return {
+          deliveredTo: options.url,
+          error: `Handoff delivery failed with response ${response.status}.`,
+          status: "failed"
+        };
+      }
+      return {
+        deliveredAt: Date.now(),
+        deliveredTo: options.url,
+        status: "delivered"
+      };
+    } finally {
+      if (timeout) {
+        clearTimeout(timeout);
+      }
+    }
+  },
+  id: options.id,
+  kind: options.kind ?? "webhook"
+});
+var escapeXml = (value) => value.replaceAll("&", "&amp;").replaceAll('"', "&quot;").replaceAll("'", "&apos;").replaceAll("<", "&lt;").replaceAll(">", "&gt;");
+var defaultTwilioTransferTwiML = (input) => {
+  if (!input.target) {
+    return "<Response><Hangup /></Response>";
+  }
+  return `<Response><Dial>${escapeXml(input.target)}</Dial></Response>`;
+};
+var resolveTwilioCallSid = async (resolver, input) => {
+  if (typeof resolver === "function") {
+    return resolver(input);
+  }
+  if (typeof resolver === "string" && resolver.length > 0) {
+    return resolver;
+  }
+  const metadataSid = typeof input.metadata?.callSid === "string" ? input.metadata.callSid : undefined;
+  const sessionMetadata = input.session.metadata && typeof input.session.metadata === "object" ? input.session.metadata : undefined;
+  const sessionSid = typeof sessionMetadata?.callSid === "string" ? sessionMetadata.callSid : undefined;
+  return metadataSid ?? sessionSid;
+};
+var createVoiceTwilioRedirectHandoffAdapter = (options) => ({
+  actions: options.actions ?? ["transfer"],
+  handoff: async (input) => {
+    const fetchImpl = options.fetch ?? globalThis.fetch;
+    const callSid = await resolveTwilioCallSid(options.callSid, input);
+    if (!callSid) {
+      return {
+        error: "Twilio handoff requires a callSid.",
+        status: "failed"
+      };
+    }
+    if (typeof fetchImpl !== "function") {
+      return {
+        error: "Twilio handoff failed: fetch is not available in this runtime.",
+        status: "failed"
+      };
+    }
+    const url = `https://api.twilio.com/2010-04-01/Accounts/${encodeURIComponent(options.accountSid)}/Calls/${encodeURIComponent(callSid)}.json`;
+    const body = new URLSearchParams({
+      Twiml: await (options.buildTwiML?.(input) ?? defaultTwilioTransferTwiML(input))
+    });
+    const auth = btoa(`${options.accountSid}:${options.authToken}`);
+    const controller = options.timeoutMs && options.timeoutMs > 0 ? new AbortController : undefined;
+    const timeout = controller && options.timeoutMs ? setTimeout(() => controller.abort(), options.timeoutMs) : undefined;
+    try {
+      const response = await fetchImpl(url, {
+        body,
+        headers: {
+          authorization: `Basic ${auth}`,
+          "content-type": "application/x-www-form-urlencoded"
+        },
+        method: "POST",
+        signal: controller?.signal
+      });
+      if (!response.ok) {
+        return {
+          deliveredTo: url,
+          error: `Twilio handoff failed with response ${response.status}.`,
+          status: "failed"
+        };
+      }
+      return {
+        deliveredAt: Date.now(),
+        deliveredTo: url,
+        metadata: {
+          callSid
+        },
+        status: "delivered"
+      };
+    } finally {
+      if (timeout) {
+        clearTimeout(timeout);
+      }
+    }
+  },
+  id: options.id ?? "twilio-redirect",
+  kind: "twilio-redirect"
+});
+
 // src/turnDetection.ts
 var DEFAULT_SILENCE_MS = 700;
 var DEFAULT_SPEECH_THRESHOLD = 0.015;
@@ -3400,6 +3608,34 @@ var createVoiceSession = (options) => {
       type: "call_lifecycle"
     });
   };
+  const runHandoff = async (input) => {
+    const result = await deliverVoiceHandoff({
+      config: options.handoff,
+      handoff: {
+        action: input.action,
+        api,
+        context: options.context,
+        metadata: input.metadata,
+        reason: input.reason,
+        result: input.result,
+        session: input.session,
+        target: input.target
+      }
+    });
+    if (!result) {
+      return;
+    }
+    await appendTrace({
+      metadata: input.metadata,
+      payload: {
+        ...result,
+        reason: input.reason,
+        target: input.target
+      },
+      session: input.session,
+      type: "call.handoff"
+    });
+  };
   const readSession = async () => options.store.getOrCreate(options.id);
   const writeSession = async (mutate) => {
     const session = await options.store.getOrCreate(options.id);
@@ -3679,6 +3915,14 @@ var createVoiceSession = (options) => {
       type: "call.lifecycle"
     });
     await sendCallLifecycle(session);
+    await runHandoff({
+      action: "transfer",
+      metadata: input.metadata,
+      reason: input.reason,
+      result: input.result,
+      session,
+      target: input.target
+    });
     await completeInternal(input.result, {
       disposition: "transferred",
       invokeOnComplete: false,
@@ -3705,6 +3949,13 @@ var createVoiceSession = (options) => {
       type: "call.lifecycle"
     });
     await sendCallLifecycle(session);
+    await runHandoff({
+      action: "escalate",
+      metadata: input.metadata,
+      reason: input.reason,
+      result: input.result,
+      session
+    });
     await completeInternal(input.result, {
       disposition: "escalated",
       invokeOnComplete: false,
@@ -3728,6 +3979,12 @@ var createVoiceSession = (options) => {
       type: "call.lifecycle"
     });
     await sendCallLifecycle(session);
+    await runHandoff({
+      action: "no-answer",
+      metadata: input?.metadata,
+      result: input?.result,
+      session
+    });
     await completeInternal(input?.result, {
       disposition: "no-answer",
       invokeOnComplete: false,
@@ -3750,6 +4007,12 @@ var createVoiceSession = (options) => {
       type: "call.lifecycle"
     });
     await sendCallLifecycle(session);
+    await runHandoff({
+      action: "voicemail",
+      metadata: input?.metadata,
+      result: input?.result,
+      session
+    });
     await completeInternal(input?.result, {
       disposition: "voicemail",
       invokeOnComplete: false,
@@ -4922,6 +5185,7 @@ var voice = (config) => {
       audioConditioning: sessionOptions.audioConditioning,
       context,
       id: sessionId,
+      handoff: config.handoff,
       languageStrategy: config.languageStrategy,
       lexicon,
       logger: sessionOptions.logger,
@@ -5117,7 +5381,7 @@ var voice = (config) => {
 };
 // src/agent.ts
 var normalizeText3 = (value) => typeof value === "string" ? value.trim() : "";
-var toErrorMessage2 = (error) => error instanceof Error ? error.message : String(error);
+var toErrorMessage3 = (error) => error instanceof Error ? error.message : String(error);
 var createHistoryMessages = (session, turn) => {
   const messages = [];
   for (const previousTurn of session.turns) {
@@ -5298,7 +5562,7 @@ var createVoiceAgent = (options) => {
             toolCallId: toolCall.id
           });
         } catch (error) {
-          const errorMessage = toErrorMessage2(error);
+          const errorMessage = toErrorMessage3(error);
           toolResults.push({
             error: errorMessage,
             status: "error",
@@ -6563,7 +6827,7 @@ var sleep3 = async (delayMs) => {
   }
   await new Promise((resolve2) => setTimeout(resolve2, delayMs));
 };
-var toHex3 = (bytes) => Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
+var toHex4 = (bytes) => Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
 var signVoiceTraceSinkBody = async (input) => {
   const encoder = new TextEncoder;
   const key = await crypto.subtle.importKey("raw", encoder.encode(input.secret), {
@@ -6572,7 +6836,7 @@ var signVoiceTraceSinkBody = async (input) => {
   }, false, ["sign"]);
   const payload = encoder.encode(`${input.timestamp}.${input.body}`);
   const signature = await crypto.subtle.sign("HMAC", key, payload);
-  return `sha256=${toHex3(new Uint8Array(signature))}`;
+  return `sha256=${toHex4(new Uint8Array(signature))}`;
 };
 var createVoiceTraceSinkDeliveryError = (input) => {
   if (input.response) {
@@ -8937,7 +9201,7 @@ var createVoiceMemoryStore = () => {
 };
 // src/opsWebhook.ts
 import { Elysia as Elysia5 } from "elysia";
-var toHex4 = (bytes) => Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
+var toHex5 = (bytes) => Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
 var signVoiceOpsWebhookBody = async (input) => {
   const encoder = new TextEncoder;
   const key = await crypto.subtle.importKey("raw", encoder.encode(input.secret), {
@@ -8945,7 +9209,7 @@ var signVoiceOpsWebhookBody = async (input) => {
     name: "HMAC"
   }, false, ["sign"]);
   const signature = await crypto.subtle.sign("HMAC", key, encoder.encode(`${input.timestamp}.${input.body}`));
-  return `sha256=${toHex4(new Uint8Array(signature))}`;
+  return `sha256=${toHex5(new Uint8Array(signature))}`;
 };
 var timingSafeEqual = (left, right) => {
   const encoder = new TextEncoder;
@@ -10630,7 +10894,7 @@ var createVoiceSTTRoutingCorrectionHandler = (mode = "generic") => {
 import { Buffer as Buffer2 } from "buffer";
 var TWILIO_MULAW_SAMPLE_RATE = 8000;
 var VOICE_PCM_SAMPLE_RATE = 16000;
-var escapeXml = (value) => value.replaceAll("&", "&amp;").replaceAll('"', "&quot;").replaceAll("'", "&apos;").replaceAll("<", "&lt;").replaceAll(">", "&gt;");
+var escapeXml2 = (value) => value.replaceAll("&", "&amp;").replaceAll('"', "&quot;").replaceAll("'", "&apos;").replaceAll("<", "&lt;").replaceAll(">", "&gt;");
 var normalizeOnTurn2 = (handler) => {
   if (handler.length > 1) {
     const directHandler = handler;
@@ -10826,8 +11090,8 @@ var createTwilioSocketAdapter = (socket, getState) => ({
   }
 });
 var createTwilioVoiceResponse = (options) => {
-  const parameters = Object.entries(options.parameters ?? {}).filter((entry) => entry[1] !== undefined).map(([name, value]) => `<Parameter name="${escapeXml(name)}" value="${escapeXml(String(value))}" />`).join("");
-  return `<?xml version="1.0" encoding="UTF-8"?><Response><Connect><Stream url="${escapeXml(options.streamUrl)}"${options.track ? ` track="${escapeXml(options.track)}"` : ""}${options.streamName ? ` name="${escapeXml(options.streamName)}"` : ""}>${parameters}</Stream></Connect></Response>`;
+  const parameters = Object.entries(options.parameters ?? {}).filter((entry) => entry[1] !== undefined).map(([name, value]) => `<Parameter name="${escapeXml2(name)}" value="${escapeXml2(String(value))}" />`).join("");
+  return `<?xml version="1.0" encoding="UTF-8"?><Response><Connect><Stream url="${escapeXml2(options.streamUrl)}"${options.track ? ` track="${escapeXml2(options.track)}"` : ""}${options.streamName ? ` name="${escapeXml2(options.streamName)}"` : ""}>${parameters}</Stream></Connect></Response>`;
 };
 var createTwilioMediaStreamBridge = (socket, options) => {
   const runtimePreset = resolveVoiceRuntimePreset(options.preset);
@@ -11119,13 +11383,16 @@ export {
   deliverVoiceTraceEventsToSinks,
   deliverVoiceIntegrationEventToSinks,
   deliverVoiceIntegrationEvent,
+  deliverVoiceHandoff,
   decodeTwilioMulawBase64,
   deadLetterVoiceOpsTask,
   createVoiceZendeskTicketUpdateSink,
   createVoiceZendeskTicketSyncSinks,
   createVoiceZendeskTicketSink,
+  createVoiceWebhookHandoffAdapter,
   createVoiceWebhookDeliveryWorkerLoop,
   createVoiceWebhookDeliveryWorker,
+  createVoiceTwilioRedirectHandoffAdapter,
   createVoiceTraceSinkStore,
   createVoiceTraceSinkDeliveryWorkerLoop,
   createVoiceTraceSinkDeliveryWorker,

package/dist/react/index.js

@@ -589,6 +589,7 @@ var createVoiceStream = (path, options = {}) => {
 var EMPTY_SNAPSHOT = {
   assistantAudio: [],
   assistantTexts: [],
+  call: null,
   error: null,
   isConnected: false,
   partial: "",
@@ -606,6 +607,7 @@ var useVoiceStream = (path, options = {}) => {
   const snapshot = useSyncExternalStore(stream.subscribe, stream.getSnapshot, stream.getServerSnapshot) ?? EMPTY_SNAPSHOT;
   return {
     ...snapshot,
+    callControl: (message) => stream.callControl(message),
     close: () => stream.close(),
     endTurn: () => stream.endTurn(),
     sendAudio: (audio) => stream.sendAudio(audio)
@@ -1248,6 +1250,7 @@ var createVoiceController = (path, options = {}) => {
 var EMPTY_SNAPSHOT2 = {
   assistantAudio: [],
   assistantTexts: [],
+  call: null,
   error: null,
   isConnected: false,
   isRecording: false,
@@ -1268,6 +1271,7 @@ var useVoiceController = (path, options = {}) => {
   return {
     ...snapshot,
     bindHTMX: controller.bindHTMX,
+    callControl: (message) => controller.callControl(message),
     close: () => controller.close(),
     endTurn: () => controller.endTurn(),
     sendAudio: (audio) => controller.sendAudio(audio),

package/dist/react/useVoiceController.d.ts

@@ -1,6 +1,7 @@
 import type { VoiceControllerOptions } from '../types';
 export declare const useVoiceController: <TResult = unknown>(path: string, options?: VoiceControllerOptions) => {
     bindHTMX: (options: import("..").VoiceHTMXBindingOptions) => () => void;
+    callControl: (message: Parameters<(message: Omit<import("..").VoiceClientCallControlMessage, "type">) => void>[0]) => void;
     close: () => void;
     endTurn: () => void;
     sendAudio: (audio: Uint8Array | ArrayBuffer) => void;

package/dist/react/useVoiceStream.d.ts

@@ -1,5 +1,6 @@
 import type { VoiceConnectionOptions } from '../types';
 export declare const useVoiceStream: <TResult = unknown>(path: string, options?: VoiceConnectionOptions) => {
+    callControl: (message: Parameters<(message: Omit<import("..").VoiceClientCallControlMessage, "type">) => void>[0]) => void;
     close: () => void;
     endTurn: () => void;
     sendAudio: (audio: Uint8Array | ArrayBuffer) => void;

package/dist/testing/index.js

@@ -4459,6 +4459,214 @@ var createVoiceMemoryStore = () => {
 // src/session.ts
 import { Buffer } from "buffer";
 
+// src/handoff.ts
+var toHex = (bytes) => Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
+var signHandoffBody = async (input) => {
+  const encoder = new TextEncoder;
+  const key = await crypto.subtle.importKey("raw", encoder.encode(input.secret), {
+    hash: "SHA-256",
+    name: "HMAC"
+  }, false, ["sign"]);
+  const signature = await crypto.subtle.sign("HMAC", key, encoder.encode(`${input.timestamp}.${input.body}`));
+  return `sha256=${toHex(new Uint8Array(signature))}`;
+};
+var toErrorMessage = (error) => error instanceof Error ? error.message : String(error);
+var createSkippedDelivery = (adapter) => ({
+  adapterId: adapter.id,
+  adapterKind: adapter.kind,
+  status: "skipped"
+});
+var aggregateHandoffStatus = (deliveries) => {
+  const statuses = Object.values(deliveries).map((delivery) => delivery.status);
+  if (statuses.some((status) => status === "failed")) {
+    return "failed";
+  }
+  if (statuses.some((status) => status === "delivered")) {
+    return "delivered";
+  }
+  return "skipped";
+};
+var defaultWebhookBody = (input) => ({
+  action: input.action,
+  metadata: input.metadata,
+  reason: input.reason,
+  result: input.result,
+  session: {
+    id: input.session.id,
+    scenarioId: input.session.scenarioId,
+    status: input.session.status
+  },
+  source: "absolutejs-voice",
+  target: input.target
+});
+var deliverVoiceHandoff = async (input) => {
+  if (!input.config || input.config.adapters.length === 0) {
+    return;
+  }
+  const deliveries = {};
+  for (const adapter of input.config.adapters) {
+    if (adapter.actions && !adapter.actions.includes(input.handoff.action)) {
+      deliveries[adapter.id] = createSkippedDelivery(adapter);
+      continue;
+    }
+    try {
+      const result = await adapter.handoff(input.handoff);
+      deliveries[adapter.id] = {
+        ...result,
+        adapterId: adapter.id,
+        adapterKind: adapter.kind
+      };
+    } catch (error) {
+      deliveries[adapter.id] = {
+        adapterId: adapter.id,
+        adapterKind: adapter.kind,
+        error: toErrorMessage(error),
+        status: "failed"
+      };
+      if (input.config.failMode === "throw") {
+        throw error;
+      }
+    }
+  }
+  return {
+    action: input.handoff.action,
+    deliveries,
+    status: aggregateHandoffStatus(deliveries)
+  };
+};
+var createVoiceWebhookHandoffAdapter = (options) => ({
+  actions: options.actions,
+  handoff: async (input) => {
+    const fetchImpl = options.fetch ?? globalThis.fetch;
+    if (typeof fetchImpl !== "function") {
+      return {
+        deliveredTo: options.url,
+        error: "Handoff delivery failed: fetch is not available in this runtime.",
+        status: "failed"
+      };
+    }
+    const body = JSON.stringify(await options.body?.(input) ?? defaultWebhookBody(input));
+    const headers = {
+      "content-type": "application/json",
+      ...options.headers
+    };
+    if (options.signingSecret) {
+      const timestamp = String(Date.now());
+      headers["x-absolutejs-timestamp"] = timestamp;
+      headers["x-absolutejs-signature"] = await signHandoffBody({
+        body,
+        secret: options.signingSecret,
+        timestamp
+      });
+    }
+    const controller = options.timeoutMs && options.timeoutMs > 0 ? new AbortController : undefined;
+    const timeout = controller && options.timeoutMs ? setTimeout(() => controller.abort(), options.timeoutMs) : undefined;
+    try {
+      const response = await fetchImpl(options.url, {
+        body,
+        headers,
+        method: options.method ?? "POST",
+        signal: controller?.signal
+      });
+      if (!response.ok) {
+        return {
+          deliveredTo: options.url,
+          error: `Handoff delivery failed with response ${response.status}.`,
+          status: "failed"
+        };
+      }
+      return {
+        deliveredAt: Date.now(),
+        deliveredTo: options.url,
+        status: "delivered"
+      };
+    } finally {
+      if (timeout) {
+        clearTimeout(timeout);
+      }
+    }
+  },
+  id: options.id,
+  kind: options.kind ?? "webhook"
+});
+var escapeXml = (value) => value.replaceAll("&", "&amp;").replaceAll('"', "&quot;").replaceAll("'", "&apos;").replaceAll("<", "&lt;").replaceAll(">", "&gt;");
+var defaultTwilioTransferTwiML = (input) => {
+  if (!input.target) {
+    return "<Response><Hangup /></Response>";
+  }
+  return `<Response><Dial>${escapeXml(input.target)}</Dial></Response>`;
+};
+var resolveTwilioCallSid = async (resolver, input) => {
+  if (typeof resolver === "function") {
+    return resolver(input);
+  }
+  if (typeof resolver === "string" && resolver.length > 0) {
+    return resolver;
+  }
+  const metadataSid = typeof input.metadata?.callSid === "string" ? input.metadata.callSid : undefined;
+  const sessionMetadata = input.session.metadata && typeof input.session.metadata === "object" ? input.session.metadata : undefined;
+  const sessionSid = typeof sessionMetadata?.callSid === "string" ? sessionMetadata.callSid : undefined;
+  return metadataSid ?? sessionSid;
+};
+var createVoiceTwilioRedirectHandoffAdapter = (options) => ({
+  actions: options.actions ?? ["transfer"],
+  handoff: async (input) => {
+    const fetchImpl = options.fetch ?? globalThis.fetch;
+    const callSid = await resolveTwilioCallSid(options.callSid, input);
+    if (!callSid) {
+      return {
+        error: "Twilio handoff requires a callSid.",
+        status: "failed"
+      };
+    }
+    if (typeof fetchImpl !== "function") {
+      return {
+        error: "Twilio handoff failed: fetch is not available in this runtime.",
+        status: "failed"
+      };
+    }
+    const url = `https://api.twilio.com/2010-04-01/Accounts/${encodeURIComponent(options.accountSid)}/Calls/${encodeURIComponent(callSid)}.json`;
+    const body = new URLSearchParams({
+      Twiml: await (options.buildTwiML?.(input) ?? defaultTwilioTransferTwiML(input))
+    });
+    const auth = btoa(`${options.accountSid}:${options.authToken}`);
+    const controller = options.timeoutMs && options.timeoutMs > 0 ? new AbortController : undefined;
+    const timeout = controller && options.timeoutMs ? setTimeout(() => controller.abort(), options.timeoutMs) : undefined;
+    try {
+      const response = await fetchImpl(url, {
+        body,
+        headers: {
+          authorization: `Basic ${auth}`,
+          "content-type": "application/x-www-form-urlencoded"
+        },
+        method: "POST",
+        signal: controller?.signal
+      });
+      if (!response.ok) {
+        return {
+          deliveredTo: url,
+          error: `Twilio handoff failed with response ${response.status}.`,
+          status: "failed"
+        };
+      }
+      return {
+        deliveredAt: Date.now(),
+        deliveredTo: url,
+        metadata: {
+          callSid
+        },
+        status: "delivered"
+      };
+    } finally {
+      if (timeout) {
+        clearTimeout(timeout);
+      }
+    }
+  },
+  id: options.id ?? "twilio-redirect",
+  kind: "twilio-redirect"
+});
+
 // src/logger.ts
 var noop2 = () => {};
 var createNoopLogger = () => ({
@@ -4763,6 +4971,34 @@ var createVoiceSession = (options) => {
       type: "call_lifecycle"
     });
   };
+  const runHandoff = async (input) => {
+    const result = await deliverVoiceHandoff({
+      config: options.handoff,
+      handoff: {
+        action: input.action,
+        api,
+        context: options.context,
+        metadata: input.metadata,
+        reason: input.reason,
+        result: input.result,
+        session: input.session,
+        target: input.target
+      }
+    });
+    if (!result) {
+      return;
+    }
+    await appendTrace({
+      metadata: input.metadata,
+      payload: {
+        ...result,
+        reason: input.reason,
+        target: input.target
+      },
+      session: input.session,
+      type: "call.handoff"
+    });
+  };
   const readSession = async () => options.store.getOrCreate(options.id);
   const writeSession = async (mutate) => {
     const session = await options.store.getOrCreate(options.id);
@@ -5042,6 +5278,14 @@ var createVoiceSession = (options) => {
       type: "call.lifecycle"
     });
     await sendCallLifecycle(session);
+    await runHandoff({
+      action: "transfer",
+      metadata: input.metadata,
+      reason: input.reason,
+      result: input.result,
+      session,
+      target: input.target
+    });
     await completeInternal(input.result, {
       disposition: "transferred",
       invokeOnComplete: false,
@@ -5068,6 +5312,13 @@ var createVoiceSession = (options) => {
       type: "call.lifecycle"
     });
     await sendCallLifecycle(session);
+    await runHandoff({
+      action: "escalate",
+      metadata: input.metadata,
+      reason: input.reason,
+      result: input.result,
+      session
+    });
     await completeInternal(input.result, {
       disposition: "escalated",
       invokeOnComplete: false,
@@ -5091,6 +5342,12 @@ var createVoiceSession = (options) => {
       type: "call.lifecycle"
     });
     await sendCallLifecycle(session);
+    await runHandoff({
+      action: "no-answer",
+      metadata: input?.metadata,
+      result: input?.result,
+      session
+    });
     await completeInternal(input?.result, {
       disposition: "no-answer",
       invokeOnComplete: false,
@@ -5113,6 +5370,12 @@ var createVoiceSession = (options) => {
       type: "call.lifecycle"
     });
     await sendCallLifecycle(session);
+    await runHandoff({
+      action: "voicemail",
+      metadata: input?.metadata,
+      result: input?.result,
+      session
+    });
     await completeInternal(input?.result, {
       disposition: "voicemail",
       invokeOnComplete: false,
@@ -6490,7 +6753,7 @@ var createVoiceCallReviewFromLiveTelephonyReport = (report, options = {}) => {
     }
   };
 };
-var toErrorMessage = (error) => {
+var toErrorMessage2 = (error) => {
   if (typeof error === "string" && error.trim().length > 0) {
     return error;
   }
@@ -6577,7 +6840,7 @@ var createVoiceCallReviewRecorder = (options = {}) => {
       };
     },
     recordError: (error) => {
-      const message = toErrorMessage(error);
+      const message = toErrorMessage2(error);
       errors.push(message);
       push("turn", "error", {
         reason: message
@@ -7286,7 +7549,7 @@ var runVoiceSessionBenchmarkSeries = async (input) => {
 import { Buffer as Buffer2 } from "buffer";
 var TWILIO_MULAW_SAMPLE_RATE = 8000;
 var VOICE_PCM_SAMPLE_RATE = 16000;
-var escapeXml = (value) => value.replaceAll("&", "&amp;").replaceAll('"', "&quot;").replaceAll("'", "&apos;").replaceAll("<", "&lt;").replaceAll(">", "&gt;");
+var escapeXml2 = (value) => value.replaceAll("&", "&amp;").replaceAll('"', "&quot;").replaceAll("'", "&apos;").replaceAll("<", "&lt;").replaceAll(">", "&gt;");
 var normalizeOnTurn = (handler) => {
   if (handler.length > 1) {
     const directHandler = handler;
@@ -7482,8 +7745,8 @@ var createTwilioSocketAdapter = (socket, getState) => ({
   }
 });
 var createTwilioVoiceResponse = (options) => {
-  const parameters = Object.entries(options.parameters ?? {}).filter((entry) => entry[1] !== undefined).map(([name, value]) => `<Parameter name="${escapeXml(name)}" value="${escapeXml(String(value))}" />`).join("");
-  return `<?xml version="1.0" encoding="UTF-8"?><Response><Connect><Stream url="${escapeXml(options.streamUrl)}"${options.track ? ` track="${escapeXml(options.track)}"` : ""}${options.streamName ? ` name="${escapeXml(options.streamName)}"` : ""}>${parameters}</Stream></Connect></Response>`;
+  const parameters = Object.entries(options.parameters ?? {}).filter((entry) => entry[1] !== undefined).map(([name, value]) => `<Parameter name="${escapeXml2(name)}" value="${escapeXml2(String(value))}" />`).join("");
+  return `<?xml version="1.0" encoding="UTF-8"?><Response><Connect><Stream url="${escapeXml2(options.streamUrl)}"${options.track ? ` track="${escapeXml2(options.track)}"` : ""}${options.streamName ? ` name="${escapeXml2(options.streamName)}"` : ""}>${parameters}</Stream></Connect></Response>`;
 };
 var createTwilioMediaStreamBridge = (socket, options) => {
   const runtimePreset = resolveVoiceRuntimePreset(options.preset);

package/dist/trace.d.ts

@@ -1,4 +1,4 @@
-export type VoiceTraceEventType = 'assistant.guardrail' | 'assistant.memory' | 'assistant.run' | 'agent.handoff' | 'agent.model' | 'agent.result' | 'agent.tool' | 'call.lifecycle' | 'session.error' | 'turn.assistant' | 'turn.committed' | 'turn.cost' | 'turn.transcript';
+export type VoiceTraceEventType = 'assistant.guardrail' | 'assistant.memory' | 'assistant.run' | 'agent.handoff' | 'agent.model' | 'agent.result' | 'agent.tool' | 'call.handoff' | 'call.lifecycle' | 'session.error' | 'turn.assistant' | 'turn.committed' | 'turn.cost' | 'turn.transcript';
 export type VoiceTraceEvent<TPayload extends Record<string, unknown> = Record<string, unknown>> = {
     at: number;
     id?: string;

package/dist/types.d.ts

@@ -269,6 +269,35 @@ export type VoiceCallLifecycleState = {
     lastEventAt: number;
     startedAt: number;
 };
+export type VoiceHandoffAction = 'escalate' | 'no-answer' | 'transfer' | 'voicemail';
+export type VoiceHandoffStatus = 'delivered' | 'failed' | 'skipped';
+export type VoiceHandoffResult = {
+    deliveredAt?: number;
+    deliveredTo?: string;
+    error?: string;
+    metadata?: Record<string, unknown>;
+    status: VoiceHandoffStatus;
+};
+export type VoiceHandoffInput<TContext = unknown, TSession extends VoiceSessionRecord = VoiceSessionRecord, TResult = unknown> = {
+    action: VoiceHandoffAction;
+    api: VoiceSessionHandle<TContext, TSession, TResult>;
+    context: TContext;
+    metadata?: Record<string, unknown>;
+    reason?: string;
+    result?: TResult;
+    session: TSession;
+    target?: string;
+};
+export type VoiceHandoffAdapter<TContext = unknown, TSession extends VoiceSessionRecord = VoiceSessionRecord, TResult = unknown> = {
+    actions?: VoiceHandoffAction[];
+    handoff: (input: VoiceHandoffInput<TContext, TSession, TResult>) => Promise<VoiceHandoffResult> | VoiceHandoffResult;
+    id: string;
+    kind?: string;
+};
+export type VoiceHandoffConfig<TContext = unknown, TSession extends VoiceSessionRecord = VoiceSessionRecord, TResult = unknown> = {
+    adapters: VoiceHandoffAdapter<TContext, TSession, TResult>[];
+    failMode?: 'record' | 'throw';
+};
 export type VoiceSessionStore<TSession extends VoiceSessionRecord = VoiceSessionRecord> = SessionStore<TSession, VoiceSessionSummary>;
 export type VoiceLogger = {
     debug?: (message: string, meta?: Record<string, unknown>) => void;
@@ -567,6 +596,7 @@ export type VoicePluginConfig<TContext = unknown, TSession extends VoiceSessionR
     audioConditioning?: VoiceAudioConditioningConfig;
     logger?: VoiceLogger;
     htmx?: boolean | VoiceHTMXConfig<TSession, NoInfer<TResult>>;
+    handoff?: VoiceHandoffConfig<TContext, TSession, TResult>;
     ops?: VoiceRuntimeOpsConfig<TContext, TSession, TResult>;
     trace?: VoiceTraceEventStore;
 } & VoiceRouteConfig<TContext, TSession, TResult>;
@@ -588,6 +618,7 @@ export type CreateVoiceSessionOptions<TContext = unknown, TSession extends Voice
     sttLifecycle: VoiceSTTLifecycle;
     turnDetection: VoiceResolvedTurnDetectionConfig;
     audioConditioning?: VoiceResolvedAudioConditioningConfig;
+    handoff?: VoiceHandoffConfig<TContext, TSession, TResult>;
     route: VoiceNormalizedRouteConfig<TContext, TSession, TResult>;
     logger?: VoiceLogger;
 };

package/dist/vue/index.js

@@ -590,6 +590,7 @@ var useVoiceStream = (path, options = {}) => {
   const stream = createVoiceStream(path, options);
   const assistantAudio = shallowRef([]);
   const assistantTexts = shallowRef([]);
+  const call = shallowRef(null);
   const error = ref(null);
   const isConnected = ref(false);
   const partial = ref("");
@@ -599,6 +600,7 @@ var useVoiceStream = (path, options = {}) => {
   const sync = () => {
     assistantAudio.value = [...stream.assistantAudio];
     assistantTexts.value = [...stream.assistantTexts];
+    call.value = stream.call;
     error.value = stream.error;
     isConnected.value = stream.isConnected;
     partial.value = stream.partial;
@@ -616,6 +618,8 @@ var useVoiceStream = (path, options = {}) => {
   return {
     assistantAudio,
     assistantTexts,
+    call,
+    callControl: (message) => stream.callControl(message),
     close: () => destroy(),
     endTurn: () => stream.endTurn(),
     error,

package/dist/vue/useVoiceStream.d.ts

@@ -12,6 +12,8 @@ export declare const useVoiceStream: <TResult = unknown>(path: string, options?:
         turnId?: string;
     }[]>;
     assistantTexts: import("vue").ShallowRef<string[], string[]>;
+    call: import("vue").ShallowRef<import("..").VoiceCallLifecycleState | null, import("..").VoiceCallLifecycleState | null>;
+    callControl: (message: Parameters<(message: Omit<import("..").VoiceClientCallControlMessage, "type">) => void>[0]) => void;
     close: () => void;
     endTurn: () => void;
     error: import("vue").Ref<string | null, string | null>;

package/package.json

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