@openclaw/voice-call 2026.2.25 → 2026.3.2

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## 2026.3.2
+
+### Changes
+
+- Version alignment with core OpenClaw release numbers.
+
+## 2026.3.1
+
+### Changes
+
+- Version alignment with core OpenClaw release numbers.
+
+## 2026.2.26
+
+### Changes
+
+- Version alignment with core OpenClaw release numbers.
+
 ## 2026.2.25
 
 ### Changes

package/index.ts

@@ -181,7 +181,15 @@ const voiceCallPlugin = {
           logger: api.logger,
         });
       }
-      runtime = await runtimePromise;
+      try {
+        runtime = await runtimePromise;
+      } catch (err) {
+        // Reset so the next call can retry instead of caching the
+        // rejected promise forever (which also leaves the port orphaned
+        // if the server started before the failure).  See: #32387
+        runtimePromise = null;
+        throw err;
+      }
       return runtime;
     };
 
@@ -189,6 +197,16 @@ const voiceCallPlugin = {
       respond(false, { error: err instanceof Error ? err.message : String(err) });
     };
 
+    const resolveCallMessageRequest = async (params: GatewayRequestHandlerOptions["params"]) => {
+      const callId = typeof params?.callId === "string" ? params.callId.trim() : "";
+      const message = typeof params?.message === "string" ? params.message.trim() : "";
+      if (!callId || !message) {
+        return { error: "callId and message required" } as const;
+      }
+      const rt = await ensureRuntime();
+      return { rt, callId, message } as const;
+    };
+
     api.registerGatewayMethod(
       "voicecall.initiate",
       async ({ params, respond }: GatewayRequestHandlerOptions) => {
@@ -228,14 +246,12 @@ const voiceCallPlugin = {
       "voicecall.continue",
       async ({ params, respond }: GatewayRequestHandlerOptions) => {
         try {
-          const callId = typeof params?.callId === "string" ? params.callId.trim() : "";
-          const message = typeof params?.message === "string" ? params.message.trim() : "";
-          if (!callId || !message) {
-            respond(false, { error: "callId and message required" });
+          const request = await resolveCallMessageRequest(params);
+          if ("error" in request) {
+            respond(false, { error: request.error });
             return;
           }
-          const rt = await ensureRuntime();
-          const result = await rt.manager.continueCall(callId, message);
+          const result = await request.rt.manager.continueCall(request.callId, request.message);
           if (!result.success) {
             respond(false, { error: result.error || "continue failed" });
             return;
@@ -251,14 +267,12 @@ const voiceCallPlugin = {
       "voicecall.speak",
       async ({ params, respond }: GatewayRequestHandlerOptions) => {
         try {
-          const callId = typeof params?.callId === "string" ? params.callId.trim() : "";
-          const message = typeof params?.message === "string" ? params.message.trim() : "";
-          if (!callId || !message) {
-            respond(false, { error: "callId and message required" });
+          const request = await resolveCallMessageRequest(params);
+          if ("error" in request) {
+            respond(false, { error: request.error });
             return;
           }
-          const rt = await ensureRuntime();
-          const result = await rt.manager.speak(callId, message);
+          const result = await request.rt.manager.speak(request.callId, request.message);
           if (!result.success) {
             respond(false, { error: result.error || "speak failed" });
             return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openclaw/voice-call",
-  "version": "2026.2.25",
+  "version": "2026.3.2",
   "description": "OpenClaw voice-call plugin",
   "type": "module",
   "dependencies": {

package/src/cli.ts

@@ -10,7 +10,7 @@ import {
   cleanupTailscaleExposureRoute,
   getTailscaleSelfInfo,
   setupTailscaleExposureRoute,
-} from "./webhook.js";
+} from "./webhook/tailscale.js";
 
 type Logger = {
   info: (message: string) => void;

package/src/http-headers.test.ts

@@ -0,0 +1,16 @@
+import { describe, expect, it } from "vitest";
+import { getHeader } from "./http-headers.js";
+
+describe("getHeader", () => {
+  it("returns first value when header is an array", () => {
+    expect(getHeader({ "x-test": ["first", "second"] }, "x-test")).toBe("first");
+  });
+
+  it("matches headers case-insensitively", () => {
+    expect(getHeader({ "X-Twilio-Signature": "sig-1" }, "x-twilio-signature")).toBe("sig-1");
+  });
+
+  it("returns undefined for missing header", () => {
+    expect(getHeader({ host: "example.com" }, "x-missing")).toBeUndefined();
+  });
+});

package/src/http-headers.ts

@@ -0,0 +1,12 @@
+export type HttpHeaderMap = Record<string, string | string[] | undefined>;
+
+export function getHeader(headers: HttpHeaderMap, name: string): string | undefined {
+  const target = name.toLowerCase();
+  const direct = headers[target];
+  const value =
+    direct ?? Object.entries(headers).find(([key]) => key.toLowerCase() === target)?.[1];
+  if (Array.isArray(value)) {
+    return value[0];
+  }
+  return value;
+}

package/src/manager/events.test.ts

@@ -41,6 +41,7 @@ function createProvider(overrides: Partial<VoiceCallProvider> = {}): VoiceCallPr
     playTts: async () => {},
     startListening: async () => {},
     stopListening: async () => {},
+    getCallStatus: async () => ({ status: "in-progress", isTerminal: false }),
     ...overrides,
   };
 }
@@ -235,6 +236,80 @@ describe("processEvent (functional)", () => {
     expect(ctx.activeCalls.size).toBe(0);
   });
 
+  it("auto-registers externally-initiated outbound-api calls with correct direction", () => {
+    const ctx = createContext();
+    const event: NormalizedEvent = {
+      id: "evt-external-1",
+      type: "call.initiated",
+      callId: "CA-external-123",
+      providerCallId: "CA-external-123",
+      timestamp: Date.now(),
+      direction: "outbound",
+      from: "+15550000000",
+      to: "+15559876543",
+    };
+
+    processEvent(ctx, event);
+
+    // 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");
+  });
+
+  it("does not reject externally-initiated outbound calls even with disabled inbound policy", () => {
+    const { ctx, hangupCalls } = createRejectingInboundContext();
+    const event: NormalizedEvent = {
+      id: "evt-external-2",
+      type: "call.initiated",
+      callId: "CA-external-456",
+      providerCallId: "CA-external-456",
+      timestamp: Date.now(),
+      direction: "outbound",
+      from: "+15550000000",
+      to: "+15559876543",
+    };
+
+    processEvent(ctx, event);
+
+    // 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");
+  });
+
+  it("preserves inbound direction for auto-registered inbound calls", () => {
+    const ctx = createContext({
+      config: VoiceCallConfigSchema.parse({
+        enabled: true,
+        provider: "plivo",
+        fromNumber: "+15550000000",
+        inboundPolicy: "open",
+      }),
+    });
+    const event: NormalizedEvent = {
+      id: "evt-inbound-dir",
+      type: "call.initiated",
+      callId: "CA-inbound-789",
+      providerCallId: "CA-inbound-789",
+      timestamp: Date.now(),
+      direction: "inbound",
+      from: "+15554444444",
+      to: "+15550000000",
+    };
+
+    processEvent(ctx, event);
+
+    expect(ctx.activeCalls.size).toBe(1);
+    const call = [...ctx.activeCalls.values()][0];
+    expect(call?.direction).toBe("inbound");
+  });
+
   it("deduplicates by dedupeKey even when event IDs differ", () => {
     const now = Date.now();
     const ctx = createContext();

package/src/manager/events.ts

@@ -59,9 +59,10 @@ function shouldAcceptInbound(config: EventContext["config"], from: string | unde
   }
 }
 
-function createInboundCall(params: {
+function createWebhookCall(params: {
   ctx: EventContext;
   providerCallId: string;
+  direction: "inbound" | "outbound";
   from: string;
   to: string;
 }): CallRecord {
@@ -71,7 +72,7 @@ function createInboundCall(params: {
     callId,
     providerCallId: params.providerCallId,
     provider: params.ctx.provider?.name || "twilio",
-    direction: "inbound",
+    direction: params.direction,
     state: "ringing",
     from: params.from,
     to: params.to,
@@ -79,7 +80,10 @@ function createInboundCall(params: {
     transcript: [],
     processedEventIds: [],
     metadata: {
-      initialMessage: params.ctx.config.inboundGreeting || "Hello! How can I help you today?",
+      initialMessage:
+        params.direction === "inbound"
+          ? params.ctx.config.inboundGreeting || "Hello! How can I help you today?"
+          : undefined,
     },
   };
 
@@ -87,7 +91,9 @@ function createInboundCall(params: {
   params.ctx.providerCallIdMap.set(params.providerCallId, callId);
   persistCallRecord(params.ctx.storePath, callRecord);
 
-  console.log(`[voice-call] Created inbound call record: ${callId} from ${params.from}`);
+  console.log(
+    `[voice-call] Created ${params.direction} call record: ${callId} from ${params.from}`,
+  );
   return callRecord;
 }
 
@@ -104,9 +110,18 @@ export function processEvent(ctx: EventContext, event: NormalizedEvent): void {
     callIdOrProviderCallId: event.callId,
   });
 
-  if (!call && event.direction === "inbound" && event.providerCallId) {
-    if (!shouldAcceptInbound(ctx.config, event.from)) {
-      const pid = event.providerCallId;
+  const providerCallId = event.providerCallId;
+  const eventDirection =
+    event.direction === "inbound" || event.direction === "outbound" ? event.direction : undefined;
+
+  // Auto-register untracked calls arriving via webhook. This covers both
+  // true inbound calls and externally-initiated outbound-api calls (e.g. calls
+  // placed directly via the Twilio REST API pointing at our webhook URL).
+  if (!call && providerCallId && eventDirection) {
+    // Apply inbound policy for true inbound calls; external outbound-api calls
+    // are implicitly trusted because the caller controls the webhook URL.
+    if (eventDirection === "inbound" && !shouldAcceptInbound(ctx.config, event.from)) {
+      const pid = providerCallId;
       if (!ctx.provider) {
         console.warn(
           `[voice-call] Inbound call rejected by policy but no provider to hang up (providerCallId: ${pid}, from: ${event.from}); call will time out on provider side.`,
@@ -132,9 +147,10 @@ export function processEvent(ctx: EventContext, event: NormalizedEvent): void {
       return;
     }
 
-    call = createInboundCall({
+    call = createWebhookCall({
       ctx,
-      providerCallId: event.providerCallId,
+      providerCallId,
+      direction: eventDirection === "outbound" ? "outbound" : "inbound",
       from: event.from || "unknown",
       to: event.to || ctx.config.fromNumber || "unknown",
     });

package/src/manager.closed-loop.test.ts

@@ -0,0 +1,218 @@
+import { describe, expect, it } from "vitest";
+import { createManagerHarness, FakeProvider, markCallAnswered } from "./manager.test-harness.js";
+
+describe("CallManager closed-loop turns", () => {
+  it("completes a closed-loop turn without live audio", async () => {
+    const { manager, provider } = await createManagerHarness({
+      transcriptTimeoutMs: 5000,
+    });
+
+    const started = await manager.initiateCall("+15550000003");
+    expect(started.success).toBe(true);
+
+    markCallAnswered(manager, started.callId, "evt-closed-loop-answered");
+
+    const turnPromise = manager.continueCall(started.callId, "How can I help?");
+    await new Promise((resolve) => setTimeout(resolve, 0));
+
+    manager.processEvent({
+      id: "evt-closed-loop-speech",
+      type: "call.speech",
+      callId: started.callId,
+      providerCallId: "request-uuid",
+      timestamp: Date.now(),
+      transcript: "Please check status",
+      isFinal: true,
+    });
+
+    const turn = await turnPromise;
+    expect(turn.success).toBe(true);
+    expect(turn.transcript).toBe("Please check status");
+    expect(provider.startListeningCalls).toHaveLength(1);
+    expect(provider.stopListeningCalls).toHaveLength(1);
+
+    const call = manager.getCall(started.callId);
+    expect(call?.transcript.map((entry) => entry.text)).toEqual([
+      "How can I help?",
+      "Please check status",
+    ]);
+    const metadata = (call?.metadata ?? {}) as Record<string, unknown>;
+    expect(typeof metadata.lastTurnLatencyMs).toBe("number");
+    expect(typeof metadata.lastTurnListenWaitMs).toBe("number");
+    expect(metadata.turnCount).toBe(1);
+  });
+
+  it("rejects overlapping continueCall requests for the same call", async () => {
+    const { manager, provider } = await createManagerHarness({
+      transcriptTimeoutMs: 5000,
+    });
+
+    const started = await manager.initiateCall("+15550000004");
+    expect(started.success).toBe(true);
+
+    markCallAnswered(manager, started.callId, "evt-overlap-answered");
+
+    const first = manager.continueCall(started.callId, "First prompt");
+    const second = await manager.continueCall(started.callId, "Second prompt");
+    expect(second.success).toBe(false);
+    expect(second.error).toBe("Already waiting for transcript");
+
+    manager.processEvent({
+      id: "evt-overlap-speech",
+      type: "call.speech",
+      callId: started.callId,
+      providerCallId: "request-uuid",
+      timestamp: Date.now(),
+      transcript: "Done",
+      isFinal: true,
+    });
+
+    const firstResult = await first;
+    expect(firstResult.success).toBe(true);
+    expect(firstResult.transcript).toBe("Done");
+    expect(provider.startListeningCalls).toHaveLength(1);
+    expect(provider.stopListeningCalls).toHaveLength(1);
+  });
+
+  it("ignores speech events with mismatched turnToken while waiting for transcript", async () => {
+    const { manager, provider } = await createManagerHarness(
+      {
+        transcriptTimeoutMs: 5000,
+      },
+      new FakeProvider("twilio"),
+    );
+
+    const started = await manager.initiateCall("+15550000004");
+    expect(started.success).toBe(true);
+
+    markCallAnswered(manager, started.callId, "evt-turn-token-answered");
+
+    const turnPromise = manager.continueCall(started.callId, "Prompt");
+    await new Promise((resolve) => setTimeout(resolve, 0));
+
+    const expectedTurnToken = provider.startListeningCalls[0]?.turnToken;
+    expect(typeof expectedTurnToken).toBe("string");
+
+    manager.processEvent({
+      id: "evt-turn-token-bad",
+      type: "call.speech",
+      callId: started.callId,
+      providerCallId: "request-uuid",
+      timestamp: Date.now(),
+      transcript: "stale replay",
+      isFinal: true,
+      turnToken: "wrong-token",
+    });
+
+    const pendingState = await Promise.race([
+      turnPromise.then(() => "resolved"),
+      new Promise<"pending">((resolve) => setTimeout(() => resolve("pending"), 0)),
+    ]);
+    expect(pendingState).toBe("pending");
+
+    manager.processEvent({
+      id: "evt-turn-token-good",
+      type: "call.speech",
+      callId: started.callId,
+      providerCallId: "request-uuid",
+      timestamp: Date.now(),
+      transcript: "final answer",
+      isFinal: true,
+      turnToken: expectedTurnToken,
+    });
+
+    const turnResult = await turnPromise;
+    expect(turnResult.success).toBe(true);
+    expect(turnResult.transcript).toBe("final answer");
+
+    const call = manager.getCall(started.callId);
+    expect(call?.transcript.map((entry) => entry.text)).toEqual(["Prompt", "final answer"]);
+  });
+
+  it("tracks latency metadata across multiple closed-loop turns", async () => {
+    const { manager, provider } = await createManagerHarness({
+      transcriptTimeoutMs: 5000,
+    });
+
+    const started = await manager.initiateCall("+15550000005");
+    expect(started.success).toBe(true);
+
+    markCallAnswered(manager, started.callId, "evt-multi-answered");
+
+    const firstTurn = manager.continueCall(started.callId, "First question");
+    await new Promise((resolve) => setTimeout(resolve, 0));
+    manager.processEvent({
+      id: "evt-multi-speech-1",
+      type: "call.speech",
+      callId: started.callId,
+      providerCallId: "request-uuid",
+      timestamp: Date.now(),
+      transcript: "First answer",
+      isFinal: true,
+    });
+    await firstTurn;
+
+    const secondTurn = manager.continueCall(started.callId, "Second question");
+    await new Promise((resolve) => setTimeout(resolve, 0));
+    manager.processEvent({
+      id: "evt-multi-speech-2",
+      type: "call.speech",
+      callId: started.callId,
+      providerCallId: "request-uuid",
+      timestamp: Date.now(),
+      transcript: "Second answer",
+      isFinal: true,
+    });
+    const secondResult = await secondTurn;
+
+    expect(secondResult.success).toBe(true);
+
+    const call = manager.getCall(started.callId);
+    expect(call?.transcript.map((entry) => entry.text)).toEqual([
+      "First question",
+      "First answer",
+      "Second question",
+      "Second answer",
+    ]);
+    const metadata = (call?.metadata ?? {}) as Record<string, unknown>;
+    expect(metadata.turnCount).toBe(2);
+    expect(typeof metadata.lastTurnLatencyMs).toBe("number");
+    expect(typeof metadata.lastTurnListenWaitMs).toBe("number");
+    expect(provider.startListeningCalls).toHaveLength(2);
+    expect(provider.stopListeningCalls).toHaveLength(2);
+  });
+
+  it("handles repeated closed-loop turns without waiter churn", async () => {
+    const { manager, provider } = await createManagerHarness({
+      transcriptTimeoutMs: 5000,
+    });
+
+    const started = await manager.initiateCall("+15550000006");
+    expect(started.success).toBe(true);
+
+    markCallAnswered(manager, started.callId, "evt-loop-answered");
+
+    for (let i = 1; i <= 5; i++) {
+      const turnPromise = manager.continueCall(started.callId, `Prompt ${i}`);
+      await new Promise((resolve) => setTimeout(resolve, 0));
+      manager.processEvent({
+        id: `evt-loop-speech-${i}`,
+        type: "call.speech",
+        callId: started.callId,
+        providerCallId: "request-uuid",
+        timestamp: Date.now(),
+        transcript: `Answer ${i}`,
+        isFinal: true,
+      });
+      const result = await turnPromise;
+      expect(result.success).toBe(true);
+      expect(result.transcript).toBe(`Answer ${i}`);
+    }
+
+    const call = manager.getCall(started.callId);
+    const metadata = (call?.metadata ?? {}) as Record<string, unknown>;
+    expect(metadata.turnCount).toBe(5);
+    expect(provider.startListeningCalls).toHaveLength(5);
+    expect(provider.stopListeningCalls).toHaveLength(5);
+  });
+});

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

@@ -0,0 +1,121 @@
+import { describe, expect, it } from "vitest";
+import { createManagerHarness } from "./manager.test-harness.js";
+
+describe("CallManager inbound allowlist", () => {
+  it("rejects inbound calls with missing caller ID when allowlist enabled", async () => {
+    const { manager, provider } = await createManagerHarness({
+      inboundPolicy: "allowlist",
+      allowFrom: ["+15550001234"],
+    });
+
+    manager.processEvent({
+      id: "evt-allowlist-missing",
+      type: "call.initiated",
+      callId: "call-missing",
+      providerCallId: "provider-missing",
+      timestamp: Date.now(),
+      direction: "inbound",
+      to: "+15550000000",
+    });
+
+    expect(manager.getCallByProviderCallId("provider-missing")).toBeUndefined();
+    expect(provider.hangupCalls).toHaveLength(1);
+    expect(provider.hangupCalls[0]?.providerCallId).toBe("provider-missing");
+  });
+
+  it("rejects inbound calls with anonymous caller ID when allowlist enabled", async () => {
+    const { manager, provider } = await createManagerHarness({
+      inboundPolicy: "allowlist",
+      allowFrom: ["+15550001234"],
+    });
+
+    manager.processEvent({
+      id: "evt-allowlist-anon",
+      type: "call.initiated",
+      callId: "call-anon",
+      providerCallId: "provider-anon",
+      timestamp: Date.now(),
+      direction: "inbound",
+      from: "anonymous",
+      to: "+15550000000",
+    });
+
+    expect(manager.getCallByProviderCallId("provider-anon")).toBeUndefined();
+    expect(provider.hangupCalls).toHaveLength(1);
+    expect(provider.hangupCalls[0]?.providerCallId).toBe("provider-anon");
+  });
+
+  it("rejects inbound calls that only match allowlist suffixes", async () => {
+    const { manager, provider } = await createManagerHarness({
+      inboundPolicy: "allowlist",
+      allowFrom: ["+15550001234"],
+    });
+
+    manager.processEvent({
+      id: "evt-allowlist-suffix",
+      type: "call.initiated",
+      callId: "call-suffix",
+      providerCallId: "provider-suffix",
+      timestamp: Date.now(),
+      direction: "inbound",
+      from: "+99915550001234",
+      to: "+15550000000",
+    });
+
+    expect(manager.getCallByProviderCallId("provider-suffix")).toBeUndefined();
+    expect(provider.hangupCalls).toHaveLength(1);
+    expect(provider.hangupCalls[0]?.providerCallId).toBe("provider-suffix");
+  });
+
+  it("rejects duplicate inbound events with a single hangup call", async () => {
+    const { manager, provider } = await createManagerHarness({
+      inboundPolicy: "disabled",
+    });
+
+    manager.processEvent({
+      id: "evt-reject-init",
+      type: "call.initiated",
+      callId: "provider-dup",
+      providerCallId: "provider-dup",
+      timestamp: Date.now(),
+      direction: "inbound",
+      from: "+15552222222",
+      to: "+15550000000",
+    });
+
+    manager.processEvent({
+      id: "evt-reject-ring",
+      type: "call.ringing",
+      callId: "provider-dup",
+      providerCallId: "provider-dup",
+      timestamp: Date.now(),
+      direction: "inbound",
+      from: "+15552222222",
+      to: "+15550000000",
+    });
+
+    expect(manager.getCallByProviderCallId("provider-dup")).toBeUndefined();
+    expect(provider.hangupCalls).toHaveLength(1);
+    expect(provider.hangupCalls[0]?.providerCallId).toBe("provider-dup");
+  });
+
+  it("accepts inbound calls that exactly match the allowlist", async () => {
+    const { manager } = await createManagerHarness({
+      inboundPolicy: "allowlist",
+      allowFrom: ["+15550001234"],
+    });
+
+    manager.processEvent({
+      id: "evt-allowlist-exact",
+      type: "call.initiated",
+      callId: "call-exact",
+      providerCallId: "provider-exact",
+      timestamp: Date.now(),
+      direction: "inbound",
+      from: "+15550001234",
+      to: "+15550000000",
+    });
+
+    expect(manager.getCallByProviderCallId("provider-exact")).toBeDefined();
+  });
+});