@openclaw/voice-call 2026.2.25 → 2026.3.2

package/src/providers/twilio.test.ts

@@ -60,7 +60,77 @@ describe("TwilioProvider", () => {
     expect(result.providerResponseBody).toContain("<Connect>");
   });
 
-  it("uses a stable dedupeKey for identical request payloads", () => {
+  it("returns queue TwiML for second inbound call when first call is active", () => {
+    const provider = createProvider();
+    const firstInbound = createContext("CallStatus=ringing&Direction=inbound&CallSid=CA111");
+    const secondInbound = createContext("CallStatus=ringing&Direction=inbound&CallSid=CA222");
+
+    const firstResult = provider.parseWebhookEvent(firstInbound);
+    const secondResult = provider.parseWebhookEvent(secondInbound);
+
+    expect(firstResult.providerResponseBody).toContain("<Connect>");
+    expect(secondResult.providerResponseBody).toContain("Please hold while we connect you.");
+    expect(secondResult.providerResponseBody).toContain("<Enqueue");
+    expect(secondResult.providerResponseBody).toContain("hold-queue");
+  });
+
+  it("connects next inbound call after unregisterCallStream cleanup", () => {
+    const provider = createProvider();
+    const firstInbound = createContext("CallStatus=ringing&Direction=inbound&CallSid=CA311");
+    const secondInbound = createContext("CallStatus=ringing&Direction=inbound&CallSid=CA322");
+
+    provider.parseWebhookEvent(firstInbound);
+    provider.unregisterCallStream("CA311");
+    const secondResult = provider.parseWebhookEvent(secondInbound);
+
+    expect(secondResult.providerResponseBody).toContain("<Connect>");
+    expect(secondResult.providerResponseBody).not.toContain("hold-queue");
+  });
+
+  it("cleans up active inbound call on completed status callback", () => {
+    const provider = createProvider();
+    const firstInbound = createContext("CallStatus=ringing&Direction=inbound&CallSid=CA411");
+    const completed = createContext("CallStatus=completed&Direction=inbound&CallSid=CA411", {
+      type: "status",
+    });
+    const nextInbound = createContext("CallStatus=ringing&Direction=inbound&CallSid=CA422");
+
+    provider.parseWebhookEvent(firstInbound);
+    provider.parseWebhookEvent(completed);
+    const nextResult = provider.parseWebhookEvent(nextInbound);
+
+    expect(nextResult.providerResponseBody).toContain("<Connect>");
+    expect(nextResult.providerResponseBody).not.toContain("hold-queue");
+  });
+
+  it("cleans up active inbound call on canceled status callback", () => {
+    const provider = createProvider();
+    const firstInbound = createContext("CallStatus=ringing&Direction=inbound&CallSid=CA511");
+    const canceled = createContext("CallStatus=canceled&Direction=inbound&CallSid=CA511", {
+      type: "status",
+    });
+    const nextInbound = createContext("CallStatus=ringing&Direction=inbound&CallSid=CA522");
+
+    provider.parseWebhookEvent(firstInbound);
+    provider.parseWebhookEvent(canceled);
+    const nextResult = provider.parseWebhookEvent(nextInbound);
+
+    expect(nextResult.providerResponseBody).toContain("<Connect>");
+    expect(nextResult.providerResponseBody).not.toContain("hold-queue");
+  });
+
+  it("QUEUE_TWIML references /voice/hold-music waitUrl", () => {
+    const provider = createProvider();
+    const firstInbound = createContext("CallStatus=ringing&Direction=inbound&CallSid=CA611");
+    const secondInbound = createContext("CallStatus=ringing&Direction=inbound&CallSid=CA622");
+
+    provider.parseWebhookEvent(firstInbound);
+    const result = provider.parseWebhookEvent(secondInbound);
+
+    expect(result.providerResponseBody).toContain('waitUrl="/voice/hold-music"');
+  });
+
+  it("uses a stable fallback dedupeKey for identical request payloads", () => {
     const provider = createProvider();
     const rawBody = "CallSid=CA789&Direction=inbound&SpeechResult=hello";
     const ctxA = {
@@ -78,10 +148,31 @@ describe("TwilioProvider", () => {
     expect(eventA).toBeDefined();
     expect(eventB).toBeDefined();
     expect(eventA?.id).not.toBe(eventB?.id);
-    expect(eventA?.dedupeKey).toBe("twilio:idempotency:idem-123");
+    expect(eventA?.dedupeKey).toContain("twilio:fallback:");
     expect(eventA?.dedupeKey).toBe(eventB?.dedupeKey);
   });
 
+  it("uses verified request key for dedupe and ignores idempotency header changes", () => {
+    const provider = createProvider();
+    const rawBody = "CallSid=CA790&Direction=inbound&SpeechResult=hello";
+    const ctxA = {
+      ...createContext(rawBody, { callId: "call-1", turnToken: "turn-1" }),
+      headers: { "i-twilio-idempotency-token": "idem-a" },
+    };
+    const ctxB = {
+      ...createContext(rawBody, { callId: "call-1", turnToken: "turn-1" }),
+      headers: { "i-twilio-idempotency-token": "idem-b" },
+    };
+
+    const eventA = provider.parseWebhookEvent(ctxA, { verifiedRequestKey: "twilio:req:abc" })
+      .events[0];
+    const eventB = provider.parseWebhookEvent(ctxB, { verifiedRequestKey: "twilio:req:abc" })
+      .events[0];
+
+    expect(eventA?.dedupeKey).toBe("twilio:req:abc");
+    expect(eventB?.dedupeKey).toBe("twilio:req:abc");
+  });
+
   it("keeps turnToken from query on speech events", () => {
     const provider = createProvider();
     const ctx = createContext("CallSid=CA222&Direction=inbound&SpeechResult=hello", {

package/src/providers/twilio.ts

@@ -1,9 +1,12 @@
 import crypto from "node:crypto";
 import type { TwilioConfig, WebhookSecurityConfig } from "../config.js";
+import { getHeader } from "../http-headers.js";
 import type { MediaStreamHandler } from "../media-stream.js";
 import { chunkAudio } from "../telephony-audio.js";
 import type { TelephonyTtsProvider } from "../telephony-tts.js";
 import type {
+  GetCallStatusInput,
+  GetCallStatusResult,
   HangupCallInput,
   InitiateCallInput,
   InitiateCallResult,
@@ -13,37 +16,39 @@ import type {
   StartListeningInput,
   StopListeningInput,
   WebhookContext,
+  WebhookParseOptions,
   WebhookVerificationResult,
 } from "../types.js";
 import { escapeXml, mapVoiceToPolly } from "../voice-mapping.js";
 import type { VoiceCallProvider } from "./base.js";
+import {
+  isProviderStatusTerminal,
+  mapProviderStatusToEndReason,
+  normalizeProviderStatus,
+} from "./shared/call-status.js";
+import { guardedJsonApiRequest } from "./shared/guarded-json-api.js";
 import { twilioApiRequest } from "./twilio/api.js";
+import { decideTwimlResponse, readTwimlRequestView } from "./twilio/twiml-policy.js";
 import { verifyTwilioProviderWebhook } from "./twilio/webhook.js";
 
-function getHeader(
-  headers: Record<string, string | string[] | undefined>,
-  name: string,
-): string | undefined {
-  const value = headers[name.toLowerCase()];
-  if (Array.isArray(value)) {
-    return value[0];
-  }
-  return value;
-}
-
-function createTwilioRequestDedupeKey(ctx: WebhookContext): string {
-  const idempotencyToken = getHeader(ctx.headers, "i-twilio-idempotency-token");
-  if (idempotencyToken) {
-    return `twilio:idempotency:${idempotencyToken}`;
+function createTwilioRequestDedupeKey(ctx: WebhookContext, verifiedRequestKey?: string): string {
+  if (verifiedRequestKey) {
+    return verifiedRequestKey;
   }
 
   const signature = getHeader(ctx.headers, "x-twilio-signature") ?? "";
+  const params = new URLSearchParams(ctx.rawBody);
+  const callSid = params.get("CallSid") ?? "";
+  const callStatus = params.get("CallStatus") ?? "";
+  const direction = params.get("Direction") ?? "";
   const callId = typeof ctx.query?.callId === "string" ? ctx.query.callId.trim() : "";
   const flow = typeof ctx.query?.flow === "string" ? ctx.query.flow.trim() : "";
   const turnToken = typeof ctx.query?.turnToken === "string" ? ctx.query.turnToken.trim() : "";
   return `twilio:fallback:${crypto
     .createHash("sha256")
-    .update(`${signature}\n${callId}\n${flow}\n${turnToken}\n${ctx.rawBody}`)
+    .update(
+      `${signature}\n${callSid}\n${callStatus}\n${direction}\n${callId}\n${flow}\n${turnToken}\n${ctx.rawBody}`,
+    )
     .digest("hex")}`;
 }
 
@@ -96,6 +101,7 @@ export class TwilioProvider implements VoiceCallProvider {
   private readonly twimlStorage = new Map<string, string>();
   /** Track notify-mode calls to avoid streaming on follow-up callbacks */
   private readonly notifyCalls = new Set<string>();
+  private readonly activeStreamCalls = new Set<string>();
 
   /**
    * Delete stored TwiML for a given `callId`.
@@ -168,6 +174,7 @@ export class TwilioProvider implements VoiceCallProvider {
 
   unregisterCallStream(callSid: string): void {
     this.callStreamMap.delete(callSid);
+    this.activeStreamCalls.delete(callSid);
   }
 
   isValidStreamToken(callSid: string, token?: string): boolean {
@@ -232,7 +239,10 @@ export class TwilioProvider implements VoiceCallProvider {
   /**
    * Parse Twilio webhook event into normalized format.
    */
-  parseWebhookEvent(ctx: WebhookContext): ProviderWebhookParseResult {
+  parseWebhookEvent(
+    ctx: WebhookContext,
+    options?: WebhookParseOptions,
+  ): ProviderWebhookParseResult {
     try {
       const params = new URLSearchParams(ctx.rawBody);
       const callIdFromQuery =
@@ -243,7 +253,7 @@ export class TwilioProvider implements VoiceCallProvider {
         typeof ctx.query?.turnToken === "string" && ctx.query.turnToken.trim()
           ? ctx.query.turnToken.trim()
           : undefined;
-      const dedupeKey = createTwilioRequestDedupeKey(ctx);
+      const dedupeKey = createTwilioRequestDedupeKey(ctx, options?.verifiedRequestKey);
       const event = this.normalizeEvent(params, {
         callIdOverride: callIdFromQuery,
         dedupeKey,
@@ -323,32 +333,28 @@ export class TwilioProvider implements VoiceCallProvider {
     }
 
     // Handle call status changes
-    const callStatus = params.get("CallStatus");
-    switch (callStatus) {
-      case "initiated":
-        return { ...baseEvent, type: "call.initiated" };
-      case "ringing":
-        return { ...baseEvent, type: "call.ringing" };
-      case "in-progress":
-        return { ...baseEvent, type: "call.answered" };
-      case "completed":
-      case "busy":
-      case "no-answer":
-      case "failed":
-        this.streamAuthTokens.delete(callSid);
-        if (callIdOverride) {
-          this.deleteStoredTwiml(callIdOverride);
-        }
-        return { ...baseEvent, type: "call.ended", reason: callStatus };
-      case "canceled":
-        this.streamAuthTokens.delete(callSid);
-        if (callIdOverride) {
-          this.deleteStoredTwiml(callIdOverride);
-        }
-        return { ...baseEvent, type: "call.ended", reason: "hangup-bot" };
-      default:
-        return null;
+    const callStatus = normalizeProviderStatus(params.get("CallStatus"));
+    if (callStatus === "initiated") {
+      return { ...baseEvent, type: "call.initiated" };
+    }
+    if (callStatus === "ringing") {
+      return { ...baseEvent, type: "call.ringing" };
+    }
+    if (callStatus === "in-progress") {
+      return { ...baseEvent, type: "call.answered" };
+    }
+
+    const endReason = mapProviderStatusToEndReason(callStatus);
+    if (endReason) {
+      this.streamAuthTokens.delete(callSid);
+      this.activeStreamCalls.delete(callSid);
+      if (callIdOverride) {
+        this.deleteStoredTwiml(callIdOverride);
+      }
+      return { ...baseEvent, type: "call.ended", reason: endReason };
     }
+
+    return null;
   }
 
   private static readonly EMPTY_TWIML =
@@ -359,6 +365,12 @@ export class TwilioProvider implements VoiceCallProvider {
   <Pause length="30"/>
 </Response>`;
 
+  private static readonly QUEUE_TWIML = `<?xml version="1.0" encoding="UTF-8"?>
+<Response>
+  <Say voice="alice">Please hold while we connect you.</Say>
+  <Enqueue waitUrl="/voice/hold-music">hold-queue</Enqueue>
+</Response>`;
+
   /**
    * Generate TwiML response for webhook.
    * When a call is answered, connects to media stream for bidirectional audio.
@@ -368,59 +380,40 @@ export class TwilioProvider implements VoiceCallProvider {
       return TwilioProvider.EMPTY_TWIML;
     }
 
-    const params = new URLSearchParams(ctx.rawBody);
-    const type = typeof ctx.query?.type === "string" ? ctx.query.type.trim() : undefined;
-    const isStatusCallback = type === "status";
-    const callStatus = params.get("CallStatus");
-    const direction = params.get("Direction");
-    const isOutbound = direction?.startsWith("outbound") ?? false;
-    const callSid = params.get("CallSid") || undefined;
-    const callIdFromQuery =
-      typeof ctx.query?.callId === "string" && ctx.query.callId.trim()
-        ? ctx.query.callId.trim()
-        : undefined;
-
-    // Avoid logging webhook params/TwiML (may contain PII).
-
-    // Handle initial TwiML request (when Twilio first initiates the call)
-    // Check if we have stored TwiML for this call (notify mode)
-    if (callIdFromQuery && !isStatusCallback) {
-      const storedTwiml = this.twimlStorage.get(callIdFromQuery);
-      if (storedTwiml) {
-        // Clean up after serving (one-time use)
-        this.deleteStoredTwiml(callIdFromQuery);
-        return storedTwiml;
-      }
-      if (this.notifyCalls.has(callIdFromQuery)) {
-        return TwilioProvider.EMPTY_TWIML;
-      }
-
-      // Conversation mode: return streaming TwiML immediately for outbound calls.
-      if (isOutbound) {
-        const streamUrl = callSid ? this.getStreamUrlForCall(callSid) : null;
-        return streamUrl ? this.getStreamConnectXml(streamUrl) : TwilioProvider.PAUSE_TWIML;
-      }
-    }
+    const view = readTwimlRequestView(ctx);
+    const storedTwiml = view.callIdFromQuery
+      ? this.twimlStorage.get(view.callIdFromQuery)
+      : undefined;
+    const decision = decideTwimlResponse({
+      ...view,
+      hasStoredTwiml: Boolean(storedTwiml),
+      isNotifyCall: view.callIdFromQuery ? this.notifyCalls.has(view.callIdFromQuery) : false,
+      hasActiveStreams: this.activeStreamCalls.size > 0,
+      canStream: Boolean(view.callSid && this.getStreamUrl()),
+    });
 
-    // Status callbacks should not receive TwiML.
-    if (isStatusCallback) {
-      return TwilioProvider.EMPTY_TWIML;
+    if (decision.consumeStoredTwimlCallId) {
+      this.deleteStoredTwiml(decision.consumeStoredTwimlCallId);
     }
-
-    // Handle subsequent webhook requests (status callbacks, etc.)
-    // For inbound calls, answer immediately with stream
-    if (direction === "inbound") {
-      const streamUrl = callSid ? this.getStreamUrlForCall(callSid) : null;
-      return streamUrl ? this.getStreamConnectXml(streamUrl) : TwilioProvider.PAUSE_TWIML;
+    if (decision.activateStreamCallSid) {
+      this.activeStreamCalls.add(decision.activateStreamCallSid);
     }
 
-    // For outbound calls, only connect to stream when call is in-progress
-    if (callStatus !== "in-progress") {
-      return TwilioProvider.EMPTY_TWIML;
+    switch (decision.kind) {
+      case "stored":
+        return storedTwiml ?? TwilioProvider.EMPTY_TWIML;
+      case "queue":
+        return TwilioProvider.QUEUE_TWIML;
+      case "pause":
+        return TwilioProvider.PAUSE_TWIML;
+      case "stream": {
+        const streamUrl = view.callSid ? this.getStreamUrlForCall(view.callSid) : null;
+        return streamUrl ? this.getStreamConnectXml(streamUrl) : TwilioProvider.PAUSE_TWIML;
+      }
+      case "empty":
+      default:
+        return TwilioProvider.EMPTY_TWIML;
     }
-
-    const streamUrl = callSid ? this.getStreamUrlForCall(callSid) : null;
-    return streamUrl ? this.getStreamConnectXml(streamUrl) : TwilioProvider.PAUSE_TWIML;
   }
 
   /**
@@ -544,6 +537,7 @@ export class TwilioProvider implements VoiceCallProvider {
 
     this.callWebhookUrls.delete(input.providerCallId);
     this.streamAuthTokens.delete(input.providerCallId);
+    this.activeStreamCalls.delete(input.providerCallId);
 
     await this.apiRequest(
       `/Calls/${input.providerCallId}.json`,
@@ -672,6 +666,32 @@ export class TwilioProvider implements VoiceCallProvider {
     // Twilio's <Gather> automatically stops on speech end
     // No explicit action needed
   }
+
+  async getCallStatus(input: GetCallStatusInput): Promise<GetCallStatusResult> {
+    try {
+      const data = await guardedJsonApiRequest<{ status?: string }>({
+        url: `${this.baseUrl}/Calls/${input.providerCallId}.json`,
+        method: "GET",
+        headers: {
+          Authorization: `Basic ${Buffer.from(`${this.accountSid}:${this.authToken}`).toString("base64")}`,
+        },
+        allowNotFound: true,
+        allowedHostnames: ["api.twilio.com"],
+        auditContext: "twilio-get-call-status",
+        errorPrefix: "Twilio get call status error",
+      });
+
+      if (!data) {
+        return { status: "not-found", isTerminal: true };
+      }
+
+      const status = normalizeProviderStatus(data.status);
+      return { status, isTerminal: isProviderStatusTerminal(status) };
+    } catch {
+      // Transient error — keep the call and rely on timer fallback
+      return { status: "error", isTerminal: false, isUnknown: true };
+    }
+  }
 }
 
 // -----------------------------------------------------------------------------

package/src/runtime.test.ts

@@ -0,0 +1,147 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import type { VoiceCallConfig } from "./config.js";
+import type { CoreConfig } from "./core-bridge.js";
+
+const mocks = vi.hoisted(() => ({
+  resolveVoiceCallConfig: vi.fn(),
+  validateProviderConfig: vi.fn(),
+  managerInitialize: vi.fn(),
+  webhookStart: vi.fn(),
+  webhookStop: vi.fn(),
+  webhookGetMediaStreamHandler: vi.fn(),
+  startTunnel: vi.fn(),
+  setupTailscaleExposure: vi.fn(),
+  cleanupTailscaleExposure: vi.fn(),
+}));
+
+vi.mock("./config.js", () => ({
+  resolveVoiceCallConfig: mocks.resolveVoiceCallConfig,
+  validateProviderConfig: mocks.validateProviderConfig,
+}));
+
+vi.mock("./manager.js", () => ({
+  CallManager: class {
+    initialize = mocks.managerInitialize;
+  },
+}));
+
+vi.mock("./webhook.js", () => ({
+  VoiceCallWebhookServer: class {
+    start = mocks.webhookStart;
+    stop = mocks.webhookStop;
+    getMediaStreamHandler = mocks.webhookGetMediaStreamHandler;
+  },
+}));
+
+vi.mock("./tunnel.js", () => ({
+  startTunnel: mocks.startTunnel,
+}));
+
+vi.mock("./webhook/tailscale.js", () => ({
+  setupTailscaleExposure: mocks.setupTailscaleExposure,
+  cleanupTailscaleExposure: mocks.cleanupTailscaleExposure,
+}));
+
+import { createVoiceCallRuntime } from "./runtime.js";
+
+function createBaseConfig(): VoiceCallConfig {
+  return {
+    enabled: true,
+    provider: "mock",
+    fromNumber: "+15550001234",
+    inboundPolicy: "disabled",
+    allowFrom: [],
+    outbound: { defaultMode: "notify", notifyHangupDelaySec: 3 },
+    maxDurationSeconds: 300,
+    staleCallReaperSeconds: 600,
+    silenceTimeoutMs: 800,
+    transcriptTimeoutMs: 180000,
+    ringTimeoutMs: 30000,
+    maxConcurrentCalls: 1,
+    serve: { port: 3334, bind: "127.0.0.1", path: "/voice/webhook" },
+    tailscale: { mode: "off", path: "/voice/webhook" },
+    tunnel: { provider: "ngrok", allowNgrokFreeTierLoopbackBypass: false },
+    webhookSecurity: {
+      allowedHosts: [],
+      trustForwardingHeaders: false,
+      trustedProxyIPs: [],
+    },
+    streaming: {
+      enabled: false,
+      sttProvider: "openai-realtime",
+      sttModel: "gpt-4o-transcribe",
+      silenceDurationMs: 800,
+      vadThreshold: 0.5,
+      streamPath: "/voice/stream",
+      preStartTimeoutMs: 5000,
+      maxPendingConnections: 32,
+      maxPendingConnectionsPerIp: 4,
+      maxConnections: 128,
+    },
+    skipSignatureVerification: false,
+    stt: { provider: "openai", model: "whisper-1" },
+    tts: {
+      provider: "openai",
+      openai: { model: "gpt-4o-mini-tts", voice: "coral" },
+    },
+    responseModel: "openai/gpt-4o-mini",
+    responseTimeoutMs: 30000,
+  };
+}
+
+describe("createVoiceCallRuntime lifecycle", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mocks.resolveVoiceCallConfig.mockImplementation((cfg: VoiceCallConfig) => cfg);
+    mocks.validateProviderConfig.mockReturnValue({ valid: true, errors: [] });
+    mocks.managerInitialize.mockResolvedValue(undefined);
+    mocks.webhookStart.mockResolvedValue("http://127.0.0.1:3334/voice/webhook");
+    mocks.webhookStop.mockResolvedValue(undefined);
+    mocks.webhookGetMediaStreamHandler.mockReturnValue(undefined);
+    mocks.startTunnel.mockResolvedValue(null);
+    mocks.setupTailscaleExposure.mockResolvedValue(null);
+    mocks.cleanupTailscaleExposure.mockResolvedValue(undefined);
+  });
+
+  it("cleans up tunnel, tailscale, and webhook server when init fails after start", async () => {
+    const tunnelStop = vi.fn().mockResolvedValue(undefined);
+    mocks.startTunnel.mockResolvedValue({
+      publicUrl: "https://public.example/voice/webhook",
+      provider: "ngrok",
+      stop: tunnelStop,
+    });
+    mocks.managerInitialize.mockRejectedValue(new Error("init failed"));
+
+    await expect(
+      createVoiceCallRuntime({
+        config: createBaseConfig(),
+        coreConfig: {},
+      }),
+    ).rejects.toThrow("init failed");
+
+    expect(tunnelStop).toHaveBeenCalledTimes(1);
+    expect(mocks.cleanupTailscaleExposure).toHaveBeenCalledTimes(1);
+    expect(mocks.webhookStop).toHaveBeenCalledTimes(1);
+  });
+
+  it("returns an idempotent stop handler", async () => {
+    const tunnelStop = vi.fn().mockResolvedValue(undefined);
+    mocks.startTunnel.mockResolvedValue({
+      publicUrl: "https://public.example/voice/webhook",
+      provider: "ngrok",
+      stop: tunnelStop,
+    });
+
+    const runtime = await createVoiceCallRuntime({
+      config: createBaseConfig(),
+      coreConfig: {} as CoreConfig,
+    });
+
+    await runtime.stop();
+    await runtime.stop();
+
+    expect(tunnelStop).toHaveBeenCalledTimes(1);
+    expect(mocks.cleanupTailscaleExposure).toHaveBeenCalledTimes(1);
+    expect(mocks.webhookStop).toHaveBeenCalledTimes(1);
+  });
+});