@clawvoice/voice-assistant 1.0.0

package/dist/diagnostics/health.js

@@ -0,0 +1,182 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runDiagnostics = runDiagnostics;
+function runDiagnostics(config) {
+    const checks = [];
+    checks.push(checkMode(config));
+    checks.push(checkTelephonyProvider(config));
+    checks.push(checkVoiceProvider(config));
+    checks.push(checkTelephonyCredentials(config));
+    checks.push(checkVoiceCredentials(config));
+    checks.push(checkWebhookConfig(config));
+    checks.push(checkDisclosure(config));
+    checks.push(checkCallDuration(config));
+    const overall = deriveOverall(checks);
+    return {
+        overall,
+        checks,
+        generatedAt: new Date().toISOString(),
+    };
+}
+function checkMode(config) {
+    return {
+        name: "mode",
+        status: "pass",
+        detail: `Inbound: ${config.inboundEnabled ? "enabled" : "disabled"}`,
+    };
+}
+function checkTelephonyProvider(config) {
+    const valid = ["twilio", "telnyx"];
+    if (!valid.includes(config.telephonyProvider)) {
+        return {
+            name: "telephony-provider",
+            status: "fail",
+            detail: `Unknown telephony provider: ${config.telephonyProvider}`,
+            remediation: `Set CLAWVOICE_TELEPHONY_PROVIDER to one of: ${valid.join(", ")}`,
+        };
+    }
+    return {
+        name: "telephony-provider",
+        status: "pass",
+        detail: `Telephony: ${config.telephonyProvider}`,
+    };
+}
+function checkVoiceProvider(config) {
+    const valid = ["deepgram-agent", "elevenlabs-conversational"];
+    if (!valid.includes(config.voiceProvider)) {
+        return {
+            name: "voice-provider",
+            status: "fail",
+            detail: `Unknown voice provider: ${config.voiceProvider}`,
+            remediation: `Set CLAWVOICE_VOICE_PROVIDER to one of: ${valid.join(", ")}`,
+        };
+    }
+    return {
+        name: "voice-provider",
+        status: "pass",
+        detail: `Voice: ${config.voiceProvider}`,
+    };
+}
+function checkTelephonyCredentials(config) {
+    if (config.telephonyProvider === "twilio") {
+        if (!config.twilioAccountSid || !config.twilioAuthToken) {
+            return {
+                name: "telephony-credentials",
+                status: "fail",
+                detail: "Twilio credentials missing.",
+                remediation: "Set TWILIO_ACCOUNT_SID and TWILIO_AUTH_TOKEN, or run 'clawvoice setup'.",
+            };
+        }
+    }
+    if (config.telephonyProvider === "telnyx") {
+        if (!config.telnyxApiKey) {
+            return {
+                name: "telephony-credentials",
+                status: "fail",
+                detail: "Telnyx API key missing.",
+                remediation: "Set TELNYX_API_KEY, or run 'clawvoice setup'.",
+            };
+        }
+    }
+    return {
+        name: "telephony-credentials",
+        status: "pass",
+        detail: "Telephony credentials configured.",
+    };
+}
+function checkVoiceCredentials(config) {
+    if (config.voiceProvider === "deepgram-agent") {
+        if (!config.deepgramApiKey) {
+            return {
+                name: "voice-credentials",
+                status: "fail",
+                detail: "Deepgram API key missing.",
+                remediation: "Set DEEPGRAM_API_KEY, or run 'clawvoice setup'.",
+            };
+        }
+    }
+    if (config.voiceProvider === "elevenlabs-conversational") {
+        if (!config.elevenlabsApiKey || !config.elevenlabsAgentId) {
+            return {
+                name: "voice-credentials",
+                status: "fail",
+                detail: "ElevenLabs credentials missing.",
+                remediation: "Set ELEVENLABS_API_KEY and ELEVENLABS_AGENT_ID, or run 'clawvoice setup'.",
+            };
+        }
+    }
+    return {
+        name: "voice-credentials",
+        status: "pass",
+        detail: "Voice credentials configured.",
+    };
+}
+function checkWebhookConfig(config) {
+    if (config.telephonyProvider === "telnyx" && !config.telnyxWebhookSecret) {
+        return {
+            name: "webhook-config",
+            status: "warn",
+            detail: "Telnyx webhook secret not configured. Webhooks will not be verified.",
+            remediation: "Set TELNYX_WEBHOOK_SECRET for production security.",
+        };
+    }
+    if (config.telephonyProvider === "twilio" && !config.twilioAuthToken) {
+        return {
+            name: "webhook-config",
+            status: "warn",
+            detail: "Twilio auth token needed for webhook signature verification.",
+            remediation: "Ensure TWILIO_AUTH_TOKEN is set.",
+        };
+    }
+    return {
+        name: "webhook-config",
+        status: "pass",
+        detail: "Webhook verification keys present.",
+    };
+}
+function checkDisclosure(config) {
+    if (config.disclosureEnabled && !config.disclosureStatement) {
+        return {
+            name: "disclosure",
+            status: "warn",
+            detail: "Disclosure enabled but statement is empty.",
+            remediation: "Set CLAWVOICE_DISCLOSURE_STATEMENT or disable disclosure.",
+        };
+    }
+    return {
+        name: "disclosure",
+        status: "pass",
+        detail: config.disclosureEnabled
+            ? "Disclosure enabled."
+            : "Disclosure disabled.",
+    };
+}
+function checkCallDuration(config) {
+    if (config.maxCallDuration <= 0 || !Number.isFinite(config.maxCallDuration)) {
+        return {
+            name: "call-duration",
+            status: "fail",
+            detail: `Invalid maxCallDuration: ${config.maxCallDuration}`,
+            remediation: "Set CLAWVOICE_MAX_CALL_DURATION to a positive number (seconds).",
+        };
+    }
+    if (config.maxCallDuration > 7200) {
+        return {
+            name: "call-duration",
+            status: "warn",
+            detail: `maxCallDuration is ${config.maxCallDuration}s (over 2 hours). This may incur high costs.`,
+        };
+    }
+    return {
+        name: "call-duration",
+        status: "pass",
+        detail: `Max call duration: ${config.maxCallDuration}s`,
+    };
+}
+function deriveOverall(checks) {
+    if (checks.some((c) => c.status === "fail"))
+        return "fail";
+    if (checks.some((c) => c.status === "warn"))
+        return "warn";
+    return "pass";
+}

package/dist/hooks.d.ts

@@ -0,0 +1,16 @@
+import { PluginAPI } from "@openclaw/plugin-sdk";
+import { ClawVoiceConfig } from "./config";
+export declare function isVoiceSession(context: unknown): boolean;
+export declare function getMemoryWritePolicy(config: ClawVoiceConfig): {
+    namespace: string;
+};
+export declare function getMemoryReadPolicy(config: ClawVoiceConfig): {
+    allowed: boolean;
+    reason?: string;
+};
+export declare function getToolDenyList(config: ClawVoiceConfig): string[];
+export declare function detectPromptInjection(text: string): {
+    detected: boolean;
+    pattern?: string;
+};
+export declare function registerHooks(api: PluginAPI, config: ClawVoiceConfig): void;

package/dist/hooks.js

@@ -0,0 +1,113 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isVoiceSession = isVoiceSession;
+exports.getMemoryWritePolicy = getMemoryWritePolicy;
+exports.getMemoryReadPolicy = getMemoryReadPolicy;
+exports.getToolDenyList = getToolDenyList;
+exports.detectPromptInjection = detectPromptInjection;
+exports.registerHooks = registerHooks;
+const VOICE_MEMORY_NAMESPACE = "voice-memory";
+/**
+ * Tools that are always blocked in voice sessions regardless of config.
+ * These pose safety/security risks when executed via voice channel.
+ */
+const BUILT_IN_DENIED_TOOLS = [
+    "exec",
+    "browser",
+    "web_fetch",
+];
+/**
+ * Patterns in user/agent messages that indicate prompt injection attempts.
+ * Matches common injection vectors: role override, system prompt leak, ignore instructions.
+ */
+const PROMPT_INJECTION_PATTERNS = [
+    /ignore\s+(previous|prior|above|all)\s+(instructions?|prompts?|rules?)/i,
+    /you\s+are\s+now\s+(a|an|the)\s+/i,
+    /system\s*:\s*/i,
+    /\[system\]/i,
+    /pretend\s+(you\s+are|to\s+be|that)/i,
+    /override\s+(your|the)\s+(instructions?|rules?|prompt)/i,
+    /disregard\s+(your|the|all|previous)/i,
+    /reveal\s+(your|the)\s+(system|original|initial)\s+(prompt|instructions?)/i,
+];
+function isVoiceSession(context) {
+    if (typeof context !== "object" || context === null) {
+        return false;
+    }
+    const ctx = context;
+    if (typeof ctx.session !== "object" || ctx.session === null) {
+        return false;
+    }
+    const session = ctx.session;
+    return session.channel === "voice";
+}
+function getMemoryWritePolicy(config) {
+    return { namespace: VOICE_MEMORY_NAMESPACE };
+}
+function getMemoryReadPolicy(config) {
+    if (config.mainMemoryAccess === "read") {
+        return { allowed: true };
+    }
+    return {
+        allowed: false,
+        reason: "Main memory access is disabled for voice sessions (mainMemoryAccess=none).",
+    };
+}
+function getToolDenyList(config) {
+    const denied = new Set(BUILT_IN_DENIED_TOOLS);
+    if (config.restrictTools) {
+        for (const tool of config.deniedTools) {
+            denied.add(tool);
+        }
+    }
+    return [...denied];
+}
+function detectPromptInjection(text) {
+    for (const pattern of PROMPT_INJECTION_PATTERNS) {
+        if (pattern.test(text)) {
+            return { detected: true, pattern: pattern.source };
+        }
+    }
+    return { detected: false };
+}
+function registerHooks(api, config) {
+    api.hooks.on("before_tool_execute", (_event, context) => {
+        if (!isVoiceSession(context)) {
+            return null;
+        }
+        return { deniedTools: getToolDenyList(config) };
+    });
+    api.hooks.on("before_memory_write", (_event, context) => {
+        if (!isVoiceSession(context)) {
+            return null;
+        }
+        const policy = getMemoryWritePolicy(config);
+        return { namespace: policy.namespace };
+    });
+    api.hooks.on("before_memory_read", (_event, context) => {
+        if (!isVoiceSession(context)) {
+            return null;
+        }
+        const policy = getMemoryReadPolicy(config);
+        if (!policy.allowed) {
+            return { blocked: true, reason: policy.reason };
+        }
+        return null;
+    });
+    api.hooks.on("before_response", (event, context) => {
+        if (!isVoiceSession(context)) {
+            return null;
+        }
+        const text = typeof event === "object" && event !== null
+            ? String(event.text ?? "")
+            : "";
+        const result = detectPromptInjection(text);
+        if (result.detected) {
+            return {
+                blocked: true,
+                reason: "Voice session prompt-injection guard triggered. The message was blocked for safety.",
+            };
+        }
+        return null;
+    });
+}

package/dist/inbound/classifier.d.ts

@@ -0,0 +1,5 @@
+import { ClawVoiceConfig } from "../config";
+import { AmdResult, InboundCallEvent, InboundCallRecord, InboundDecision } from "./types";
+export declare function classifyInboundEvent(providerCallId: string, from: string, to: string, provider: "telnyx" | "twilio", amdResult?: AmdResult): InboundCallEvent;
+export declare function decideInboundAction(event: InboundCallEvent, config: ClawVoiceConfig): InboundDecision;
+export declare function buildInboundRecord(event: InboundCallEvent, decision: InboundDecision): InboundCallRecord;

package/dist/inbound/classifier.js

@@ -0,0 +1,72 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.classifyInboundEvent = classifyInboundEvent;
+exports.decideInboundAction = decideInboundAction;
+exports.buildInboundRecord = buildInboundRecord;
+const node_crypto_1 = require("node:crypto");
+function classifyInboundEvent(providerCallId, from, to, provider, amdResult) {
+    let eventType;
+    if (amdResult === "machine_start") {
+        eventType = "amd_machine_detected";
+    }
+    else if (amdResult === "human") {
+        eventType = "amd_human_detected";
+    }
+    else if (amdResult === "fax") {
+        eventType = "call_failed";
+    }
+    else {
+        eventType = "incoming_call";
+    }
+    return {
+        eventType,
+        providerCallId,
+        from,
+        to,
+        provider,
+        timestamp: new Date().toISOString(),
+        amdResult,
+    };
+}
+function decideInboundAction(event, config) {
+    if (event.eventType === "call_failed") {
+        return { action: "reject", reason: "Fax or unsupported media detected" };
+    }
+    if (event.eventType === "amd_machine_detected") {
+        return {
+            action: "send_to_voicemail",
+            reason: "Answering machine detected — recording voicemail greeting",
+        };
+    }
+    if (!config.amdEnabled && event.eventType === "incoming_call") {
+        return {
+            action: "answer_and_bridge",
+            reason: "AMD disabled — answering directly",
+        };
+    }
+    if (event.eventType === "incoming_call" ||
+        event.eventType === "amd_human_detected") {
+        return {
+            action: "answer_and_bridge",
+            reason: "Human caller detected — bridging to voice agent",
+        };
+    }
+    return { action: "log_only", reason: "Unrecognized event — logging only" };
+}
+function createInboundCallId() {
+    return `inbound-${(0, node_crypto_1.randomUUID)()}`;
+}
+function buildInboundRecord(event, decision) {
+    return {
+        callId: createInboundCallId(),
+        providerCallId: event.providerCallId,
+        from: event.from,
+        to: event.to,
+        provider: event.provider,
+        direction: "inbound",
+        eventType: event.eventType,
+        decision,
+        amdResult: event.amdResult,
+        receivedAt: event.timestamp,
+    };
+}

package/dist/inbound/types.d.ts

@@ -0,0 +1,30 @@
+export type InboundEventType = "incoming_call" | "amd_machine_detected" | "amd_human_detected" | "voicemail_greeting" | "call_completed" | "call_failed";
+export type AmdResult = "machine_start" | "human" | "fax" | "unknown";
+export interface InboundCallEvent {
+    eventType: InboundEventType;
+    providerCallId: string;
+    from: string;
+    to: string;
+    provider: "telnyx" | "twilio";
+    timestamp: string;
+    amdResult?: AmdResult;
+    detail?: string;
+}
+export type InboundAction = "answer_and_bridge" | "send_to_voicemail" | "reject" | "log_only";
+export interface InboundDecision {
+    action: InboundAction;
+    reason: string;
+}
+export interface InboundCallRecord {
+    callId: string;
+    providerCallId: string;
+    from: string;
+    to: string;
+    provider: "telnyx" | "twilio";
+    direction: "inbound";
+    eventType: InboundEventType;
+    decision: InboundDecision;
+    amdResult?: AmdResult;
+    receivedAt: string;
+    completedAt?: string;
+}

package/dist/inbound/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+import { Plugin, PluginAPI } from "@openclaw/plugin-sdk";
+declare const plugin: Plugin;
+export declare function activate(api: PluginAPI): Promise<void>;
+export declare function register(api: PluginAPI): Promise<void>;
+export default plugin;

package/dist/index.js

@@ -0,0 +1,52 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.activate = activate;
+exports.register = register;
+const cli_1 = require("./cli");
+const config_1 = require("./config");
+const health_1 = require("./diagnostics/health");
+const hooks_1 = require("./hooks");
+const routes_1 = require("./routes");
+const memory_extraction_1 = require("./services/memory-extraction");
+const voice_call_1 = require("./services/voice-call");
+const tools_1 = require("./tools");
+const plugin = {
+    name: "clawvoice",
+    async init(api) {
+        const config = (0, config_1.resolveConfig)(api.config);
+        const validation = (0, config_1.validateConfig)(config);
+        if (!validation.ok) {
+            throw new Error(validation.errors.join("; "));
+        }
+        const diagnostics = (0, health_1.runDiagnostics)(config);
+        for (const check of diagnostics.checks) {
+            if (check.status === "fail" || check.status === "warn") {
+                api.log.warn(`ClawVoice config ${check.status}: ${check.name}`, {
+                    detail: check.detail,
+                    remediation: check.remediation,
+                });
+            }
+        }
+        const callService = new voice_call_1.VoiceCallService(config);
+        const memoryService = new memory_extraction_1.MemoryExtractionService(config);
+        (0, tools_1.registerTools)(api, config, callService, memoryService);
+        (0, cli_1.registerCLI)(api, config, callService, memoryService);
+        (0, routes_1.registerRoutes)(api, config, (record) => {
+            callService.trackInboundCall(record);
+        });
+        (0, hooks_1.registerHooks)(api, config);
+        api.services.register("clawvoice-calls", callService);
+        api.log.info("ClawVoice initialized", {
+            telephonyProvider: config.telephonyProvider,
+            voiceProvider: config.voiceProvider,
+            inboundEnabled: config.inboundEnabled,
+        });
+    },
+};
+async function activate(api) {
+    await plugin.init(api);
+}
+async function register(api) {
+    await activate(api);
+}
+exports.default = plugin;

package/dist/routes.d.ts

@@ -0,0 +1,6 @@
+import { PluginAPI } from "@openclaw/plugin-sdk";
+import { ClawVoiceConfig } from "./config";
+import { InboundCallRecord } from "./inbound/types";
+type InboundHandler = (record: InboundCallRecord) => void;
+export declare function registerRoutes(api: PluginAPI, config: ClawVoiceConfig, onInbound?: InboundHandler): void;
+export {};

package/dist/routes.js

@@ -0,0 +1,89 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerRoutes = registerRoutes;
+const classifier_1 = require("./inbound/classifier");
+const verify_1 = require("./webhooks/verify");
+function registerRoutes(api, config, onInbound) {
+    const router = api.http.router("/clawvoice");
+    router.post("/webhooks/telnyx", async (req, response) => {
+        const request = req;
+        const body = typeof request.body === "string" ? request.body : JSON.stringify(request.body ?? "");
+        const result = (0, verify_1.verifyTelnyxSignature)(body, request.headers?.["telnyx-signature-ed25519"], request.headers?.["telnyx-timestamp"], config.telnyxWebhookSecret);
+        if (!result.valid) {
+            response.status(401).json({ error: "Unauthorized", reason: result.reason });
+            return;
+        }
+        if (config.inboundEnabled) {
+            const parsed = parseWebhookBody(request.body);
+            if (parsed) {
+                const event = (0, classifier_1.classifyInboundEvent)(parsed.providerCallId, parsed.from, parsed.to, "telnyx", parsed.amdResult);
+                const decision = (0, classifier_1.decideInboundAction)(event, config);
+                const record = (0, classifier_1.buildInboundRecord)(event, decision);
+                onInbound?.(record);
+            }
+        }
+        response.status(200).json({ ok: true });
+    });
+    router.post("/webhooks/twilio/voice", async (req, response) => {
+        const request = req;
+        const url = `${request.protocol ?? "https"}://${request.headers?.host ?? "localhost"}${request.url ?? "/"}`;
+        const params = typeof request.body === "object" && request.body !== null ? request.body : {};
+        const result = (0, verify_1.verifyTwilioSignature)(url, params, request.headers?.["x-twilio-signature"], config.twilioAuthToken);
+        if (!result.valid) {
+            response.status(401).json({ error: "Unauthorized", reason: result.reason });
+            return;
+        }
+        if (config.inboundEnabled) {
+            const parsed = parseWebhookBody(request.body);
+            if (parsed) {
+                const event = (0, classifier_1.classifyInboundEvent)(parsed.providerCallId, parsed.from, parsed.to, "twilio", parsed.amdResult);
+                const decision = (0, classifier_1.decideInboundAction)(event, config);
+                const record = (0, classifier_1.buildInboundRecord)(event, decision);
+                onInbound?.(record);
+            }
+        }
+        response.status(200).json({ ok: true });
+    });
+    router.post("/webhooks/twilio/amd", async (req, response) => {
+        const request = req;
+        const url = `${request.protocol ?? "https"}://${request.headers?.host ?? "localhost"}${request.url ?? "/"}`;
+        const params = typeof request.body === "object" && request.body !== null ? request.body : {};
+        const result = (0, verify_1.verifyTwilioSignature)(url, params, request.headers?.["x-twilio-signature"], config.twilioAuthToken);
+        if (!result.valid) {
+            response.status(401).json({ error: "Unauthorized", reason: result.reason });
+            return;
+        }
+        const amdStatus = typeof params.AnsweredBy === "string" ? params.AnsweredBy : undefined;
+        const callSid = typeof params.CallSid === "string" ? params.CallSid : "unknown";
+        const amdResult = amdStatus === "human" ? "human"
+            : amdStatus === "machine_start" ? "machine_start"
+                : amdStatus === "fax" ? "fax"
+                    : "unknown";
+        if (config.inboundEnabled) {
+            const event = (0, classifier_1.classifyInboundEvent)(callSid, typeof params.From === "string" ? params.From : "", typeof params.To === "string" ? params.To : "", "twilio", amdResult);
+            const decision = (0, classifier_1.decideInboundAction)(event, config);
+            const record = (0, classifier_1.buildInboundRecord)(event, decision);
+            onInbound?.(record);
+        }
+        response.status(200).json({ ok: true });
+    });
+}
+function parseWebhookBody(body) {
+    if (typeof body !== "object" || body === null) {
+        return null;
+    }
+    const b = body;
+    const providerCallId = typeof b.CallSid === "string" ? b.CallSid
+        : typeof b.call_control_id === "string" ? b.call_control_id
+            : undefined;
+    if (!providerCallId) {
+        return null;
+    }
+    const from = typeof b.From === "string" ? b.From
+        : typeof b.from === "string" ? b.from
+            : "";
+    const to = typeof b.To === "string" ? b.To
+        : typeof b.to === "string" ? b.to
+            : "";
+    return { providerCallId, from, to };
+}

package/dist/services/memory-extraction.d.ts

@@ -0,0 +1,42 @@
+import { ClawVoiceConfig } from "../config";
+import { TranscriptEntry } from "../voice/types";
+export type MemoryCategory = "preference" | "health" | "relationship" | "schedule" | "interest" | "other";
+export type MemoryStatus = "pending" | "approved" | "rejected" | "promoted";
+export interface MemoryCandidate {
+    id: string;
+    callId: string;
+    category: MemoryCategory;
+    content: string;
+    confidence: number;
+    sourceQuote: string;
+    status: MemoryStatus;
+    extractedAt: string;
+    promotedAt?: string;
+}
+export interface ExtractionResult {
+    callId: string;
+    candidates: MemoryCandidate[];
+    extractedAt: string;
+}
+export type MemoryWriter = (namespace: string, key: string, value: unknown) => Promise<void>;
+export type MemoryReader = (namespace: string, key: string) => Promise<unknown>;
+export declare class MemoryExtractionService {
+    private readonly config;
+    private readonly candidates;
+    private memoryWriter;
+    private memoryReader;
+    private idCounter;
+    constructor(config: ClawVoiceConfig);
+    setMemoryWriter(writer: MemoryWriter): void;
+    setMemoryReader(reader: MemoryReader): void;
+    extractFromTranscript(callId: string, transcript: TranscriptEntry[]): ExtractionResult;
+    getPendingCandidates(callId?: string): MemoryCandidate[];
+    getCandidate(memoryId: string): MemoryCandidate | undefined;
+    approveAndPromote(memoryId: string): Promise<{
+        promoted: boolean;
+        reason?: string;
+    }>;
+    rejectCandidate(memoryId: string): boolean;
+    getAllCandidates(): MemoryCandidate[];
+    resetIdCounter(): void;
+}