@openclaw/voice-call 2026.1.29

package/src/manager/context.ts

@@ -0,0 +1,21 @@
+import type { CallId, CallRecord } from "../types.js";
+import type { VoiceCallConfig } from "../config.js";
+import type { VoiceCallProvider } from "../providers/base.js";
+
+export type TranscriptWaiter = {
+  resolve: (text: string) => void;
+  reject: (err: Error) => void;
+  timeout: NodeJS.Timeout;
+};
+
+export type CallManagerContext = {
+  activeCalls: Map<CallId, CallRecord>;
+  providerCallIdMap: Map<string, CallId>;
+  processedEventIds: Set<string>;
+  provider: VoiceCallProvider | null;
+  config: VoiceCallConfig;
+  storePath: string;
+  webhookUrl: string | null;
+  transcriptWaiters: Map<CallId, TranscriptWaiter>;
+  maxDurationTimers: Map<CallId, NodeJS.Timeout>;
+};

package/src/manager/events.ts

@@ -0,0 +1,177 @@
+import crypto from "node:crypto";
+
+import type { CallId, CallRecord, CallState, NormalizedEvent } from "../types.js";
+import { TerminalStates } from "../types.js";
+import type { CallManagerContext } from "./context.js";
+import { findCall } from "./lookup.js";
+import { addTranscriptEntry, transitionState } from "./state.js";
+import { persistCallRecord } from "./store.js";
+import {
+  clearMaxDurationTimer,
+  rejectTranscriptWaiter,
+  resolveTranscriptWaiter,
+  startMaxDurationTimer,
+} from "./timers.js";
+import { endCall } from "./outbound.js";
+
+function shouldAcceptInbound(config: CallManagerContext["config"], from: string | undefined): boolean {
+  const { inboundPolicy: policy, allowFrom } = config;
+
+  switch (policy) {
+    case "disabled":
+      console.log("[voice-call] Inbound call rejected: policy is disabled");
+      return false;
+
+    case "open":
+      console.log("[voice-call] Inbound call accepted: policy is open");
+      return true;
+
+    case "allowlist":
+    case "pairing": {
+      const normalized = from?.replace(/\D/g, "") || "";
+      const allowed = (allowFrom || []).some((num) => {
+        const normalizedAllow = num.replace(/\D/g, "");
+        return normalized.endsWith(normalizedAllow) || normalizedAllow.endsWith(normalized);
+      });
+      const status = allowed ? "accepted" : "rejected";
+      console.log(
+        `[voice-call] Inbound call ${status}: ${from} ${allowed ? "is in" : "not in"} allowlist`,
+      );
+      return allowed;
+    }
+
+    default:
+      return false;
+  }
+}
+
+function createInboundCall(params: {
+  ctx: CallManagerContext;
+  providerCallId: string;
+  from: string;
+  to: string;
+}): CallRecord {
+  const callId = crypto.randomUUID();
+
+  const callRecord: CallRecord = {
+    callId,
+    providerCallId: params.providerCallId,
+    provider: params.ctx.provider?.name || "twilio",
+    direction: "inbound",
+    state: "ringing",
+    from: params.from,
+    to: params.to,
+    startedAt: Date.now(),
+    transcript: [],
+    processedEventIds: [],
+    metadata: {
+      initialMessage: params.ctx.config.inboundGreeting || "Hello! How can I help you today?",
+    },
+  };
+
+  params.ctx.activeCalls.set(callId, callRecord);
+  params.ctx.providerCallIdMap.set(params.providerCallId, callId);
+  persistCallRecord(params.ctx.storePath, callRecord);
+
+  console.log(`[voice-call] Created inbound call record: ${callId} from ${params.from}`);
+  return callRecord;
+}
+
+export function processEvent(ctx: CallManagerContext, event: NormalizedEvent): void {
+  if (ctx.processedEventIds.has(event.id)) return;
+  ctx.processedEventIds.add(event.id);
+
+  let call = findCall({
+    activeCalls: ctx.activeCalls,
+    providerCallIdMap: ctx.providerCallIdMap,
+    callIdOrProviderCallId: event.callId,
+  });
+
+  if (!call && event.direction === "inbound" && event.providerCallId) {
+    if (!shouldAcceptInbound(ctx.config, event.from)) {
+      // TODO: Could hang up the call here.
+      return;
+    }
+
+    call = createInboundCall({
+      ctx,
+      providerCallId: event.providerCallId,
+      from: event.from || "unknown",
+      to: event.to || ctx.config.fromNumber || "unknown",
+    });
+
+    // Normalize event to internal ID for downstream consumers.
+    event.callId = call.callId;
+  }
+
+  if (!call) return;
+
+  if (event.providerCallId && !call.providerCallId) {
+    call.providerCallId = event.providerCallId;
+    ctx.providerCallIdMap.set(event.providerCallId, call.callId);
+  }
+
+  call.processedEventIds.push(event.id);
+
+  switch (event.type) {
+    case "call.initiated":
+      transitionState(call, "initiated");
+      break;
+
+    case "call.ringing":
+      transitionState(call, "ringing");
+      break;
+
+    case "call.answered":
+      call.answeredAt = event.timestamp;
+      transitionState(call, "answered");
+      startMaxDurationTimer({
+        ctx,
+        callId: call.callId,
+        onTimeout: async (callId) => {
+          await endCall(ctx, callId);
+        },
+      });
+      break;
+
+    case "call.active":
+      transitionState(call, "active");
+      break;
+
+    case "call.speaking":
+      transitionState(call, "speaking");
+      break;
+
+    case "call.speech":
+      if (event.isFinal) {
+        addTranscriptEntry(call, "user", event.transcript);
+        resolveTranscriptWaiter(ctx, call.callId, event.transcript);
+      }
+      transitionState(call, "listening");
+      break;
+
+    case "call.ended":
+      call.endedAt = event.timestamp;
+      call.endReason = event.reason;
+      transitionState(call, event.reason as CallState);
+      clearMaxDurationTimer(ctx, call.callId);
+      rejectTranscriptWaiter(ctx, call.callId, `Call ended: ${event.reason}`);
+      ctx.activeCalls.delete(call.callId);
+      if (call.providerCallId) ctx.providerCallIdMap.delete(call.providerCallId);
+      break;
+
+    case "call.error":
+      if (!event.retryable) {
+        call.endedAt = event.timestamp;
+        call.endReason = "error";
+        transitionState(call, "error");
+        clearMaxDurationTimer(ctx, call.callId);
+        rejectTranscriptWaiter(ctx, call.callId, `Call error: ${event.error}`);
+        ctx.activeCalls.delete(call.callId);
+        if (call.providerCallId) ctx.providerCallIdMap.delete(call.providerCallId);
+      }
+      break;
+  }
+
+  persistCallRecord(ctx.storePath, call);
+}

package/src/manager/lookup.ts

@@ -0,0 +1,33 @@
+import type { CallId, CallRecord } from "../types.js";
+
+export function getCallByProviderCallId(params: {
+  activeCalls: Map<CallId, CallRecord>;
+  providerCallIdMap: Map<string, CallId>;
+  providerCallId: string;
+}): CallRecord | undefined {
+  const callId = params.providerCallIdMap.get(params.providerCallId);
+  if (callId) {
+    return params.activeCalls.get(callId);
+  }
+
+  for (const call of params.activeCalls.values()) {
+    if (call.providerCallId === params.providerCallId) {
+      return call;
+    }
+  }
+  return undefined;
+}
+
+export function findCall(params: {
+  activeCalls: Map<CallId, CallRecord>;
+  providerCallIdMap: Map<string, CallId>;
+  callIdOrProviderCallId: string;
+}): CallRecord | undefined {
+  const directCall = params.activeCalls.get(params.callIdOrProviderCallId);
+  if (directCall) return directCall;
+  return getCallByProviderCallId({
+    activeCalls: params.activeCalls,
+    providerCallIdMap: params.providerCallIdMap,
+    providerCallId: params.callIdOrProviderCallId,
+  });
+}

package/src/manager/outbound.ts

@@ -0,0 +1,248 @@
+import crypto from "node:crypto";
+
+import { TerminalStates, type CallId, type CallRecord, type OutboundCallOptions } from "../types.js";
+import type { CallMode } from "../config.js";
+import { mapVoiceToPolly } from "../voice-mapping.js";
+import type { CallManagerContext } from "./context.js";
+import { getCallByProviderCallId } from "./lookup.js";
+import { generateNotifyTwiml } from "./twiml.js";
+import { addTranscriptEntry, transitionState } from "./state.js";
+import { persistCallRecord } from "./store.js";
+import { clearMaxDurationTimer, clearTranscriptWaiter, rejectTranscriptWaiter, waitForFinalTranscript } from "./timers.js";
+
+export async function initiateCall(
+  ctx: CallManagerContext,
+  to: string,
+  sessionKey?: string,
+  options?: OutboundCallOptions | string,
+): Promise<{ callId: CallId; success: boolean; error?: string }> {
+  const opts: OutboundCallOptions =
+    typeof options === "string" ? { message: options } : (options ?? {});
+  const initialMessage = opts.message;
+  const mode = opts.mode ?? ctx.config.outbound.defaultMode;
+
+  if (!ctx.provider) {
+    return { callId: "", success: false, error: "Provider not initialized" };
+  }
+  if (!ctx.webhookUrl) {
+    return { callId: "", success: false, error: "Webhook URL not configured" };
+  }
+
+  if (ctx.activeCalls.size >= ctx.config.maxConcurrentCalls) {
+    return {
+      callId: "",
+      success: false,
+      error: `Maximum concurrent calls (${ctx.config.maxConcurrentCalls}) reached`,
+    };
+  }
+
+  const callId = crypto.randomUUID();
+  const from =
+    ctx.config.fromNumber ||
+    (ctx.provider?.name === "mock" ? "+15550000000" : undefined);
+  if (!from) {
+    return { callId: "", success: false, error: "fromNumber not configured" };
+  }
+
+  const callRecord: CallRecord = {
+    callId,
+    provider: ctx.provider.name,
+    direction: "outbound",
+    state: "initiated",
+    from,
+    to,
+    sessionKey,
+    startedAt: Date.now(),
+    transcript: [],
+    processedEventIds: [],
+    metadata: {
+      ...(initialMessage && { initialMessage }),
+      mode,
+    },
+  };
+
+  ctx.activeCalls.set(callId, callRecord);
+  persistCallRecord(ctx.storePath, callRecord);
+
+  try {
+    // For notify mode with a message, use inline TwiML with <Say>.
+    let inlineTwiml: string | undefined;
+    if (mode === "notify" && initialMessage) {
+      const pollyVoice = mapVoiceToPolly(ctx.config.tts?.openai?.voice);
+      inlineTwiml = generateNotifyTwiml(initialMessage, pollyVoice);
+      console.log(`[voice-call] Using inline TwiML for notify mode (voice: ${pollyVoice})`);
+    }
+
+    const result = await ctx.provider.initiateCall({
+      callId,
+      from,
+      to,
+      webhookUrl: ctx.webhookUrl,
+      inlineTwiml,
+    });
+
+    callRecord.providerCallId = result.providerCallId;
+    ctx.providerCallIdMap.set(result.providerCallId, callId);
+    persistCallRecord(ctx.storePath, callRecord);
+
+    return { callId, success: true };
+  } catch (err) {
+    callRecord.state = "failed";
+    callRecord.endedAt = Date.now();
+    callRecord.endReason = "failed";
+    persistCallRecord(ctx.storePath, callRecord);
+    ctx.activeCalls.delete(callId);
+    if (callRecord.providerCallId) {
+      ctx.providerCallIdMap.delete(callRecord.providerCallId);
+    }
+
+    return {
+      callId,
+      success: false,
+      error: err instanceof Error ? err.message : String(err),
+    };
+  }
+}
+
+export async function speak(
+  ctx: CallManagerContext,
+  callId: CallId,
+  text: string,
+): Promise<{ success: boolean; error?: string }> {
+  const call = ctx.activeCalls.get(callId);
+  if (!call) return { success: false, error: "Call not found" };
+  if (!ctx.provider || !call.providerCallId) return { success: false, error: "Call not connected" };
+  if (TerminalStates.has(call.state)) return { success: false, error: "Call has ended" };
+
+  try {
+    transitionState(call, "speaking");
+    persistCallRecord(ctx.storePath, call);
+
+    addTranscriptEntry(call, "bot", text);
+
+    const voice =
+      ctx.provider?.name === "twilio" ? ctx.config.tts?.openai?.voice : undefined;
+    await ctx.provider.playTts({
+      callId,
+      providerCallId: call.providerCallId,
+      text,
+      voice,
+    });
+
+    return { success: true };
+  } catch (err) {
+    return { success: false, error: err instanceof Error ? err.message : String(err) };
+  }
+}
+
+export async function speakInitialMessage(
+  ctx: CallManagerContext,
+  providerCallId: string,
+): Promise<void> {
+  const call = getCallByProviderCallId({
+    activeCalls: ctx.activeCalls,
+    providerCallIdMap: ctx.providerCallIdMap,
+    providerCallId,
+  });
+  if (!call) {
+    console.warn(`[voice-call] speakInitialMessage: no call found for ${providerCallId}`);
+    return;
+  }
+
+  const initialMessage = call.metadata?.initialMessage as string | undefined;
+  const mode = (call.metadata?.mode as CallMode) ?? "conversation";
+
+  if (!initialMessage) {
+    console.log(`[voice-call] speakInitialMessage: no initial message for ${call.callId}`);
+    return;
+  }
+
+  // Clear so we don't speak it again if the provider reconnects.
+  if (call.metadata) {
+    delete call.metadata.initialMessage;
+    persistCallRecord(ctx.storePath, call);
+  }
+
+  console.log(`[voice-call] Speaking initial message for call ${call.callId} (mode: ${mode})`);
+  const result = await speak(ctx, call.callId, initialMessage);
+  if (!result.success) {
+    console.warn(`[voice-call] Failed to speak initial message: ${result.error}`);
+    return;
+  }
+
+  if (mode === "notify") {
+    const delaySec = ctx.config.outbound.notifyHangupDelaySec;
+    console.log(`[voice-call] Notify mode: auto-hangup in ${delaySec}s for call ${call.callId}`);
+    setTimeout(async () => {
+      const currentCall = ctx.activeCalls.get(call.callId);
+      if (currentCall && !TerminalStates.has(currentCall.state)) {
+        console.log(`[voice-call] Notify mode: hanging up call ${call.callId}`);
+        await endCall(ctx, call.callId);
+      }
+    }, delaySec * 1000);
+  }
+}
+
+export async function continueCall(
+  ctx: CallManagerContext,
+  callId: CallId,
+  prompt: string,
+): Promise<{ success: boolean; transcript?: string; error?: string }> {
+  const call = ctx.activeCalls.get(callId);
+  if (!call) return { success: false, error: "Call not found" };
+  if (!ctx.provider || !call.providerCallId) return { success: false, error: "Call not connected" };
+  if (TerminalStates.has(call.state)) return { success: false, error: "Call has ended" };
+
+  try {
+    await speak(ctx, callId, prompt);
+
+    transitionState(call, "listening");
+    persistCallRecord(ctx.storePath, call);
+
+    await ctx.provider.startListening({ callId, providerCallId: call.providerCallId });
+
+    const transcript = await waitForFinalTranscript(ctx, callId);
+
+    // Best-effort: stop listening after final transcript.
+    await ctx.provider.stopListening({ callId, providerCallId: call.providerCallId });
+
+    return { success: true, transcript };
+  } catch (err) {
+    return { success: false, error: err instanceof Error ? err.message : String(err) };
+  } finally {
+    clearTranscriptWaiter(ctx, callId);
+  }
+}
+
+export async function endCall(
+  ctx: CallManagerContext,
+  callId: CallId,
+): Promise<{ success: boolean; error?: string }> {
+  const call = ctx.activeCalls.get(callId);
+  if (!call) return { success: false, error: "Call not found" };
+  if (!ctx.provider || !call.providerCallId) return { success: false, error: "Call not connected" };
+  if (TerminalStates.has(call.state)) return { success: true };
+
+  try {
+    await ctx.provider.hangupCall({
+      callId,
+      providerCallId: call.providerCallId,
+      reason: "hangup-bot",
+    });
+
+    call.state = "hangup-bot";
+    call.endedAt = Date.now();
+    call.endReason = "hangup-bot";
+    persistCallRecord(ctx.storePath, call);
+
+    clearMaxDurationTimer(ctx, callId);
+    rejectTranscriptWaiter(ctx, callId, "Call ended: hangup-bot");
+
+    ctx.activeCalls.delete(callId);
+    if (call.providerCallId) ctx.providerCallIdMap.delete(call.providerCallId);
+
+    return { success: true };
+  } catch (err) {
+    return { success: false, error: err instanceof Error ? err.message : String(err) };
+  }
+}

package/src/manager/state.ts

@@ -0,0 +1,50 @@
+import { TerminalStates, type CallRecord, type CallState, type TranscriptEntry } from "../types.js";
+
+const ConversationStates = new Set<CallState>(["speaking", "listening"]);
+
+const StateOrder: readonly CallState[] = [
+  "initiated",
+  "ringing",
+  "answered",
+  "active",
+  "speaking",
+  "listening",
+];
+
+export function transitionState(call: CallRecord, newState: CallState): void {
+  // No-op for same state or already terminal.
+  if (call.state === newState || TerminalStates.has(call.state)) return;
+
+  // Terminal states can always be reached from non-terminal.
+  if (TerminalStates.has(newState)) {
+    call.state = newState;
+    return;
+  }
+
+  // Allow cycling between speaking and listening (multi-turn conversations).
+  if (ConversationStates.has(call.state) && ConversationStates.has(newState)) {
+    call.state = newState;
+    return;
+  }
+
+  // Only allow forward transitions in state order.
+  const currentIndex = StateOrder.indexOf(call.state);
+  const newIndex = StateOrder.indexOf(newState);
+  if (newIndex > currentIndex) {
+    call.state = newState;
+  }
+}
+
+export function addTranscriptEntry(
+  call: CallRecord,
+  speaker: "bot" | "user",
+  text: string,
+): void {
+  const entry: TranscriptEntry = {
+    timestamp: Date.now(),
+    speaker,
+    text,
+    isFinal: true,
+  };
+  call.transcript.push(entry);
+}

package/src/manager/store.ts

@@ -0,0 +1,88 @@
+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,86 @@
+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 });
+  });
+}