@clawvoice/voice-assistant 1.0.0

package/dist/voice/bridge.js

@@ -0,0 +1,411 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VoiceBridgeService = void 0;
+const types_1 = require("./types");
+const TWILIO_CHUNK_SIZE = 160;
+const BUFFER_CHUNKS = 20;
+const BUFFER_SIZE = TWILIO_CHUNK_SIZE * BUFFER_CHUNKS;
+const HEARTBEAT_TIMEOUT_MS = 2000;
+class VoiceBridgeService {
+    constructor(config) {
+        this.config = config;
+        this.bridges = new Map();
+        this.disconnectionHandler = null;
+    }
+    onDisconnection(handler) {
+        this.disconnectionHandler = handler;
+    }
+    negotiateAndValidate(telephonyCodec = "mulaw", voiceProviderCodec = "mulaw", sampleRate = 8000) {
+        return (0, types_1.negotiateCodec)(telephonyCodec, voiceProviderCodec, sampleRate);
+    }
+    createSession(sessionConfig) {
+        const codecResult = this.negotiateAndValidate(sessionConfig.telephonyCodec, sessionConfig.voiceProviderCodec, sessionConfig.sampleRate);
+        if (!codecResult.ok) {
+            return {
+                type: "error",
+                callId: sessionConfig.callId,
+                timestamp: new Date().toISOString(),
+                data: {
+                    error: codecResult.error,
+                    suggestion: codecResult.suggestion,
+                },
+            };
+        }
+        const bridge = {
+            callId: sessionConfig.callId,
+            providerCallId: sessionConfig.providerCallId,
+            codecResult,
+            transcript: [],
+            keepAliveTimer: null,
+            heartbeatTimer: null,
+            lastActivityAt: Date.now(),
+            greetingGraceActive: true,
+            audioBuffer: Buffer.alloc(BUFFER_SIZE),
+            audioBufferOffset: 0,
+            connected: false,
+            startedAt: new Date().toISOString(),
+            turnState: "idle",
+            pendingFunctionCalls: new Map(),
+            disconnectionRecord: null,
+            failures: [],
+            voiceSocket: null,
+        };
+        this.bridges.set(sessionConfig.callId, bridge);
+        return {
+            type: "connected",
+            callId: sessionConfig.callId,
+            timestamp: bridge.startedAt,
+            data: {
+                codec: codecResult.telephonyCodec,
+                sampleRate: codecResult.sampleRate,
+                voiceModel: sessionConfig.voiceModel,
+            },
+        };
+    }
+    buildSettingsMessage(sessionConfig) {
+        return {
+            type: "Settings",
+            audio: {
+                input: {
+                    encoding: sessionConfig.telephonyCodec === "mulaw" ? "mulaw" : "linear16",
+                    sample_rate: sessionConfig.sampleRate,
+                },
+                output: {
+                    encoding: sessionConfig.voiceProviderCodec === "mulaw" ? "mulaw" : "linear16",
+                    sample_rate: sessionConfig.sampleRate,
+                    container: "none",
+                },
+            },
+            agent: {
+                listen: { model: "nova-3" },
+                speak: { model: sessionConfig.voiceModel },
+                think: {
+                    provider: { type: "open_ai" },
+                    model: this.config.analysisModel,
+                    instructions: sessionConfig.systemPrompt ?? "",
+                },
+                greeting: { text: sessionConfig.greeting },
+            },
+        };
+    }
+    setVoiceSocket(callId, socket) {
+        const bridge = this.bridges.get(callId);
+        if (bridge) {
+            bridge.voiceSocket = socket;
+        }
+    }
+    getVoiceSocket(callId) {
+        return this.bridges.get(callId)?.voiceSocket ?? null;
+    }
+    startKeepAlive(callId, intervalMs) {
+        const bridge = this.bridges.get(callId);
+        if (!bridge) {
+            return;
+        }
+        bridge.connected = true;
+        if (bridge.keepAliveTimer) {
+            clearInterval(bridge.keepAliveTimer);
+        }
+        bridge.keepAliveTimer = setInterval(() => {
+            if (bridge.voiceSocket && bridge.voiceSocket.readyState === 1) {
+                bridge.voiceSocket.send(JSON.stringify({ type: "KeepAlive" }));
+            }
+        }, intervalMs);
+        bridge.keepAliveTimer.unref?.();
+    }
+    recordActivity(callId) {
+        const bridge = this.bridges.get(callId);
+        if (bridge) {
+            bridge.lastActivityAt = Date.now();
+        }
+    }
+    startHeartbeatMonitor(callId, timeoutMs = HEARTBEAT_TIMEOUT_MS) {
+        const bridge = this.bridges.get(callId);
+        if (!bridge) {
+            return;
+        }
+        this.stopHeartbeatMonitor(callId);
+        bridge.lastActivityAt = Date.now();
+        const check = () => {
+            const b = this.bridges.get(callId);
+            if (!b || !b.connected) {
+                return;
+            }
+            const elapsed = Date.now() - b.lastActivityAt;
+            if (elapsed >= timeoutMs) {
+                this.reportDisconnection(callId, "heartbeat_timeout", `No activity for ${elapsed}ms (threshold: ${timeoutMs}ms)`);
+                return;
+            }
+            b.heartbeatTimer = setTimeout(check, Math.max(timeoutMs - elapsed, 100));
+            b.heartbeatTimer.unref?.();
+        };
+        bridge.heartbeatTimer = setTimeout(check, timeoutMs);
+        bridge.heartbeatTimer.unref?.();
+    }
+    stopHeartbeatMonitor(callId) {
+        const bridge = this.bridges.get(callId);
+        if (bridge?.heartbeatTimer) {
+            clearTimeout(bridge.heartbeatTimer);
+            bridge.heartbeatTimer = null;
+        }
+    }
+    reportDisconnection(callId, reason, detail) {
+        const bridge = this.bridges.get(callId);
+        if (!bridge) {
+            return null;
+        }
+        const startMs = new Date(bridge.startedAt).getTime();
+        const record = {
+            callId,
+            reason,
+            detail,
+            detectedAt: new Date().toISOString(),
+            callDurationMs: Date.now() - startMs,
+            transcriptLength: bridge.transcript.length,
+        };
+        bridge.disconnectionRecord = record;
+        bridge.connected = false;
+        bridge.failures.push({
+            type: "disconnection",
+            description: `${reason}: ${detail}`,
+            timestamp: new Date().toISOString(),
+        });
+        this.stopHeartbeatMonitor(callId);
+        if (this.disconnectionHandler) {
+            this.disconnectionHandler(record);
+        }
+        return record;
+    }
+    getDisconnectionRecord(callId) {
+        return this.bridges.get(callId)?.disconnectionRecord ?? null;
+    }
+    endGreetingGrace(callId) {
+        const bridge = this.bridges.get(callId);
+        if (bridge) {
+            bridge.greetingGraceActive = false;
+        }
+    }
+    isGreetingGraceActive(callId) {
+        return this.bridges.get(callId)?.greetingGraceActive ?? false;
+    }
+    bufferTelephonyAudio(callId, chunk) {
+        const bridge = this.bridges.get(callId);
+        if (!bridge) {
+            return null;
+        }
+        bridge.lastActivityAt = Date.now();
+        const remaining = BUFFER_SIZE - bridge.audioBufferOffset;
+        const toCopy = Math.min(chunk.length, remaining);
+        chunk.copy(bridge.audioBuffer, bridge.audioBufferOffset, 0, toCopy);
+        bridge.audioBufferOffset += toCopy;
+        if (bridge.audioBufferOffset >= BUFFER_SIZE) {
+            const flushed = Buffer.from(bridge.audioBuffer.subarray(0, BUFFER_SIZE));
+            bridge.audioBufferOffset = 0;
+            return flushed;
+        }
+        return null;
+    }
+    flushAudioBuffer(callId) {
+        const bridge = this.bridges.get(callId);
+        if (!bridge || bridge.audioBufferOffset === 0) {
+            return null;
+        }
+        const flushed = Buffer.from(bridge.audioBuffer.subarray(0, bridge.audioBufferOffset));
+        bridge.audioBufferOffset = 0;
+        return flushed;
+    }
+    addTranscriptEntry(callId, entry) {
+        const bridge = this.bridges.get(callId);
+        if (bridge) {
+            bridge.transcript.push(entry);
+        }
+    }
+    getTranscript(callId) {
+        return this.bridges.get(callId)?.transcript ?? [];
+    }
+    destroySession(callId) {
+        const bridge = this.bridges.get(callId);
+        if (bridge?.keepAliveTimer) {
+            clearInterval(bridge.keepAliveTimer);
+        }
+        if (bridge?.heartbeatTimer) {
+            clearTimeout(bridge.heartbeatTimer);
+        }
+        if (bridge?.voiceSocket) {
+            try {
+                bridge.voiceSocket.close();
+            }
+            catch { /* ignore */ }
+        }
+        this.bridges.delete(callId);
+        return {
+            type: "disconnected",
+            callId,
+            timestamp: new Date().toISOString(),
+            data: {
+                transcriptLength: bridge?.transcript.length ?? 0,
+            },
+        };
+    }
+    handleVoiceAgentMessage(callId, message) {
+        const bridge = this.bridges.get(callId);
+        if (!bridge) {
+            return { action: "none" };
+        }
+        bridge.lastActivityAt = Date.now();
+        const msgType = message.type;
+        switch (msgType) {
+            case "SettingsApplied":
+                bridge.connected = true;
+                return { action: "settings_applied" };
+            case "UserStartedSpeaking":
+                return this.handleBargeIn(callId);
+            case "AgentStartedSpeaking":
+                bridge.turnState = "agent_speaking";
+                return { action: "turn_change", state: "agent_speaking" };
+            case "ConversationText": {
+                const role = message.role;
+                const content = message.content;
+                if (role && content) {
+                    const speaker = role === "user" ? "user" : "agent";
+                    const entry = {
+                        speaker,
+                        text: content,
+                        timestamp: new Date().toISOString(),
+                    };
+                    bridge.transcript.push(entry);
+                    return { action: "transcript", entry };
+                }
+                return { action: "none" };
+            }
+            case "FunctionCallRequest": {
+                const fcReq = {
+                    id: message.function_call_id,
+                    name: message.function_name,
+                    input: message.input ?? {},
+                };
+                bridge.pendingFunctionCalls.set(fcReq.id, fcReq);
+                return { action: "function_call", request: fcReq };
+            }
+            case "Error": {
+                const errorMsg = message.message ?? "Unknown voice agent error";
+                const record = this.reportDisconnection(callId, "voice_provider_error", errorMsg);
+                if (record) {
+                    return { action: "disconnection", record };
+                }
+                return { action: "error", error: errorMsg };
+            }
+            default:
+                return { action: "none" };
+        }
+    }
+    handleBargeIn(callId) {
+        const bridge = this.bridges.get(callId);
+        if (!bridge) {
+            return { action: "none" };
+        }
+        const duringGrace = bridge.greetingGraceActive;
+        bridge.turnState = "user_speaking";
+        return { action: "barge_in", duringGrace };
+    }
+    completeFunctionCall(callId, response) {
+        const bridge = this.bridges.get(callId);
+        if (!bridge) {
+            return false;
+        }
+        bridge.pendingFunctionCalls.delete(response.id);
+        return true;
+    }
+    getTurnState(callId) {
+        return this.bridges.get(callId)?.turnState ?? "idle";
+    }
+    setTurnState(callId, state) {
+        const bridge = this.bridges.get(callId);
+        if (bridge) {
+            bridge.turnState = state;
+        }
+    }
+    getPendingFunctionCalls(callId) {
+        const bridge = this.bridges.get(callId);
+        if (!bridge) {
+            return [];
+        }
+        return Array.from(bridge.pendingFunctionCalls.values());
+    }
+    recordFailure(callId, failure) {
+        const bridge = this.bridges.get(callId);
+        if (bridge) {
+            bridge.failures.push(failure);
+        }
+    }
+    getFailures(callId) {
+        return this.bridges.get(callId)?.failures ?? [];
+    }
+    generateCallSummary(callId) {
+        const bridge = this.bridges.get(callId);
+        if (!bridge) {
+            return null;
+        }
+        const startMs = new Date(bridge.startedAt).getTime();
+        const durationMs = Date.now() - startMs;
+        const pendingActions = Array.from(bridge.pendingFunctionCalls.values()).map((fc) => `${fc.name}(${JSON.stringify(fc.input)})`);
+        const outcome = this.determineOutcome(bridge);
+        const retryContext = outcome !== "completed"
+            ? this.buildRetryContext(bridge, pendingActions)
+            : null;
+        return {
+            callId,
+            outcome,
+            durationMs,
+            transcriptLength: bridge.transcript.length,
+            failures: [...bridge.failures],
+            pendingActions,
+            retryContext,
+            completedAt: new Date().toISOString(),
+        };
+    }
+    determineOutcome(bridge) {
+        if (bridge.failures.length === 0 && bridge.pendingFunctionCalls.size === 0) {
+            return "completed";
+        }
+        const hasHardFailure = bridge.failures.some((f) => f.type === "disconnection" || f.type === "timeout");
+        if (hasHardFailure || bridge.transcript.length === 0) {
+            return "failed";
+        }
+        return "partial";
+    }
+    buildRetryContext(bridge, pendingActions) {
+        const failureReasons = bridge.failures.map((f) => f.description);
+        if (bridge.disconnectionRecord) {
+            failureReasons.push(`Disconnected: ${bridge.disconnectionRecord.reason} — ${bridge.disconnectionRecord.detail}`);
+        }
+        const lastEntries = bridge.transcript.slice(-3);
+        const previousTranscriptSummary = lastEntries.length > 0
+            ? lastEntries.map((e) => `${e.speaker}: ${e.text}`).join(" | ")
+            : "No transcript recorded.";
+        const suggestedApproach = pendingActions.length > 0
+            ? `Retry with pending actions: ${pendingActions.join(", ")}`
+            : failureReasons.length > 0
+                ? `Address failures: ${failureReasons.join("; ")}`
+                : "Retry call with same parameters.";
+        return {
+            originalCallId: bridge.callId,
+            failureReasons,
+            uncompletedActions: pendingActions,
+            previousTranscriptSummary,
+            suggestedApproach,
+        };
+    }
+    getActiveBridgeCount() {
+        return this.bridges.size;
+    }
+    hasActiveBridge(callId) {
+        return this.bridges.has(callId);
+    }
+    async stopAll() {
+        for (const callId of Array.from(this.bridges.keys())) {
+            this.destroySession(callId);
+        }
+    }
+}
+exports.VoiceBridgeService = VoiceBridgeService;

package/dist/voice/types.d.ts

@@ -0,0 +1,168 @@
+/**
+ * Supported audio codecs for telephony ↔ voice provider bridging.
+ */
+export type AudioCodec = "mulaw" | "pcm16";
+/**
+ * Audio format negotiation result.
+ */
+export interface AudioFormat {
+    codec: AudioCodec;
+    sampleRate: number;
+    channels: number;
+}
+/**
+ * Configuration for a voice bridge session.
+ */
+export interface BridgeSessionConfig {
+    callId: string;
+    providerCallId: string;
+    voiceProviderUrl: string;
+    voiceProviderAuth: string;
+    telephonyCodec: AudioCodec;
+    voiceProviderCodec: AudioCodec;
+    sampleRate: number;
+    greeting: string;
+    systemPrompt?: string;
+    voiceModel: string;
+    keepAliveIntervalMs: number;
+    greetingGracePeriodMs: number;
+}
+/**
+ * Events emitted by a VoiceBridge session.
+ */
+export type BridgeEventType = "connected" | "audio_from_agent" | "transcript" | "agent_speaking" | "user_speaking" | "function_call" | "error" | "disconnected";
+export interface BridgeEvent {
+    type: BridgeEventType;
+    callId: string;
+    timestamp: string;
+    data?: Record<string, unknown>;
+}
+/**
+ * Transcript entry for a voice bridge session.
+ */
+export interface TranscriptEntry {
+    speaker: "user" | "agent";
+    text: string;
+    timestamp: string;
+}
+/**
+ * Turn-taking state for a voice bridge session.
+ */
+export type TurnState = "idle" | "agent_speaking" | "user_speaking";
+/**
+ * Reasons a voice bridge session can disconnect.
+ */
+export type DisconnectionReason = "heartbeat_timeout" | "voice_provider_error" | "telephony_provider_error" | "agent_ended" | "user_hangup" | "max_duration" | "unknown";
+/**
+ * Disconnection event data logged when a call terminates unexpectedly.
+ */
+export interface DisconnectionRecord {
+    callId: string;
+    reason: DisconnectionReason;
+    detail: string;
+    detectedAt: string;
+    callDurationMs: number;
+    transcriptLength: number;
+}
+/**
+ * Inbound function call request from the voice agent.
+ */
+export interface FunctionCallRequest {
+    id: string;
+    name: string;
+    input: Record<string, unknown>;
+}
+/**
+ * Outbound function call response back to the voice agent.
+ */
+export interface FunctionCallResponse {
+    id: string;
+    name: string;
+    output: string;
+}
+/**
+ * Result from processing a voice agent message through the bridge.
+ */
+export type VoiceAgentMessageResult = {
+    action: "audio";
+    data: Buffer;
+} | {
+    action: "function_call";
+    request: FunctionCallRequest;
+} | {
+    action: "barge_in";
+    duringGrace: boolean;
+} | {
+    action: "transcript";
+    entry: TranscriptEntry;
+} | {
+    action: "turn_change";
+    state: TurnState;
+} | {
+    action: "settings_applied";
+} | {
+    action: "error";
+    error: string;
+} | {
+    action: "disconnection";
+    record: DisconnectionRecord;
+} | {
+    action: "none";
+};
+/**
+ * Completion status of a call.
+ */
+export type CallOutcome = "completed" | "partial" | "failed";
+/**
+ * Specific failure that occurred during a call.
+ */
+export interface CallFailure {
+    type: "tool_failure" | "missing_data" | "timeout" | "disconnection" | "agent_error";
+    description: string;
+    timestamp: string;
+    functionCallId?: string;
+}
+/**
+ * Post-call summary including outcome, failures, and retry context.
+ */
+export interface CallSummary {
+    callId: string;
+    outcome: CallOutcome;
+    durationMs: number;
+    transcriptLength: number;
+    failures: CallFailure[];
+    pendingActions: string[];
+    retryContext: RetryContext | null;
+    completedAt: string;
+}
+/**
+ * Context for retrying a call that was incomplete or failed.
+ */
+export interface RetryContext {
+    originalCallId: string;
+    failureReasons: string[];
+    uncompletedActions: string[];
+    previousTranscriptSummary: string;
+    suggestedApproach: string;
+}
+/**
+ * Codec negotiation result — either success or actionable diagnostic.
+ */
+export type CodecNegotiationResult = {
+    ok: true;
+    telephonyCodec: AudioCodec;
+    voiceProviderCodec: AudioCodec;
+    sampleRate: number;
+} | {
+    ok: false;
+    error: string;
+    suggestion: string;
+};
+/**
+ * Negotiate audio codec between telephony provider and voice provider.
+ *
+ * Telephony side (Twilio/Telnyx) sends mulaw 8kHz.
+ * Deepgram Voice Agent accepts mulaw 8kHz for input and produces mulaw 8kHz output.
+ * If codecs don't match, return actionable diagnostic.
+ */
+export declare function negotiateCodec(telephonyCodec: AudioCodec, voiceProviderCodec: AudioCodec, sampleRate: number): CodecNegotiationResult;

package/dist/voice/types.js

@@ -0,0 +1,42 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.negotiateCodec = negotiateCodec;
+/**
+ * Negotiate audio codec between telephony provider and voice provider.
+ *
+ * Telephony side (Twilio/Telnyx) sends mulaw 8kHz.
+ * Deepgram Voice Agent accepts mulaw 8kHz for input and produces mulaw 8kHz output.
+ * If codecs don't match, return actionable diagnostic.
+ */
+function negotiateCodec(telephonyCodec, voiceProviderCodec, sampleRate) {
+    const supportedTelephony = ["mulaw"];
+    const supportedVoice = ["mulaw", "pcm16"];
+    const supportedRates = [8000];
+    if (!supportedTelephony.includes(telephonyCodec)) {
+        return {
+            ok: false,
+            error: `Telephony codec "${telephonyCodec}" is not supported. Supported: ${supportedTelephony.join(", ")}.`,
+            suggestion: "Set telephony provider to stream mulaw audio (default for Twilio/Telnyx media streams).",
+        };
+    }
+    if (!supportedVoice.includes(voiceProviderCodec)) {
+        return {
+            ok: false,
+            error: `Voice provider codec "${voiceProviderCodec}" is not supported. Supported: ${supportedVoice.join(", ")}.`,
+            suggestion: "Configure voice provider to use mulaw or pcm16 encoding.",
+        };
+    }
+    if (!supportedRates.includes(sampleRate)) {
+        return {
+            ok: false,
+            error: `Sample rate ${sampleRate}Hz is not supported. Supported: ${supportedRates.join(", ")}Hz.`,
+            suggestion: "Use 8000Hz sample rate for telephony audio.",
+        };
+    }
+    return {
+        ok: true,
+        telephonyCodec,
+        voiceProviderCodec,
+        sampleRate,
+    };
+}

package/dist/webhooks/verify.d.ts

@@ -0,0 +1,30 @@
+import { ClawVoiceConfig } from "../config";
+export interface WebhookVerificationResult {
+    valid: boolean;
+    provider: "telnyx" | "twilio";
+    reason?: string;
+}
+/**
+ * Verify Telnyx webhook signature using Ed25519 public-key cryptography.
+ * Telnyx sends `telnyx-signature-ed25519` and `telnyx-timestamp` headers.
+ * The signed payload is `timestamp|payload`.
+ * The `secret` parameter is the Ed25519 public key from the Telnyx dashboard.
+ */
+export declare function verifyTelnyxSignature(payload: string, signatureHeader: string | undefined, timestampHeader: string | undefined, publicKey: string | undefined): WebhookVerificationResult;
+/**
+ * Verify Twilio webhook signature using HMAC-SHA1.
+ * Twilio computes HMAC-SHA1 of the request URL + sorted POST params.
+ */
+export declare function verifyTwilioSignature(url: string, params: Record<string, string>, signatureHeader: string | undefined, authToken: string | undefined): WebhookVerificationResult;
+/**
+ * Get the appropriate verification function for the configured provider.
+ */
+export declare function getVerifier(config: ClawVoiceConfig): {
+    verify: typeof verifyTelnyxSignature;
+    secret: string | undefined;
+    token?: undefined;
+} | {
+    verify: typeof verifyTwilioSignature;
+    token: string | undefined;
+    secret?: undefined;
+};