@openclaw/voice-call 2026.3.13 → 2026.5.2-beta.1

package/src/manager/events.test.ts

@@ -1,17 +1,34 @@
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
-import { describe, expect, it } from "vitest";
+import { afterEach, describe, expect, it } from "vitest";
 import { VoiceCallConfigSchema } from "../config.js";
 import type { VoiceCallProvider } from "../providers/base.js";
-import type { HangupCallInput, NormalizedEvent } from "../types.js";
+import type { AnswerCallInput, HangupCallInput, NormalizedEvent } from "../types.js";
 import type { CallManagerContext } from "./context.js";
 import { processEvent } from "./events.js";
+import { flushPendingCallRecordWritesForTest } from "./store.js";
+
+const contexts: CallManagerContext[] = [];
+
+afterEach(async () => {
+  for (const ctx of contexts.splice(0)) {
+    for (const timer of ctx.maxDurationTimers.values()) {
+      clearTimeout(timer);
+    }
+    ctx.maxDurationTimers.clear();
+    for (const waiter of ctx.transcriptWaiters.values()) {
+      clearTimeout(waiter.timeout);
+    }
+    ctx.transcriptWaiters.clear();
+    await flushPendingCallRecordWritesForTest();
+    fs.rmSync(ctx.storePath, { recursive: true, force: true });
+  }
+});
 
 function createContext(overrides: Partial<CallManagerContext> = {}): CallManagerContext {
-  const storePath = path.join(os.tmpdir(), `openclaw-voice-call-events-test-${Date.now()}`);
-  fs.mkdirSync(storePath, { recursive: true });
-  return {
+  const storePath = fs.mkdtempSync(path.join(os.tmpdir(), "openclaw-voice-call-events-test-"));
+  const ctx: CallManagerContext = {
     activeCalls: new Map(),
     providerCallIdMap: new Map(),
     processedEventIds: new Set(),
@@ -27,8 +44,11 @@ function createContext(overrides: Partial<CallManagerContext> = {}): CallManager
     activeTurnCalls: new Set(),
     transcriptWaiters: new Map(),
     maxDurationTimers: new Map(),
+    initialMessageInFlight: new Set(),
     ...overrides,
   };
+  contexts.push(ctx);
+  return ctx;
 }
 
 function createProvider(overrides: Partial<VoiceCallProvider> = {}): VoiceCallProvider {
@@ -89,6 +109,14 @@ function createRejectingInboundContext(): {
   return { ctx, hangupCalls };
 }
 
+function requireFirstActiveCall(ctx: CallManagerContext) {
+  const call = [...ctx.activeCalls.values()][0];
+  if (!call) {
+    throw new Error("expected one active call");
+  }
+  return call;
+}
+
 describe("processEvent (functional)", () => {
   it("calls provider hangup when rejecting inbound call", () => {
     const { ctx, hangupCalls } = createRejectingInboundContext();
@@ -147,8 +175,50 @@ describe("processEvent (functional)", () => {
     processEvent(ctx, event2);
 
     expect(ctx.activeCalls.size).toBe(0);
-    expect(hangupCalls).toHaveLength(1);
-    expect(hangupCalls[0]?.providerCallId).toBe("prov-dup");
+    expect(hangupCalls).toEqual([
+      expect.objectContaining({
+        providerCallId: "prov-dup",
+        reason: "hangup-bot",
+      }),
+    ]);
+  });
+
+  it("answers accepted inbound calls when the provider requires an answer command", () => {
+    const answerCalls: AnswerCallInput[] = [];
+    const provider = createProvider({
+      answerCall: async (input: AnswerCallInput): Promise<void> => {
+        answerCalls.push(input);
+      },
+    });
+    const ctx = createContext({
+      config: VoiceCallConfigSchema.parse({
+        enabled: true,
+        provider: "telnyx",
+        fromNumber: "+15550000000",
+        inboundPolicy: "open",
+        telnyx: {
+          apiKey: "KEY123",
+          connectionId: "CONN456",
+        },
+        skipSignatureVerification: true,
+      }),
+      provider,
+    });
+    const event = createInboundInitiatedEvent({
+      id: "evt-answer",
+      providerCallId: "call-control-1",
+      from: "+15552222222",
+    });
+
+    processEvent(ctx, event);
+
+    const call = requireFirstActiveCall(ctx);
+    expect(answerCalls).toEqual([
+      {
+        callId: call.callId,
+        providerCallId: "call-control-1",
+      },
+    ]);
   });
 
   it("updates providerCallId map when provider ID changes", () => {
@@ -177,11 +247,57 @@ describe("processEvent (functional)", () => {
       timestamp: now + 1,
     });
 
-    expect(ctx.activeCalls.get("call-1")?.providerCallId).toBe("call-uuid");
+    const activeCall = ctx.activeCalls.get("call-1");
+    if (!activeCall) {
+      throw new Error("expected active call after provider id change");
+    }
+    expect(activeCall.providerCallId).toBe("call-uuid");
     expect(ctx.providerCallIdMap.get("call-uuid")).toBe("call-1");
     expect(ctx.providerCallIdMap.has("request-uuid")).toBe(false);
   });
 
+  it("does not burn replay keys for unknown calls before a later replay can resolve them", () => {
+    const now = Date.now();
+    const ctx = createContext();
+    const event: NormalizedEvent = {
+      id: "evt-late-call",
+      dedupeKey: "stable-late-call",
+      type: "call.answered",
+      callId: "call-late",
+      providerCallId: "provider-late",
+      timestamp: now + 1,
+    };
+
+    processEvent(ctx, event);
+
+    expect(ctx.processedEventIds.size).toBe(0);
+
+    ctx.activeCalls.set("call-late", {
+      callId: "call-late",
+      providerCallId: "provider-late",
+      provider: "plivo",
+      direction: "inbound",
+      state: "ringing",
+      from: "+15550000002",
+      to: "+15550000000",
+      startedAt: now,
+      transcript: [],
+      processedEventIds: [],
+      metadata: {},
+    });
+    ctx.providerCallIdMap.set("provider-late", "call-late");
+
+    processEvent(ctx, event);
+
+    const call = ctx.activeCalls.get("call-late");
+    if (!call) {
+      throw new Error("expected replayed event to resolve after call registration");
+    }
+    expect(call.state).toBe("answered");
+    expect(call.answeredAt).toBe(now + 1);
+    expect(Array.from(ctx.processedEventIds)).toEqual(["stable-late-call"]);
+  });
+
   it("invokes onCallAnswered hook for answered events", () => {
     const now = Date.now();
     let answeredCallId: string | null = null;
@@ -253,12 +369,12 @@ describe("processEvent (functional)", () => {
 
     // Call should be registered in activeCalls and providerCallIdMap
     expect(ctx.activeCalls.size).toBe(1);
-    expect(ctx.providerCallIdMap.get("CA-external-123")).toBeDefined();
-    const call = [...ctx.activeCalls.values()][0];
-    expect(call?.providerCallId).toBe("CA-external-123");
-    expect(call?.direction).toBe("outbound");
-    expect(call?.from).toBe("+15550000000");
-    expect(call?.to).toBe("+15559876543");
+    const call = requireFirstActiveCall(ctx);
+    expect(ctx.providerCallIdMap.get("CA-external-123")).toBe(call.callId);
+    expect(call.providerCallId).toBe("CA-external-123");
+    expect(call.direction).toBe("outbound");
+    expect(call.from).toBe("+15550000000");
+    expect(call.to).toBe("+15559876543");
   });
 
   it("does not reject externally-initiated outbound calls even with disabled inbound policy", () => {
@@ -279,8 +395,8 @@ describe("processEvent (functional)", () => {
     // External outbound calls bypass inbound policy — they should be accepted
     expect(ctx.activeCalls.size).toBe(1);
     expect(hangupCalls).toHaveLength(0);
-    const call = [...ctx.activeCalls.values()][0];
-    expect(call?.direction).toBe("outbound");
+    const call = requireFirstActiveCall(ctx);
+    expect(call.direction).toBe("outbound");
   });
 
   it("preserves inbound direction for auto-registered inbound calls", () => {
@@ -306,8 +422,72 @@ describe("processEvent (functional)", () => {
     processEvent(ctx, event);
 
     expect(ctx.activeCalls.size).toBe(1);
-    const call = [...ctx.activeCalls.values()][0];
-    expect(call?.direction).toBe("inbound");
+    const call = requireFirstActiveCall(ctx);
+    expect(call.direction).toBe("inbound");
+  });
+
+  it("assigns per-call session keys to inbound calls when configured", () => {
+    const ctx = createContext({
+      config: VoiceCallConfigSchema.parse({
+        enabled: true,
+        provider: "plivo",
+        fromNumber: "+15550000000",
+        inboundPolicy: "open",
+        sessionScope: "per-call",
+      }),
+    });
+    const event: NormalizedEvent = {
+      id: "evt-inbound-session-scope",
+      type: "call.initiated",
+      callId: "CA-inbound-session-scope",
+      providerCallId: "CA-inbound-session-scope",
+      timestamp: Date.now(),
+      direction: "inbound",
+      from: "+15554444444",
+      to: "+15550000000",
+    };
+
+    processEvent(ctx, event);
+
+    const call = requireFirstActiveCall(ctx);
+    expect(call.sessionKey).toBe(`voice:call:${call.callId}`);
+  });
+
+  it("applies per-number inbound greeting and stores the matched route key", () => {
+    const ctx = createContext({
+      config: VoiceCallConfigSchema.parse({
+        enabled: true,
+        provider: "plivo",
+        fromNumber: "+15550000000",
+        inboundPolicy: "open",
+        inboundGreeting: "Hello from global.",
+        numbers: {
+          "+15550002222": {
+            inboundGreeting: "Silver Fox Cards, how can I help?",
+          },
+        },
+      }),
+    });
+    const event: NormalizedEvent = {
+      id: "evt-inbound-number-route",
+      type: "call.initiated",
+      callId: "CA-inbound-number-route",
+      providerCallId: "CA-inbound-number-route",
+      timestamp: Date.now(),
+      direction: "inbound",
+      from: "+15554444444",
+      to: "+1 (555) 000-2222",
+    };
+
+    processEvent(ctx, event);
+
+    const call = requireFirstActiveCall(ctx);
+    expect(call.metadata).toEqual(
+      expect.objectContaining({
+        initialMessage: "Silver Fox Cards, how can I help?",
+        numberRouteKey: "+15550002222",
+      }),
+    );
   });
 
   it("deduplicates by dedupeKey even when event IDs differ", () => {
@@ -351,7 +531,51 @@ describe("processEvent (functional)", () => {
     });
 
     const call = ctx.activeCalls.get("call-dedupe");
-    expect(call?.transcript).toHaveLength(1);
+    if (!call) {
+      throw new Error("expected deduped call to remain active");
+    }
+    expect(call.transcript).toHaveLength(1);
     expect(Array.from(ctx.processedEventIds)).toEqual(["stable-key-1"]);
   });
+
+  it("keeps retryable call.error events replayable", () => {
+    const now = Date.now();
+    const ctx = createContext();
+    ctx.activeCalls.set("call-retryable-error", {
+      callId: "call-retryable-error",
+      providerCallId: "provider-retryable-error",
+      provider: "plivo",
+      direction: "outbound",
+      state: "active",
+      from: "+15550000000",
+      to: "+15550000001",
+      startedAt: now,
+      transcript: [],
+      processedEventIds: [],
+      metadata: {},
+    });
+    ctx.providerCallIdMap.set("provider-retryable-error", "call-retryable-error");
+
+    const event: NormalizedEvent = {
+      id: "evt-retryable-error",
+      dedupeKey: "stable-retryable-error",
+      type: "call.error",
+      callId: "call-retryable-error",
+      providerCallId: "provider-retryable-error",
+      timestamp: now + 1,
+      error: "temporary upstream failure",
+      retryable: true,
+    };
+
+    processEvent(ctx, event);
+    processEvent(ctx, event);
+
+    const call = ctx.activeCalls.get("call-retryable-error");
+    if (!call) {
+      throw new Error("expected retryable error call to remain active");
+    }
+    expect(call.state).toBe("active");
+    expect(Array.from(ctx.processedEventIds)).toEqual([]);
+    expect(call.processedEventIds).toEqual([]);
+  });
 });

package/src/manager/events.ts

@@ -1,17 +1,15 @@
 import crypto from "node:crypto";
+import { formatErrorMessage } from "openclaw/plugin-sdk/error-runtime";
 import { isAllowlistedCaller, normalizePhoneNumber } from "../allowlist.js";
-import type { CallRecord, CallState, NormalizedEvent } from "../types.js";
+import { resolveVoiceCallEffectiveConfig, resolveVoiceCallSessionKey } from "../config.js";
+import type { CallRecord, NormalizedEvent } from "../types.js";
 import type { CallManagerContext } from "./context.js";
+import { finalizeCall } from "./lifecycle.js";
 import { findCall } from "./lookup.js";
 import { endCall } from "./outbound.js";
 import { addTranscriptEntry, transitionState } from "./state.js";
 import { persistCallRecord } from "./store.js";
-import {
-  clearMaxDurationTimer,
-  rejectTranscriptWaiter,
-  resolveTranscriptWaiter,
-  startMaxDurationTimer,
-} from "./timers.js";
+import { resolveTranscriptWaiter, startMaxDurationTimer } from "./timers.js";
 
 type EventContext = Pick<
   CallManagerContext,
@@ -67,6 +65,11 @@ function createWebhookCall(params: {
   to: string;
 }): CallRecord {
   const callId = crypto.randomUUID();
+  const effective = resolveVoiceCallEffectiveConfig(
+    params.ctx.config,
+    params.direction === "inbound" ? params.to : undefined,
+  );
+  const effectiveConfig = effective.config;
 
   const callRecord: CallRecord = {
     callId,
@@ -76,14 +79,20 @@ function createWebhookCall(params: {
     state: "ringing",
     from: params.from,
     to: params.to,
+    sessionKey: resolveVoiceCallSessionKey({
+      config: effectiveConfig,
+      callId,
+      phone: params.direction === "outbound" ? params.to : params.from,
+    }),
     startedAt: Date.now(),
     transcript: [],
     processedEventIds: [],
     metadata: {
       initialMessage:
         params.direction === "inbound"
-          ? params.ctx.config.inboundGreeting || "Hello! How can I help you today?"
+          ? effectiveConfig.inboundGreeting || "Hello! How can I help you today?"
           : undefined,
+      ...(effective.numberRouteKey ? { numberRouteKey: effective.numberRouteKey } : {}),
     },
   };
 
@@ -102,7 +111,6 @@ export function processEvent(ctx: EventContext, event: NormalizedEvent): void {
   if (ctx.processedEventIds.has(dedupeKey)) {
     return;
   }
-  ctx.processedEventIds.add(dedupeKey);
 
   let call = findCall({
     activeCalls: ctx.activeCalls,
@@ -128,6 +136,7 @@ export function processEvent(ctx: EventContext, event: NormalizedEvent): void {
         );
         return;
       }
+      ctx.processedEventIds.add(dedupeKey);
       if (ctx.rejectedProviderCallIds.has(pid)) {
         return;
       }
@@ -141,7 +150,8 @@ export function processEvent(ctx: EventContext, event: NormalizedEvent): void {
           reason: "hangup-bot",
         })
         .catch((err) => {
-          const message = err instanceof Error ? err.message : String(err);
+          ctx.rejectedProviderCallIds.delete(pid);
+          const message = formatErrorMessage(err);
           console.warn(`[voice-call] Failed to reject inbound call ${pid}:`, message);
         });
       return;
@@ -175,11 +185,29 @@ export function processEvent(ctx: EventContext, event: NormalizedEvent): void {
     }
   }
 
-  call.processedEventIds.push(dedupeKey);
+  const shouldCommitReplayKey = !(event.type === "call.error" && event.retryable);
+  if (shouldCommitReplayKey) {
+    ctx.processedEventIds.add(dedupeKey);
+    call.processedEventIds.push(dedupeKey);
+  }
 
   switch (event.type) {
     case "call.initiated":
       transitionState(call, "initiated");
+      if (call.direction === "inbound" && call.providerCallId && ctx.provider?.answerCall) {
+        void ctx.provider
+          .answerCall({
+            callId: call.callId,
+            providerCallId: call.providerCallId,
+          })
+          .catch((err) => {
+            const message = formatErrorMessage(err);
+            console.warn(
+              `[voice-call] Failed to answer inbound call ${call.providerCallId}:`,
+              message,
+            );
+          });
+      }
       break;
 
     case "call.ringing":
@@ -193,7 +221,7 @@ export function processEvent(ctx: EventContext, event: NormalizedEvent): void {
         ctx,
         callId: call.callId,
         onTimeout: async (callId) => {
-          await endCall(ctx, callId);
+          await endCall(ctx, callId, { reason: "timeout" });
         },
       });
       ctx.onCallAnswered?.(call);
@@ -227,30 +255,32 @@ export function processEvent(ctx: EventContext, event: NormalizedEvent): void {
       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);
-      }
+    case "call.silence":
+    case "call.dtmf":
       break;
 
+    case "call.ended":
+      finalizeCall({
+        ctx,
+        call,
+        endReason: event.reason,
+        endedAt: event.timestamp,
+      });
+      return;
+
     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);
-        }
+        finalizeCall({
+          ctx,
+          call,
+          endReason: "error",
+          endedAt: event.timestamp,
+          transcriptRejectReason: `Call error: ${event.error}`,
+        });
+        return;
       }
+      // Keep retryable provider errors replayable so a redelivery can still
+      // drive later recovery or terminal handling for the same event key.
       break;
   }
 

package/src/manager/lifecycle.ts

@@ -0,0 +1,53 @@
+import type { CallRecord, EndReason } from "../types.js";
+import type { CallManagerContext } from "./context.js";
+import { transitionState } from "./state.js";
+import { persistCallRecord } from "./store.js";
+import { clearMaxDurationTimer, rejectTranscriptWaiter } from "./timers.js";
+
+type CallLifecycleContext = Pick<
+  CallManagerContext,
+  "activeCalls" | "providerCallIdMap" | "storePath"
+> &
+  Partial<Pick<CallManagerContext, "transcriptWaiters" | "maxDurationTimers">>;
+
+function removeProviderCallMapping(
+  providerCallIdMap: Map<string, string>,
+  call: Pick<CallRecord, "callId" | "providerCallId">,
+): void {
+  if (!call.providerCallId) {
+    return;
+  }
+  const mappedCallId = providerCallIdMap.get(call.providerCallId);
+  if (mappedCallId === call.callId) {
+    providerCallIdMap.delete(call.providerCallId);
+  }
+}
+
+export function finalizeCall(params: {
+  ctx: CallLifecycleContext;
+  call: CallRecord;
+  endReason: EndReason;
+  endedAt?: number;
+  transcriptRejectReason?: string;
+}): void {
+  const { ctx, call, endReason } = params;
+
+  call.endedAt = params.endedAt ?? Date.now();
+  call.endReason = endReason;
+  transitionState(call, endReason);
+  persistCallRecord(ctx.storePath, call);
+
+  if (ctx.maxDurationTimers) {
+    clearMaxDurationTimer({ maxDurationTimers: ctx.maxDurationTimers }, call.callId);
+  }
+  if (ctx.transcriptWaiters) {
+    rejectTranscriptWaiter(
+      { transcriptWaiters: ctx.transcriptWaiters },
+      call.callId,
+      params.transcriptRejectReason ?? `Call ended: ${endReason}`,
+    );
+  }
+
+  ctx.activeCalls.delete(call.callId);
+  removeProviderCallMapping(ctx.providerCallIdMap, call);
+}

package/src/manager/lookup.test.ts

@@ -0,0 +1,52 @@
+import { describe, expect, it } from "vitest";
+import { findCall, getCallByProviderCallId } from "./lookup.js";
+
+describe("voice-call manager lookup", () => {
+  it("resolves provider call ids from the explicit map first", () => {
+    const activeCalls = new Map([
+      ["call-1", { id: "call-1", providerCallId: "prov-1" }],
+      ["call-2", { id: "call-2", providerCallId: "prov-2" }],
+    ]);
+    const providerCallIdMap = new Map([["provider-lookup", "call-2"]]);
+
+    expect(
+      getCallByProviderCallId({
+        activeCalls: activeCalls as never,
+        providerCallIdMap,
+        providerCallId: "provider-lookup",
+      }),
+    ).toEqual({ id: "call-2", providerCallId: "prov-2" });
+  });
+
+  it("falls back to scanning active calls and supports direct call ids", () => {
+    const activeCalls = new Map([
+      ["call-1", { id: "call-1", providerCallId: "prov-1" }],
+      ["call-2", { id: "call-2", providerCallId: "prov-2" }],
+    ]);
+    const providerCallIdMap = new Map<string, string>();
+
+    expect(
+      getCallByProviderCallId({
+        activeCalls: activeCalls as never,
+        providerCallIdMap,
+        providerCallId: "prov-1",
+      }),
+    ).toEqual({ id: "call-1", providerCallId: "prov-1" });
+
+    expect(
+      findCall({
+        activeCalls: activeCalls as never,
+        providerCallIdMap,
+        callIdOrProviderCallId: "call-2",
+      }),
+    ).toEqual({ id: "call-2", providerCallId: "prov-2" });
+
+    expect(
+      findCall({
+        activeCalls: activeCalls as never,
+        providerCallIdMap,
+        callIdOrProviderCallId: "missing",
+      }),
+    ).toBeUndefined();
+  });
+});