@openclaw/voice-call 2026.1.29

package/src/tunnel.ts

@@ -0,0 +1,331 @@
+import { spawn } from "node:child_process";
+
+import { getTailscaleDnsName } from "./webhook.js";
+
+/**
+ * Tunnel configuration for exposing the webhook server.
+ */
+export interface TunnelConfig {
+  /** Tunnel provider: ngrok, tailscale-serve, or tailscale-funnel */
+  provider: "ngrok" | "tailscale-serve" | "tailscale-funnel" | "none";
+  /** Local port to tunnel */
+  port: number;
+  /** Path prefix for the tunnel (e.g., /voice/webhook) */
+  path: string;
+  /** ngrok auth token (optional, enables longer sessions) */
+  ngrokAuthToken?: string;
+  /** ngrok custom domain (paid feature) */
+  ngrokDomain?: string;
+}
+
+/**
+ * Result of starting a tunnel.
+ */
+export interface TunnelResult {
+  /** The public URL */
+  publicUrl: string;
+  /** Function to stop the tunnel */
+  stop: () => Promise<void>;
+  /** Tunnel provider name */
+  provider: string;
+}
+
+/**
+ * Start an ngrok tunnel to expose the local webhook server.
+ *
+ * Uses the ngrok CLI which must be installed: https://ngrok.com/download
+ *
+ * @example
+ * const tunnel = await startNgrokTunnel({ port: 3334, path: '/voice/webhook' });
+ * console.log('Public URL:', tunnel.publicUrl);
+ * // Later: await tunnel.stop();
+ */
+export async function startNgrokTunnel(config: {
+  port: number;
+  path: string;
+  authToken?: string;
+  domain?: string;
+}): Promise<TunnelResult> {
+  // Set auth token if provided
+  if (config.authToken) {
+    await runNgrokCommand(["config", "add-authtoken", config.authToken]);
+  }
+
+  // Build ngrok command args
+  const args = [
+    "http",
+    String(config.port),
+    "--log",
+    "stdout",
+    "--log-format",
+    "json",
+  ];
+
+  // Add custom domain if provided (paid ngrok feature)
+  if (config.domain) {
+    args.push("--domain", config.domain);
+  }
+
+  return new Promise((resolve, reject) => {
+    const proc = spawn("ngrok", args, {
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+
+    let resolved = false;
+    let publicUrl: string | null = null;
+    let outputBuffer = "";
+
+    const timeout = setTimeout(() => {
+      if (!resolved) {
+        resolved = true;
+        proc.kill("SIGTERM");
+        reject(new Error("ngrok startup timed out (30s)"));
+      }
+    }, 30000);
+
+    const processLine = (line: string) => {
+      try {
+        const log = JSON.parse(line);
+
+        // ngrok logs the public URL in a 'started tunnel' message
+        if (log.msg === "started tunnel" && log.url) {
+          publicUrl = log.url;
+        }
+
+        // Also check for the URL field directly
+        if (log.addr && log.url && !publicUrl) {
+          publicUrl = log.url;
+        }
+
+        // Check for ready state
+        if (publicUrl && !resolved) {
+          resolved = true;
+          clearTimeout(timeout);
+
+          // Add path to the public URL
+          const fullUrl = publicUrl + config.path;
+
+          console.log(`[voice-call] ngrok tunnel active: ${fullUrl}`);
+
+          resolve({
+            publicUrl: fullUrl,
+            provider: "ngrok",
+            stop: async () => {
+              proc.kill("SIGTERM");
+              await new Promise<void>((res) => {
+                proc.on("close", () => res());
+                setTimeout(res, 2000); // Fallback timeout
+              });
+            },
+          });
+        }
+      } catch {
+        // Not JSON, might be startup message
+      }
+    };
+
+    proc.stdout.on("data", (data: Buffer) => {
+      outputBuffer += data.toString();
+      const lines = outputBuffer.split("\n");
+      outputBuffer = lines.pop() || "";
+
+      for (const line of lines) {
+        if (line.trim()) {
+          processLine(line);
+        }
+      }
+    });
+
+    proc.stderr.on("data", (data: Buffer) => {
+      const msg = data.toString();
+      // Check for common errors
+      if (msg.includes("ERR_NGROK")) {
+        if (!resolved) {
+          resolved = true;
+          clearTimeout(timeout);
+          reject(new Error(`ngrok error: ${msg}`));
+        }
+      }
+    });
+
+    proc.on("error", (err) => {
+      if (!resolved) {
+        resolved = true;
+        clearTimeout(timeout);
+        reject(new Error(`Failed to start ngrok: ${err.message}`));
+      }
+    });
+
+    proc.on("close", (code) => {
+      if (!resolved) {
+        resolved = true;
+        clearTimeout(timeout);
+        reject(new Error(`ngrok exited unexpectedly with code ${code}`));
+      }
+    });
+  });
+}
+
+/**
+ * Run an ngrok command and wait for completion.
+ */
+async function runNgrokCommand(args: string[]): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const proc = spawn("ngrok", args, {
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+
+    let stdout = "";
+    let stderr = "";
+
+    proc.stdout.on("data", (data) => {
+      stdout += data.toString();
+    });
+    proc.stderr.on("data", (data) => {
+      stderr += data.toString();
+    });
+
+    proc.on("close", (code) => {
+      if (code === 0) {
+        resolve(stdout);
+      } else {
+        reject(new Error(`ngrok command failed: ${stderr || stdout}`));
+      }
+    });
+
+    proc.on("error", reject);
+  });
+}
+
+/**
+ * Check if ngrok is installed and available.
+ */
+export async function isNgrokAvailable(): Promise<boolean> {
+  return new Promise((resolve) => {
+    const proc = spawn("ngrok", ["version"], {
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+
+    proc.on("close", (code) => {
+      resolve(code === 0);
+    });
+
+    proc.on("error", () => {
+      resolve(false);
+    });
+  });
+}
+
+/**
+ * Start a Tailscale serve/funnel tunnel.
+ */
+export async function startTailscaleTunnel(config: {
+  mode: "serve" | "funnel";
+  port: number;
+  path: string;
+}): Promise<TunnelResult> {
+  // Get Tailscale DNS name
+  const dnsName = await getTailscaleDnsName();
+  if (!dnsName) {
+    throw new Error("Could not get Tailscale DNS name. Is Tailscale running?");
+  }
+
+  const path = config.path.startsWith("/") ? config.path : `/${config.path}`;
+  const localUrl = `http://127.0.0.1:${config.port}${path}`;
+
+  return new Promise((resolve, reject) => {
+    const proc = spawn(
+      "tailscale",
+      [config.mode, "--bg", "--yes", "--set-path", path, localUrl],
+      { stdio: ["ignore", "pipe", "pipe"] },
+    );
+
+    const timeout = setTimeout(() => {
+      proc.kill("SIGKILL");
+      reject(new Error(`Tailscale ${config.mode} timed out`));
+    }, 10000);
+
+    proc.on("close", (code) => {
+      clearTimeout(timeout);
+      if (code === 0) {
+        const publicUrl = `https://${dnsName}${path}`;
+        console.log(
+          `[voice-call] Tailscale ${config.mode} active: ${publicUrl}`,
+        );
+
+        resolve({
+          publicUrl,
+          provider: `tailscale-${config.mode}`,
+          stop: async () => {
+            await stopTailscaleTunnel(config.mode, path);
+          },
+        });
+      } else {
+        reject(new Error(`Tailscale ${config.mode} failed with code ${code}`));
+      }
+    });
+
+    proc.on("error", (err) => {
+      clearTimeout(timeout);
+      reject(err);
+    });
+  });
+}
+
+/**
+ * Stop a Tailscale serve/funnel tunnel.
+ */
+async function stopTailscaleTunnel(
+  mode: "serve" | "funnel",
+  path: string,
+): Promise<void> {
+  return new Promise((resolve) => {
+    const proc = spawn("tailscale", [mode, "off", path], {
+      stdio: "ignore",
+    });
+
+    const timeout = setTimeout(() => {
+      proc.kill("SIGKILL");
+      resolve();
+    }, 5000);
+
+    proc.on("close", () => {
+      clearTimeout(timeout);
+      resolve();
+    });
+  });
+}
+
+/**
+ * Start a tunnel based on configuration.
+ */
+export async function startTunnel(
+  config: TunnelConfig,
+): Promise<TunnelResult | null> {
+  switch (config.provider) {
+    case "ngrok":
+      return startNgrokTunnel({
+        port: config.port,
+        path: config.path,
+        authToken: config.ngrokAuthToken,
+        domain: config.ngrokDomain,
+      });
+
+    case "tailscale-serve":
+      return startTailscaleTunnel({
+        mode: "serve",
+        port: config.port,
+        path: config.path,
+      });
+
+    case "tailscale-funnel":
+      return startTailscaleTunnel({
+        mode: "funnel",
+        port: config.port,
+        path: config.path,
+      });
+
+    default:
+      return null;
+  }
+}

package/src/types.ts

@@ -0,0 +1,273 @@
+import { z } from "zod";
+
+import type { CallMode } from "./config.js";
+
+// -----------------------------------------------------------------------------
+// Provider Identifiers
+// -----------------------------------------------------------------------------
+
+export const ProviderNameSchema = z.enum(["telnyx", "twilio", "plivo", "mock"]);
+export type ProviderName = z.infer<typeof ProviderNameSchema>;
+
+// -----------------------------------------------------------------------------
+// Core Call Identifiers
+// -----------------------------------------------------------------------------
+
+/** Internal call identifier (UUID) */
+export type CallId = string;
+
+/** Provider-specific call identifier */
+export type ProviderCallId = string;
+
+// -----------------------------------------------------------------------------
+// Call Lifecycle States
+// -----------------------------------------------------------------------------
+
+export const CallStateSchema = z.enum([
+  // Non-terminal states
+  "initiated",
+  "ringing",
+  "answered",
+  "active",
+  "speaking",
+  "listening",
+  // Terminal states
+  "completed",
+  "hangup-user",
+  "hangup-bot",
+  "timeout",
+  "error",
+  "failed",
+  "no-answer",
+  "busy",
+  "voicemail",
+]);
+export type CallState = z.infer<typeof CallStateSchema>;
+
+export const TerminalStates = new Set<CallState>([
+  "completed",
+  "hangup-user",
+  "hangup-bot",
+  "timeout",
+  "error",
+  "failed",
+  "no-answer",
+  "busy",
+  "voicemail",
+]);
+
+export const EndReasonSchema = z.enum([
+  "completed",
+  "hangup-user",
+  "hangup-bot",
+  "timeout",
+  "error",
+  "failed",
+  "no-answer",
+  "busy",
+  "voicemail",
+]);
+export type EndReason = z.infer<typeof EndReasonSchema>;
+
+// -----------------------------------------------------------------------------
+// Normalized Call Events
+// -----------------------------------------------------------------------------
+
+const BaseEventSchema = z.object({
+  id: z.string(),
+  callId: z.string(),
+  providerCallId: z.string().optional(),
+  timestamp: z.number(),
+  // Optional fields for inbound call detection
+  direction: z.enum(["inbound", "outbound"]).optional(),
+  from: z.string().optional(),
+  to: z.string().optional(),
+});
+
+export const NormalizedEventSchema = z.discriminatedUnion("type", [
+  BaseEventSchema.extend({
+    type: z.literal("call.initiated"),
+  }),
+  BaseEventSchema.extend({
+    type: z.literal("call.ringing"),
+  }),
+  BaseEventSchema.extend({
+    type: z.literal("call.answered"),
+  }),
+  BaseEventSchema.extend({
+    type: z.literal("call.active"),
+  }),
+  BaseEventSchema.extend({
+    type: z.literal("call.speaking"),
+    text: z.string(),
+  }),
+  BaseEventSchema.extend({
+    type: z.literal("call.speech"),
+    transcript: z.string(),
+    isFinal: z.boolean(),
+    confidence: z.number().min(0).max(1).optional(),
+  }),
+  BaseEventSchema.extend({
+    type: z.literal("call.silence"),
+    durationMs: z.number(),
+  }),
+  BaseEventSchema.extend({
+    type: z.literal("call.dtmf"),
+    digits: z.string(),
+  }),
+  BaseEventSchema.extend({
+    type: z.literal("call.ended"),
+    reason: EndReasonSchema,
+  }),
+  BaseEventSchema.extend({
+    type: z.literal("call.error"),
+    error: z.string(),
+    retryable: z.boolean().optional(),
+  }),
+]);
+export type NormalizedEvent = z.infer<typeof NormalizedEventSchema>;
+
+// -----------------------------------------------------------------------------
+// Call Direction
+// -----------------------------------------------------------------------------
+
+export const CallDirectionSchema = z.enum(["outbound", "inbound"]);
+export type CallDirection = z.infer<typeof CallDirectionSchema>;
+
+// -----------------------------------------------------------------------------
+// Call Record
+// -----------------------------------------------------------------------------
+
+export const TranscriptEntrySchema = z.object({
+  timestamp: z.number(),
+  speaker: z.enum(["bot", "user"]),
+  text: z.string(),
+  isFinal: z.boolean().default(true),
+});
+export type TranscriptEntry = z.infer<typeof TranscriptEntrySchema>;
+
+export const CallRecordSchema = z.object({
+  callId: z.string(),
+  providerCallId: z.string().optional(),
+  provider: ProviderNameSchema,
+  direction: CallDirectionSchema,
+  state: CallStateSchema,
+  from: z.string(),
+  to: z.string(),
+  sessionKey: z.string().optional(),
+  startedAt: z.number(),
+  answeredAt: z.number().optional(),
+  endedAt: z.number().optional(),
+  endReason: EndReasonSchema.optional(),
+  transcript: z.array(TranscriptEntrySchema).default([]),
+  processedEventIds: z.array(z.string()).default([]),
+  metadata: z.record(z.string(), z.unknown()).optional(),
+});
+export type CallRecord = z.infer<typeof CallRecordSchema>;
+
+// -----------------------------------------------------------------------------
+// Webhook Types
+// -----------------------------------------------------------------------------
+
+export type WebhookVerificationResult = {
+  ok: boolean;
+  reason?: string;
+};
+
+export type WebhookContext = {
+  headers: Record<string, string | string[] | undefined>;
+  rawBody: string;
+  url: string;
+  method: "GET" | "POST" | "PUT" | "DELETE" | "PATCH";
+  query?: Record<string, string | string[] | undefined>;
+  remoteAddress?: string;
+};
+
+export type ProviderWebhookParseResult = {
+  events: NormalizedEvent[];
+  providerResponseBody?: string;
+  providerResponseHeaders?: Record<string, string>;
+  statusCode?: number;
+};
+
+// -----------------------------------------------------------------------------
+// Provider Method Types
+// -----------------------------------------------------------------------------
+
+export type InitiateCallInput = {
+  callId: CallId;
+  from: string;
+  to: string;
+  webhookUrl: string;
+  clientState?: Record<string, string>;
+  /** Inline TwiML to execute (skips webhook, used for notify mode) */
+  inlineTwiml?: string;
+};
+
+export type InitiateCallResult = {
+  providerCallId: ProviderCallId;
+  status: "initiated" | "queued";
+};
+
+export type HangupCallInput = {
+  callId: CallId;
+  providerCallId: ProviderCallId;
+  reason: EndReason;
+};
+
+export type PlayTtsInput = {
+  callId: CallId;
+  providerCallId: ProviderCallId;
+  text: string;
+  voice?: string;
+  locale?: string;
+};
+
+export type StartListeningInput = {
+  callId: CallId;
+  providerCallId: ProviderCallId;
+  language?: string;
+};
+
+export type StopListeningInput = {
+  callId: CallId;
+  providerCallId: ProviderCallId;
+};
+
+// -----------------------------------------------------------------------------
+// Outbound Call Options
+// -----------------------------------------------------------------------------
+
+export type OutboundCallOptions = {
+  /** Message to speak when call connects */
+  message?: string;
+  /** Call mode (overrides config default) */
+  mode?: CallMode;
+};
+
+// -----------------------------------------------------------------------------
+// Tool Result Types
+// -----------------------------------------------------------------------------
+
+export type InitiateCallToolResult = {
+  success: boolean;
+  callId?: string;
+  status?: "initiated" | "queued" | "no-answer" | "busy" | "failed";
+  error?: string;
+};
+
+export type ContinueCallToolResult = {
+  success: boolean;
+  transcript?: string;
+  error?: string;
+};
+
+export type SpeakToUserToolResult = {
+  success: boolean;
+  error?: string;
+};
+
+export type EndCallToolResult = {
+  success: boolean;
+  error?: string;
+};

package/src/utils.ts

@@ -0,0 +1,12 @@
+import os from "node:os";
+import path from "node:path";
+
+export function resolveUserPath(input: string): string {
+  const trimmed = input.trim();
+  if (!trimmed) return trimmed;
+  if (trimmed.startsWith("~")) {
+    const expanded = trimmed.replace(/^~(?=$|[\\/])/, os.homedir());
+    return path.resolve(expanded);
+  }
+  return path.resolve(trimmed);
+}

package/src/voice-mapping.ts

@@ -0,0 +1,65 @@
+/**
+ * Voice mapping and XML utilities for voice call providers.
+ */
+
+/**
+ * Escape XML special characters for TwiML and other XML responses.
+ */
+export function escapeXml(text: string): string {
+  return text
+    .replace(/&/g, "&")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&apos;");
+}
+
+/**
+ * Map of OpenAI voice names to similar Twilio Polly voices.
+ */
+const OPENAI_TO_POLLY_MAP: Record<string, string> = {
+  alloy: "Polly.Joanna", // neutral, warm
+  echo: "Polly.Matthew", // male, warm
+  fable: "Polly.Amy", // British, expressive
+  onyx: "Polly.Brian", // deep male
+  nova: "Polly.Salli", // female, friendly
+  shimmer: "Polly.Kimberly", // female, clear
+};
+
+/**
+ * Default Polly voice when no mapping is found.
+ */
+export const DEFAULT_POLLY_VOICE = "Polly.Joanna";
+
+/**
+ * Map OpenAI voice names to Twilio Polly equivalents.
+ * Falls through if already a valid Polly/Google voice.
+ *
+ * @param voice - OpenAI voice name (alloy, echo, etc.) or Polly voice name
+ * @returns Polly voice name suitable for Twilio TwiML
+ */
+export function mapVoiceToPolly(voice: string | undefined): string {
+  if (!voice) return DEFAULT_POLLY_VOICE;
+
+  // Already a Polly/Google voice - pass through
+  if (voice.startsWith("Polly.") || voice.startsWith("Google.")) {
+    return voice;
+  }
+
+  // Map OpenAI voices to Polly equivalents
+  return OPENAI_TO_POLLY_MAP[voice.toLowerCase()] || DEFAULT_POLLY_VOICE;
+}
+
+/**
+ * Check if a voice name is a known OpenAI voice.
+ */
+export function isOpenAiVoice(voice: string): boolean {
+  return voice.toLowerCase() in OPENAI_TO_POLLY_MAP;
+}
+
+/**
+ * Get all supported OpenAI voice names.
+ */
+export function getOpenAiVoiceNames(): string[] {
+  return Object.keys(OPENAI_TO_POLLY_MAP);
+}