@openclaw/voice-call 2026.5.2 → 2026.5.3-beta.1

package/src/telephony-tts.test.ts

@@ -1,196 +0,0 @@
-import { afterEach, describe, expect, it, vi } from "vitest";
-import type { VoiceCallTtsConfig } from "./config.js";
-import type { CoreConfig } from "./core-bridge.js";
-import { createTelephonyTtsProvider } from "./telephony-tts.js";
-
-function createCoreConfig(): CoreConfig {
-  const tts: VoiceCallTtsConfig = {
-    provider: "openai",
-    providers: {
-      openai: {
-        model: "gpt-4o-mini-tts",
-        voice: "alloy",
-      },
-    },
-  };
-  return { messages: { tts } };
-}
-
-function requireMergedTtsConfig(mergedConfig: CoreConfig | undefined) {
-  const tts = mergedConfig?.messages?.tts;
-  if (!tts) {
-    throw new Error("telephony TTS runtime did not receive merged TTS config");
-  }
-  return tts as Record<string, unknown>;
-}
-
-function requireOpenAIProviderConfig(tts: Record<string, unknown>): Record<string, unknown> {
-  const providers =
-    tts.providers && typeof tts.providers === "object"
-      ? (tts.providers as Record<string, unknown>)
-      : null;
-  const openai = providers?.openai;
-  if (!openai || typeof openai !== "object") {
-    throw new Error("merged TTS config did not preserve providers.openai");
-  }
-  return openai as Record<string, unknown>;
-}
-
-async function mergeOverride(override: unknown): Promise<Record<string, unknown>> {
-  let mergedConfig: CoreConfig | undefined;
-  const provider = createTelephonyTtsProvider({
-    coreConfig: createCoreConfig(),
-    ttsOverride: override as VoiceCallTtsConfig,
-    runtime: {
-      textToSpeechTelephony: async ({ cfg }) => {
-        mergedConfig = cfg;
-        return {
-          success: true,
-          audioBuffer: Buffer.alloc(2),
-          sampleRate: 8000,
-        };
-      },
-    },
-  });
-
-  await provider.synthesizeForTelephony("hello");
-  return requireMergedTtsConfig(mergedConfig);
-}
-
-afterEach(() => {
-  delete (Object.prototype as Record<string, unknown>).polluted;
-});
-
-describe("createTelephonyTtsProvider deepMerge hardening", () => {
-  it("merges safe nested overrides", async () => {
-    const tts = await mergeOverride({
-      providers: { openai: { voice: "coral" } },
-    });
-    const openai = requireOpenAIProviderConfig(tts);
-
-    expect(openai.voice).toBe("coral");
-    expect(openai.model).toBe("gpt-4o-mini-tts");
-  });
-
-  it("blocks top-level __proto__ keys", async () => {
-    const tts = await mergeOverride(
-      JSON.parse('{"__proto__":{"polluted":"top"},"providers":{"openai":{"voice":"coral"}}}'),
-    );
-    const openai = requireOpenAIProviderConfig(tts);
-
-    expect((Object.prototype as Record<string, unknown>).polluted).toBeUndefined();
-    expect(tts.polluted).toBeUndefined();
-    expect(openai.voice).toBe("coral");
-  });
-
-  it("blocks nested __proto__ keys", async () => {
-    const tts = await mergeOverride(
-      JSON.parse('{"providers":{"openai":{"model":"safe","__proto__":{"polluted":"nested"}}}}'),
-    );
-    const openai = requireOpenAIProviderConfig(tts);
-
-    expect((Object.prototype as Record<string, unknown>).polluted).toBeUndefined();
-    expect(openai.polluted).toBeUndefined();
-    expect(openai.model).toBe("safe");
-  });
-
-  it("logs fallback metadata when telephony TTS uses a fallback provider", async () => {
-    const warn = vi.fn();
-    const provider = createTelephonyTtsProvider({
-      coreConfig: createCoreConfig(),
-      runtime: {
-        textToSpeechTelephony: async () => ({
-          success: true,
-          audioBuffer: Buffer.alloc(2),
-          sampleRate: 8000,
-          provider: "microsoft",
-          fallbackFrom: "elevenlabs",
-          attemptedProviders: ["elevenlabs", "microsoft"],
-        }),
-      },
-      logger: { warn },
-    });
-
-    await provider.synthesizeForTelephony("hello");
-    expect(warn).toHaveBeenCalledWith(
-      "[voice-call] Telephony TTS fallback used from=elevenlabs to=microsoft attempts=elevenlabs -> microsoft",
-    );
-  });
-
-  it("strips telephony TTS directive tags before synthesis", async () => {
-    let requestText: string | undefined;
-    const provider = createTelephonyTtsProvider({
-      coreConfig: createCoreConfig(),
-      runtime: {
-        textToSpeechTelephony: async ({ text }) => {
-          requestText = text;
-          return {
-            success: true,
-            audioBuffer: Buffer.alloc(2),
-            sampleRate: 8000,
-          };
-        },
-      },
-    });
-
-    await provider.synthesizeForTelephony("[[tts]]Hello caller[[/tts]]");
-
-    expect(requestText).toBe("Hello caller");
-  });
-
-  it("uses hidden telephony TTS directive text for synthesis", async () => {
-    let requestText: string | undefined;
-    let requestOverrides: unknown;
-    const provider = createTelephonyTtsProvider({
-      coreConfig: createCoreConfig(),
-      runtime: {
-        textToSpeechTelephony: async ({ text, overrides }) => {
-          requestText = text;
-          requestOverrides = overrides;
-          return {
-            success: true,
-            audioBuffer: Buffer.alloc(2),
-            sampleRate: 8000,
-          };
-        },
-      },
-    });
-
-    await provider.synthesizeForTelephony(
-      "Visible text [[tts:text]]Speak this instead[[/tts:text]]",
-    );
-
-    expect(requestText).toBe("Speak this instead");
-    expect(requestOverrides).toMatchObject({ ttsText: "Speak this instead" });
-  });
-
-  it("exposes configured timeoutMs as synthesisTimeoutMs", () => {
-    const provider = createTelephonyTtsProvider({
-      coreConfig: { messages: { tts: { provider: "openai", timeoutMs: 15000 } } },
-      runtime: {
-        textToSpeechTelephony: async () => ({
-          success: true,
-          audioBuffer: Buffer.alloc(2),
-          sampleRate: 8000,
-        }),
-      },
-    });
-
-    expect(provider.synthesisTimeoutMs).toBe(15000);
-  });
-
-  it("keeps the telephony timeout default when timeoutMs is not configured", () => {
-    const provider = createTelephonyTtsProvider({
-      coreConfig: createCoreConfig(),
-      runtime: {
-        textToSpeechTelephony: async () => ({
-          success: true,
-          audioBuffer: Buffer.alloc(2),
-          sampleRate: 8000,
-        }),
-      },
-    });
-
-    expect(provider.synthesisTimeoutMs).toBe(8000);
-  });
-});

package/src/telephony-tts.ts

@@ -1,235 +0,0 @@
-import {
-  parseTtsDirectives,
-  type SpeechModelOverridePolicy,
-  type SpeechProviderConfig,
-  type TtsDirectiveOverrides,
-} from "openclaw/plugin-sdk/speech";
-import type { VoiceCallTtsConfig } from "./config.js";
-import type { CoreConfig } from "./core-bridge.js";
-import { deepMergeDefined } from "./deep-merge.js";
-import { convertPcmToMulaw8k } from "./telephony-audio.js";
-
-export type TelephonyTtsRuntime = {
-  textToSpeechTelephony: (params: {
-    text: string;
-    cfg: CoreConfig;
-    prefsPath?: string;
-    overrides?: TtsDirectiveOverrides;
-  }) => Promise<{
-    success: boolean;
-    audioBuffer?: Buffer;
-    sampleRate?: number;
-    provider?: string;
-    fallbackFrom?: string;
-    attemptedProviders?: string[];
-    error?: string;
-  }>;
-};
-
-export type TelephonyTtsProvider = {
-  synthesisTimeoutMs: number;
-  synthesizeForTelephony: (text: string) => Promise<Buffer>;
-};
-
-export const TELEPHONY_DEFAULT_TTS_TIMEOUT_MS = 8000;
-
-type TelephonyModelOverrideConfig = {
-  enabled?: boolean;
-  allowText?: boolean;
-  allowProvider?: boolean;
-  allowVoice?: boolean;
-  allowModelId?: boolean;
-  allowVoiceSettings?: boolean;
-  allowNormalization?: boolean;
-  allowSeed?: boolean;
-};
-
-export function createTelephonyTtsProvider(params: {
-  coreConfig: CoreConfig;
-  ttsOverride?: VoiceCallTtsConfig;
-  runtime: TelephonyTtsRuntime;
-  logger?: {
-    warn?: (message: string) => void;
-  };
-}): TelephonyTtsProvider {
-  const { coreConfig, ttsOverride, runtime, logger } = params;
-  const mergedConfig = applyTtsOverride(coreConfig, ttsOverride);
-  const ttsConfig = mergedConfig.messages?.tts;
-  const modelOverrides = resolveTelephonyModelOverridePolicy(
-    readTelephonyModelOverrides(ttsConfig),
-  );
-  const providerConfigs = collectTelephonyProviderConfigs(ttsConfig);
-  const activeProvider = normalizeProviderId(ttsConfig?.provider);
-  const synthesisTimeoutMs =
-    mergedConfig.messages?.tts?.timeoutMs ?? TELEPHONY_DEFAULT_TTS_TIMEOUT_MS;
-
-  return {
-    synthesisTimeoutMs,
-    synthesizeForTelephony: async (text: string) => {
-      const directives = parseTtsDirectives(text, modelOverrides, {
-        cfg: mergedConfig,
-        providerConfigs,
-        preferredProviderId: activeProvider,
-      });
-      if (directives.warnings.length > 0) {
-        logger?.warn?.(
-          `[voice-call] Ignored telephony TTS directive overrides (${directives.warnings.join("; ")})`,
-        );
-      }
-      const cleanText = directives.hasDirective
-        ? directives.ttsText?.trim() || directives.cleanedText.trim()
-        : text;
-      const result = await runtime.textToSpeechTelephony({
-        text: cleanText,
-        cfg: mergedConfig,
-        overrides: directives.overrides,
-      });
-
-      if (!result.success || !result.audioBuffer || !result.sampleRate) {
-        throw new Error(result.error ?? "TTS conversion failed");
-      }
-
-      if (result.fallbackFrom && result.provider && result.fallbackFrom !== result.provider) {
-        const attemptedChain =
-          result.attemptedProviders && result.attemptedProviders.length > 0
-            ? result.attemptedProviders.join(" -> ")
-            : `${result.fallbackFrom} -> ${result.provider}`;
-        logger?.warn?.(
-          `[voice-call] Telephony TTS fallback used from=${result.fallbackFrom} to=${result.provider} attempts=${attemptedChain}`,
-        );
-      }
-
-      return convertPcmToMulaw8k(result.audioBuffer, result.sampleRate);
-    },
-  };
-}
-
-function applyTtsOverride(coreConfig: CoreConfig, override?: VoiceCallTtsConfig): CoreConfig {
-  if (!override) {
-    return coreConfig;
-  }
-
-  const base = coreConfig.messages?.tts;
-  const merged = mergeTtsConfig(base, override);
-  if (!merged) {
-    return coreConfig;
-  }
-
-  return {
-    ...coreConfig,
-    messages: {
-      ...coreConfig.messages,
-      tts: merged,
-    },
-  };
-}
-
-function mergeTtsConfig(
-  base?: VoiceCallTtsConfig,
-  override?: VoiceCallTtsConfig,
-): VoiceCallTtsConfig | undefined {
-  if (!base && !override) {
-    return undefined;
-  }
-  if (!override) {
-    return base;
-  }
-  if (!base) {
-    return override;
-  }
-  return deepMergeDefined(base, override) as VoiceCallTtsConfig;
-}
-
-function resolveTelephonyModelOverridePolicy(
-  overrides: TelephonyModelOverrideConfig | undefined,
-): SpeechModelOverridePolicy {
-  const enabled = overrides?.enabled ?? true;
-  if (!enabled) {
-    return {
-      enabled: false,
-      allowText: false,
-      allowProvider: false,
-      allowVoice: false,
-      allowModelId: false,
-      allowVoiceSettings: false,
-      allowNormalization: false,
-      allowSeed: false,
-    };
-  }
-  const allow = (value: boolean | undefined, defaultValue = true) => value ?? defaultValue;
-  return {
-    enabled: true,
-    allowText: allow(overrides?.allowText),
-    allowProvider: allow(overrides?.allowProvider, false),
-    allowVoice: allow(overrides?.allowVoice),
-    allowModelId: allow(overrides?.allowModelId),
-    allowVoiceSettings: allow(overrides?.allowVoiceSettings),
-    allowNormalization: allow(overrides?.allowNormalization),
-    allowSeed: allow(overrides?.allowSeed),
-  };
-}
-
-function readTelephonyModelOverrides(
-  ttsConfig: VoiceCallTtsConfig | undefined,
-): TelephonyModelOverrideConfig | undefined {
-  const value = (ttsConfig as Record<string, unknown> | undefined)?.modelOverrides;
-  return value && typeof value === "object" && !Array.isArray(value)
-    ? (value as TelephonyModelOverrideConfig)
-    : undefined;
-}
-
-function normalizeProviderId(value: unknown): string | undefined {
-  return typeof value === "string" ? value.trim().toLowerCase() || undefined : undefined;
-}
-
-function asProviderConfig(value: unknown): SpeechProviderConfig {
-  return value && typeof value === "object" && !Array.isArray(value)
-    ? (value as SpeechProviderConfig)
-    : {};
-}
-
-function collectTelephonyProviderConfigs(
-  ttsConfig: VoiceCallTtsConfig | undefined,
-): Record<string, SpeechProviderConfig> {
-  if (!ttsConfig) {
-    return {};
-  }
-  const entries: Record<string, SpeechProviderConfig> = {};
-  const rawProviders =
-    ttsConfig.providers &&
-    typeof ttsConfig.providers === "object" &&
-    !Array.isArray(ttsConfig.providers)
-      ? (ttsConfig.providers as Record<string, unknown>)
-      : {};
-  for (const [providerId, value] of Object.entries(rawProviders)) {
-    const normalized = normalizeProviderId(providerId) ?? providerId;
-    entries[normalized] = asProviderConfig(value);
-  }
-  const reservedKeys = new Set([
-    "auto",
-    "enabled",
-    "maxTextLength",
-    "mode",
-    "modelOverrides",
-    "persona",
-    "personas",
-    "prefsPath",
-    "provider",
-    "providers",
-    "summaryModel",
-    "timeoutMs",
-  ]);
-  for (const [key, value] of Object.entries(ttsConfig as Record<string, unknown>)) {
-    if (
-      reservedKeys.has(key) ||
-      typeof value !== "object" ||
-      value === null ||
-      Array.isArray(value)
-    ) {
-      continue;
-    }
-    const normalized = normalizeProviderId(key) ?? key;
-    entries[normalized] ??= asProviderConfig(value);
-  }
-  return entries;
-}

package/src/test-fixtures.ts

@@ -1,73 +0,0 @@
-import type { VoiceCallConfig } from "./config.js";
-import { DEFAULT_VOICE_CALL_REALTIME_INSTRUCTIONS } from "./realtime-defaults.js";
-
-export function createVoiceCallBaseConfig(params?: {
-  provider?: "telnyx" | "twilio" | "plivo" | "mock";
-  tunnelProvider?: "none" | "ngrok";
-}): VoiceCallConfig {
-  return {
-    enabled: true,
-    provider: params?.provider ?? "mock",
-    fromNumber: "+15550001234",
-    inboundPolicy: "disabled",
-    allowFrom: [],
-    numbers: {},
-    outbound: { defaultMode: "notify", notifyHangupDelaySec: 3 },
-    maxDurationSeconds: 300,
-    staleCallReaperSeconds: 600,
-    silenceTimeoutMs: 800,
-    transcriptTimeoutMs: 180000,
-    ringTimeoutMs: 30000,
-    maxConcurrentCalls: 1,
-    sessionScope: "per-phone",
-    serve: { port: 3334, bind: "127.0.0.1", path: "/voice/webhook" },
-    tailscale: { mode: "off", path: "/voice/webhook" },
-    tunnel: {
-      provider: params?.tunnelProvider ?? "none",
-      allowNgrokFreeTierLoopbackBypass: false,
-    },
-    webhookSecurity: {
-      allowedHosts: [],
-      trustForwardingHeaders: false,
-      trustedProxyIPs: [],
-    },
-    streaming: {
-      enabled: false,
-      providers: {
-        openai: {
-          model: "gpt-4o-transcribe",
-          silenceDurationMs: 800,
-          vadThreshold: 0.5,
-        },
-      },
-      streamPath: "/voice/stream",
-      preStartTimeoutMs: 5000,
-      maxPendingConnections: 32,
-      maxPendingConnectionsPerIp: 4,
-      maxConnections: 128,
-    },
-    realtime: {
-      enabled: false,
-      streamPath: "/voice/stream/realtime",
-      instructions: DEFAULT_VOICE_CALL_REALTIME_INSTRUCTIONS,
-      toolPolicy: "safe-read-only",
-      tools: [],
-      fastContext: {
-        enabled: false,
-        timeoutMs: 800,
-        maxResults: 3,
-        sources: ["memory", "sessions"],
-        fallbackToConsult: false,
-      },
-      providers: {},
-    },
-    skipSignatureVerification: false,
-    tts: {
-      provider: "openai",
-      providers: {
-        openai: { model: "gpt-4o-mini-tts", voice: "coral" },
-      },
-    },
-    responseTimeoutMs: 30000,
-  };
-}

package/src/tts-provider-voice.test.ts

@@ -1,34 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { resolvePreferredTtsVoice } from "./tts-provider-voice.js";
-
-describe("resolvePreferredTtsVoice", () => {
-  it("returns provider voice when present", () => {
-    expect(
-      resolvePreferredTtsVoice({
-        tts: {
-          provider: "openai",
-          providers: {
-            openai: {
-              voice: "coral",
-            },
-          },
-        },
-      }),
-    ).toBe("coral");
-  });
-
-  it("falls back to voiceId for providers that use that field", () => {
-    expect(
-      resolvePreferredTtsVoice({
-        tts: {
-          provider: "elevenlabs",
-          providers: {
-            elevenlabs: {
-              voiceId: "voice-123",
-            },
-          },
-        },
-      }),
-    ).toBe("voice-123");
-  });
-});

package/src/tts-provider-voice.ts

@@ -1,21 +0,0 @@
-import { normalizeOptionalString } from "openclaw/plugin-sdk/text-runtime";
-import type { VoiceCallTtsConfig } from "./config.js";
-
-function resolveProviderVoiceSetting(providerConfig: unknown): string | undefined {
-  if (!providerConfig || typeof providerConfig !== "object") {
-    return undefined;
-  }
-  const candidate = providerConfig as {
-    voice?: unknown;
-    voiceId?: unknown;
-  };
-  return normalizeOptionalString(candidate.voice) ?? normalizeOptionalString(candidate.voiceId);
-}
-
-export function resolvePreferredTtsVoice(config: { tts?: VoiceCallTtsConfig }): string | undefined {
-  const providerId = config.tts?.provider;
-  if (!providerId) {
-    return undefined;
-  }
-  return resolveProviderVoiceSetting(config.tts?.providers?.[providerId]);
-}