@clawvoice/voice-assistant 1.0.0

package/dist/services/memory-extraction.js

@@ -0,0 +1,117 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MemoryExtractionService = void 0;
+const CATEGORY_PATTERNS = [
+    { category: "health", pattern: /\b(medication|doctor|appointment|pain|health|symptom|medicine)\b/i },
+    { category: "schedule", pattern: /\b(tomorrow|next week|monday|tuesday|wednesday|thursday|friday|at \d|o'clock|appointment)\b/i },
+    { category: "preference", pattern: /\b(i (like|prefer|enjoy|love|hate|dislike)|my favorite|i always|i never)\b/i },
+    { category: "relationship", pattern: /\b(my (son|daughter|wife|husband|friend|neighbor|sister|brother|mother|father))\b/i },
+    { category: "interest", pattern: /\b(hobby|garden|cook|read|music|sport|travel|game)\b/i },
+];
+class MemoryExtractionService {
+    constructor(config) {
+        this.config = config;
+        this.candidates = new Map();
+        this.memoryWriter = null;
+        this.memoryReader = null;
+        this.idCounter = 0;
+    }
+    setMemoryWriter(writer) {
+        this.memoryWriter = writer;
+    }
+    setMemoryReader(reader) {
+        this.memoryReader = reader;
+    }
+    extractFromTranscript(callId, transcript) {
+        const userTurns = transcript.filter((t) => t.speaker === "user");
+        const found = [];
+        for (const turn of userTurns) {
+            for (const { category, pattern } of CATEGORY_PATTERNS) {
+                if (pattern.test(turn.text)) {
+                    this.idCounter += 1;
+                    found.push({
+                        id: `mem-${callId}-${this.idCounter}`,
+                        callId,
+                        category,
+                        content: turn.text,
+                        confidence: 0.7,
+                        sourceQuote: turn.text.slice(0, 200),
+                        status: "pending",
+                        extractedAt: new Date().toISOString(),
+                    });
+                    break;
+                }
+            }
+        }
+        this.candidates.set(callId, found);
+        return {
+            callId,
+            candidates: found,
+            extractedAt: new Date().toISOString(),
+        };
+    }
+    getPendingCandidates(callId) {
+        if (callId) {
+            return (this.candidates.get(callId) ?? []).filter((c) => c.status === "pending");
+        }
+        const all = [];
+        for (const list of this.candidates.values()) {
+            all.push(...list.filter((c) => c.status === "pending"));
+        }
+        return all;
+    }
+    getCandidate(memoryId) {
+        for (const list of this.candidates.values()) {
+            const found = list.find((c) => c.id === memoryId);
+            if (found)
+                return found;
+        }
+        return undefined;
+    }
+    async approveAndPromote(memoryId) {
+        const candidate = this.getCandidate(memoryId);
+        if (!candidate) {
+            return { promoted: false, reason: "Memory candidate not found." };
+        }
+        if (candidate.status === "promoted") {
+            return { promoted: false, reason: "Already promoted." };
+        }
+        candidate.status = "approved";
+        if (!this.memoryWriter) {
+            return {
+                promoted: false,
+                reason: "No memory writer configured.",
+            };
+        }
+        await this.memoryWriter("main", `voice-promoted/${candidate.id}`, {
+            content: candidate.content,
+            category: candidate.category,
+            sourceCallId: candidate.callId,
+            confidence: candidate.confidence,
+            sourceQuote: candidate.sourceQuote,
+            promotedAt: new Date().toISOString(),
+        });
+        candidate.status = "promoted";
+        candidate.promotedAt = new Date().toISOString();
+        return { promoted: true };
+    }
+    rejectCandidate(memoryId) {
+        const candidate = this.getCandidate(memoryId);
+        if (!candidate || candidate.status !== "pending") {
+            return false;
+        }
+        candidate.status = "rejected";
+        return true;
+    }
+    getAllCandidates() {
+        const all = [];
+        for (const list of this.candidates.values()) {
+            all.push(...list);
+        }
+        return all;
+    }
+    resetIdCounter() {
+        this.idCounter = 0;
+    }
+}
+exports.MemoryExtractionService = MemoryExtractionService;

package/dist/services/post-call.d.ts

@@ -0,0 +1,56 @@
+import { ClawVoiceConfig } from "../config";
+import { CallSummary, TranscriptEntry } from "../voice/types";
+/**
+ * Structured call record persisted to voice-memory/calls/.
+ */
+export interface PersistedCallRecord {
+    callId: string;
+    outcome: string;
+    durationMs: number;
+    transcript: TranscriptEntry[];
+    failures: CallSummary["failures"];
+    pendingActions: string[];
+    retryContext: CallSummary["retryContext"];
+    completedAt: string;
+    persistedAt: string;
+}
+/**
+ * Notification payload sent to integrations after a call.
+ */
+export interface CallNotification {
+    channel: "telegram" | "discord" | "slack";
+    text: string;
+    callId: string;
+}
+export type MemoryWriter = (namespace: string, key: string, value: unknown) => Promise<void>;
+export type NotificationSender = (notification: CallNotification) => Promise<void>;
+/**
+ * Handles post-call transcript persistence and summary delivery.
+ */
+export declare class PostCallService {
+    private readonly config;
+    private memoryWriter;
+    private notificationSender;
+    private static readonly MAX_PROCESSED;
+    private readonly processedCalls;
+    constructor(config: ClawVoiceConfig);
+    setMemoryWriter(writer: MemoryWriter): void;
+    setNotificationSender(sender: NotificationSender): void;
+    /**
+     * Process a completed call: persist transcript and deliver summary.
+     * Idempotent — skips calls already processed.
+     */
+    processCompletedCall(summary: CallSummary, transcript: TranscriptEntry[]): Promise<{
+        persisted: boolean;
+        notified: boolean;
+    }>;
+    private persistCallRecord;
+    private deliverSummary;
+    /**
+     * Format a human-readable summary for notifications.
+     */
+    formatSummaryText(summary: CallSummary, transcript: TranscriptEntry[]): string;
+    private getConfiguredChannels;
+    isProcessed(callId: string): boolean;
+    getProcessedCount(): number;
+}

package/dist/services/post-call.js

@@ -0,0 +1,112 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PostCallService = void 0;
+/**
+ * Handles post-call transcript persistence and summary delivery.
+ */
+class PostCallService {
+    constructor(config) {
+        this.config = config;
+        this.memoryWriter = null;
+        this.notificationSender = null;
+        this.processedCalls = new Set();
+    }
+    setMemoryWriter(writer) {
+        this.memoryWriter = writer;
+    }
+    setNotificationSender(sender) {
+        this.notificationSender = sender;
+    }
+    /**
+     * Process a completed call: persist transcript and deliver summary.
+     * Idempotent — skips calls already processed.
+     */
+    async processCompletedCall(summary, transcript) {
+        if (this.processedCalls.has(summary.callId)) {
+            return { persisted: false, notified: false };
+        }
+        this.processedCalls.add(summary.callId);
+        if (this.processedCalls.size > PostCallService.MAX_PROCESSED) {
+            const oldest = this.processedCalls.values().next().value;
+            if (oldest) {
+                this.processedCalls.delete(oldest);
+            }
+        }
+        const persisted = await this.persistCallRecord(summary, transcript);
+        const notified = await this.deliverSummary(summary, transcript);
+        return { persisted, notified };
+    }
+    async persistCallRecord(summary, transcript) {
+        if (!this.memoryWriter) {
+            return false;
+        }
+        const record = {
+            callId: summary.callId,
+            outcome: summary.outcome,
+            durationMs: summary.durationMs,
+            transcript,
+            failures: summary.failures,
+            pendingActions: summary.pendingActions,
+            retryContext: summary.retryContext,
+            completedAt: summary.completedAt,
+            persistedAt: new Date().toISOString(),
+        };
+        await this.memoryWriter("voice-memory", `calls/${summary.callId}`, record);
+        return true;
+    }
+    async deliverSummary(summary, transcript) {
+        if (!this.notificationSender) {
+            return false;
+        }
+        const text = this.formatSummaryText(summary, transcript);
+        const channels = this.getConfiguredChannels();
+        if (channels.length === 0) {
+            return false;
+        }
+        for (const channel of channels) {
+            await this.notificationSender({
+                channel,
+                text,
+                callId: summary.callId,
+            });
+        }
+        return true;
+    }
+    /**
+     * Format a human-readable summary for notifications.
+     */
+    formatSummaryText(summary, transcript) {
+        const lines = [];
+        lines.push(`Call ${summary.callId} — ${summary.outcome}`);
+        lines.push(`Duration: ${Math.round(summary.durationMs / 1000)}s`);
+        lines.push(`Transcript: ${transcript.length} turns`);
+        if (summary.failures.length > 0) {
+            lines.push(`Failures: ${summary.failures.map((f) => f.description).join("; ")}`);
+        }
+        if (summary.pendingActions.length > 0) {
+            lines.push(`Pending: ${summary.pendingActions.join(", ")}`);
+        }
+        if (summary.retryContext) {
+            lines.push(`Retry: ${summary.retryContext.suggestedApproach}`);
+        }
+        return lines.join("\n");
+    }
+    getConfiguredChannels() {
+        const channels = [];
+        if (this.config.notifyTelegram)
+            channels.push("telegram");
+        if (this.config.notifyDiscord)
+            channels.push("discord");
+        if (this.config.notifySlack)
+            channels.push("slack");
+        return channels;
+    }
+    isProcessed(callId) {
+        return this.processedCalls.has(callId);
+    }
+    getProcessedCount() {
+        return this.processedCalls.size;
+    }
+}
+exports.PostCallService = PostCallService;
+PostCallService.MAX_PROCESSED = 1000;

package/dist/services/relay.d.ts

@@ -0,0 +1,9 @@
+import { ClawVoiceConfig } from "../config";
+export declare class WebSocketRelayService {
+    private readonly config;
+    private running;
+    constructor(config: ClawVoiceConfig);
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    isRunning(): boolean;
+}

package/dist/services/relay.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WebSocketRelayService = void 0;
+class WebSocketRelayService {
+    constructor(config) {
+        this.config = config;
+        this.running = false;
+    }
+    async start() {
+        this.running = this.config.mode === "managed";
+    }
+    async stop() {
+        this.running = false;
+    }
+    isRunning() {
+        return this.running;
+    }
+}
+exports.WebSocketRelayService = WebSocketRelayService;

package/dist/services/voice-call.d.ts

@@ -0,0 +1,61 @@
+import { ClawVoiceConfig } from "../config";
+import { InboundCallRecord } from "../inbound/types";
+import { VoiceBridgeService } from "../voice/bridge";
+import { CallSummary } from "../voice/types";
+import { PostCallService } from "./post-call";
+export interface CallRecord {
+    callId: string;
+    providerCallId: string;
+    to: string;
+    provider: "telnyx" | "twilio";
+    purpose?: string;
+    greeting: string;
+    startedAt: string;
+    endedAt?: string;
+    status: "in-progress" | "completed";
+    summary?: CallSummary;
+}
+export interface StartCallRequest {
+    phoneNumber: string;
+    purpose?: string;
+    greeting?: string;
+}
+export interface StartCallResponse {
+    callId: string;
+    to: string;
+    openingGreeting: string;
+    message: string;
+}
+export interface HangupResponse {
+    callId: string;
+    message: string;
+}
+export declare class VoiceCallService {
+    private readonly config;
+    private running;
+    private readonly activeCalls;
+    private readonly recentCalls;
+    private readonly inboundRecords;
+    private readonly callTimers;
+    private readonly telephonyAdapter;
+    private dailyCallCount;
+    private dailyResetDate;
+    readonly bridge: VoiceBridgeService;
+    readonly postCall: PostCallService;
+    constructor(config: ClawVoiceConfig, fetchFn?: typeof globalThis.fetch);
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    isRunning(): boolean;
+    getProviderSummary(): string;
+    private createCallId;
+    private checkDailyLimit;
+    startCall(request: StartCallRequest): Promise<StartCallResponse>;
+    hangup(callId?: string): Promise<HangupResponse>;
+    getActiveCalls(): CallRecord[];
+    private scheduleAutoHangup;
+    private autoHangup;
+    trackInboundCall(record: InboundCallRecord): void;
+    getInboundRecords(): InboundCallRecord[];
+    getCallSummary(callId: string): CallSummary | null;
+    private completeCall;
+}

package/dist/services/voice-call.js

@@ -0,0 +1,189 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VoiceCallService = void 0;
+const telnyx_1 = require("../telephony/telnyx");
+const twilio_1 = require("../telephony/twilio");
+const bridge_1 = require("../voice/bridge");
+const post_call_1 = require("./post-call");
+class VoiceCallService {
+    constructor(config, fetchFn) {
+        this.config = config;
+        this.running = false;
+        this.activeCalls = new Map();
+        this.recentCalls = [];
+        this.inboundRecords = [];
+        this.callTimers = new Map();
+        this.dailyCallCount = 0;
+        this.dailyResetDate = new Date().toISOString().slice(0, 10);
+        this.telephonyAdapter =
+            config.telephonyProvider === "twilio"
+                ? new twilio_1.TwilioTelephonyAdapter(config, fetchFn)
+                : new telnyx_1.TelnyxTelephonyAdapter(config, fetchFn);
+        this.bridge = new bridge_1.VoiceBridgeService(config);
+        this.postCall = new post_call_1.PostCallService(config);
+    }
+    async start() {
+        this.running = true;
+    }
+    async stop() {
+        for (const timer of this.callTimers.values()) {
+            clearTimeout(timer);
+        }
+        this.callTimers.clear();
+        await this.bridge.stopAll();
+        this.running = false;
+    }
+    isRunning() {
+        return this.running;
+    }
+    getProviderSummary() {
+        return `${this.config.telephonyProvider}:${this.config.voiceProvider}`;
+    }
+    createCallId() {
+        const now = Date.now();
+        const random = Math.floor(Math.random() * 1000000)
+            .toString()
+            .padStart(6, "0");
+        return `call-${now}-${random}`;
+    }
+    checkDailyLimit() {
+        const today = new Date().toISOString().slice(0, 10);
+        if (today !== this.dailyResetDate) {
+            this.dailyCallCount = 0;
+            this.dailyResetDate = today;
+        }
+        if (this.config.dailyCallLimit > 0 && this.dailyCallCount >= this.config.dailyCallLimit) {
+            throw new Error(`Daily call limit reached (${this.config.dailyCallLimit}). Try again tomorrow.`);
+        }
+    }
+    async startCall(request) {
+        this.checkDailyLimit();
+        const baseGreeting = request.greeting?.trim() ||
+            "Hello, this is an AI assistant calling on behalf of my user.";
+        const disclosure = this.config.disclosureEnabled
+            ? this.config.disclosureStatement.trim()
+            : "";
+        const greeting = disclosure.length > 0
+            ? `${disclosure} ${baseGreeting}`
+            : baseGreeting;
+        const providerResult = await this.telephonyAdapter.startCall({
+            to: request.phoneNumber,
+            from: this.config.telephonyProvider === "twilio"
+                ? this.config.twilioPhoneNumber
+                : this.config.telnyxPhoneNumber,
+            greeting,
+            purpose: request.purpose,
+        });
+        const callId = this.createCallId();
+        const record = {
+            callId,
+            providerCallId: providerResult.providerCallId,
+            to: providerResult.normalizedTo,
+            provider: this.config.telephonyProvider,
+            purpose: request.purpose,
+            greeting,
+            startedAt: new Date().toISOString(),
+            status: "in-progress",
+        };
+        this.activeCalls.set(callId, record);
+        this.recentCalls.unshift(record);
+        this.recentCalls.splice(20);
+        this.dailyCallCount++;
+        this.scheduleAutoHangup(callId);
+        const bridgeEvent = this.bridge.createSession({
+            callId,
+            providerCallId: providerResult.providerCallId,
+            voiceProviderUrl: this.config.voiceProvider === "deepgram-agent"
+                ? "wss://agent.deepgram.com/v1/agent/converse"
+                : `wss://api.elevenlabs.io/v1/convai/conversation?agent_id=${this.config.elevenlabsAgentId ?? ""}`,
+            voiceProviderAuth: this.config.deepgramApiKey ?? "",
+            telephonyCodec: "mulaw",
+            voiceProviderCodec: "mulaw",
+            sampleRate: 8000,
+            greeting,
+            systemPrompt: this.config.voiceSystemPrompt
+                ? (request.purpose ? `${this.config.voiceSystemPrompt}\n\nCall purpose: ${request.purpose}` : this.config.voiceSystemPrompt)
+                : (request.purpose ?? ""),
+            voiceModel: this.config.deepgramVoice,
+            keepAliveIntervalMs: 5000,
+            greetingGracePeriodMs: 3000,
+        });
+        if (bridgeEvent.type === "connected") {
+            this.bridge.startKeepAlive(callId, 5000);
+            setTimeout(() => this.bridge.endGreetingGrace(callId), 3000);
+        }
+        return {
+            callId,
+            to: providerResult.normalizedTo,
+            openingGreeting: greeting,
+            message: `Outbound call initiated via ${this.config.telephonyProvider}.`,
+        };
+    }
+    async hangup(callId) {
+        const selectedCallId = callId ?? this.activeCalls.keys().next().value;
+        if (typeof selectedCallId !== "string") {
+            throw new Error("No active call found to hang up.");
+        }
+        const call = this.activeCalls.get(selectedCallId);
+        if (!call) {
+            throw new Error(`Call not found: ${selectedCallId}`);
+        }
+        await this.completeCall(selectedCallId, call.providerCallId);
+        return {
+            callId: selectedCallId,
+            message: "Call ended with a polite closing and clean connection termination.",
+        };
+    }
+    getActiveCalls() {
+        return Array.from(this.activeCalls.values());
+    }
+    scheduleAutoHangup(callId) {
+        const durationMs = Math.floor(this.config.maxCallDuration * 1000);
+        const timer = setTimeout(() => {
+            void this.autoHangup(callId);
+        }, durationMs);
+        timer.unref?.();
+        this.callTimers.set(callId, timer);
+    }
+    async autoHangup(callId) {
+        const call = this.activeCalls.get(callId);
+        if (!call) {
+            return;
+        }
+        await this.completeCall(callId, call.providerCallId);
+    }
+    trackInboundCall(record) {
+        this.inboundRecords.unshift(record);
+        this.inboundRecords.splice(50);
+    }
+    getInboundRecords() {
+        return [...this.inboundRecords];
+    }
+    getCallSummary(callId) {
+        const call = this.recentCalls.find((c) => c.callId === callId);
+        return call?.summary ?? null;
+    }
+    async completeCall(callId, providerCallId) {
+        const call = this.activeCalls.get(callId);
+        if (!call) {
+            return;
+        }
+        const transcript = this.bridge.getTranscript(callId);
+        const summary = this.bridge.generateCallSummary(callId);
+        call.summary = summary ?? undefined;
+        this.bridge.destroySession(callId);
+        await this.telephonyAdapter.hangup(providerCallId);
+        call.status = "completed";
+        call.endedAt = new Date().toISOString();
+        this.activeCalls.delete(callId);
+        if (summary) {
+            await this.postCall.processCompletedCall(summary, transcript).catch(() => undefined);
+        }
+        const timer = this.callTimers.get(callId);
+        if (timer) {
+            clearTimeout(timer);
+            this.callTimers.delete(callId);
+        }
+    }
+}
+exports.VoiceCallService = VoiceCallService;

package/dist/telephony/telnyx.d.ts

@@ -0,0 +1,12 @@
+import { ClawVoiceConfig } from "../config";
+import { StartCallInput, StartCallResult, TelephonyProviderAdapter } from "./types";
+type FetchFn = typeof globalThis.fetch;
+export declare class TelnyxTelephonyAdapter implements TelephonyProviderAdapter {
+    private readonly config;
+    private readonly fetchFn;
+    constructor(config: ClawVoiceConfig, fetchFn?: FetchFn);
+    providerName(): string;
+    startCall(input: StartCallInput): Promise<StartCallResult>;
+    hangup(providerCallId: string): Promise<void>;
+}
+export {};

package/dist/telephony/telnyx.js

@@ -0,0 +1,60 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TelnyxTelephonyAdapter = void 0;
+const util_1 = require("./util");
+class TelnyxTelephonyAdapter {
+    constructor(config, fetchFn) {
+        this.config = config;
+        this.fetchFn = fetchFn ?? globalThis.fetch;
+    }
+    providerName() {
+        return "telnyx";
+    }
+    async startCall(input) {
+        const normalizedTo = (0, util_1.normalizeE164)(input.to);
+        if (!this.config.telnyxApiKey ||
+            !this.config.telnyxConnectionId ||
+            !this.config.telnyxPhoneNumber) {
+            throw new Error("Telnyx credentials missing: telnyxApiKey, telnyxConnectionId, and telnyxPhoneNumber are required");
+        }
+        const from = input.from ?? this.config.telnyxPhoneNumber;
+        const response = await this.fetchFn("https://api.telnyx.com/v2/calls", {
+            method: "POST",
+            headers: {
+                Authorization: `Bearer ${this.config.telnyxApiKey}`,
+                "Content-Type": "application/json",
+            },
+            body: JSON.stringify({
+                connection_id: this.config.telnyxConnectionId,
+                to: normalizedTo,
+                from: from ?? "",
+                answering_machine_detection: this.config.amdEnabled
+                    ? "detect"
+                    : "disabled",
+            }),
+        });
+        if (!response.ok) {
+            const errorText = await response.text().catch(() => "Unknown error");
+            throw new Error(`Telnyx API error (${response.status}): ${errorText}`);
+        }
+        const data = (await response.json());
+        return {
+            providerCallId: data.data.call_control_id,
+            normalizedTo,
+        };
+    }
+    async hangup(providerCallId) {
+        if (!this.config.telnyxApiKey) {
+            return;
+        }
+        await this.fetchFn(`https://api.telnyx.com/v2/calls/${providerCallId}/actions/hangup`, {
+            method: "POST",
+            headers: {
+                Authorization: `Bearer ${this.config.telnyxApiKey}`,
+                "Content-Type": "application/json",
+            },
+            body: JSON.stringify({}),
+        }).catch(() => undefined);
+    }
+}
+exports.TelnyxTelephonyAdapter = TelnyxTelephonyAdapter;

package/dist/telephony/twilio.d.ts

@@ -0,0 +1,12 @@
+import { ClawVoiceConfig } from "../config";
+import { StartCallInput, StartCallResult, TelephonyProviderAdapter } from "./types";
+type FetchFn = typeof globalThis.fetch;
+export declare class TwilioTelephonyAdapter implements TelephonyProviderAdapter {
+    private readonly config;
+    private readonly fetchFn;
+    constructor(config: ClawVoiceConfig, fetchFn?: FetchFn);
+    providerName(): string;
+    startCall(input: StartCallInput): Promise<StartCallResult>;
+    hangup(providerCallId: string): Promise<void>;
+}
+export {};