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

package/src/manager.inbound-allowlist.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, it } from "vitest";
-import { createManagerHarness } from "./manager.test-harness.js";
+import { FakeProvider, createManagerHarness } from "./manager.test-harness.js";
 
 describe("CallManager inbound allowlist", () => {
   it("rejects inbound calls with missing caller ID when allowlist enabled", async () => {
@@ -19,8 +19,9 @@ describe("CallManager inbound allowlist", () => {
     });
 
     expect(manager.getCallByProviderCallId("provider-missing")).toBeUndefined();
-    expect(provider.hangupCalls).toHaveLength(1);
-    expect(provider.hangupCalls[0]?.providerCallId).toBe("provider-missing");
+    expect(provider.hangupCalls).toEqual([
+      expect.objectContaining({ providerCallId: "provider-missing" }),
+    ]);
   });
 
   it("rejects inbound calls with anonymous caller ID when allowlist enabled", async () => {
@@ -41,8 +42,9 @@ describe("CallManager inbound allowlist", () => {
     });
 
     expect(manager.getCallByProviderCallId("provider-anon")).toBeUndefined();
-    expect(provider.hangupCalls).toHaveLength(1);
-    expect(provider.hangupCalls[0]?.providerCallId).toBe("provider-anon");
+    expect(provider.hangupCalls).toEqual([
+      expect.objectContaining({ providerCallId: "provider-anon" }),
+    ]);
   });
 
   it("rejects inbound calls that only match allowlist suffixes", async () => {
@@ -63,8 +65,9 @@ describe("CallManager inbound allowlist", () => {
     });
 
     expect(manager.getCallByProviderCallId("provider-suffix")).toBeUndefined();
-    expect(provider.hangupCalls).toHaveLength(1);
-    expect(provider.hangupCalls[0]?.providerCallId).toBe("provider-suffix");
+    expect(provider.hangupCalls).toEqual([
+      expect.objectContaining({ providerCallId: "provider-suffix" }),
+    ]);
   });
 
   it("rejects duplicate inbound events with a single hangup call", async () => {
@@ -95,8 +98,60 @@ describe("CallManager inbound allowlist", () => {
     });
 
     expect(manager.getCallByProviderCallId("provider-dup")).toBeUndefined();
-    expect(provider.hangupCalls).toHaveLength(1);
-    expect(provider.hangupCalls[0]?.providerCallId).toBe("provider-dup");
+    expect(provider.hangupCalls).toEqual([
+      expect.objectContaining({ providerCallId: "provider-dup" }),
+    ]);
+  });
+
+  it("retries rejected inbound hangup after a transient provider failure", async () => {
+    class FlakyHangupProvider extends FakeProvider {
+      hangupFailuresRemaining = 1;
+
+      override async hangupCall(input: Parameters<FakeProvider["hangupCall"]>[0]): Promise<void> {
+        this.hangupCalls.push(input);
+        if (this.hangupFailuresRemaining > 0) {
+          this.hangupFailuresRemaining -= 1;
+          throw new Error("provider down");
+        }
+      }
+    }
+
+    const provider = new FlakyHangupProvider();
+    const { manager } = await createManagerHarness(
+      {
+        inboundPolicy: "disabled",
+      },
+      provider,
+    );
+
+    manager.processEvent({
+      id: "evt-reject-fail-init",
+      type: "call.initiated",
+      callId: "provider-flaky",
+      providerCallId: "provider-flaky",
+      timestamp: Date.now(),
+      direction: "inbound",
+      from: "+15553333333",
+      to: "+15550000000",
+    });
+    await Promise.resolve();
+
+    manager.processEvent({
+      id: "evt-reject-fail-ring",
+      type: "call.ringing",
+      callId: "provider-flaky",
+      providerCallId: "provider-flaky",
+      timestamp: Date.now(),
+      direction: "inbound",
+      from: "+15553333333",
+      to: "+15550000000",
+    });
+
+    expect(manager.getCallByProviderCallId("provider-flaky")).toBeUndefined();
+    expect(provider.hangupCalls).toEqual([
+      expect.objectContaining({ providerCallId: "provider-flaky" }),
+      expect.objectContaining({ providerCallId: "provider-flaky" }),
+    ]);
   });
 
   it("accepts inbound calls that exactly match the allowlist", async () => {
@@ -116,6 +171,18 @@ describe("CallManager inbound allowlist", () => {
       to: "+15550000000",
     });
 
-    expect(manager.getCallByProviderCallId("provider-exact")).toBeDefined();
+    const call = manager.getCallByProviderCallId("provider-exact");
+    if (!call) {
+      throw new Error("expected exact allowlist match to keep the inbound call");
+    }
+    expect(call).toMatchObject({
+      providerCallId: "provider-exact",
+      direction: "inbound",
+      from: "+15550001234",
+      to: "+15550000000",
+    });
+    expect(call.callId).toMatch(
+      /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i,
+    );
   });
 });

package/src/manager.notify.test.ts

@@ -1,6 +1,119 @@
-import { describe, expect, it } from "vitest";
+import { describe, expect, it, vi } from "vitest";
 import { createManagerHarness, FakeProvider } from "./manager.test-harness.js";
 
+class FailFirstPlayTtsProvider extends FakeProvider {
+  private failed = false;
+
+  override async playTts(input: Parameters<FakeProvider["playTts"]>[0]): Promise<void> {
+    this.playTtsCalls.push(input);
+    if (!this.failed) {
+      this.failed = true;
+      throw new Error("synthetic tts failure");
+    }
+  }
+}
+
+class DelayedPlayTtsProvider extends FakeProvider {
+  private releasePlayTts: (() => void) | null = null;
+  private resolvePlayTtsStarted: (() => void) | null = null;
+  readonly playTtsStarted = vi.fn();
+  readonly playTtsStartedPromise = new Promise<void>((resolve) => {
+    this.resolvePlayTtsStarted = resolve;
+  });
+
+  override async playTts(input: Parameters<FakeProvider["playTts"]>[0]): Promise<void> {
+    this.playTtsCalls.push(input);
+    this.playTtsStarted();
+    this.resolvePlayTtsStarted?.();
+    this.resolvePlayTtsStarted = null;
+    await new Promise<void>((resolve) => {
+      this.releasePlayTts = resolve;
+    });
+  }
+
+  releaseCurrentPlayback(): void {
+    this.releasePlayTts?.();
+    this.releasePlayTts = null;
+  }
+}
+
+class FailStartListeningProvider extends FakeProvider {
+  override async startListening(
+    input: Parameters<FakeProvider["startListening"]>[0],
+  ): Promise<void> {
+    this.startListeningCalls.push(input);
+    throw new Error("synthetic start listening failure");
+  }
+}
+
+function requireCall(
+  manager: Awaited<ReturnType<typeof createManagerHarness>>["manager"],
+  callId: string,
+) {
+  const call = manager.getCall(callId);
+  if (!call) {
+    throw new Error(`expected active call ${callId}`);
+  }
+  return call;
+}
+
+function requireMappedCall(
+  manager: Awaited<ReturnType<typeof createManagerHarness>>["manager"],
+  providerCallId: string,
+) {
+  const call = manager.getCallByProviderCallId(providerCallId);
+  if (!call) {
+    throw new Error(`expected mapped provider call ${providerCallId}`);
+  }
+  return call;
+}
+
+function requireFirstPlayTtsCall(provider: FakeProvider) {
+  const call = provider.playTtsCalls[0];
+  if (!call) {
+    throw new Error("expected provider.playTts to be called once");
+  }
+  return call;
+}
+
+type HarnessManager = Awaited<ReturnType<typeof createManagerHarness>>["manager"];
+
+async function waitForPlaybackDispatch() {
+  await new Promise((resolve) => setTimeout(resolve, 0));
+}
+
+async function initiateCallWithMessage(
+  manager: HarnessManager,
+  to: string,
+  message: string,
+  mode: "notify" | "conversation",
+) {
+  const { callId, success } = await manager.initiateCall(to, undefined, { message, mode });
+  expect(success).toBe(true);
+  return callId;
+}
+
+async function answerCall(
+  manager: HarnessManager,
+  callId: string,
+  eventId: string,
+  providerCallId = "call-uuid",
+) {
+  manager.processEvent({
+    id: eventId,
+    type: "call.answered",
+    callId,
+    providerCallId,
+    timestamp: Date.now(),
+  });
+  await waitForPlaybackDispatch();
+}
+
+function expectFirstPlayTtsText(provider: FakeProvider, text: string) {
+  expect(provider.playTtsCalls).toHaveLength(1);
+  expect(requireFirstPlayTtsCall(provider).text).toBe(text);
+}
+
 describe("CallManager notify and mapping", () => {
   it("upgrades providerCallId mapping when provider ID changes", async () => {
     const { manager } = await createManagerHarness();
@@ -9,8 +122,8 @@ describe("CallManager notify and mapping", () => {
     expect(success).toBe(true);
     expect(error).toBeUndefined();
 
-    expect(manager.getCall(callId)?.providerCallId).toBe("request-uuid");
-    expect(manager.getCallByProviderCallId("request-uuid")?.callId).toBe(callId);
+    expect(requireCall(manager, callId).providerCallId).toBe("request-uuid");
+    expect(requireMappedCall(manager, "request-uuid").callId).toBe(callId);
 
     manager.processEvent({
       id: "evt-1",
@@ -20,8 +133,8 @@ describe("CallManager notify and mapping", () => {
       timestamp: Date.now(),
     });
 
-    expect(manager.getCall(callId)?.providerCallId).toBe("call-uuid");
-    expect(manager.getCallByProviderCallId("call-uuid")?.callId).toBe(callId);
+    expect(requireCall(manager, callId).providerCallId).toBe("call-uuid");
+    expect(requireMappedCall(manager, "call-uuid").callId).toBe(callId);
     expect(manager.getCallByProviderCallId("request-uuid")).toBeUndefined();
   });
 
@@ -30,24 +143,235 @@ describe("CallManager notify and mapping", () => {
     async (providerName) => {
       const { manager, provider } = await createManagerHarness({}, new FakeProvider(providerName));
 
-      const { callId, success } = await manager.initiateCall("+15550000002", undefined, {
-        message: "Hello there",
-        mode: "notify",
-      });
-      expect(success).toBe(true);
+      const callId = await initiateCallWithMessage(
+        manager,
+        "+15550000002",
+        "Hello there",
+        "notify",
+      );
+      await answerCall(manager, callId, `evt-2-${providerName}`);
 
-      manager.processEvent({
-        id: `evt-2-${providerName}`,
-        type: "call.answered",
+      expectFirstPlayTtsText(provider, "Hello there");
+    },
+  );
+
+  it("speaks initial message on answered for conversation mode with non-stream provider", async () => {
+    const { manager, provider } = await createManagerHarness({}, new FakeProvider("plivo"));
+
+    const callId = await initiateCallWithMessage(
+      manager,
+      "+15550000003",
+      "Hello from conversation",
+      "conversation",
+    );
+    await answerCall(manager, callId, "evt-conversation-plivo");
+
+    expectFirstPlayTtsText(provider, "Hello from conversation");
+  });
+
+  it("speaks initial message on answered for conversation mode when Twilio streaming is disabled", async () => {
+    const { manager, provider } = await createManagerHarness(
+      { streaming: { enabled: false } },
+      new FakeProvider("twilio"),
+    );
+
+    const callId = await initiateCallWithMessage(
+      manager,
+      "+15550000004",
+      "Twilio non-stream",
+      "conversation",
+    );
+    await answerCall(manager, callId, "evt-conversation-twilio-no-stream");
+
+    expectFirstPlayTtsText(provider, "Twilio non-stream");
+  });
+
+  it("lets realtime conversations own the initial greeting instead of posting legacy TwiML", async () => {
+    const { manager, provider } = await createManagerHarness(
+      { realtime: { enabled: true, provider: "openai" } },
+      new FakeProvider("twilio"),
+    );
+
+    const callId = await initiateCallWithMessage(
+      manager,
+      "+15550000010",
+      "Tell Nana dinner is at 6pm.",
+      "conversation",
+    );
+    await answerCall(manager, callId, "evt-conversation-twilio-realtime");
+
+    expect(provider.playTtsCalls).toHaveLength(0);
+    expect(requireCall(manager, callId).metadata).toEqual(
+      expect.objectContaining({ initialMessage: "Tell Nana dinner is at 6pm." }),
+    );
+  });
+
+  it("still speaks initial message in notify mode when realtime is enabled", async () => {
+    const { manager, provider } = await createManagerHarness(
+      { realtime: { enabled: true, provider: "openai" } },
+      new FakeProvider("twilio"),
+    );
+
+    const callId = await initiateCallWithMessage(manager, "+15550000011", "Notify text", "notify");
+    await answerCall(manager, callId, "evt-notify-twilio-realtime");
+
+    expectFirstPlayTtsText(provider, "Notify text");
+  });
+
+  it("waits for stream connect in conversation mode when Twilio streaming is enabled", async () => {
+    const { manager, provider } = await createManagerHarness(
+      { streaming: { enabled: true } },
+      new FakeProvider("twilio"),
+    );
+
+    const callId = await initiateCallWithMessage(
+      manager,
+      "+15550000005",
+      "Twilio stream",
+      "conversation",
+    );
+    await answerCall(manager, callId, "evt-conversation-twilio-stream");
+
+    expect(provider.playTtsCalls).toHaveLength(0);
+  });
+
+  it("speaks on answered when Twilio streaming is enabled but stream-connect path is unavailable", async () => {
+    const twilioProvider = new FakeProvider("twilio");
+    twilioProvider.twilioStreamConnectEnabled = false;
+    const { manager, provider } = await createManagerHarness(
+      { streaming: { enabled: true } },
+      twilioProvider,
+    );
+
+    const callId = await initiateCallWithMessage(
+      manager,
+      "+15550000009",
+      "Twilio stream unavailable",
+      "conversation",
+    );
+    await answerCall(manager, callId, "evt-conversation-twilio-stream-unavailable");
+
+    expectFirstPlayTtsText(provider, "Twilio stream unavailable");
+  });
+
+  it("starts listening after the initial greeting for Telnyx conversation calls", async () => {
+    const { manager, provider } = await createManagerHarness({}, new FakeProvider("telnyx"));
+
+    const callId = await initiateCallWithMessage(
+      manager,
+      "+15550000012",
+      "Telnyx hello",
+      "conversation",
+    );
+    await answerCall(manager, callId, "evt-conversation-telnyx");
+
+    expectFirstPlayTtsText(provider, "Telnyx hello");
+    expect(provider.startListeningCalls).toEqual([
+      expect.objectContaining({
         callId,
         providerCallId: "call-uuid",
-        timestamp: Date.now(),
-      });
+      }),
+    ]);
+    expect(requireCall(manager, callId).state).toBe("listening");
+  });
 
-      await new Promise((resolve) => setTimeout(resolve, 0));
+  it("logs fire-and-forget initial-message failures instead of leaking unhandled rejections", async () => {
+    const provider = new FailStartListeningProvider("twilio");
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    try {
+      const { manager } = await createManagerHarness({ streaming: { enabled: false } }, provider);
 
-      expect(provider.playTtsCalls).toHaveLength(1);
-      expect(provider.playTtsCalls[0]?.text).toBe("Hello there");
-    },
-  );
+      const callId = await initiateCallWithMessage(
+        manager,
+        "+15550000013",
+        "Twilio hello",
+        "conversation",
+      );
+      await answerCall(manager, callId, "evt-initial-message-start-listening-fails");
+
+      expectFirstPlayTtsText(provider, "Twilio hello");
+      expect(provider.startListeningCalls).toEqual([
+        expect.objectContaining({
+          callId,
+          providerCallId: "call-uuid",
+        }),
+      ]);
+      expect(warn).toHaveBeenCalledWith(
+        expect.stringContaining(
+          `[voice-call] Failed to speak initial message for call ${callId}: synthetic start listening failure`,
+        ),
+      );
+    } finally {
+      warn.mockRestore();
+    }
+  });
+
+  it("preserves initialMessage after a failed first playback and retries on next trigger", async () => {
+    const provider = new FailFirstPlayTtsProvider("plivo");
+    const { manager } = await createManagerHarness({}, provider);
+
+    const callId = await initiateCallWithMessage(manager, "+15550000006", "Retry me", "notify");
+    await answerCall(manager, callId, "evt-retry-1");
+
+    const afterFailure = requireCall(manager, callId);
+    expect(provider.playTtsCalls).toHaveLength(1);
+    expect(afterFailure.metadata).toEqual(expect.objectContaining({ initialMessage: "Retry me" }));
+    expect(afterFailure.state).toBe("listening");
+
+    await answerCall(manager, callId, "evt-retry-2");
+
+    const afterSuccess = requireCall(manager, callId);
+    expect(provider.playTtsCalls).toHaveLength(2);
+    expect(afterSuccess.metadata).not.toHaveProperty("initialMessage");
+  });
+
+  it("speaks initial message only once on repeated stream-connect triggers", async () => {
+    const { manager, provider } = await createManagerHarness(
+      { streaming: { enabled: true } },
+      new FakeProvider("twilio"),
+    );
+
+    const callId = await initiateCallWithMessage(
+      manager,
+      "+15550000007",
+      "Stream hello",
+      "conversation",
+    );
+    await answerCall(manager, callId, "evt-stream-answered");
+    expect(provider.playTtsCalls).toHaveLength(0);
+
+    await manager.speakInitialMessage("call-uuid");
+    await manager.speakInitialMessage("call-uuid");
+
+    expectFirstPlayTtsText(provider, "Stream hello");
+  });
+
+  it("prevents concurrent initial-message replays while first playback is in flight", async () => {
+    const provider = new DelayedPlayTtsProvider("twilio");
+    const { manager } = await createManagerHarness({ streaming: { enabled: true } }, provider);
+
+    const callId = await initiateCallWithMessage(
+      manager,
+      "+15550000008",
+      "In-flight hello",
+      "conversation",
+    );
+    await answerCall(manager, callId, "evt-stream-answered-concurrent");
+    expect(provider.playTtsCalls).toHaveLength(0);
+
+    const first = manager.speakInitialMessage("call-uuid");
+    await provider.playTtsStartedPromise;
+    expect(provider.playTtsStarted).toHaveBeenCalledTimes(1);
+
+    const second = manager.speakInitialMessage("call-uuid");
+    await waitForPlaybackDispatch();
+    expect(provider.playTtsCalls).toHaveLength(1);
+
+    provider.releaseCurrentPlayback();
+    await Promise.all([first, second]);
+
+    const call = requireCall(manager, callId);
+    expect(call.metadata).not.toHaveProperty("initialMessage");
+    expectFirstPlayTtsText(provider, "In-flight hello");
+  });
 });

package/src/manager.restore.test.ts

@@ -1,4 +1,4 @@
-import { describe, expect, it } from "vitest";
+import { afterEach, describe, expect, it, vi } from "vitest";
 import { VoiceCallConfigSchema } from "./config.js";
 import { CallManager } from "./manager.js";
 import {
@@ -7,8 +7,23 @@ import {
   makePersistedCall,
   writeCallsToStore,
 } from "./manager.test-harness.js";
+import { flushPendingCallRecordWritesForTest, loadActiveCallsFromStore } from "./manager/store.js";
+
+function requireSingleActiveCall(manager: CallManager) {
+  const activeCalls = manager.getActiveCalls();
+  expect(activeCalls).toHaveLength(1);
+  const activeCall = activeCalls[0];
+  if (!activeCall) {
+    throw new Error("expected restored active call");
+  }
+  return activeCall;
+}
 
 describe("CallManager verification on restore", () => {
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
   async function initializeManager(params?: {
     callOverrides?: Parameters<typeof makePersistedCall>[0];
     providerResult?: FakeProvider["getCallStatusResult"];
@@ -34,7 +49,7 @@ describe("CallManager verification on restore", () => {
     const manager = new CallManager(config, storePath);
     await manager.initialize(provider, "https://example.com/voice/webhook");
 
-    return { call, manager };
+    return { call, manager, provider, storePath };
   }
 
   it("skips stale calls reported terminal by provider", async () => {
@@ -50,20 +65,22 @@ describe("CallManager verification on restore", () => {
       providerResult: { status: "in-progress", isTerminal: false },
     });
 
-    expect(manager.getActiveCalls()).toHaveLength(1);
-    expect(manager.getActiveCalls()[0]?.callId).toBe(call.callId);
+    const activeCall = requireSingleActiveCall(manager);
+    expect(activeCall.callId).toBe(call.callId);
   });
 
   it("keeps calls when provider returns unknown (transient error)", async () => {
-    const { manager } = await initializeManager({
+    const { call, manager } = await initializeManager({
       providerResult: { status: "error", isTerminal: false, isUnknown: true },
     });
 
-    expect(manager.getActiveCalls()).toHaveLength(1);
+    const activeCall = requireSingleActiveCall(manager);
+    expect(activeCall.callId).toBe(call.callId);
+    expect(activeCall.state).toBe(call.state);
   });
 
   it("skips calls older than maxDurationSeconds", async () => {
-    const { manager } = await initializeManager({
+    const { manager, provider, storePath } = await initializeManager({
       callOverrides: {
         startedAt: Date.now() - 600_000,
         answeredAt: Date.now() - 590_000,
@@ -72,6 +89,14 @@ describe("CallManager verification on restore", () => {
     });
 
     expect(manager.getActiveCalls()).toHaveLength(0);
+    expect(provider.hangupCalls).toEqual([
+      expect.objectContaining({
+        reason: "timeout",
+      }),
+    ]);
+
+    await flushPendingCallRecordWritesForTest();
+    expect(loadActiveCallsFromStore(storePath).activeCalls.size).toBe(0);
   });
 
   it("skips calls without providerCallId", async () => {
@@ -83,7 +108,7 @@ describe("CallManager verification on restore", () => {
   });
 
   it("keeps call when getCallStatus throws (verification failure)", async () => {
-    const { manager } = await initializeManager({
+    const { call, manager } = await initializeManager({
       configureProvider: (provider) => {
         provider.getCallStatus = async () => {
           throw new Error("network failure");
@@ -91,6 +116,68 @@ describe("CallManager verification on restore", () => {
       },
     });
 
+    const activeCall = requireSingleActiveCall(manager);
+    expect(activeCall.callId).toBe(call.callId);
+    expect(activeCall.state).toBe(call.state);
+  });
+
+  it("uses only remaining max duration for restored answered calls", async () => {
+    vi.useFakeTimers();
+    const now = new Date("2026-03-17T03:07:00Z");
+    vi.setSystemTime(now);
+    const { manager, provider } = await initializeManager({
+      callOverrides: {
+        startedAt: now.getTime() - 290_000,
+        answeredAt: now.getTime() - 290_000,
+        state: "answered",
+      },
+      configOverrides: { maxDurationSeconds: 300 },
+    });
+
     expect(manager.getActiveCalls()).toHaveLength(1);
+    await vi.advanceTimersByTimeAsync(9_000);
+    expect(manager.getActiveCalls()).toHaveLength(1);
+    expect(provider.hangupCalls).toHaveLength(0);
+
+    await vi.advanceTimersByTimeAsync(1_100);
+    expect(manager.getActiveCalls()).toHaveLength(0);
+    expect(provider.hangupCalls).toEqual([
+      expect.objectContaining({
+        reason: "timeout",
+      }),
+    ]);
+  });
+
+  it("restores dedupe keys from terminal persisted calls so replayed webhooks stay ignored", async () => {
+    const storePath = createTestStorePath();
+    const persisted = makePersistedCall({
+      state: "completed",
+      endedAt: Date.now() - 5_000,
+      endReason: "completed",
+      processedEventIds: ["evt-terminal-init"],
+    });
+    writeCallsToStore(storePath, [persisted]);
+
+    const provider = new FakeProvider();
+    const config = VoiceCallConfigSchema.parse({
+      enabled: true,
+      provider: "plivo",
+      fromNumber: "+15550000000",
+    });
+    const manager = new CallManager(config, storePath);
+    await manager.initialize(provider, "https://example.com/voice/webhook");
+
+    manager.processEvent({
+      id: "evt-terminal-init",
+      type: "call.initiated",
+      callId: String(persisted.providerCallId),
+      providerCallId: String(persisted.providerCallId),
+      timestamp: Date.now(),
+      direction: "outbound",
+      from: "+15550000000",
+      to: "+15550000001",
+    });
+
+    expect(manager.getActiveCalls()).toHaveLength(0);
   });
 });