@absolutejs/voice 0.0.22-beta.30 → 0.0.22-beta.31

package/dist/handoff.d.ts

@@ -1,14 +1,24 @@
-import type { VoiceHandoffAction, VoiceHandoffAdapter, VoiceHandoffConfig, VoiceHandoffInput, VoiceHandoffResult, VoiceSessionRecord } from './types';
+import type { VoiceHandoffAction, VoiceHandoffAdapter, VoiceHandoffConfig, VoiceHandoffDeliveryStore, VoiceHandoffInput, VoiceHandoffResult, VoiceSessionRecord, StoredVoiceHandoffDelivery } from './types';
 type MaybePromise<T> = T | Promise<T>;
 export type VoiceHandoffDelivery = VoiceHandoffResult & {
     adapterId: string;
     adapterKind?: string;
 };
+export type VoiceHandoffDeliveryRecord<TContext = unknown, TSession extends VoiceSessionRecord = VoiceSessionRecord, TResult = unknown> = StoredVoiceHandoffDelivery<TContext, TSession, TResult>;
 export type VoiceHandoffFanoutResult = {
     action: VoiceHandoffAction;
     deliveries: Record<string, VoiceHandoffDelivery>;
     status: VoiceHandoffResult['status'];
 };
+export type VoiceHandoffDeliveryRecordInput<TContext = unknown, TSession extends VoiceSessionRecord = VoiceSessionRecord, TResult = unknown> = Omit<VoiceHandoffInput<TContext, TSession, TResult>, 'api'> & {
+    id?: string;
+};
+export type VoiceQueuedHandoffDeliveryOptions<TContext = unknown, TSession extends VoiceSessionRecord = VoiceSessionRecord, TResult = unknown> = {
+    adapters: VoiceHandoffAdapter<TContext, TSession, TResult>[];
+    api: VoiceHandoffInput<TContext, TSession, TResult>['api'];
+    delivery: VoiceHandoffDeliveryRecord<TContext, TSession, TResult>;
+    failMode?: VoiceHandoffConfig<TContext, TSession, TResult>['failMode'];
+};
 export type VoiceWebhookHandoffAdapterOptions<TContext = unknown, TSession extends VoiceSessionRecord = VoiceSessionRecord, TResult = unknown> = {
     actions?: VoiceHandoffAction[];
     body?: (input: VoiceHandoffInput<TContext, TSession, TResult>) => MaybePromise<Record<string, unknown>>;
@@ -35,6 +45,10 @@ export declare const deliverVoiceHandoff: <TContext, TSession extends VoiceSessi
     config?: VoiceHandoffConfig<TContext, TSession, TResult>;
     handoff: VoiceHandoffInput<TContext, TSession, TResult>;
 }) => Promise<VoiceHandoffFanoutResult | undefined>;
+export declare const createVoiceHandoffDeliveryRecord: <TContext, TSession extends VoiceSessionRecord, TResult>(input: VoiceHandoffDeliveryRecordInput<TContext, TSession, TResult>) => VoiceHandoffDeliveryRecord<TContext, TSession, TResult>;
+export declare const applyVoiceHandoffDeliveryResult: <TContext, TSession extends VoiceSessionRecord, TResult>(delivery: VoiceHandoffDeliveryRecord<TContext, TSession, TResult>, result: VoiceHandoffFanoutResult) => VoiceHandoffDeliveryRecord<TContext, TSession, TResult>;
+export declare const deliverVoiceHandoffDelivery: <TContext, TSession extends VoiceSessionRecord, TResult>(options: VoiceQueuedHandoffDeliveryOptions<TContext, TSession, TResult>) => Promise<VoiceHandoffDeliveryRecord<TContext, TSession, TResult>>;
+export declare const createVoiceMemoryHandoffDeliveryStore: <TDelivery extends VoiceHandoffDeliveryRecord = VoiceHandoffDeliveryRecord>() => VoiceHandoffDeliveryStore<TDelivery>;
 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,9 +14,9 @@ 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 { applyVoiceHandoffDeliveryResult, createVoiceHandoffDeliveryRecord, createVoiceMemoryHandoffDeliveryStore, createVoiceTwilioRedirectHandoffAdapter, createVoiceWebhookHandoffAdapter, deliverVoiceHandoff, deliverVoiceHandoffDelivery } from './handoff';
 export { createVoiceHandoffHealthHTMLHandler, createVoiceHandoffHealthJSONHandler, createVoiceHandoffHealthRoutes, renderVoiceHandoffHealthHTML, summarizeVoiceHandoffHealth } from './handoffHealth';
-export { createVoiceIntegrationSinkWorker, createVoiceIntegrationSinkWorkerLoop, createVoiceOpsTaskWorker, createVoiceOpsTaskProcessorWorker, createVoiceOpsTaskProcessorWorkerLoop, createVoiceRedisIdempotencyStore, createVoiceRedisTaskLeaseCoordinator, createVoiceTraceSinkDeliveryWorker, createVoiceTraceSinkDeliveryWorkerLoop, createVoiceWebhookDeliveryWorker, createVoiceWebhookDeliveryWorkerLoop, summarizeVoiceTraceSinkDeliveries, summarizeVoiceOpsTaskQueue, summarizeVoiceIntegrationEvents } from './queue';
+export { createVoiceHandoffDeliveryWorker, createVoiceHandoffDeliveryWorkerLoop, createVoiceIntegrationSinkWorker, createVoiceIntegrationSinkWorkerLoop, createVoiceOpsTaskWorker, createVoiceOpsTaskProcessorWorker, createVoiceOpsTaskProcessorWorkerLoop, createVoiceRedisIdempotencyStore, createVoiceRedisTaskLeaseCoordinator, createVoiceTraceSinkDeliveryWorker, createVoiceTraceSinkDeliveryWorkerLoop, createVoiceWebhookDeliveryWorker, createVoiceWebhookDeliveryWorkerLoop, summarizeVoiceHandoffDeliveries, 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';
 export { createVoiceCallReviewFromSession, recordVoiceRuntimeOps } from './runtimeOps';
@@ -42,13 +42,13 @@ 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 { 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 { 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';
 export type { VoicePostgresClient, VoicePostgresRuntimeStorage, VoicePostgresStoreOptions } from './postgresStore';
-export type { VoiceOpsTaskLease, VoiceOpsTaskWorker, VoiceOpsTaskWorkerOptions, VoiceIdempotencyStore, VoiceIntegrationEventQueueSummary, VoiceIntegrationSinkWorkerLoop, VoiceIntegrationSinkWorkerLoopOptions, VoiceIntegrationSinkWorkerOptions, VoiceIntegrationSinkWorkerResult, VoiceRedisIdempotencyClient, VoiceRedisIdempotencyStoreOptions, VoiceRedisTaskLeaseClient, VoiceRedisTaskLeaseCoordinator, VoiceRedisTaskLeaseCoordinatorOptions, VoiceTraceSinkDeliveryQueueSummary, VoiceTraceSinkDeliveryWorkerLoop, VoiceTraceSinkDeliveryWorkerLoopOptions, VoiceTraceSinkDeliveryWorkerOptions, VoiceTraceSinkDeliveryWorkerResult, VoiceOpsTaskClaimFilters, VoiceWebhookDeliveryWorkerLoop, VoiceWebhookDeliveryWorkerLoopOptions, VoiceWebhookDeliveryWorkerOptions, VoiceWebhookDeliveryWorkerResult, VoiceOpsTaskProcessorWorkerLoop, VoiceOpsTaskProcessorWorkerLoopOptions, VoiceOpsTaskProcessorWorkerOptions, VoiceOpsTaskProcessorWorkerResult, VoiceOpsTaskQueueSummary } from './queue';
+export type { VoiceOpsTaskLease, VoiceOpsTaskWorker, VoiceOpsTaskWorkerOptions, VoiceHandoffDeliveryQueueSummary, VoiceHandoffDeliveryWorkerLoop, VoiceHandoffDeliveryWorkerLoopOptions, VoiceHandoffDeliveryWorkerOptions, VoiceHandoffDeliveryWorkerResult, VoiceIdempotencyStore, VoiceIntegrationEventQueueSummary, VoiceIntegrationSinkWorkerLoop, VoiceIntegrationSinkWorkerLoopOptions, VoiceIntegrationSinkWorkerOptions, VoiceIntegrationSinkWorkerResult, VoiceRedisIdempotencyClient, VoiceRedisIdempotencyStoreOptions, VoiceRedisTaskLeaseClient, VoiceRedisTaskLeaseCoordinator, VoiceRedisTaskLeaseCoordinatorOptions, VoiceTraceSinkDeliveryQueueSummary, VoiceTraceSinkDeliveryWorkerLoop, VoiceTraceSinkDeliveryWorkerLoopOptions, VoiceTraceSinkDeliveryWorkerOptions, VoiceTraceSinkDeliveryWorkerResult, VoiceOpsTaskClaimFilters, VoiceWebhookDeliveryWorkerLoop, VoiceWebhookDeliveryWorkerLoopOptions, VoiceWebhookDeliveryWorkerOptions, VoiceWebhookDeliveryWorkerResult, VoiceOpsTaskProcessorWorkerLoop, VoiceOpsTaskProcessorWorkerLoopOptions, VoiceOpsTaskProcessorWorkerOptions, VoiceOpsTaskProcessorWorkerResult, VoiceOpsTaskQueueSummary } from './queue';
 export type { VoiceS3ReviewStoreClient, VoiceS3ReviewStoreFile, VoiceS3ReviewStoreOptions } from './s3Store';
 export type { VoiceSQLiteRuntimeStorage, VoiceSQLiteStoreOptions } from './sqliteStore';
 export type { StoredVoiceIntegrationEvent, StoredVoiceExternalObjectMap, StoredVoiceOpsTask, VoiceExternalObjectMap, VoiceExternalObjectMapStore, VoiceOpsTaskAgeBucket, VoiceOpsTaskAnalyticsOptions, VoiceOpsTaskAnalyticsSummary, VoiceOpsTaskAssignmentRule, VoiceOpsTaskAssignmentRuleCondition, VoiceOpsTaskAssignmentRules, VoiceOpsTaskAssigneeAnalytics, VoiceOpsDispositionTaskPolicies, VoiceOpsSLABreachPolicy, VoiceIntegrationDeliveryStatus, VoiceIntegrationEvent, VoiceIntegrationEventStore, VoiceIntegrationSinkDelivery, VoiceIntegrationEventType, VoiceIntegrationWebhookConfig, VoiceOpsTask, VoiceOpsTaskHistoryEntry, VoiceOpsTaskKind, VoiceOpsTaskPolicy, VoiceOpsTaskPriority, VoiceOpsTaskStatus, VoiceOpsTaskStore, VoiceOpsTaskSummary, VoiceOpsTaskWorkerAnalytics } from './ops';

package/dist/index.js

@@ -3019,6 +3019,14 @@ var aggregateHandoffStatus = (deliveries) => {
   }
   return "skipped";
 };
+var createHandoffDeliveryId = (input) => [
+  "voice-handoff",
+  input.sessionId,
+  input.action,
+  Date.now(),
+  crypto.randomUUID()
+].join(":");
+var resolveHandoffDeliveryError = (deliveries) => Object.values(deliveries).map((delivery) => delivery.error).find(Boolean);
 var defaultWebhookBody = (input) => ({
   action: input.action,
   metadata: input.metadata,
@@ -3067,6 +3075,73 @@ var deliverVoiceHandoff = async (input) => {
     status: aggregateHandoffStatus(deliveries)
   };
 };
+var createVoiceHandoffDeliveryRecord = (input) => {
+  const now = Date.now();
+  return {
+    action: input.action,
+    context: input.context,
+    createdAt: now,
+    deliveryAttempts: 0,
+    deliveryStatus: "pending",
+    id: input.id ?? createHandoffDeliveryId({
+      action: input.action,
+      sessionId: input.session.id
+    }),
+    metadata: input.metadata,
+    reason: input.reason,
+    result: input.result,
+    session: input.session,
+    sessionId: input.session.id,
+    target: input.target,
+    updatedAt: now
+  };
+};
+var applyVoiceHandoffDeliveryResult = (delivery, result) => ({
+  ...delivery,
+  deliveredAt: result.status === "delivered" || result.status === "skipped" ? Date.now() : delivery.deliveredAt,
+  deliveries: result.deliveries,
+  deliveryAttempts: (delivery.deliveryAttempts ?? 0) + 1,
+  deliveryError: result.status === "failed" ? resolveHandoffDeliveryError(result.deliveries) : undefined,
+  deliveryStatus: result.status,
+  updatedAt: Date.now()
+});
+var deliverVoiceHandoffDelivery = async (options) => {
+  const result = await deliverVoiceHandoff({
+    config: {
+      adapters: options.adapters,
+      failMode: options.failMode
+    },
+    handoff: {
+      action: options.delivery.action,
+      api: options.api,
+      context: options.delivery.context,
+      metadata: options.delivery.metadata,
+      reason: options.delivery.reason,
+      result: options.delivery.result,
+      session: options.delivery.session,
+      target: options.delivery.target
+    }
+  });
+  return result ? applyVoiceHandoffDeliveryResult(options.delivery, result) : {
+    ...options.delivery,
+    deliveryAttempts: (options.delivery.deliveryAttempts ?? 0) + 1,
+    deliveryStatus: "skipped",
+    updatedAt: Date.now()
+  };
+};
+var createVoiceMemoryHandoffDeliveryStore = () => {
+  const deliveries = new Map;
+  return {
+    get: async (id) => deliveries.get(id),
+    list: async () => [...deliveries.values()].sort((left, right) => left.createdAt - right.createdAt || left.id.localeCompare(right.id)),
+    remove: async (id) => {
+      deliveries.delete(id);
+    },
+    set: async (id, delivery) => {
+      deliveries.set(id, delivery);
+    }
+  };
+};
 var createVoiceWebhookHandoffAdapter = (options) => ({
   actions: options.actions,
   handoff: async (input) => {
@@ -3609,6 +3684,21 @@ var createVoiceSession = (options) => {
     });
   };
   const runHandoff = async (input) => {
+    const queuedDelivery = options.handoff?.deliveryQueue ? createVoiceHandoffDeliveryRecord({
+      action: input.action,
+      context: options.context,
+      metadata: input.metadata,
+      reason: input.reason,
+      result: input.result,
+      session: input.session,
+      target: input.target
+    }) : undefined;
+    if (queuedDelivery) {
+      await options.handoff?.deliveryQueue?.set(queuedDelivery.id, queuedDelivery);
+    }
+    if (options.handoff?.enqueueOnly) {
+      return;
+    }
     const result = await deliverVoiceHandoff({
       config: options.handoff,
       handoff: {
@@ -3625,6 +3715,10 @@ var createVoiceSession = (options) => {
     if (!result) {
       return;
     }
+    if (queuedDelivery) {
+      const updatedDelivery = applyVoiceHandoffDeliveryResult(queuedDelivery, result);
+      await options.handoff?.deliveryQueue?.set(updatedDelivery.id, updatedDelivery);
+    }
     await appendTrace({
       metadata: input.metadata,
       payload: {
@@ -9625,6 +9719,8 @@ var shouldDeadLetterSinkEvent = (event, sinks, maxFailures) => typeof maxFailure
 var shouldDeadLetterTask = (task, maxFailures) => typeof maxFailures === "number" && maxFailures > 0 && (task.processingAttempts ?? 0) >= maxFailures;
 var shouldProcessTraceDeliveryStatus = (status, allowed) => allowed.includes(status);
 var shouldDeadLetterTraceDelivery = (delivery, maxFailures) => typeof maxFailures === "number" && maxFailures > 0 && (delivery.deliveryAttempts ?? 0) >= maxFailures;
+var shouldProcessHandoffDeliveryStatus = (status, allowed) => allowed.includes(status);
+var shouldDeadLetterHandoffDelivery = (delivery, maxFailures) => typeof maxFailures === "number" && maxFailures > 0 && (delivery.deliveryAttempts ?? 0) >= maxFailures;
 var summarizeVoiceIntegrationEvents = (events, input = {}) => {
   const buildSummary = async () => {
     const deadLetterIds = new Set(input.deadLetters ? (await input.deadLetters.list()).map((event) => event.id) : []);
@@ -9706,6 +9802,48 @@ var summarizeVoiceTraceSinkDeliveries = (deliveries, input = {}) => {
   };
   return buildSummary();
 };
+var summarizeVoiceHandoffDeliveries = (deliveries, input = {}) => {
+  const buildSummary = async () => {
+    const deadLetterIds = new Set(input.deadLetters ? (await input.deadLetters.list()).map((delivery) => delivery.id) : []);
+    const byAction = new Map;
+    const summary = {
+      byAction: [],
+      deadLettered: 0,
+      delivered: 0,
+      failed: 0,
+      pending: 0,
+      retryEligible: 0,
+      skipped: 0,
+      total: deliveries.length
+    };
+    for (const delivery of deliveries) {
+      byAction.set(delivery.action, (byAction.get(delivery.action) ?? 0) + 1);
+      if (deadLetterIds.has(delivery.id)) {
+        summary.deadLettered += 1;
+      }
+      switch (delivery.deliveryStatus) {
+        case "delivered":
+          summary.delivered += 1;
+          break;
+        case "failed":
+          summary.failed += 1;
+          if ((delivery.deliveryAttempts ?? 0) > 0) {
+            summary.retryEligible += 1;
+          }
+          break;
+        case "skipped":
+          summary.skipped += 1;
+          break;
+        case "pending":
+          summary.pending += 1;
+          break;
+      }
+    }
+    summary.byAction = [...byAction.entries()].sort((left, right) => right[1] - left[1]);
+    return summary;
+  };
+  return buildSummary();
+};
 var summarizeVoiceOpsTaskQueue = (tasks, input = {}) => {
   const buildSummary = async () => {
     const deadLetterIds = new Set(input.deadLetters ? (await input.deadLetters.list()).map((task) => task.id) : []);
@@ -10135,6 +10273,108 @@ var createVoiceTraceSinkDeliveryWorkerLoop = (options) => {
     tick
   };
 };
+var createVoiceHandoffDeliveryWorker = (options) => {
+  const allowedStatuses = options.statuses ?? ["pending", "failed"];
+  const leaseMs = Math.max(1, options.leaseMs ?? 30000);
+  return {
+    drain: async () => {
+      const result = {
+        alreadyProcessed: 0,
+        attempted: 0,
+        deadLettered: 0,
+        delivered: 0,
+        failed: 0,
+        skipped: 0
+      };
+      const deliveries = [...await options.deliveries.list()].sort((left, right) => left.createdAt - right.createdAt);
+      for (const delivery of deliveries) {
+        if (!shouldProcessHandoffDeliveryStatus(delivery.deliveryStatus, allowedStatuses)) {
+          continue;
+        }
+        if (shouldDeadLetterHandoffDelivery(delivery, options.maxFailures)) {
+          await options.deadLetters?.set(delivery.id, delivery);
+          await options.onDeadLetter?.(delivery);
+          result.deadLettered += 1;
+          continue;
+        }
+        const claimed = await options.leases.claim({
+          leaseMs,
+          taskId: delivery.id,
+          workerId: options.workerId
+        });
+        if (!claimed) {
+          continue;
+        }
+        try {
+          const idempotencyKey = `${delivery.id}:handoff`;
+          if (options.idempotency && await options.idempotency.has(idempotencyKey)) {
+            result.alreadyProcessed += 1;
+            continue;
+          }
+          result.attempted += 1;
+          const updatedDelivery = await deliverVoiceHandoffDelivery({
+            adapters: options.adapters,
+            api: options.api,
+            delivery,
+            failMode: options.failMode
+          });
+          await options.deliveries.set(updatedDelivery.id, updatedDelivery);
+          if (updatedDelivery.deliveryStatus === "delivered" || updatedDelivery.deliveryStatus === "skipped") {
+            await options.idempotency?.set(idempotencyKey, {
+              ttlSeconds: options.idempotencyTtlSeconds
+            });
+          }
+          if (updatedDelivery.deliveryStatus === "delivered") {
+            result.delivered += 1;
+          } else if (updatedDelivery.deliveryStatus === "skipped") {
+            result.skipped += 1;
+          } else if (updatedDelivery.deliveryStatus === "failed") {
+            result.failed += 1;
+            if (shouldDeadLetterHandoffDelivery(updatedDelivery, options.maxFailures)) {
+              await options.deadLetters?.set(updatedDelivery.id, updatedDelivery);
+              await options.onDeadLetter?.(updatedDelivery);
+              result.deadLettered += 1;
+            }
+          }
+        } finally {
+          await options.leases.release({
+            taskId: delivery.id,
+            workerId: options.workerId
+          });
+        }
+      }
+      return result;
+    }
+  };
+};
+var createVoiceHandoffDeliveryWorkerLoop = (options) => {
+  const pollIntervalMs = Math.max(1, options.pollIntervalMs ?? 1000);
+  let timer;
+  let running = false;
+  const tick = async () => options.worker.drain();
+  return {
+    isRunning: () => running,
+    start: () => {
+      if (timer) {
+        return;
+      }
+      running = true;
+      timer = setInterval(() => {
+        tick().catch((error) => {
+          options.onError?.(error);
+        });
+      }, pollIntervalMs);
+    },
+    stop: () => {
+      if (timer) {
+        clearInterval(timer);
+        timer = undefined;
+      }
+      running = false;
+    },
+    tick
+  };
+};
 var createVoiceOpsTaskWorker = (options) => {
   const leaseMs = Math.max(1, options.leaseMs ?? 30000);
   const getTask = async (taskId) => {
@@ -11532,6 +11772,7 @@ export {
   summarizeVoiceOpsTaskAnalytics,
   summarizeVoiceIntegrationEvents,
   summarizeVoiceHandoffHealth,
+  summarizeVoiceHandoffDeliveries,
   summarizeVoiceAssistantRuns,
   summarizeVoiceAssistantHealth,
   startVoiceOpsTask,
@@ -11577,6 +11818,7 @@ export {
   deliverVoiceTraceEventsToSinks,
   deliverVoiceIntegrationEventToSinks,
   deliverVoiceIntegrationEvent,
+  deliverVoiceHandoffDelivery,
   deliverVoiceHandoff,
   decodeTwilioMulawBase64,
   deadLetterVoiceOpsTask,
@@ -11641,6 +11883,7 @@ export {
   createVoiceMemoryTraceSinkDeliveryStore,
   createVoiceMemoryTraceEventStore,
   createVoiceMemoryStore,
+  createVoiceMemoryHandoffDeliveryStore,
   createVoiceMemoryAssistantMemoryStore,
   createVoiceLinearIssueUpdateSink,
   createVoiceLinearIssueSyncSinks,
@@ -11656,6 +11899,9 @@ export {
   createVoiceHandoffHealthRoutes,
   createVoiceHandoffHealthJSONHandler,
   createVoiceHandoffHealthHTMLHandler,
+  createVoiceHandoffDeliveryWorkerLoop,
+  createVoiceHandoffDeliveryWorker,
+  createVoiceHandoffDeliveryRecord,
   createVoiceFileTraceSinkDeliveryStore,
   createVoiceFileTraceEventStore,
   createVoiceFileTaskStore,
@@ -11706,6 +11952,7 @@ export {
   assignVoiceOpsTask,
   applyVoiceOpsTaskPolicy,
   applyVoiceOpsTaskAssignmentRule,
+  applyVoiceHandoffDeliveryResult,
   applyRiskTieredPhraseHintCorrections,
   applyPhraseHintCorrections,
   TURN_PROFILE_DEFAULTS

package/dist/queue.d.ts

@@ -1,6 +1,7 @@
 import type { RedisClient } from 'bun';
 import type { VoiceIntegrationSink } from './opsSinks';
 import type { VoiceTraceRedactionConfig, VoiceTraceSink, VoiceTraceSinkDeliveryRecord, VoiceTraceSinkDeliveryStore, VoiceTraceSinkDeliveryQueueStatus } from './trace';
+import type { StoredVoiceHandoffDelivery, VoiceHandoffAdapter, VoiceHandoffDeliveryQueueStatus, VoiceHandoffDeliveryStore, VoiceSessionHandle, VoiceSessionRecord } from './types';
 import type { VoiceOpsTaskPriority, StoredVoiceOpsTask, StoredVoiceIntegrationEvent, VoiceIntegrationDeliveryStatus, VoiceIntegrationEventStore, VoiceIntegrationWebhookConfig, VoiceOpsTaskKind, VoiceOpsTaskStatus, VoiceOpsTaskStore } from './ops';
 export type VoiceOpsTaskLease = {
     expiresAt: number;
@@ -159,6 +160,50 @@ export type VoiceTraceSinkDeliveryQueueSummary = {
     skipped: number;
     total: number;
 };
+export type VoiceHandoffDeliveryWorkerOptions<TContext = unknown, TSession extends VoiceSessionRecord = VoiceSessionRecord, TResult = unknown, TDelivery extends StoredVoiceHandoffDelivery<TContext, TSession, TResult> = StoredVoiceHandoffDelivery<TContext, TSession, TResult>> = {
+    adapters: VoiceHandoffAdapter<TContext, TSession, TResult>[];
+    api: VoiceSessionHandle<TContext, TSession, TResult>;
+    deadLetters?: VoiceHandoffDeliveryStore<TDelivery>;
+    deliveries: VoiceHandoffDeliveryStore<TDelivery>;
+    failMode?: 'record' | 'throw';
+    idempotency?: VoiceIdempotencyStore;
+    idempotencyTtlSeconds?: number;
+    leaseMs?: number;
+    leases: VoiceRedisTaskLeaseCoordinator;
+    maxFailures?: number;
+    onDeadLetter?: (delivery: TDelivery) => Promise<void> | void;
+    statuses?: VoiceHandoffDeliveryQueueStatus[];
+    workerId: string;
+};
+export type VoiceHandoffDeliveryWorkerResult = {
+    alreadyProcessed: number;
+    attempted: number;
+    deadLettered: number;
+    delivered: number;
+    failed: number;
+    skipped: number;
+};
+export type VoiceHandoffDeliveryWorkerLoopOptions<TContext = unknown, TSession extends VoiceSessionRecord = VoiceSessionRecord, TResult = unknown, TDelivery extends StoredVoiceHandoffDelivery<TContext, TSession, TResult> = StoredVoiceHandoffDelivery<TContext, TSession, TResult>> = {
+    onError?: (error: unknown) => Promise<void> | void;
+    pollIntervalMs?: number;
+    worker: ReturnType<typeof createVoiceHandoffDeliveryWorker<TContext, TSession, TResult, TDelivery>>;
+};
+export type VoiceHandoffDeliveryWorkerLoop = {
+    isRunning: () => boolean;
+    start: () => void;
+    stop: () => void;
+    tick: () => Promise<VoiceHandoffDeliveryWorkerResult>;
+};
+export type VoiceHandoffDeliveryQueueSummary = {
+    byAction: Array<[StoredVoiceHandoffDelivery['action'], number]>;
+    deadLettered: number;
+    delivered: number;
+    failed: number;
+    pending: number;
+    retryEligible: number;
+    skipped: number;
+    total: number;
+};
 export type VoiceOpsTaskWorkerOptions<TTask extends StoredVoiceOpsTask = StoredVoiceOpsTask> = {
     leaseMs?: number;
     leases: VoiceRedisTaskLeaseCoordinator;
@@ -252,6 +297,9 @@ export declare const summarizeVoiceIntegrationEvents: <TEvent extends StoredVoic
 export declare const summarizeVoiceTraceSinkDeliveries: <TDelivery extends VoiceTraceSinkDeliveryRecord = VoiceTraceSinkDeliveryRecord>(deliveries: TDelivery[], input?: {
     deadLetters?: VoiceTraceSinkDeliveryStore<TDelivery>;
 }) => Promise<VoiceTraceSinkDeliveryQueueSummary> | VoiceTraceSinkDeliveryQueueSummary;
+export declare const summarizeVoiceHandoffDeliveries: <TDelivery extends StoredVoiceHandoffDelivery = StoredVoiceHandoffDelivery>(deliveries: TDelivery[], input?: {
+    deadLetters?: VoiceHandoffDeliveryStore<TDelivery>;
+}) => Promise<VoiceHandoffDeliveryQueueSummary> | VoiceHandoffDeliveryQueueSummary;
 export declare const summarizeVoiceOpsTaskQueue: <TTask extends StoredVoiceOpsTask = StoredVoiceOpsTask>(tasks: TTask[], input?: {
     deadLetters?: VoiceOpsTaskStore<TTask>;
 }) => Promise<VoiceOpsTaskQueueSummary> | VoiceOpsTaskQueueSummary;
@@ -269,6 +317,10 @@ export declare const createVoiceTraceSinkDeliveryWorker: <TDelivery extends Voic
     drain: () => Promise<VoiceTraceSinkDeliveryWorkerResult>;
 };
 export declare const createVoiceTraceSinkDeliveryWorkerLoop: <TDelivery extends VoiceTraceSinkDeliveryRecord = VoiceTraceSinkDeliveryRecord>(options: VoiceTraceSinkDeliveryWorkerLoopOptions<TDelivery>) => VoiceTraceSinkDeliveryWorkerLoop;
+export declare const createVoiceHandoffDeliveryWorker: <TContext = unknown, TSession extends VoiceSessionRecord = VoiceSessionRecord, TResult = unknown, TDelivery extends StoredVoiceHandoffDelivery<TContext, TSession, TResult> = StoredVoiceHandoffDelivery<TContext, TSession, TResult>>(options: VoiceHandoffDeliveryWorkerOptions<TContext, TSession, TResult, TDelivery>) => {
+    drain: () => Promise<VoiceHandoffDeliveryWorkerResult>;
+};
+export declare const createVoiceHandoffDeliveryWorkerLoop: <TContext = unknown, TSession extends VoiceSessionRecord = VoiceSessionRecord, TResult = unknown, TDelivery extends StoredVoiceHandoffDelivery<TContext, TSession, TResult> = StoredVoiceHandoffDelivery<TContext, TSession, TResult>>(options: VoiceHandoffDeliveryWorkerLoopOptions<TContext, TSession, TResult, TDelivery>) => VoiceHandoffDeliveryWorkerLoop;
 export declare const createVoiceOpsTaskWorker: <TTask extends StoredVoiceOpsTask = StoredVoiceOpsTask>(options: VoiceOpsTaskWorkerOptions<TTask>) => VoiceOpsTaskWorker<TTask>;
 export declare const createVoiceOpsTaskProcessorWorker: <TTask extends StoredVoiceOpsTask = StoredVoiceOpsTask>(options: VoiceOpsTaskProcessorWorkerOptions<TTask>) => {
     drain: () => Promise<VoiceOpsTaskProcessorWorkerResult>;

package/dist/testing/index.js

@@ -4486,6 +4486,14 @@ var aggregateHandoffStatus = (deliveries) => {
   }
   return "skipped";
 };
+var createHandoffDeliveryId = (input) => [
+  "voice-handoff",
+  input.sessionId,
+  input.action,
+  Date.now(),
+  crypto.randomUUID()
+].join(":");
+var resolveHandoffDeliveryError = (deliveries) => Object.values(deliveries).map((delivery) => delivery.error).find(Boolean);
 var defaultWebhookBody = (input) => ({
   action: input.action,
   metadata: input.metadata,
@@ -4534,6 +4542,73 @@ var deliverVoiceHandoff = async (input) => {
     status: aggregateHandoffStatus(deliveries)
   };
 };
+var createVoiceHandoffDeliveryRecord = (input) => {
+  const now = Date.now();
+  return {
+    action: input.action,
+    context: input.context,
+    createdAt: now,
+    deliveryAttempts: 0,
+    deliveryStatus: "pending",
+    id: input.id ?? createHandoffDeliveryId({
+      action: input.action,
+      sessionId: input.session.id
+    }),
+    metadata: input.metadata,
+    reason: input.reason,
+    result: input.result,
+    session: input.session,
+    sessionId: input.session.id,
+    target: input.target,
+    updatedAt: now
+  };
+};
+var applyVoiceHandoffDeliveryResult = (delivery, result) => ({
+  ...delivery,
+  deliveredAt: result.status === "delivered" || result.status === "skipped" ? Date.now() : delivery.deliveredAt,
+  deliveries: result.deliveries,
+  deliveryAttempts: (delivery.deliveryAttempts ?? 0) + 1,
+  deliveryError: result.status === "failed" ? resolveHandoffDeliveryError(result.deliveries) : undefined,
+  deliveryStatus: result.status,
+  updatedAt: Date.now()
+});
+var deliverVoiceHandoffDelivery = async (options) => {
+  const result = await deliverVoiceHandoff({
+    config: {
+      adapters: options.adapters,
+      failMode: options.failMode
+    },
+    handoff: {
+      action: options.delivery.action,
+      api: options.api,
+      context: options.delivery.context,
+      metadata: options.delivery.metadata,
+      reason: options.delivery.reason,
+      result: options.delivery.result,
+      session: options.delivery.session,
+      target: options.delivery.target
+    }
+  });
+  return result ? applyVoiceHandoffDeliveryResult(options.delivery, result) : {
+    ...options.delivery,
+    deliveryAttempts: (options.delivery.deliveryAttempts ?? 0) + 1,
+    deliveryStatus: "skipped",
+    updatedAt: Date.now()
+  };
+};
+var createVoiceMemoryHandoffDeliveryStore = () => {
+  const deliveries = new Map;
+  return {
+    get: async (id) => deliveries.get(id),
+    list: async () => [...deliveries.values()].sort((left, right) => left.createdAt - right.createdAt || left.id.localeCompare(right.id)),
+    remove: async (id) => {
+      deliveries.delete(id);
+    },
+    set: async (id, delivery) => {
+      deliveries.set(id, delivery);
+    }
+  };
+};
 var createVoiceWebhookHandoffAdapter = (options) => ({
   actions: options.actions,
   handoff: async (input) => {
@@ -4972,6 +5047,21 @@ var createVoiceSession = (options) => {
     });
   };
   const runHandoff = async (input) => {
+    const queuedDelivery = options.handoff?.deliveryQueue ? createVoiceHandoffDeliveryRecord({
+      action: input.action,
+      context: options.context,
+      metadata: input.metadata,
+      reason: input.reason,
+      result: input.result,
+      session: input.session,
+      target: input.target
+    }) : undefined;
+    if (queuedDelivery) {
+      await options.handoff?.deliveryQueue?.set(queuedDelivery.id, queuedDelivery);
+    }
+    if (options.handoff?.enqueueOnly) {
+      return;
+    }
     const result = await deliverVoiceHandoff({
       config: options.handoff,
       handoff: {
@@ -4988,6 +5078,10 @@ var createVoiceSession = (options) => {
     if (!result) {
       return;
     }
+    if (queuedDelivery) {
+      const updatedDelivery = applyVoiceHandoffDeliveryResult(queuedDelivery, result);
+      await options.handoff?.deliveryQueue?.set(updatedDelivery.id, updatedDelivery);
+    }
     await appendTrace({
       metadata: input.metadata,
       payload: {

package/dist/types.d.ts

@@ -278,6 +278,34 @@ export type VoiceHandoffResult = {
     metadata?: Record<string, unknown>;
     status: VoiceHandoffStatus;
 };
+export type VoiceHandoffDeliveryQueueStatus = VoiceHandoffStatus | 'pending';
+export type StoredVoiceHandoffDelivery<TContext = unknown, TSession extends VoiceSessionRecord = VoiceSessionRecord, TResult = unknown> = {
+    action: VoiceHandoffAction;
+    context: TContext;
+    createdAt: number;
+    deliveredAt?: number;
+    deliveries?: Record<string, VoiceHandoffResult & {
+        adapterId: string;
+        adapterKind?: string;
+    }>;
+    deliveryAttempts?: number;
+    deliveryError?: string;
+    deliveryStatus: VoiceHandoffDeliveryQueueStatus;
+    id: string;
+    metadata?: Record<string, unknown>;
+    reason?: string;
+    result?: TResult;
+    session: TSession;
+    sessionId: string;
+    target?: string;
+    updatedAt: number;
+};
+export type VoiceHandoffDeliveryStore<TDelivery extends StoredVoiceHandoffDelivery = StoredVoiceHandoffDelivery> = {
+    get: (id: string) => Promise<TDelivery | undefined> | TDelivery | undefined;
+    list: () => Promise<TDelivery[]> | TDelivery[];
+    remove: (id: string) => Promise<void> | void;
+    set: (id: string, delivery: TDelivery) => Promise<void> | void;
+};
 export type VoiceHandoffInput<TContext = unknown, TSession extends VoiceSessionRecord = VoiceSessionRecord, TResult = unknown> = {
     action: VoiceHandoffAction;
     api: VoiceSessionHandle<TContext, TSession, TResult>;
@@ -296,6 +324,8 @@ export type VoiceHandoffAdapter<TContext = unknown, TSession extends VoiceSessio
 };
 export type VoiceHandoffConfig<TContext = unknown, TSession extends VoiceSessionRecord = VoiceSessionRecord, TResult = unknown> = {
     adapters: VoiceHandoffAdapter<TContext, TSession, TResult>[];
+    deliveryQueue?: VoiceHandoffDeliveryStore<StoredVoiceHandoffDelivery<TContext, TSession, TResult>>;
+    enqueueOnly?: boolean;
     failMode?: 'record' | 'throw';
 };
 export type VoiceSessionStore<TSession extends VoiceSessionRecord = VoiceSessionRecord> = SessionStore<TSession, VoiceSessionSummary>;

package/package.json

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