@openclaw/voice-call 2026.3.1 → 2026.3.2

package/src/providers/twilio/twiml-policy.ts

@@ -0,0 +1,91 @@
+import type { WebhookContext } from "../../types.js";
+
+export type TwimlResponseKind = "empty" | "pause" | "queue" | "stored" | "stream";
+
+export type TwimlRequestView = {
+  callStatus: string | null;
+  direction: string | null;
+  isStatusCallback: boolean;
+  callSid?: string;
+  callIdFromQuery?: string;
+};
+
+export type TwimlPolicyInput = TwimlRequestView & {
+  hasStoredTwiml: boolean;
+  isNotifyCall: boolean;
+  hasActiveStreams: boolean;
+  canStream: boolean;
+};
+
+export type TwimlDecision =
+  | {
+      kind: "empty" | "pause" | "queue";
+      consumeStoredTwimlCallId?: string;
+      activateStreamCallSid?: string;
+    }
+  | {
+      kind: "stored";
+      consumeStoredTwimlCallId: string;
+      activateStreamCallSid?: string;
+    }
+  | {
+      kind: "stream";
+      consumeStoredTwimlCallId?: string;
+      activateStreamCallSid?: string;
+    };
+
+function isOutboundDirection(direction: string | null): boolean {
+  return direction?.startsWith("outbound") ?? false;
+}
+
+export function readTwimlRequestView(ctx: WebhookContext): TwimlRequestView {
+  const params = new URLSearchParams(ctx.rawBody);
+  const type = typeof ctx.query?.type === "string" ? ctx.query.type.trim() : undefined;
+  const callIdFromQuery =
+    typeof ctx.query?.callId === "string" && ctx.query.callId.trim()
+      ? ctx.query.callId.trim()
+      : undefined;
+
+  return {
+    callStatus: params.get("CallStatus"),
+    direction: params.get("Direction"),
+    isStatusCallback: type === "status",
+    callSid: params.get("CallSid") || undefined,
+    callIdFromQuery,
+  };
+}
+
+export function decideTwimlResponse(input: TwimlPolicyInput): TwimlDecision {
+  if (input.callIdFromQuery && !input.isStatusCallback) {
+    if (input.hasStoredTwiml) {
+      return { kind: "stored", consumeStoredTwimlCallId: input.callIdFromQuery };
+    }
+    if (input.isNotifyCall) {
+      return { kind: "empty" };
+    }
+
+    if (isOutboundDirection(input.direction)) {
+      return input.canStream ? { kind: "stream" } : { kind: "pause" };
+    }
+  }
+
+  if (input.isStatusCallback) {
+    return { kind: "empty" };
+  }
+
+  if (input.direction === "inbound") {
+    if (input.hasActiveStreams) {
+      return { kind: "queue" };
+    }
+    if (input.canStream && input.callSid) {
+      return { kind: "stream", activateStreamCallSid: input.callSid };
+    }
+    return { kind: "pause" };
+  }
+
+  if (input.callStatus !== "in-progress") {
+    return { kind: "empty" };
+  }
+
+  return input.canStream ? { kind: "stream" } : { kind: "pause" };
+}

package/src/providers/twilio.test.ts

@@ -60,6 +60,76 @@ describe("TwilioProvider", () => {
     expect(result.providerResponseBody).toContain("<Connect>");
   });
 
+  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";

package/src/providers/twilio.ts

@@ -5,6 +5,8 @@ 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,
@@ -19,7 +21,14 @@ import type {
 } 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 createTwilioRequestDedupeKey(ctx: WebhookContext, verifiedRequestKey?: string): string {
@@ -92,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`.
@@ -164,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 {
@@ -322,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 =
@@ -358,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.
@@ -367,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;
   }
 
   /**
@@ -543,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`,
@@ -671,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);
+  });
+});