@openclaw/voice-call 2026.3.13 → 2026.5.1-beta.1

package/src/webhook.types.ts

@@ -0,0 +1,5 @@
+export type WebhookResponsePayload = {
+  statusCode: number;
+  body: string;
+  headers?: Record<string, string>;
+};

package/src/websocket-test-support.ts

@@ -0,0 +1,72 @@
+import { once } from "node:events";
+import http from "node:http";
+import { WebSocket } from "ws";
+
+export const withTimeout = async <T>(promise: Promise<T>, timeoutMs = 2000): Promise<T> => {
+  let timer: ReturnType<typeof setTimeout> | null = null;
+  const timeout = new Promise<never>((_, reject) => {
+    timer = setTimeout(() => reject(new Error(`Timed out after ${timeoutMs}ms`)), timeoutMs);
+  });
+
+  try {
+    return await Promise.race([promise, timeout]);
+  } finally {
+    if (timer) {
+      clearTimeout(timer);
+    }
+  }
+};
+
+export const startUpgradeWsServer = async (params: {
+  urlPath: string;
+  onUpgrade: (
+    request: http.IncomingMessage,
+    socket: Parameters<http.Server["emit"]>[2],
+    head: Buffer,
+  ) => void;
+}): Promise<{
+  url: string;
+  close: () => Promise<void>;
+}> => {
+  const server = http.createServer();
+  server.on("upgrade", (request, socket, head) => {
+    params.onUpgrade(request, socket, head);
+  });
+
+  await new Promise<void>((resolve) => {
+    server.listen(0, "127.0.0.1", resolve);
+  });
+
+  const address = server.address();
+  if (!address || typeof address === "string") {
+    throw new Error("Failed to resolve test server address");
+  }
+
+  return {
+    url: `ws://127.0.0.1:${address.port}${params.urlPath}`,
+    close: async () => {
+      await new Promise<void>((resolve, reject) => {
+        server.close((err) => (err ? reject(err) : resolve()));
+      });
+    },
+  };
+};
+
+export const connectWs = async (url: string): Promise<WebSocket> => {
+  const ws = new WebSocket(url);
+  await withTimeout(once(ws, "open") as Promise<[unknown]>);
+  return ws;
+};
+
+export const waitForClose = async (
+  ws: WebSocket,
+): Promise<{
+  code: number;
+  reason: string;
+}> => {
+  const [code, reason] = (await withTimeout(once(ws, "close") as Promise<[number, Buffer]>)) ?? [];
+  return {
+    code,
+    reason: Buffer.isBuffer(reason) ? reason.toString("utf8") : String(reason || ""),
+  };
+};

package/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "extends": "../tsconfig.package-boundary.base.json",
+  "compilerOptions": {
+    "rootDir": "."
+  },
+  "include": ["./*.ts", "./src/**/*.ts"],
+  "exclude": [
+    "./**/*.test.ts",
+    "./dist/**",
+    "./node_modules/**",
+    "./src/test-support/**",
+    "./src/**/*test-helpers.ts",
+    "./src/**/*test-harness.ts",
+    "./src/**/*test-support.ts"
+  ]
+}

package/CHANGELOG.md

@@ -1,121 +0,0 @@
-# Changelog
-
-## 2026.3.13
-
-### Changes
-
-- Version alignment with core OpenClaw release numbers.
-
-## 2026.3.12
-
-### Changes
-
-- Version alignment with core OpenClaw release numbers.
-
-## 2026.3.11
-
-### Changes
-
-- Version alignment with core OpenClaw release numbers.
-
-## 2026.3.10
-
-### Changes
-
-- Version alignment with core OpenClaw release numbers.
-
-## 2026.3.9
-
-### Changes
-
-- Version alignment with core OpenClaw release numbers.
-
-## 2026.3.8-beta.1
-
-### Changes
-
-- Version alignment with core OpenClaw release numbers.
-
-## 2026.3.8
-
-### Changes
-
-- Version alignment with core OpenClaw release numbers.
-
-## 2026.3.7
-
-### Changes
-
-- Version alignment with core OpenClaw release numbers.
-
-## 2026.3.3
-
-### Changes
-
-- Version alignment with core OpenClaw release numbers.
-
-## 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
-
-- Version alignment with core OpenClaw release numbers.
-
-## 2026.2.24
-
-### Changes
-
-- Version alignment with core OpenClaw release numbers.
-
-## 2026.2.22
-
-### Changes
-
-- Version alignment with core OpenClaw release numbers.
-
-## 2026.1.26
-
-### Changes
-
-- Breaking: voice-call TTS now uses core `messages.tts` (plugin TTS config deep‑merges with core).
-- Telephony TTS supports OpenAI + ElevenLabs; Edge TTS is ignored for calls.
-- Removed legacy `tts.model`/`tts.voice`/`tts.instructions` plugin fields.
-- Ngrok free-tier bypass renamed to `tunnel.allowNgrokFreeTierLoopbackBypass` and gated to loopback + `tunnel.provider="ngrok"`.
-
-## 0.1.0
-
-### Highlights
-
-- First public release of the @openclaw/voice-call plugin.
-
-### Features
-
-- Providers: Twilio (Programmable Voice + Media Streams), Telnyx (Call Control v2), and mock provider for local dev.
-- Call flows: outbound notify vs. conversation modes, configurable auto‑hangup, and multi‑turn continuation.
-- Inbound handling: policy controls (disabled/allowlist/open), allowlist matching, and inbound greeting.
-- Webhooks: built‑in server with configurable bind/port/path plus `publicUrl` override.
-- Exposure helpers: ngrok + Tailscale serve/funnel; dev‑only signature bypass for ngrok free tier.
-- Streaming: OpenAI Realtime STT over media WebSocket with partial + final transcripts.
-- Speech: OpenAI TTS (model/voice/instructions) with Twilio `<Say>` fallback.
-- Tooling: `voice_call` tool actions for initiate/continue/speak/end/status.
-- Gateway RPC: `voicecall.initiate|continue|speak|end|status` (+ legacy `voicecall.start`).
-- CLI: `openclaw voicecall` commands (call/start/continue/speak/end/status/tail/expose).
-- Observability: JSONL call logs and `voicecall tail` for live inspection.
-- Response controls: `responseModel`, `responseSystemPrompt`, and `responseTimeoutMs` for auto‑responses.

package/src/providers/index.ts

@@ -1,10 +0,0 @@
-export type { VoiceCallProvider } from "./base.js";
-export { MockProvider } from "./mock.js";
-export {
-  OpenAIRealtimeSTTProvider,
-  type RealtimeSTTConfig,
-  type RealtimeSTTSession,
-} from "./stt-openai-realtime.js";
-export { TelnyxProvider } from "./telnyx.js";
-export { TwilioProvider } from "./twilio.js";
-export { PlivoProvider } from "./plivo.js";

package/src/providers/stt-openai-realtime.test.ts

@@ -1,42 +0,0 @@
-import { describe, expect, it } from "vitest";
-import type { RealtimeSTTConfig } from "./stt-openai-realtime.js";
-import { OpenAIRealtimeSTTProvider } from "./stt-openai-realtime.js";
-
-type ProviderInternals = {
-  vadThreshold: number;
-  silenceDurationMs: number;
-};
-
-function readProviderInternals(config: RealtimeSTTConfig): ProviderInternals {
-  const provider = new OpenAIRealtimeSTTProvider(config) as unknown as Record<string, unknown>;
-  return {
-    vadThreshold: provider["vadThreshold"] as number,
-    silenceDurationMs: provider["silenceDurationMs"] as number,
-  };
-}
-
-describe("OpenAIRealtimeSTTProvider constructor defaults", () => {
-  it("uses vadThreshold: 0 when explicitly configured (max sensitivity)", () => {
-    const provider = readProviderInternals({
-      apiKey: "sk-test", // pragma: allowlist secret
-      vadThreshold: 0,
-    });
-    expect(provider.vadThreshold).toBe(0);
-  });
-
-  it("uses silenceDurationMs: 0 when explicitly configured", () => {
-    const provider = readProviderInternals({
-      apiKey: "sk-test", // pragma: allowlist secret
-      silenceDurationMs: 0,
-    });
-    expect(provider.silenceDurationMs).toBe(0);
-  });
-
-  it("falls back to defaults when values are undefined", () => {
-    const provider = readProviderInternals({
-      apiKey: "sk-test", // pragma: allowlist secret
-    });
-    expect(provider.vadThreshold).toBe(0.5);
-    expect(provider.silenceDurationMs).toBe(800);
-  });
-});

package/src/providers/stt-openai-realtime.ts

@@ -1,311 +0,0 @@
-/**
- * OpenAI Realtime STT Provider
- *
- * Uses the OpenAI Realtime API for streaming transcription with:
- * - Direct mu-law audio support (no conversion needed)
- * - Built-in server-side VAD for turn detection
- * - Low-latency streaming transcription
- * - Partial transcript callbacks for real-time UI updates
- */
-
-import WebSocket from "ws";
-
-/**
- * Configuration for OpenAI Realtime STT.
- */
-export interface RealtimeSTTConfig {
-  /** OpenAI API key */
-  apiKey: string;
-  /** Model to use (default: gpt-4o-transcribe) */
-  model?: string;
-  /** Silence duration in ms before considering speech ended (default: 800) */
-  silenceDurationMs?: number;
-  /** VAD threshold 0-1 (default: 0.5) */
-  vadThreshold?: number;
-}
-
-/**
- * Session for streaming audio and receiving transcripts.
- */
-export interface RealtimeSTTSession {
-  /** Connect to the transcription service */
-  connect(): Promise<void>;
-  /** Send mu-law audio data (8kHz mono) */
-  sendAudio(audio: Buffer): void;
-  /** Wait for next complete transcript (after VAD detects end of speech) */
-  waitForTranscript(timeoutMs?: number): Promise<string>;
-  /** Set callback for partial transcripts (streaming) */
-  onPartial(callback: (partial: string) => void): void;
-  /** Set callback for final transcripts */
-  onTranscript(callback: (transcript: string) => void): void;
-  /** Set callback when speech starts (VAD) */
-  onSpeechStart(callback: () => void): void;
-  /** Close the session */
-  close(): void;
-  /** Check if session is connected */
-  isConnected(): boolean;
-}
-
-/**
- * Provider factory for OpenAI Realtime STT sessions.
- */
-export class OpenAIRealtimeSTTProvider {
-  readonly name = "openai-realtime";
-  private apiKey: string;
-  private model: string;
-  private silenceDurationMs: number;
-  private vadThreshold: number;
-
-  constructor(config: RealtimeSTTConfig) {
-    if (!config.apiKey) {
-      throw new Error("OpenAI API key required for Realtime STT");
-    }
-    this.apiKey = config.apiKey;
-    this.model = config.model || "gpt-4o-transcribe";
-    this.silenceDurationMs = config.silenceDurationMs ?? 800;
-    this.vadThreshold = config.vadThreshold ?? 0.5;
-  }
-
-  /**
-   * Create a new realtime transcription session.
-   */
-  createSession(): RealtimeSTTSession {
-    return new OpenAIRealtimeSTTSession(
-      this.apiKey,
-      this.model,
-      this.silenceDurationMs,
-      this.vadThreshold,
-    );
-  }
-}
-
-/**
- * WebSocket-based session for real-time speech-to-text.
- */
-class OpenAIRealtimeSTTSession implements RealtimeSTTSession {
-  private static readonly MAX_RECONNECT_ATTEMPTS = 5;
-  private static readonly RECONNECT_DELAY_MS = 1000;
-
-  private ws: WebSocket | null = null;
-  private connected = false;
-  private closed = false;
-  private reconnectAttempts = 0;
-  private pendingTranscript = "";
-  private onTranscriptCallback: ((transcript: string) => void) | null = null;
-  private onPartialCallback: ((partial: string) => void) | null = null;
-  private onSpeechStartCallback: (() => void) | null = null;
-
-  constructor(
-    private readonly apiKey: string,
-    private readonly model: string,
-    private readonly silenceDurationMs: number,
-    private readonly vadThreshold: number,
-  ) {}
-
-  async connect(): Promise<void> {
-    this.closed = false;
-    this.reconnectAttempts = 0;
-    return this.doConnect();
-  }
-
-  private async doConnect(): Promise<void> {
-    return new Promise((resolve, reject) => {
-      const url = "wss://api.openai.com/v1/realtime?intent=transcription";
-
-      this.ws = new WebSocket(url, {
-        headers: {
-          Authorization: `Bearer ${this.apiKey}`,
-          "OpenAI-Beta": "realtime=v1",
-        },
-      });
-
-      this.ws.on("open", () => {
-        console.log("[RealtimeSTT] WebSocket connected");
-        this.connected = true;
-        this.reconnectAttempts = 0;
-
-        // Configure the transcription session
-        this.sendEvent({
-          type: "transcription_session.update",
-          session: {
-            input_audio_format: "g711_ulaw",
-            input_audio_transcription: {
-              model: this.model,
-            },
-            turn_detection: {
-              type: "server_vad",
-              threshold: this.vadThreshold,
-              prefix_padding_ms: 300,
-              silence_duration_ms: this.silenceDurationMs,
-            },
-          },
-        });
-
-        resolve();
-      });
-
-      this.ws.on("message", (data: Buffer) => {
-        try {
-          const event = JSON.parse(data.toString());
-          this.handleEvent(event);
-        } catch (e) {
-          console.error("[RealtimeSTT] Failed to parse event:", e);
-        }
-      });
-
-      this.ws.on("error", (error) => {
-        console.error("[RealtimeSTT] WebSocket error:", error);
-        if (!this.connected) {
-          reject(error);
-        }
-      });
-
-      this.ws.on("close", (code, reason) => {
-        console.log(
-          `[RealtimeSTT] WebSocket closed (code: ${code}, reason: ${reason?.toString() || "none"})`,
-        );
-        this.connected = false;
-
-        // Attempt reconnection if not intentionally closed
-        if (!this.closed) {
-          void this.attemptReconnect();
-        }
-      });
-
-      setTimeout(() => {
-        if (!this.connected) {
-          reject(new Error("Realtime STT connection timeout"));
-        }
-      }, 10000);
-    });
-  }
-
-  private async attemptReconnect(): Promise<void> {
-    if (this.closed) {
-      return;
-    }
-
-    if (this.reconnectAttempts >= OpenAIRealtimeSTTSession.MAX_RECONNECT_ATTEMPTS) {
-      console.error(
-        `[RealtimeSTT] Max reconnect attempts (${OpenAIRealtimeSTTSession.MAX_RECONNECT_ATTEMPTS}) reached`,
-      );
-      return;
-    }
-
-    this.reconnectAttempts++;
-    const delay = OpenAIRealtimeSTTSession.RECONNECT_DELAY_MS * 2 ** (this.reconnectAttempts - 1);
-    console.log(
-      `[RealtimeSTT] Reconnecting ${this.reconnectAttempts}/${OpenAIRealtimeSTTSession.MAX_RECONNECT_ATTEMPTS} in ${delay}ms...`,
-    );
-
-    await new Promise((resolve) => setTimeout(resolve, delay));
-
-    if (this.closed) {
-      return;
-    }
-
-    try {
-      await this.doConnect();
-      console.log("[RealtimeSTT] Reconnected successfully");
-    } catch (error) {
-      console.error("[RealtimeSTT] Reconnect failed:", error);
-    }
-  }
-
-  private handleEvent(event: {
-    type: string;
-    delta?: string;
-    transcript?: string;
-    error?: unknown;
-  }): void {
-    switch (event.type) {
-      case "transcription_session.created":
-      case "transcription_session.updated":
-      case "input_audio_buffer.speech_stopped":
-      case "input_audio_buffer.committed":
-        console.log(`[RealtimeSTT] ${event.type}`);
-        break;
-
-      case "conversation.item.input_audio_transcription.delta":
-        if (event.delta) {
-          this.pendingTranscript += event.delta;
-          this.onPartialCallback?.(this.pendingTranscript);
-        }
-        break;
-
-      case "conversation.item.input_audio_transcription.completed":
-        if (event.transcript) {
-          console.log(`[RealtimeSTT] Transcript: ${event.transcript}`);
-          this.onTranscriptCallback?.(event.transcript);
-        }
-        this.pendingTranscript = "";
-        break;
-
-      case "input_audio_buffer.speech_started":
-        console.log("[RealtimeSTT] Speech started");
-        this.pendingTranscript = "";
-        this.onSpeechStartCallback?.();
-        break;
-
-      case "error":
-        console.error("[RealtimeSTT] Error:", event.error);
-        break;
-    }
-  }
-
-  private sendEvent(event: unknown): void {
-    if (this.ws?.readyState === WebSocket.OPEN) {
-      this.ws.send(JSON.stringify(event));
-    }
-  }
-
-  sendAudio(muLawData: Buffer): void {
-    if (!this.connected) {
-      return;
-    }
-    this.sendEvent({
-      type: "input_audio_buffer.append",
-      audio: muLawData.toString("base64"),
-    });
-  }
-
-  onPartial(callback: (partial: string) => void): void {
-    this.onPartialCallback = callback;
-  }
-
-  onTranscript(callback: (transcript: string) => void): void {
-    this.onTranscriptCallback = callback;
-  }
-
-  onSpeechStart(callback: () => void): void {
-    this.onSpeechStartCallback = callback;
-  }
-
-  async waitForTranscript(timeoutMs = 30000): Promise<string> {
-    return new Promise((resolve, reject) => {
-      const timeout = setTimeout(() => {
-        this.onTranscriptCallback = null;
-        reject(new Error("Transcript timeout"));
-      }, timeoutMs);
-
-      this.onTranscriptCallback = (transcript) => {
-        clearTimeout(timeout);
-        this.onTranscriptCallback = null;
-        resolve(transcript);
-      };
-    });
-  }
-
-  close(): void {
-    this.closed = true;
-    if (this.ws) {
-      this.ws.close();
-      this.ws = null;
-    }
-    this.connected = false;
-  }
-
-  isConnected(): boolean {
-    return this.connected;
-  }
-}

package/src/providers/tts-openai.test.ts

@@ -1,43 +0,0 @@
-import { describe, expect, it } from "vitest";
-import type { OpenAITTSConfig } from "./tts-openai.js";
-import { OpenAITTSProvider } from "./tts-openai.js";
-
-type ProviderInternals = {
-  model: string;
-  voice: string;
-  speed: number;
-};
-
-function readProviderInternals(config: OpenAITTSConfig): ProviderInternals {
-  return new OpenAITTSProvider(config) as unknown as ProviderInternals;
-}
-
-describe("OpenAITTSProvider constructor defaults", () => {
-  it("uses speed: 0 when explicitly configured", () => {
-    const provider = readProviderInternals({
-      apiKey: "sk-test", // pragma: allowlist secret
-      speed: 0,
-    });
-
-    expect(provider.speed).toBe(0);
-  });
-
-  it("falls back to speed default when undefined", () => {
-    const provider = readProviderInternals({
-      apiKey: "sk-test", // pragma: allowlist secret
-    });
-
-    expect(provider.speed).toBe(1.0);
-  });
-
-  it("treats blank model and voice overrides as unset", () => {
-    const provider = readProviderInternals({
-      apiKey: "sk-test", // pragma: allowlist secret
-      model: "   ",
-      voice: "",
-    });
-
-    expect(provider.model).toBe("gpt-4o-mini-tts");
-    expect(provider.voice).toBe("coral");
-  });
-});