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

package/src/config-compat.test.ts

@@ -0,0 +1,120 @@
+import { describe, expect, it } from "vitest";
+import {
+  VOICE_CALL_LEGACY_CONFIG_REMOVAL_VERSION,
+  collectVoiceCallLegacyConfigIssues,
+  formatVoiceCallLegacyConfigWarnings,
+  migrateVoiceCallLegacyConfigInput,
+  normalizeVoiceCallLegacyConfigInput,
+  parseVoiceCallPluginConfig,
+} from "./config-compat.js";
+
+describe("voice-call config compatibility", () => {
+  it("maps deprecated provider and twilio.from fields into canonical config", () => {
+    const parsed = parseVoiceCallPluginConfig({
+      enabled: true,
+      provider: "log",
+      twilio: {
+        from: "+15550001234",
+      },
+    });
+
+    expect(parsed.provider).toBe("mock");
+    expect(parsed.fromNumber).toBe("+15550001234");
+  });
+
+  it("moves legacy streaming OpenAI fields into streaming.providers.openai", () => {
+    const normalized = normalizeVoiceCallLegacyConfigInput({
+      streaming: {
+        enabled: true,
+        sttProvider: "openai",
+        openaiApiKey: "sk-test", // pragma: allowlist secret
+        sttModel: "gpt-4o-transcribe",
+        silenceDurationMs: 700,
+        vadThreshold: 0.4,
+      },
+    });
+
+    expect(normalized).toMatchObject({
+      streaming: {
+        enabled: true,
+        provider: "openai",
+        providers: {
+          openai: {
+            apiKey: "sk-test",
+            model: "gpt-4o-transcribe",
+            silenceDurationMs: 700,
+            vadThreshold: 0.4,
+          },
+        },
+      },
+    });
+    expect((normalized.streaming as Record<string, unknown>).openaiApiKey).toBeUndefined();
+    expect((normalized.streaming as Record<string, unknown>).sttModel).toBeUndefined();
+  });
+
+  it("reports doctor-oriented legacy issues and warnings", () => {
+    const raw = {
+      provider: "log",
+      twilio: {
+        from: "+15550001234",
+      },
+      streaming: {
+        sttProvider: "openai",
+        openaiApiKey: "sk-test", // pragma: allowlist secret
+      },
+    };
+
+    expect(collectVoiceCallLegacyConfigIssues(raw)).toEqual([
+      {
+        path: "provider",
+        replacement: "provider",
+        message: 'Replace provider "log" with "mock".',
+      },
+      {
+        path: "twilio.from",
+        replacement: "fromNumber",
+        message: "Move twilio.from to fromNumber.",
+      },
+      {
+        path: "streaming.sttProvider",
+        replacement: "streaming.provider",
+        message: "Move streaming.sttProvider to streaming.provider.",
+      },
+      {
+        path: "streaming.openaiApiKey",
+        replacement: "streaming.providers.openai.apiKey",
+        message: "Move streaming.openaiApiKey to streaming.providers.openai.apiKey.",
+      },
+    ]);
+    expect(
+      formatVoiceCallLegacyConfigWarnings({
+        value: raw,
+        configPathPrefix: "plugins.entries.voice-call.config",
+        doctorFixCommand: "openclaw doctor --fix",
+      }),
+    ).toEqual([
+      `[voice-call] legacy config keys detected under plugins.entries.voice-call.config; runtime loading will not rewrite them, and support for the legacy shape will be removed in ${VOICE_CALL_LEGACY_CONFIG_REMOVAL_VERSION}. Run "openclaw doctor --fix".`,
+      '[voice-call] plugins.entries.voice-call.config.provider: Replace provider "log" with "mock".',
+      "[voice-call] plugins.entries.voice-call.config.twilio.from: Move twilio.from to fromNumber.",
+      "[voice-call] plugins.entries.voice-call.config.streaming.sttProvider: Move streaming.sttProvider to streaming.provider.",
+      "[voice-call] plugins.entries.voice-call.config.streaming.openaiApiKey: Move streaming.openaiApiKey to streaming.providers.openai.apiKey.",
+    ]);
+  });
+
+  it("returns doctor migration change lines", () => {
+    const migration = migrateVoiceCallLegacyConfigInput({
+      value: {
+        provider: "log",
+        streaming: {
+          sttProvider: "openai",
+        },
+      },
+      configPathPrefix: "plugins.entries.voice-call.config",
+    });
+
+    expect(migration.changes).toEqual([
+      'Moved plugins.entries.voice-call.config.provider "log" → "mock".',
+      "Moved plugins.entries.voice-call.config.streaming.sttProvider → plugins.entries.voice-call.config.streaming.provider.",
+    ]);
+  });
+});

package/src/config-compat.ts

@@ -0,0 +1,227 @@
+import { asOptionalRecord, readStringField } from "openclaw/plugin-sdk/text-runtime";
+import type { VoiceCallConfig } from "./config.js";
+import { VoiceCallConfigSchema } from "./config.js";
+
+export const VOICE_CALL_LEGACY_CONFIG_REMOVAL_VERSION = "2026.6.0";
+
+type VoiceCallLegacyConfigIssue = {
+  path: string;
+  replacement: string;
+  message: string;
+};
+
+const asObject = asOptionalRecord;
+const getString = readStringField;
+
+function getNumber(obj: Record<string, unknown> | undefined, key: string): number | undefined {
+  const value = obj?.[key];
+  return typeof value === "number" ? value : undefined;
+}
+
+function mergeProviderConfig(
+  providersValue: unknown,
+  providerId: string,
+  compatValues: Record<string, unknown>,
+): Record<string, unknown> | undefined {
+  if (Object.keys(compatValues).length === 0) {
+    return asObject(providersValue);
+  }
+
+  const providers = asObject(providersValue) ?? {};
+  const existing = asObject(providers[providerId]) ?? {};
+  return {
+    ...providers,
+    [providerId]: {
+      ...existing,
+      ...compatValues,
+    },
+  };
+}
+
+export function collectVoiceCallLegacyConfigIssues(value: unknown): VoiceCallLegacyConfigIssue[] {
+  const raw = asObject(value) ?? {};
+  const twilio = asObject(raw.twilio);
+  const streaming = asObject(raw.streaming);
+
+  const issues: VoiceCallLegacyConfigIssue[] = [];
+  if (raw.provider === "log") {
+    issues.push({
+      path: "provider",
+      replacement: "provider",
+      message: 'Replace provider "log" with "mock".',
+    });
+  }
+  if (typeof twilio?.from === "string") {
+    issues.push({
+      path: "twilio.from",
+      replacement: "fromNumber",
+      message: "Move twilio.from to fromNumber.",
+    });
+  }
+  if (typeof streaming?.sttProvider === "string") {
+    issues.push({
+      path: "streaming.sttProvider",
+      replacement: "streaming.provider",
+      message: "Move streaming.sttProvider to streaming.provider.",
+    });
+  }
+  if (typeof streaming?.openaiApiKey === "string") {
+    issues.push({
+      path: "streaming.openaiApiKey",
+      replacement: "streaming.providers.openai.apiKey",
+      message: "Move streaming.openaiApiKey to streaming.providers.openai.apiKey.",
+    });
+  }
+  if (typeof streaming?.sttModel === "string") {
+    issues.push({
+      path: "streaming.sttModel",
+      replacement: "streaming.providers.openai.model",
+      message: "Move streaming.sttModel to streaming.providers.openai.model.",
+    });
+  }
+  if (typeof streaming?.silenceDurationMs === "number") {
+    issues.push({
+      path: "streaming.silenceDurationMs",
+      replacement: "streaming.providers.openai.silenceDurationMs",
+      message: "Move streaming.silenceDurationMs to streaming.providers.openai.silenceDurationMs.",
+    });
+  }
+  if (typeof streaming?.vadThreshold === "number") {
+    issues.push({
+      path: "streaming.vadThreshold",
+      replacement: "streaming.providers.openai.vadThreshold",
+      message: "Move streaming.vadThreshold to streaming.providers.openai.vadThreshold.",
+    });
+  }
+
+  return issues;
+}
+
+export function formatVoiceCallLegacyConfigWarnings(params: {
+  value: unknown;
+  configPathPrefix: string;
+  doctorFixCommand: string;
+}): string[] {
+  const issues = collectVoiceCallLegacyConfigIssues(params.value);
+  if (issues.length === 0) {
+    return [];
+  }
+
+  return [
+    `[voice-call] legacy config keys detected under ${params.configPathPrefix}; runtime loading will not rewrite them, and support for the legacy shape will be removed in ${VOICE_CALL_LEGACY_CONFIG_REMOVAL_VERSION}. Run "${params.doctorFixCommand}".`,
+    ...issues.map(
+      (issue) => `[voice-call] ${params.configPathPrefix}.${issue.path}: ${issue.message}`,
+    ),
+  ];
+}
+
+export function migrateVoiceCallLegacyConfigInput(params: {
+  value: unknown;
+  configPathPrefix?: string;
+}): {
+  config: Record<string, unknown>;
+  changes: string[];
+  issues: VoiceCallLegacyConfigIssue[];
+} {
+  const raw = asObject(params.value) ?? {};
+  const twilio = asObject(raw.twilio);
+  const streaming = asObject(raw.streaming);
+  const configPathPrefix = params.configPathPrefix ?? "plugins.entries.voice-call.config";
+  const issues = collectVoiceCallLegacyConfigIssues(raw);
+
+  const legacyStreamingOpenAICompat: Record<string, unknown> = {};
+  const streamingOpenAIApiKey = getString(streaming, "openaiApiKey");
+  if (streamingOpenAIApiKey) {
+    legacyStreamingOpenAICompat.apiKey = streamingOpenAIApiKey;
+  }
+  const streamingSttModel = getString(streaming, "sttModel");
+  if (streamingSttModel) {
+    legacyStreamingOpenAICompat.model = streamingSttModel;
+  }
+  const streamingSilenceDurationMs = getNumber(streaming, "silenceDurationMs");
+  if (streamingSilenceDurationMs !== undefined) {
+    legacyStreamingOpenAICompat.silenceDurationMs = streamingSilenceDurationMs;
+  }
+  const streamingVadThreshold = getNumber(streaming, "vadThreshold");
+  if (streamingVadThreshold !== undefined) {
+    legacyStreamingOpenAICompat.vadThreshold = streamingVadThreshold;
+  }
+  const streamingProvider = getString(streaming, "provider");
+  const legacyStreamingProvider = getString(streaming, "sttProvider");
+
+  const normalizedStreaming: Record<string, unknown> | undefined = streaming
+    ? {
+        ...streaming,
+        provider: streamingProvider ?? legacyStreamingProvider,
+        providers: mergeProviderConfig(streaming.providers, "openai", legacyStreamingOpenAICompat),
+      }
+    : undefined;
+
+  if (normalizedStreaming) {
+    delete normalizedStreaming.sttProvider;
+    delete normalizedStreaming.openaiApiKey;
+    delete normalizedStreaming.sttModel;
+    delete normalizedStreaming.silenceDurationMs;
+    delete normalizedStreaming.vadThreshold;
+  }
+
+  const normalizedTwilio = twilio
+    ? {
+        ...twilio,
+      }
+    : undefined;
+  if (normalizedTwilio) {
+    delete normalizedTwilio.from;
+  }
+
+  const config = {
+    ...raw,
+    provider: raw.provider === "log" ? "mock" : raw.provider,
+    fromNumber: raw.fromNumber ?? (typeof twilio?.from === "string" ? twilio.from : undefined),
+    twilio: normalizedTwilio,
+    streaming: normalizedStreaming,
+  };
+
+  const changes: string[] = [];
+  if (raw.provider === "log") {
+    changes.push(`Moved ${configPathPrefix}.provider "log" → "mock".`);
+  }
+  if (typeof twilio?.from === "string" && typeof raw.fromNumber !== "string") {
+    changes.push(`Moved ${configPathPrefix}.twilio.from → ${configPathPrefix}.fromNumber.`);
+  }
+  if (typeof streaming?.sttProvider === "string") {
+    changes.push(
+      `Moved ${configPathPrefix}.streaming.sttProvider → ${configPathPrefix}.streaming.provider.`,
+    );
+  }
+  if (typeof streaming?.openaiApiKey === "string") {
+    changes.push(
+      `Moved ${configPathPrefix}.streaming.openaiApiKey → ${configPathPrefix}.streaming.providers.openai.apiKey.`,
+    );
+  }
+  if (typeof streaming?.sttModel === "string") {
+    changes.push(
+      `Moved ${configPathPrefix}.streaming.sttModel → ${configPathPrefix}.streaming.providers.openai.model.`,
+    );
+  }
+  if (typeof streaming?.silenceDurationMs === "number") {
+    changes.push(
+      `Moved ${configPathPrefix}.streaming.silenceDurationMs → ${configPathPrefix}.streaming.providers.openai.silenceDurationMs.`,
+    );
+  }
+  if (typeof streaming?.vadThreshold === "number") {
+    changes.push(
+      `Moved ${configPathPrefix}.streaming.vadThreshold → ${configPathPrefix}.streaming.providers.openai.vadThreshold.`,
+    );
+  }
+
+  return { config, changes, issues };
+}
+
+export function normalizeVoiceCallLegacyConfigInput(value: unknown): Record<string, unknown> {
+  return migrateVoiceCallLegacyConfigInput({ value }).config;
+}
+
+export function parseVoiceCallPluginConfig(value: unknown): VoiceCallConfig {
+  return VoiceCallConfigSchema.parse(normalizeVoiceCallLegacyConfigInput(value));
+}

package/src/config.test.ts

@@ -1,5 +1,7 @@
 import { afterEach, beforeEach, describe, expect, it } from "vitest";
 import {
+  VoiceCallConfigSchema,
+  resolveTwilioAuthToken,
   validateProviderConfig,
   normalizeVoiceCallConfig,
   resolveVoiceCallConfig,
@@ -11,11 +13,25 @@ function createBaseConfig(provider: "telnyx" | "twilio" | "plivo" | "mock"): Voi
   return createVoiceCallBaseConfig({ provider });
 }
 
+function envRef(id: string) {
+  return { source: "env" as const, provider: "default", id };
+}
+
+function requireElevenLabsTtsConfig(config: Pick<VoiceCallConfig, "tts">) {
+  const tts = config.tts;
+  const elevenlabs = tts?.providers?.elevenlabs;
+  if (!elevenlabs || typeof elevenlabs !== "object") {
+    throw new Error("voice-call config did not preserve nested elevenlabs TTS config");
+  }
+  return { tts, elevenlabs };
+}
+
 describe("validateProviderConfig", () => {
   const originalEnv = { ...process.env };
   const clearProviderEnv = () => {
     delete process.env.TWILIO_ACCOUNT_SID;
     delete process.env.TWILIO_AUTH_TOKEN;
+    delete process.env.TWILIO_FROM_NUMBER;
     delete process.env.TELNYX_API_KEY;
     delete process.env.TELNYX_CONNECTION_ID;
     delete process.env.TELNYX_PUBLIC_KEY;
@@ -54,6 +70,7 @@ describe("validateProviderConfig", () => {
         if (provider === "twilio") {
           process.env.TWILIO_ACCOUNT_SID = "AC123";
           process.env.TWILIO_AUTH_TOKEN = "secret";
+          process.env.TWILIO_FROM_NUMBER = "+15550001234";
         } else if (provider === "telnyx") {
           process.env.TELNYX_API_KEY = "KEY123";
           process.env.TELNYX_CONNECTION_ID = "CONN456";
@@ -69,6 +86,24 @@ describe("validateProviderConfig", () => {
   });
 
   describe("twilio provider", () => {
+    it("accepts SecretRef-backed auth tokens before runtime resolution", () => {
+      const config = VoiceCallConfigSchema.parse({
+        enabled: true,
+        provider: "twilio",
+        fromNumber: "+15550001234",
+        twilio: {
+          accountSid: "AC123",
+          authToken: envRef("TWILIO_AUTH_TOKEN"),
+        },
+      });
+
+      expect(config.twilio?.authToken).toEqual(envRef("TWILIO_AUTH_TOKEN"));
+      expect(validateProviderConfig(config)).toMatchObject({ valid: true, errors: [] });
+      expect(() => resolveTwilioAuthToken(config)).toThrow(
+        'plugins.entries.voice-call.config.twilio.authToken: unresolved SecretRef "env:default:TWILIO_AUTH_TOKEN"',
+      );
+    });
+
     it("passes validation with mixed config and env vars", () => {
       process.env.TWILIO_AUTH_TOKEN = "secret";
       let config = createBaseConfig("twilio");
@@ -81,6 +116,20 @@ describe("validateProviderConfig", () => {
       expect(result.errors).toEqual([]);
     });
 
+    it("resolves the Twilio from number from environment", () => {
+      process.env.TWILIO_ACCOUNT_SID = "AC123";
+      process.env.TWILIO_AUTH_TOKEN = "secret";
+      process.env.TWILIO_FROM_NUMBER = "+15550001234";
+
+      const config = resolveVoiceCallConfig({
+        ...createBaseConfig("twilio"),
+        fromNumber: undefined,
+      });
+
+      expect(config.fromNumber).toBe("+15550001234");
+      expect(validateProviderConfig(config)).toMatchObject({ valid: true, errors: [] });
+    });
+
     it("fails validation when required twilio credentials are missing", () => {
       process.env.TWILIO_AUTH_TOKEN = "secret";
       const missingSid = validateProviderConfig(resolveVoiceCallConfig(createBaseConfig("twilio")));
@@ -170,6 +219,43 @@ describe("validateProviderConfig", () => {
       expect(result.errors).toEqual([]);
     });
   });
+
+  describe("realtime config", () => {
+    it("rejects disabled inbound policy for realtime mode", () => {
+      const config = createBaseConfig("twilio");
+      config.realtime.enabled = true;
+      config.inboundPolicy = "disabled";
+
+      const result = validateProviderConfig(config);
+
+      expect(result.valid).toBe(false);
+      expect(result.errors).toContain(
+        'plugins.entries.voice-call.config.inboundPolicy must not be "disabled" when realtime.enabled is true',
+      );
+    });
+
+    it("rejects enabling realtime and streaming together", () => {
+      const config = createBaseConfig("twilio");
+      config.realtime.enabled = true;
+      config.streaming.enabled = true;
+      config.inboundPolicy = "allowlist";
+
+      const result = validateProviderConfig(config);
+
+      expect(result.valid).toBe(false);
+      expect(result.errors).toContain(
+        "plugins.entries.voice-call.config.realtime.enabled and plugins.entries.voice-call.config.streaming.enabled cannot both be true",
+      );
+    });
+  });
+});
+
+describe("resolveVoiceCallConfig", () => {
+  it("enables the pre-answer stale call reaper by default", () => {
+    const config = resolveVoiceCallConfig({ enabled: true, provider: "mock" });
+
+    expect(config.staleCallReaperSeconds).toBe(120);
+  });
 });
 
 describe("normalizeVoiceCallConfig", () => {
@@ -185,34 +271,96 @@ describe("normalizeVoiceCallConfig", () => {
 
     expect(normalized.serve.path).toBe("/voice/webhook");
     expect(normalized.streaming.streamPath).toBe("/custom-stream");
-    expect(normalized.streaming.sttModel).toBe("gpt-4o-transcribe");
+    expect(normalized.streaming.provider).toBeUndefined();
+    expect(normalized.streaming.providers).toEqual({});
+    expect(normalized.realtime.streamPath).toBe("/voice/stream/realtime");
+    expect(normalized.realtime.toolPolicy).toBe("safe-read-only");
+    expect(normalized.realtime.fastContext).toEqual({
+      enabled: false,
+      timeoutMs: 800,
+      maxResults: 3,
+      sources: ["memory", "sessions"],
+      fallbackToConsult: false,
+    });
+    expect(normalized.realtime.instructions).toContain("openclaw_agent_consult");
     expect(normalized.tunnel.provider).toBe("none");
     expect(normalized.webhookSecurity.allowedHosts).toEqual([]);
   });
 
+  it("derives the realtime stream path from a custom webhook path", () => {
+    const normalized = normalizeVoiceCallConfig({
+      enabled: true,
+      provider: "twilio",
+      serve: {
+        path: "/custom/webhook",
+      },
+    });
+
+    expect(normalized.realtime.streamPath).toBe("/custom/stream/realtime");
+  });
+
   it("accepts partial nested TTS overrides and preserves nested objects", () => {
     const normalized = normalizeVoiceCallConfig({
       tts: {
         provider: "elevenlabs",
-        elevenlabs: {
-          apiKey: {
-            source: "env",
-            provider: "elevenlabs",
-            id: "ELEVENLABS_API_KEY",
-          },
-          voiceSettings: {
-            speed: 1.1,
+        providers: {
+          elevenlabs: {
+            apiKey: {
+              source: "env",
+              provider: "elevenlabs",
+              id: "ELEVENLABS_API_KEY",
+            },
+            voiceSettings: {
+              speed: 1.1,
+            },
           },
         },
       },
     });
 
-    expect(normalized.tts?.provider).toBe("elevenlabs");
-    expect(normalized.tts?.elevenlabs?.apiKey).toEqual({
+    const { tts, elevenlabs } = requireElevenLabsTtsConfig(normalized);
+    expect(tts.provider).toBe("elevenlabs");
+    expect(elevenlabs.apiKey).toEqual({
       source: "env",
       provider: "elevenlabs",
       id: "ELEVENLABS_API_KEY",
     });
-    expect(normalized.tts?.elevenlabs?.voiceSettings).toEqual({ speed: 1.1 });
+    expect(elevenlabs.voiceSettings).toEqual({ speed: 1.1 });
+  });
+});
+
+describe("resolveVoiceCallConfig", () => {
+  it("preserves configured realtime instructions without env indirection", () => {
+    const resolved = resolveVoiceCallConfig({
+      enabled: true,
+      provider: "twilio",
+      realtime: {
+        enabled: true,
+        instructions: "Stay concise.",
+      },
+    });
+
+    expect(resolved.realtime.instructions).toBe("Stay concise.");
+    expect(resolved.realtime.toolPolicy).toBe("safe-read-only");
+    expect(resolved.realtime.provider).toBeUndefined();
+  });
+
+  it("leaves responseModel unset so voice responses can inherit runtime defaults", () => {
+    const resolved = resolveVoiceCallConfig({
+      enabled: true,
+      provider: "mock",
+    });
+
+    expect(resolved.responseModel).toBeUndefined();
+  });
+
+  it("preserves the configured voice response agent id", () => {
+    const resolved = resolveVoiceCallConfig({
+      enabled: true,
+      provider: "mock",
+      agentId: "voice",
+    });
+
+    expect(resolved.agentId).toBe("voice");
   });
 });