@absolutejs/voice 0.0.22-beta.3 → 0.0.22-beta.300

package/dist/turnQuality.d.ts

@@ -0,0 +1,94 @@
+import { Elysia } from 'elysia';
+import type { VoiceSessionRecord, VoiceSessionStore, VoiceTranscriptQuality } from './types';
+export type VoiceTurnQualityStatus = 'pass' | 'warn' | 'fail' | 'unknown';
+export type VoiceTurnQualityItem = {
+    averageConfidence?: number;
+    committedAt: number;
+    correctionChanged: boolean;
+    correctionProvider?: string;
+    correctionReason?: string;
+    costUnits?: number;
+    fallbackSelectionReason?: string;
+    fallbackUsed: boolean;
+    finalTranscriptCount: number;
+    latencyMs?: number;
+    partialTranscriptCount: number;
+    selectedTranscriptCount: number;
+    sessionId: string;
+    source?: VoiceTranscriptQuality['source'];
+    status: VoiceTurnQualityStatus;
+    text: string;
+    turnId: string;
+};
+export type VoiceTurnQualityReport = {
+    checkedAt: number;
+    failed: number;
+    sessions: number;
+    status: VoiceTurnQualityStatus;
+    total: number;
+    turns: VoiceTurnQualityItem[];
+    warnings: number;
+};
+export type VoiceTurnQualityOptions<TSession extends VoiceSessionRecord = VoiceSessionRecord> = {
+    confidenceWarnThreshold?: number;
+    limit?: number;
+    sessionIds?: string[];
+    sessions?: TSession[];
+    store?: VoiceSessionStore<TSession>;
+};
+export type VoiceTurnQualityHTMLHandlerOptions<TSession extends VoiceSessionRecord = VoiceSessionRecord> = VoiceTurnQualityOptions<TSession> & {
+    headers?: HeadersInit;
+    render?: (report: VoiceTurnQualityReport) => string | Promise<string>;
+    title?: string;
+};
+export type VoiceTurnQualityRoutesOptions<TSession extends VoiceSessionRecord = VoiceSessionRecord> = VoiceTurnQualityHTMLHandlerOptions<TSession> & {
+    htmlPath?: false | string;
+    name?: string;
+    path?: string;
+};
+export declare const summarizeVoiceTurnQuality: <TSession extends VoiceSessionRecord = VoiceSessionRecord>(options: VoiceTurnQualityOptions<TSession>) => Promise<VoiceTurnQualityReport>;
+export declare const renderVoiceTurnQualityHTML: (report: VoiceTurnQualityReport, options?: {
+    title?: string;
+}) => string;
+export declare const createVoiceTurnQualityJSONHandler: <TSession extends VoiceSessionRecord = VoiceSessionRecord>(options: VoiceTurnQualityOptions<TSession>) => () => Promise<VoiceTurnQualityReport>;
+export declare const createVoiceTurnQualityHTMLHandler: <TSession extends VoiceSessionRecord = VoiceSessionRecord>(options: VoiceTurnQualityHTMLHandlerOptions<TSession>) => () => Promise<Response>;
+export declare const createVoiceTurnQualityRoutes: <TSession extends VoiceSessionRecord = VoiceSessionRecord>(options: VoiceTurnQualityRoutesOptions<TSession>) => Elysia<"", {
+    decorator: {};
+    store: {};
+    derive: {};
+    resolve: {};
+}, {
+    typebox: {};
+    error: {};
+}, {
+    schema: {};
+    standaloneSchema: {};
+    macro: {};
+    macroFn: {};
+    parser: {};
+    response: {};
+}, {
+    [x: string]: {
+        get: {
+            body: unknown;
+            params: {};
+            query: unknown;
+            headers: unknown;
+            response: {
+                200: VoiceTurnQualityReport;
+            };
+        };
+    };
+}, {
+    derive: {};
+    resolve: {};
+    schema: {};
+    standaloneSchema: {};
+    response: {};
+}, {
+    derive: {};
+    resolve: {};
+    schema: {};
+    standaloneSchema: {};
+    response: {};
+}>;

package/dist/types.d.ts

@@ -3,6 +3,7 @@ import type { VoiceOpsDispositionTaskPolicies, VoiceOpsTaskAssignmentRule, Voice
 import type { VoiceIntegrationSink } from './opsSinks';
 import type { StoredVoiceCallReviewArtifact, VoiceCallReviewArtifact, VoiceCallReviewStore } from './testing/review';
 import type { VoiceTraceEventStore } from './trace';
+import type { VoiceLiveOpsControlState } from './liveOps';
 export type AudioFormat = {
     container: 'raw';
     encoding: 'alaw' | 'mulaw' | 'pcm_s16le';
@@ -193,6 +194,15 @@ export type RealtimeAdapter<TOptions extends RealtimeAdapterOpenOptions = Realti
     open: (options: TOptions) => Promise<RealtimeAdapterSession> | RealtimeAdapterSession;
 };
 export type VoiceSessionStatus = 'active' | 'reconnecting' | 'completed' | 'failed';
+export type VoiceReconnectClientStatus = 'idle' | 'reconnecting' | 'resumed' | 'exhausted';
+export type VoiceReconnectClientState = {
+    attempts: number;
+    lastDisconnectAt?: number;
+    lastResumedAt?: number;
+    maxAttempts: number;
+    nextAttemptAt?: number;
+    status: VoiceReconnectClientStatus;
+};
 export type VoiceTurnRecord<TResult = unknown> = {
     id: string;
     text: string;
@@ -269,6 +279,65 @@ 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 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>;
+    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>[];
+    deliveryQueue?: VoiceHandoffDeliveryStore<StoredVoiceHandoffDelivery<TContext, TSession, TResult>>;
+    enqueueOnly?: boolean;
+    failMode?: 'record' | 'throw';
+};
 export type VoiceSessionStore<TSession extends VoiceSessionRecord = VoiceSessionRecord> = SessionStore<TSession, VoiceSessionSummary>;
 export type VoiceLogger = {
     debug?: (message: string, meta?: Record<string, unknown>) => void;
@@ -416,6 +485,10 @@ export type VoiceLexiconResolver<TContext = unknown> = (input: {
 }) => Promise<VoiceLexiconEntry[] | void> | VoiceLexiconEntry[] | void;
 export type VoiceOnTurnObjectHandler<TContext = unknown, TSession extends VoiceSessionRecord = VoiceSessionRecord, TResult = unknown> = (input: {
     context: TContext;
+    liveOps?: {
+        control: VoiceLiveOpsControlState;
+        injectedInstruction?: string;
+    };
     session: TSession;
     turn: VoiceTurnRecord;
     api: VoiceSessionHandle<TContext, TSession, TResult>;
@@ -537,6 +610,9 @@ export type VoiceRuntimeOpsConfig<TContext = unknown, TSession extends VoiceSess
     tasks?: VoiceOpsTaskStore;
     webhook?: VoiceIntegrationWebhookConfig;
 };
+export type VoiceLiveOpsRuntimeConfig = {
+    getControl: (sessionId: string) => Promise<VoiceLiveOpsControlState | null | undefined> | VoiceLiveOpsControlState | null | undefined;
+};
 export type VoiceNormalizedRouteConfig<TContext = unknown, TSession extends VoiceSessionRecord = VoiceSessionRecord, TResult = unknown> = Omit<VoiceRouteConfig<TContext, TSession, TResult>, 'onTurn'> & {
     onTurn: VoiceOnTurnObjectHandler<TContext, TSession, TResult>;
 };
@@ -557,9 +633,11 @@ export type VoicePluginConfig<TContext = unknown, TSession extends VoiceSessionR
     lexicon?: VoiceLexiconEntry[] | VoiceLexiconResolver<TContext>;
     phraseHints?: VoicePhraseHint[] | VoicePhraseHintResolver<TContext>;
     preset?: VoiceRuntimePreset;
-    stt: STTAdapter;
+    stt?: STTAdapter;
     sttFallback?: VoiceSTTFallbackConfig;
     sttLifecycle?: VoiceSTTLifecycle;
+    realtime?: RealtimeAdapter;
+    realtimeInputFormat?: AudioFormat;
     tts?: TTSAdapter;
     session: VoiceSessionStore<NoInfer<TSession>>;
     reconnect?: VoiceReconnectConfig;
@@ -567,7 +645,9 @@ 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>;
+    liveOps?: VoiceLiveOpsRuntimeConfig;
     trace?: VoiceTraceEventStore;
 } & VoiceRouteConfig<TContext, TSession, TResult>;
 export type CreateVoiceSessionOptions<TContext = unknown, TSession extends VoiceSessionRecord = VoiceSessionRecord, TResult = unknown> = {
@@ -575,7 +655,9 @@ export type CreateVoiceSessionOptions<TContext = unknown, TSession extends Voice
     id: string;
     context: TContext;
     socket: VoiceSocket;
-    stt: STTAdapter;
+    stt?: STTAdapter;
+    realtime?: RealtimeAdapter;
+    realtimeInputFormat?: AudioFormat;
     tts?: TTSAdapter;
     languageStrategy?: VoiceLanguageStrategy;
     lexicon?: VoiceLexiconEntry[];
@@ -588,6 +670,8 @@ export type CreateVoiceSessionOptions<TContext = unknown, TSession extends Voice
     sttLifecycle: VoiceSTTLifecycle;
     turnDetection: VoiceResolvedTurnDetectionConfig;
     audioConditioning?: VoiceResolvedAudioConditioningConfig;
+    handoff?: VoiceHandoffConfig<TContext, TSession, TResult>;
+    liveOps?: VoiceLiveOpsRuntimeConfig;
     route: VoiceNormalizedRouteConfig<TContext, TSession, TResult>;
     logger?: VoiceLogger;
 };
@@ -604,16 +688,33 @@ export type VoiceClientCloseMessage = {
     type: 'close';
     reason?: string;
 };
+export type VoiceClientCallControlMessage = {
+    type: 'call_control';
+    action: 'complete' | 'escalate' | 'no-answer' | 'transfer' | 'voicemail';
+    metadata?: Record<string, unknown>;
+    reason?: string;
+    target?: string;
+};
 export type VoiceClientPingMessage = {
     type: 'ping';
 };
-export type VoiceClientMessage = VoiceClientStartMessage | VoiceClientEndTurnMessage | VoiceClientCloseMessage | VoiceClientPingMessage;
+export type VoiceClientMessage = VoiceClientStartMessage | VoiceClientEndTurnMessage | VoiceClientCloseMessage | VoiceClientCallControlMessage | VoiceClientPingMessage;
 export type VoiceServerSessionMessage = {
     type: 'session';
     sessionId: string;
     status: VoiceSessionStatus;
     scenarioId?: string;
 };
+export type VoiceServerReplayMessage<TResult = unknown> = {
+    type: 'replay';
+    assistantTexts: string[];
+    call?: VoiceCallLifecycleState;
+    partial: string;
+    scenarioId?: string;
+    sessionId: string;
+    status: VoiceSessionStatus;
+    turns: VoiceTurnRecord<TResult>[];
+};
 export type VoiceServerPartialMessage = {
     type: 'partial';
     transcript: Transcript;
@@ -642,6 +743,11 @@ export type VoiceServerCompleteMessage = {
     type: 'complete';
     sessionId: string;
 };
+export type VoiceServerCallLifecycleMessage = {
+    type: 'call_lifecycle';
+    event: VoiceCallLifecycleEvent;
+    sessionId: string;
+};
 export type VoiceServerErrorMessage = {
     type: 'error';
     message: string;
@@ -650,17 +756,23 @@ export type VoiceServerErrorMessage = {
 export type VoiceServerPongMessage = {
     type: 'pong';
 };
-export type VoiceServerMessage<TResult = unknown> = VoiceServerSessionMessage | VoiceServerPartialMessage | VoiceServerFinalMessage | VoiceServerTurnMessage<TResult> | VoiceServerAssistantMessage | VoiceServerAudioMessage | VoiceServerCompleteMessage | VoiceServerErrorMessage | VoiceServerPongMessage;
+export type VoiceServerConnectionMessage = {
+    type: 'connection';
+    reconnect: VoiceReconnectClientState;
+};
+export type VoiceServerMessage<TResult = unknown> = VoiceServerSessionMessage | VoiceServerReplayMessage<TResult> | VoiceServerPartialMessage | VoiceServerFinalMessage | VoiceServerTurnMessage<TResult> | VoiceServerAssistantMessage | VoiceServerAudioMessage | VoiceServerCallLifecycleMessage | VoiceServerCompleteMessage | VoiceServerErrorMessage | VoiceServerPongMessage | VoiceServerConnectionMessage;
 export type VoiceConnectionOptions = {
     protocols?: string[];
     scenarioId?: string;
     reconnect?: boolean;
+    reconnectReportPath?: string;
     maxReconnectAttempts?: number;
     pingInterval?: number;
     sessionId?: string;
 };
 export type VoiceCaptureOptions = {
     channelCount?: 1 | 2;
+    onAudio?: (audio: Uint8Array | ArrayBuffer, sendAudio: (audio: Uint8Array | ArrayBuffer) => void) => void;
     onLevel?: (level: number) => void;
     sampleRateHz?: number;
 };
@@ -674,6 +786,46 @@ export type VoiceBargeInOptions = {
     enabled?: boolean;
     interruptOnPartial?: boolean;
     interruptThreshold?: number;
+    monitor?: VoiceBargeInMonitor;
+};
+export type VoiceBargeInTriggerReason = 'input-level' | 'manual-audio' | 'manual-interrupt' | 'partial-transcript';
+export type VoiceBargeInMonitorEvent = {
+    at: number;
+    id: string;
+    latencyMs?: number;
+    playbackStopLatencyMs?: number;
+    reason: VoiceBargeInTriggerReason;
+    sessionId?: string | null;
+    status: 'requested' | 'stopped' | 'skipped';
+    thresholdMs?: number;
+};
+export type VoiceBargeInMonitorSnapshot = {
+    averageLatencyMs?: number;
+    events: VoiceBargeInMonitorEvent[];
+    failed: number;
+    lastEvent?: VoiceBargeInMonitorEvent;
+    passed: number;
+    status: 'empty' | 'fail' | 'pass' | 'warn';
+    thresholdMs: number;
+    total: number;
+};
+export type VoiceBargeInMonitor = {
+    getSnapshot: () => VoiceBargeInMonitorSnapshot;
+    recordRequested: (input: {
+        reason: VoiceBargeInTriggerReason;
+        sessionId?: string | null;
+    }) => VoiceBargeInMonitorEvent;
+    recordSkipped: (input: {
+        reason: VoiceBargeInTriggerReason;
+        sessionId?: string | null;
+    }) => VoiceBargeInMonitorEvent;
+    recordStopped: (input: {
+        latencyMs?: number;
+        playbackStopLatencyMs?: number;
+        reason: VoiceBargeInTriggerReason;
+        sessionId?: string | null;
+    }) => VoiceBargeInMonitorEvent;
+    subscribe: (subscriber: () => void) => () => void;
 };
 export type VoiceAudioPlayerOptions = {
     autoStart?: boolean;
@@ -728,9 +880,11 @@ export type VoiceHTMXOptions<TSession extends VoiceSessionRecord = VoiceSessionR
 };
 export type VoiceHTMXConfig<TSession extends VoiceSessionRecord = VoiceSessionRecord, TResult = unknown> = VoiceHTMXRenderer<TSession, TResult> | VoiceHTMXOptions<TSession, TResult>;
 export type VoiceStreamState<TResult = unknown> = {
+    call: VoiceCallLifecycleState | null;
     sessionId: string | null;
     scenarioId: string | null;
     status: VoiceSessionStatus | 'idle';
+    reconnect: VoiceReconnectClientState;
     partial: string;
     turns: VoiceTurnRecord<TResult>[];
     assistantTexts: string[];
@@ -744,6 +898,8 @@ export type VoiceStreamState<TResult = unknown> = {
     isConnected: boolean;
 };
 export type VoiceStream<TResult = unknown> = {
+    call: VoiceCallLifecycleState | null;
+    callControl: (message: Omit<VoiceClientCallControlMessage, 'type'>) => void;
     close: () => void;
     start: (input?: {
         scenarioId?: string;
@@ -755,6 +911,7 @@ export type VoiceStream<TResult = unknown> = {
     getSnapshot: () => VoiceStreamState<TResult>;
     isConnected: boolean;
     partial: string;
+    reconnect: VoiceReconnectClientState;
     sendAudio: (audio: Uint8Array | ArrayBuffer) => void;
     sessionId: string | null;
     scenarioId: string | null;
@@ -810,6 +967,8 @@ export type VoiceBargeInBinding = {
 };
 export type VoiceController<TResult = unknown> = {
     bindHTMX: (options: VoiceHTMXBindingOptions) => () => void;
+    call: VoiceCallLifecycleState | null;
+    callControl: (message: Omit<VoiceClientCallControlMessage, 'type'>) => void;
     close: () => void;
     endTurn: () => void;
     start: (input?: {
@@ -822,6 +981,7 @@ export type VoiceController<TResult = unknown> = {
     isConnected: boolean;
     isRecording: boolean;
     partial: string;
+    reconnect: VoiceReconnectClientState;
     recordingError: string | null;
     sendAudio: (audio: Uint8Array | ArrayBuffer) => void;
     sessionId: string | null;
@@ -855,6 +1015,19 @@ export type VoiceStoreAction<TResult = unknown> = {
     sessionId: string;
     scenarioId?: string;
     status: VoiceSessionStatus;
+} | {
+    type: 'replay';
+    assistantTexts: string[];
+    call?: VoiceCallLifecycleState;
+    partial: string;
+    scenarioId?: string;
+    sessionId: string;
+    status: VoiceSessionStatus;
+    turns: VoiceTurnRecord<TResult>[];
+} | {
+    type: 'call_lifecycle';
+    event: VoiceCallLifecycleEvent;
+    sessionId: string;
 } | {
     type: 'partial';
     transcript: Transcript;
@@ -881,6 +1054,9 @@ export type VoiceStoreAction<TResult = unknown> = {
     message: string;
 } | {
     type: 'connected';
+} | {
+    type: 'connection';
+    reconnect: VoiceReconnectClientState;
 } | {
     type: 'disconnected';
 };