@openclaw/voice-call 2026.3.1 → 2026.3.2

package/src/runtime.ts

@@ -10,11 +10,8 @@ import { TwilioProvider } from "./providers/twilio.js";
 import type { TelephonyTtsRuntime } from "./telephony-tts.js";
 import { createTelephonyTtsProvider } from "./telephony-tts.js";
 import { startTunnel, type TunnelResult } from "./tunnel.js";
-import {
-  cleanupTailscaleExposure,
-  setupTailscaleExposure,
-  VoiceCallWebhookServer,
-} from "./webhook.js";
+import { VoiceCallWebhookServer } from "./webhook.js";
+import { cleanupTailscaleExposure, setupTailscaleExposure } from "./webhook/tailscale.js";
 
 export type VoiceCallRuntime = {
   config: VoiceCallConfig;
@@ -33,6 +30,49 @@ type Logger = {
   debug?: (message: string) => void;
 };
 
+function createRuntimeResourceLifecycle(params: {
+  config: VoiceCallConfig;
+  webhookServer: VoiceCallWebhookServer;
+}): {
+  setTunnelResult: (result: TunnelResult | null) => void;
+  stop: (opts?: { suppressErrors?: boolean }) => Promise<void>;
+} {
+  let tunnelResult: TunnelResult | null = null;
+  let stopped = false;
+
+  const runStep = async (step: () => Promise<void>, suppressErrors: boolean) => {
+    if (suppressErrors) {
+      await step().catch(() => {});
+      return;
+    }
+    await step();
+  };
+
+  return {
+    setTunnelResult: (result) => {
+      tunnelResult = result;
+    },
+    stop: async (opts) => {
+      if (stopped) {
+        return;
+      }
+      stopped = true;
+      const suppressErrors = opts?.suppressErrors ?? false;
+      await runStep(async () => {
+        if (tunnelResult) {
+          await tunnelResult.stop();
+        }
+      }, suppressErrors);
+      await runStep(async () => {
+        await cleanupTailscaleExposure(params.config);
+      }, suppressErrors);
+      await runStep(async () => {
+        await params.webhookServer.stop();
+      }, suppressErrors);
+    },
+  };
+}
+
 function isLoopbackBind(bind: string | undefined): boolean {
   if (!bind) {
     return false;
@@ -126,92 +166,99 @@ export async function createVoiceCallRuntime(params: {
   const provider = resolveProvider(config);
   const manager = new CallManager(config);
   const webhookServer = new VoiceCallWebhookServer(config, manager, provider, coreConfig);
+  const lifecycle = createRuntimeResourceLifecycle({ config, webhookServer });
 
   const localUrl = await webhookServer.start();
 
-  // Determine public URL - priority: config.publicUrl > tunnel > legacy tailscale
-  let publicUrl: string | null = config.publicUrl ?? null;
-  let tunnelResult: TunnelResult | null = null;
-
-  if (!publicUrl && config.tunnel?.provider && config.tunnel.provider !== "none") {
-    try {
-      tunnelResult = await startTunnel({
-        provider: config.tunnel.provider,
-        port: config.serve.port,
-        path: config.serve.path,
-        ngrokAuthToken: config.tunnel.ngrokAuthToken,
-        ngrokDomain: config.tunnel.ngrokDomain,
-      });
-      publicUrl = tunnelResult?.publicUrl ?? null;
-    } catch (err) {
-      log.error(
-        `[voice-call] Tunnel setup failed: ${err instanceof Error ? err.message : String(err)}`,
-      );
-    }
-  }
-
-  if (!publicUrl && config.tailscale?.mode !== "off") {
-    publicUrl = await setupTailscaleExposure(config);
-  }
-
-  const webhookUrl = publicUrl ?? localUrl;
+  // Wrap remaining initialization in try/catch so the webhook server is
+  // properly stopped if any subsequent step fails.  Without this, the server
+  // keeps the port bound while the runtime promise rejects, causing
+  // EADDRINUSE on the next attempt.  See: #32387
+  try {
+    // Determine public URL - priority: config.publicUrl > tunnel > legacy tailscale
+    let publicUrl: string | null = config.publicUrl ?? null;
 
-  if (publicUrl && provider.name === "twilio") {
-    (provider as TwilioProvider).setPublicUrl(publicUrl);
-  }
-
-  if (provider.name === "twilio" && config.streaming?.enabled) {
-    const twilioProvider = provider as TwilioProvider;
-    if (ttsRuntime?.textToSpeechTelephony) {
+    if (!publicUrl && config.tunnel?.provider && config.tunnel.provider !== "none") {
       try {
-        const ttsProvider = createTelephonyTtsProvider({
-          coreConfig,
-          ttsOverride: config.tts,
-          runtime: ttsRuntime,
+        const nextTunnelResult = await startTunnel({
+          provider: config.tunnel.provider,
+          port: config.serve.port,
+          path: config.serve.path,
+          ngrokAuthToken: config.tunnel.ngrokAuthToken,
+          ngrokDomain: config.tunnel.ngrokDomain,
         });
-        twilioProvider.setTTSProvider(ttsProvider);
-        log.info("[voice-call] Telephony TTS provider configured");
+        lifecycle.setTunnelResult(nextTunnelResult);
+        publicUrl = nextTunnelResult?.publicUrl ?? null;
       } catch (err) {
-        log.warn(
-          `[voice-call] Failed to initialize telephony TTS: ${
-            err instanceof Error ? err.message : String(err)
-          }`,
+        log.error(
+          `[voice-call] Tunnel setup failed: ${err instanceof Error ? err.message : String(err)}`,
         );
       }
-    } else {
-      log.warn("[voice-call] Telephony TTS unavailable; streaming TTS disabled");
     }
 
-    const mediaHandler = webhookServer.getMediaStreamHandler();
-    if (mediaHandler) {
-      twilioProvider.setMediaStreamHandler(mediaHandler);
-      log.info("[voice-call] Media stream handler wired to provider");
+    if (!publicUrl && config.tailscale?.mode !== "off") {
+      publicUrl = await setupTailscaleExposure(config);
     }
-  }
 
-  manager.initialize(provider, webhookUrl);
+    const webhookUrl = publicUrl ?? localUrl;
 
-  const stop = async () => {
-    if (tunnelResult) {
-      await tunnelResult.stop();
+    if (publicUrl && provider.name === "twilio") {
+      (provider as TwilioProvider).setPublicUrl(publicUrl);
     }
-    await cleanupTailscaleExposure(config);
-    await webhookServer.stop();
-  };
 
-  log.info("[voice-call] Runtime initialized");
-  log.info(`[voice-call] Webhook URL: ${webhookUrl}`);
-  if (publicUrl) {
-    log.info(`[voice-call] Public URL: ${publicUrl}`);
-  }
+    if (provider.name === "twilio" && config.streaming?.enabled) {
+      const twilioProvider = provider as TwilioProvider;
+      if (ttsRuntime?.textToSpeechTelephony) {
+        try {
+          const ttsProvider = createTelephonyTtsProvider({
+            coreConfig,
+            ttsOverride: config.tts,
+            runtime: ttsRuntime,
+          });
+          twilioProvider.setTTSProvider(ttsProvider);
+          log.info("[voice-call] Telephony TTS provider configured");
+        } catch (err) {
+          log.warn(
+            `[voice-call] Failed to initialize telephony TTS: ${
+              err instanceof Error ? err.message : String(err)
+            }`,
+          );
+        }
+      } else {
+        log.warn("[voice-call] Telephony TTS unavailable; streaming TTS disabled");
+      }
 
-  return {
-    config,
-    provider,
-    manager,
-    webhookServer,
-    webhookUrl,
-    publicUrl,
-    stop,
-  };
+      const mediaHandler = webhookServer.getMediaStreamHandler();
+      if (mediaHandler) {
+        twilioProvider.setMediaStreamHandler(mediaHandler);
+        log.info("[voice-call] Media stream handler wired to provider");
+      }
+    }
+
+    await manager.initialize(provider, webhookUrl);
+
+    const stop = async () => await lifecycle.stop();
+
+    log.info("[voice-call] Runtime initialized");
+    log.info(`[voice-call] Webhook URL: ${webhookUrl}`);
+    if (publicUrl) {
+      log.info(`[voice-call] Public URL: ${publicUrl}`);
+    }
+
+    return {
+      config,
+      provider,
+      manager,
+      webhookServer,
+      webhookUrl,
+      publicUrl,
+      stop,
+    };
+  } catch (err) {
+    // If any step after the server started fails, clean up every provisioned
+    // resource (tunnel, tailscale exposure, and webhook server) so retries
+    // don't leak processes or keep the port bound.
+    await lifecycle.stop({ suppressErrors: true });
+    throw err;
+  }
 }

package/src/tunnel.ts

@@ -1,5 +1,5 @@
 import { spawn } from "node:child_process";
-import { getTailscaleDnsName } from "./webhook.js";
+import { getTailscaleDnsName } from "./webhook/tailscale.js";
 
 /**
  * Tunnel configuration for exposing the webhook server.

package/src/types.ts

@@ -248,6 +248,23 @@ export type StopListeningInput = {
   providerCallId: ProviderCallId;
 };
 
+// -----------------------------------------------------------------------------
+// Call Status Verification (used on restart to verify persisted calls)
+// -----------------------------------------------------------------------------
+
+export type GetCallStatusInput = {
+  providerCallId: ProviderCallId;
+};
+
+export type GetCallStatusResult = {
+  /** Provider-specific status string (e.g. "completed", "in-progress") */
+  status: string;
+  /** True when the provider confirms the call has ended */
+  isTerminal: boolean;
+  /** True when the status could not be determined (transient error) */
+  isUnknown?: boolean;
+};
+
 // -----------------------------------------------------------------------------
 // Outbound Call Options
 // -----------------------------------------------------------------------------

package/src/webhook/tailscale.ts

@@ -0,0 +1,115 @@
+import { spawn } from "node:child_process";
+import type { VoiceCallConfig } from "../config.js";
+
+export type TailscaleSelfInfo = {
+  dnsName: string | null;
+  nodeId: string | null;
+};
+
+function runTailscaleCommand(
+  args: string[],
+  timeoutMs = 2500,
+): Promise<{ code: number; stdout: string }> {
+  return new Promise((resolve) => {
+    const proc = spawn("tailscale", args, {
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+
+    let stdout = "";
+    proc.stdout.on("data", (data) => {
+      stdout += data;
+    });
+
+    const timer = setTimeout(() => {
+      proc.kill("SIGKILL");
+      resolve({ code: -1, stdout: "" });
+    }, timeoutMs);
+
+    proc.on("close", (code) => {
+      clearTimeout(timer);
+      resolve({ code: code ?? -1, stdout });
+    });
+  });
+}
+
+export async function getTailscaleSelfInfo(): Promise<TailscaleSelfInfo | null> {
+  const { code, stdout } = await runTailscaleCommand(["status", "--json"]);
+  if (code !== 0) {
+    return null;
+  }
+
+  try {
+    const status = JSON.parse(stdout);
+    return {
+      dnsName: status.Self?.DNSName?.replace(/\.$/, "") || null,
+      nodeId: status.Self?.ID || null,
+    };
+  } catch {
+    return null;
+  }
+}
+
+export async function getTailscaleDnsName(): Promise<string | null> {
+  const info = await getTailscaleSelfInfo();
+  return info?.dnsName ?? null;
+}
+
+export async function setupTailscaleExposureRoute(opts: {
+  mode: "serve" | "funnel";
+  path: string;
+  localUrl: string;
+}): Promise<string | null> {
+  const dnsName = await getTailscaleDnsName();
+  if (!dnsName) {
+    console.warn("[voice-call] Could not get Tailscale DNS name");
+    return null;
+  }
+
+  const { code } = await runTailscaleCommand([
+    opts.mode,
+    "--bg",
+    "--yes",
+    "--set-path",
+    opts.path,
+    opts.localUrl,
+  ]);
+
+  if (code === 0) {
+    const publicUrl = `https://${dnsName}${opts.path}`;
+    console.log(`[voice-call] Tailscale ${opts.mode} active: ${publicUrl}`);
+    return publicUrl;
+  }
+
+  console.warn(`[voice-call] Tailscale ${opts.mode} failed`);
+  return null;
+}
+
+export async function cleanupTailscaleExposureRoute(opts: {
+  mode: "serve" | "funnel";
+  path: string;
+}): Promise<void> {
+  await runTailscaleCommand([opts.mode, "off", opts.path]);
+}
+
+export async function setupTailscaleExposure(config: VoiceCallConfig): Promise<string | null> {
+  if (config.tailscale.mode === "off") {
+    return null;
+  }
+
+  const mode = config.tailscale.mode === "funnel" ? "funnel" : "serve";
+  const localUrl = `http://127.0.0.1:${config.serve.port}${config.serve.path}`;
+  return setupTailscaleExposureRoute({
+    mode,
+    path: config.tailscale.path,
+    localUrl,
+  });
+}
+
+export async function cleanupTailscaleExposure(config: VoiceCallConfig): Promise<void> {
+  if (config.tailscale.mode === "off") {
+    return;
+  }
+
+  const mode = config.tailscale.mode === "funnel" ? "funnel" : "serve";
+  await cleanupTailscaleExposureRoute({ mode, path: config.tailscale.path });
+}

package/src/webhook-security.test.ts

@@ -86,6 +86,18 @@ function twilioSignature(params: { authToken: string; url: string; postBody: str
   return crypto.createHmac("sha1", params.authToken).update(dataToSign).digest("base64");
 }
 
+function expectReplayResultPair(
+  first: { ok: boolean; isReplay?: boolean; verifiedRequestKey?: string },
+  second: { ok: boolean; isReplay?: boolean; verifiedRequestKey?: string },
+) {
+  expect(first.ok).toBe(true);
+  expect(first.isReplay).toBeFalsy();
+  expect(first.verifiedRequestKey).toBeTruthy();
+  expect(second.ok).toBe(true);
+  expect(second.isReplay).toBe(true);
+  expect(second.verifiedRequestKey).toBe(first.verifiedRequestKey);
+}
+
 describe("verifyPlivoWebhook", () => {
   it("accepts valid V2 signature", () => {
     const authToken = "test-auth-token";
@@ -196,12 +208,7 @@ describe("verifyPlivoWebhook", () => {
     const first = verifyPlivoWebhook(ctx, authToken);
     const second = verifyPlivoWebhook(ctx, authToken);
 
-    expect(first.ok).toBe(true);
-    expect(first.isReplay).toBeFalsy();
-    expect(first.verifiedRequestKey).toBeTruthy();
-    expect(second.ok).toBe(true);
-    expect(second.isReplay).toBe(true);
-    expect(second.verifiedRequestKey).toBe(first.verifiedRequestKey);
+    expectReplayResultPair(first, second);
   });
 
   it("returns a stable request key when verification is skipped", () => {
@@ -245,12 +252,7 @@ describe("verifyTelnyxWebhook", () => {
     const first = verifyTelnyxWebhook(ctx, pemPublicKey);
     const second = verifyTelnyxWebhook(ctx, pemPublicKey);
 
-    expect(first.ok).toBe(true);
-    expect(first.isReplay).toBeFalsy();
-    expect(first.verifiedRequestKey).toBeTruthy();
-    expect(second.ok).toBe(true);
-    expect(second.isReplay).toBe(true);
-    expect(second.verifiedRequestKey).toBe(first.verifiedRequestKey);
+    expectReplayResultPair(first, second);
   });
 
   it("returns a stable request key when verification is skipped", () => {
@@ -603,7 +605,6 @@ describe("verifyTwilioWebhook", () => {
     expect(result.ok).toBe(false);
     expect(result.verificationUrl).toBe("https://legitimate.example.com/voice/webhook");
   });
-
   it("returns a stable request key when verification is skipped", () => {
     const ctx = {
       headers: {},
@@ -619,4 +620,32 @@ describe("verifyTwilioWebhook", () => {
     expect(second.verifiedRequestKey).toBe(first.verifiedRequestKey);
     expect(second.isReplay).toBe(true);
   });
+
+  it("succeeds when Twilio signs URL without port but server URL has port", () => {
+    const authToken = "test-auth-token";
+    const postBody = "CallSid=CS123&CallStatus=completed&From=%2B15550000000";
+    // Twilio signs using URL without port.
+    const urlWithPort = "https://example.com:8443/voice/webhook";
+    const signedUrl = "https://example.com/voice/webhook";
+
+    const signature = twilioSignature({ authToken, url: signedUrl, postBody });
+
+    const result = verifyTwilioWebhook(
+      {
+        headers: {
+          host: "example.com:8443",
+          "x-twilio-signature": signature,
+        },
+        rawBody: postBody,
+        url: urlWithPort,
+        method: "POST",
+      },
+      authToken,
+      { publicUrl: urlWithPort },
+    );
+
+    expect(result.ok).toBe(true);
+    expect(result.verificationUrl).toBe(signedUrl);
+    expect(result.verifiedRequestKey).toMatch(/^twilio:req:/);
+  });
 });

package/src/webhook-security.ts

@@ -379,6 +379,41 @@ function isLoopbackAddress(address?: string): boolean {
   return false;
 }
 
+function stripPortFromUrl(url: string): string {
+  try {
+    const parsed = new URL(url);
+    if (!parsed.port) {
+      return url;
+    }
+    parsed.port = "";
+    return parsed.toString();
+  } catch {
+    return url;
+  }
+}
+
+function setPortOnUrl(url: string, port: string): string {
+  try {
+    const parsed = new URL(url);
+    parsed.port = port;
+    return parsed.toString();
+  } catch {
+    return url;
+  }
+}
+
+function extractPortFromHostHeader(hostHeader?: string): string | undefined {
+  if (!hostHeader) {
+    return undefined;
+  }
+  try {
+    const parsed = new URL(`https://${hostHeader}`);
+    return parsed.port || undefined;
+  } catch {
+    return undefined;
+  }
+}
+
 /**
  * Result of Twilio webhook verification with detailed info.
  */
@@ -609,6 +644,45 @@ export function verifyTwilioWebhook(
     return { ok: true, verificationUrl, isReplay, verifiedRequestKey: replayKey };
   }
 
+  // Twilio webhook signatures can differ in whether port is included.
+  // Retry a small, deterministic set of URL variants before failing closed.
+  const variants = new Set<string>();
+  variants.add(verificationUrl);
+  variants.add(stripPortFromUrl(verificationUrl));
+
+  if (options?.publicUrl) {
+    try {
+      const publicPort = new URL(options.publicUrl).port;
+      if (publicPort) {
+        variants.add(setPortOnUrl(verificationUrl, publicPort));
+      }
+    } catch {
+      // ignore invalid publicUrl; primary verification already used best effort
+    }
+  }
+
+  const hostHeaderPort = extractPortFromHostHeader(getHeader(ctx.headers, "host"));
+  if (hostHeaderPort) {
+    variants.add(setPortOnUrl(verificationUrl, hostHeaderPort));
+  }
+
+  for (const candidateUrl of variants) {
+    if (candidateUrl === verificationUrl) {
+      continue;
+    }
+    const isValidCandidate = validateTwilioSignature(authToken, signature, candidateUrl, params);
+    if (!isValidCandidate) {
+      continue;
+    }
+    const replayKey = createTwilioReplayKey({
+      verificationUrl: candidateUrl,
+      signature,
+      requestParams: params,
+    });
+    const isReplay = markReplay(twilioReplayCache, replayKey);
+    return { ok: true, verificationUrl: candidateUrl, isReplay, verifiedRequestKey: replayKey };
+  }
+
   // Check if this is ngrok free tier - the URL might have different format
   const isNgrokFreeTier =
     verificationUrl.includes(".ngrok-free.app") || verificationUrl.includes(".ngrok.io");