@clawdbot/voice-call 0.1.0 → 2026.1.16

package/src/manager/store.ts

@@ -0,0 +1,89 @@
+import fs from "node:fs";
+import fsp from "node:fs/promises";
+import path from "node:path";
+
+import { CallRecordSchema, TerminalStates, type CallId, type CallRecord } from "../types.js";
+
+export function persistCallRecord(storePath: string, call: CallRecord): void {
+  const logPath = path.join(storePath, "calls.jsonl");
+  const line = `${JSON.stringify(call)}\n`;
+  // Fire-and-forget async write to avoid blocking event loop.
+  fsp.appendFile(logPath, line).catch((err) => {
+    console.error("[voice-call] Failed to persist call record:", err);
+  });
+}
+
+export function loadActiveCallsFromStore(storePath: string): {
+  activeCalls: Map<CallId, CallRecord>;
+  providerCallIdMap: Map<string, CallId>;
+  processedEventIds: Set<string>;
+} {
+  const logPath = path.join(storePath, "calls.jsonl");
+  if (!fs.existsSync(logPath)) {
+    return {
+      activeCalls: new Map(),
+      providerCallIdMap: new Map(),
+      processedEventIds: new Set(),
+    };
+  }
+
+  const content = fs.readFileSync(logPath, "utf-8");
+  const lines = content.split("\n");
+
+  const callMap = new Map<CallId, CallRecord>();
+  for (const line of lines) {
+    if (!line.trim()) continue;
+    try {
+      const call = CallRecordSchema.parse(JSON.parse(line));
+      callMap.set(call.callId, call);
+    } catch {
+      // Skip invalid lines.
+    }
+  }
+
+  const activeCalls = new Map<CallId, CallRecord>();
+  const providerCallIdMap = new Map<string, CallId>();
+  const processedEventIds = new Set<string>();
+
+  for (const [callId, call] of callMap) {
+    if (TerminalStates.has(call.state)) continue;
+    activeCalls.set(callId, call);
+    if (call.providerCallId) {
+      providerCallIdMap.set(call.providerCallId, callId);
+    }
+    for (const eventId of call.processedEventIds) {
+      processedEventIds.add(eventId);
+    }
+  }
+
+  return { activeCalls, providerCallIdMap, processedEventIds };
+}
+
+export async function getCallHistoryFromStore(
+  storePath: string,
+  limit = 50,
+): Promise<CallRecord[]> {
+  const logPath = path.join(storePath, "calls.jsonl");
+
+  try {
+    await fsp.access(logPath);
+  } catch {
+    return [];
+  }
+
+  const content = await fsp.readFile(logPath, "utf-8");
+  const lines = content.trim().split("\n").filter(Boolean);
+  const calls: CallRecord[] = [];
+
+  for (const line of lines.slice(-limit)) {
+    try {
+      const parsed = CallRecordSchema.parse(JSON.parse(line));
+      calls.push(parsed);
+    } catch {
+      // Skip invalid lines.
+    }
+  }
+
+  return calls;
+}
+

package/src/manager/timers.ts

@@ -0,0 +1,87 @@
+import { TerminalStates, type CallId } from "../types.js";
+import type { CallManagerContext } from "./context.js";
+import { persistCallRecord } from "./store.js";
+
+export function clearMaxDurationTimer(ctx: CallManagerContext, callId: CallId): void {
+  const timer = ctx.maxDurationTimers.get(callId);
+  if (timer) {
+    clearTimeout(timer);
+    ctx.maxDurationTimers.delete(callId);
+  }
+}
+
+export function startMaxDurationTimer(params: {
+  ctx: CallManagerContext;
+  callId: CallId;
+  onTimeout: (callId: CallId) => Promise<void>;
+}): void {
+  clearMaxDurationTimer(params.ctx, params.callId);
+
+  const maxDurationMs = params.ctx.config.maxDurationSeconds * 1000;
+  console.log(
+    `[voice-call] Starting max duration timer (${params.ctx.config.maxDurationSeconds}s) for call ${params.callId}`,
+  );
+
+  const timer = setTimeout(async () => {
+    params.ctx.maxDurationTimers.delete(params.callId);
+    const call = params.ctx.activeCalls.get(params.callId);
+    if (call && !TerminalStates.has(call.state)) {
+      console.log(
+        `[voice-call] Max duration reached (${params.ctx.config.maxDurationSeconds}s), ending call ${params.callId}`,
+      );
+      call.endReason = "timeout";
+      persistCallRecord(params.ctx.storePath, call);
+      await params.onTimeout(params.callId);
+    }
+  }, maxDurationMs);
+
+  params.ctx.maxDurationTimers.set(params.callId, timer);
+}
+
+export function clearTranscriptWaiter(ctx: CallManagerContext, callId: CallId): void {
+  const waiter = ctx.transcriptWaiters.get(callId);
+  if (!waiter) return;
+  clearTimeout(waiter.timeout);
+  ctx.transcriptWaiters.delete(callId);
+}
+
+export function rejectTranscriptWaiter(
+  ctx: CallManagerContext,
+  callId: CallId,
+  reason: string,
+): void {
+  const waiter = ctx.transcriptWaiters.get(callId);
+  if (!waiter) return;
+  clearTranscriptWaiter(ctx, callId);
+  waiter.reject(new Error(reason));
+}
+
+export function resolveTranscriptWaiter(
+  ctx: CallManagerContext,
+  callId: CallId,
+  transcript: string,
+): void {
+  const waiter = ctx.transcriptWaiters.get(callId);
+  if (!waiter) return;
+  clearTranscriptWaiter(ctx, callId);
+  waiter.resolve(transcript);
+}
+
+export function waitForFinalTranscript(
+  ctx: CallManagerContext,
+  callId: CallId,
+): Promise<string> {
+  // Only allow one in-flight waiter per call.
+  rejectTranscriptWaiter(ctx, callId, "Transcript waiter replaced");
+
+  const timeoutMs = ctx.config.transcriptTimeoutMs;
+  return new Promise((resolve, reject) => {
+    const timeout = setTimeout(() => {
+      ctx.transcriptWaiters.delete(callId);
+      reject(new Error(`Timed out waiting for transcript after ${timeoutMs}ms`));
+    }, timeoutMs);
+
+    ctx.transcriptWaiters.set(callId, { resolve, reject, timeout });
+  });
+}
+

package/src/manager/twiml.ts

@@ -0,0 +1,10 @@
+import { escapeXml } from "../voice-mapping.js";
+
+export function generateNotifyTwiml(message: string, voice: string): string {
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<Response>
+  <Say voice="${voice}">${escapeXml(message)}</Say>
+  <Hangup/>
+</Response>`;
+}
+

package/src/manager.test.ts

@@ -0,0 +1,108 @@
+import os from "node:os";
+import path from "node:path";
+
+import { describe, expect, it } from "vitest";
+
+import { VoiceCallConfigSchema } from "./config.js";
+import { CallManager } from "./manager.js";
+import type {
+  HangupCallInput,
+  InitiateCallInput,
+  InitiateCallResult,
+  PlayTtsInput,
+  ProviderWebhookParseResult,
+  StartListeningInput,
+  StopListeningInput,
+  WebhookContext,
+  WebhookVerificationResult,
+} from "./types.js";
+import type { VoiceCallProvider } from "./providers/base.js";
+
+class FakeProvider implements VoiceCallProvider {
+  readonly name = "plivo" as const;
+  readonly playTtsCalls: PlayTtsInput[] = [];
+
+  verifyWebhook(_ctx: WebhookContext): WebhookVerificationResult {
+    return { ok: true };
+  }
+  parseWebhookEvent(_ctx: WebhookContext): ProviderWebhookParseResult {
+    return { events: [], statusCode: 200 };
+  }
+  async initiateCall(_input: InitiateCallInput): Promise<InitiateCallResult> {
+    return { providerCallId: "request-uuid", status: "initiated" };
+  }
+  async hangupCall(_input: HangupCallInput): Promise<void> {}
+  async playTts(input: PlayTtsInput): Promise<void> {
+    this.playTtsCalls.push(input);
+  }
+  async startListening(_input: StartListeningInput): Promise<void> {}
+  async stopListening(_input: StopListeningInput): Promise<void> {}
+}
+
+describe("CallManager", () => {
+  it("upgrades providerCallId mapping when provider ID changes", async () => {
+    const config = VoiceCallConfigSchema.parse({
+      enabled: true,
+      provider: "plivo",
+      fromNumber: "+15550000000",
+    });
+
+    const storePath = path.join(os.tmpdir(), `clawdbot-voice-call-test-${Date.now()}`);
+    const manager = new CallManager(config, storePath);
+    manager.initialize(new FakeProvider(), "https://example.com/voice/webhook");
+
+    const { callId, success, error } = await manager.initiateCall("+15550000001");
+    expect(success).toBe(true);
+    expect(error).toBeUndefined();
+
+    // The provider returned a request UUID as the initial providerCallId.
+    expect(manager.getCall(callId)?.providerCallId).toBe("request-uuid");
+    expect(manager.getCallByProviderCallId("request-uuid")?.callId).toBe(callId);
+
+    // Provider later reports the actual call UUID.
+    manager.processEvent({
+      id: "evt-1",
+      type: "call.answered",
+      callId,
+      providerCallId: "call-uuid",
+      timestamp: Date.now(),
+    });
+
+    expect(manager.getCall(callId)?.providerCallId).toBe("call-uuid");
+    expect(manager.getCallByProviderCallId("call-uuid")?.callId).toBe(callId);
+    expect(manager.getCallByProviderCallId("request-uuid")).toBeUndefined();
+  });
+
+  it("speaks initial message on answered for notify mode (non-Twilio)", async () => {
+    const config = VoiceCallConfigSchema.parse({
+      enabled: true,
+      provider: "plivo",
+      fromNumber: "+15550000000",
+    });
+
+    const storePath = path.join(os.tmpdir(), `clawdbot-voice-call-test-${Date.now()}`);
+    const provider = new FakeProvider();
+    const manager = new CallManager(config, storePath);
+    manager.initialize(provider, "https://example.com/voice/webhook");
+
+    const { callId, success } = await manager.initiateCall(
+      "+15550000002",
+      undefined,
+      { message: "Hello there", mode: "notify" },
+    );
+    expect(success).toBe(true);
+
+    manager.processEvent({
+      id: "evt-2",
+      type: "call.answered",
+      callId,
+      providerCallId: "call-uuid",
+      timestamp: Date.now(),
+    });
+
+    await new Promise((resolve) => setTimeout(resolve, 0));
+
+    expect(provider.playTtsCalls).toHaveLength(1);
+    expect(provider.playTtsCalls[0]?.text).toBe("Hello there");
+  });
+});

package/src/manager.ts

@@ -580,8 +580,16 @@ export class CallManager {
     }
 
     // Update provider call ID if we got it
-    if (event.providerCallId && !call.providerCallId) {
+    if (event.providerCallId && event.providerCallId !== call.providerCallId) {
+      const previousProviderCallId = call.providerCallId;
       call.providerCallId = event.providerCallId;
+      this.providerCallIdMap.set(event.providerCallId, call.callId);
+      if (previousProviderCallId) {
+        const mapped = this.providerCallIdMap.get(previousProviderCallId);
+        if (mapped === call.callId) {
+          this.providerCallIdMap.delete(previousProviderCallId);
+        }
+      }
     }
 
     // Track processed event
@@ -602,6 +610,9 @@ export class CallManager {
         this.transitionState(call, "answered");
         // Start max duration timer when call is answered
         this.startMaxDurationTimer(call.callId);
+        // Best-effort: speak initial message (for inbound greetings and outbound
+        // conversation mode) once the call is answered.
+        this.maybeSpeakInitialMessageOnAnswered(call);
         break;
 
       case "call.active":
@@ -653,6 +664,23 @@ export class CallManager {
     this.persistCallRecord(call);
   }
 
+  private maybeSpeakInitialMessageOnAnswered(call: CallRecord): void {
+    const initialMessage =
+      typeof call.metadata?.initialMessage === "string"
+        ? call.metadata.initialMessage.trim()
+        : "";
+
+    if (!initialMessage) return;
+
+    if (!this.provider || !call.providerCallId) return;
+
+    // Twilio has provider-specific state for speaking (<Say> fallback) and can
+    // fail for inbound calls; keep existing Twilio behavior unchanged.
+    if (this.provider.name === "twilio") return;
+
+    void this.speakInitialMessage(call.providerCallId);
+  }
+
   /**
    * Get an active call by ID.
    */

package/src/providers/index.ts

@@ -7,3 +7,4 @@ export {
 } from "./stt-openai-realtime.js";
 export { TelnyxProvider } from "./telnyx.js";
 export { TwilioProvider } from "./twilio.js";
+export { PlivoProvider } from "./plivo.js";

package/src/providers/plivo.test.ts

@@ -0,0 +1,29 @@
+import { describe, expect, it } from "vitest";
+
+import { PlivoProvider } from "./plivo.js";
+
+describe("PlivoProvider", () => {
+  it("parses answer callback into call.answered and returns keep-alive XML", () => {
+    const provider = new PlivoProvider({
+      authId: "MA000000000000000000",
+      authToken: "test-token",
+    });
+
+    const result = provider.parseWebhookEvent({
+      headers: { host: "example.com" },
+      rawBody:
+        "CallUUID=call-uuid&CallStatus=in-progress&Direction=outbound&From=%2B15550000000&To=%2B15550000001&Event=StartApp",
+      url: "https://example.com/voice/webhook?provider=plivo&flow=answer&callId=internal-call-id",
+      method: "POST",
+      query: { provider: "plivo", flow: "answer", callId: "internal-call-id" },
+    });
+
+    expect(result.events).toHaveLength(1);
+    expect(result.events[0]?.type).toBe("call.answered");
+    expect(result.events[0]?.callId).toBe("internal-call-id");
+    expect(result.events[0]?.providerCallId).toBe("call-uuid");
+    expect(result.providerResponseBody).toContain("<Wait");
+    expect(result.providerResponseBody).toContain('length="300"');
+  });
+});
+