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

package/src/config.ts

@@ -1,11 +1,14 @@
+import { REALTIME_VOICE_AGENT_CONSULT_TOOL_POLICIES } from "openclaw/plugin-sdk/realtime-voice";
 import {
-  TtsAutoSchema,
-  TtsConfigSchema,
-  TtsModeSchema,
-  TtsProviderSchema,
-} from "openclaw/plugin-sdk/voice-call";
-import { z } from "zod";
+  buildSecretInputSchema,
+  hasConfiguredSecretInput,
+  normalizeResolvedSecretInputString,
+  type SecretInput,
+} from "openclaw/plugin-sdk/secret-input";
+import { z } from "openclaw/plugin-sdk/zod";
+import { TtsConfigSchema } from "../api.js";
 import { deepMergeDefined } from "./deep-merge.js";
+import { DEFAULT_VOICE_CALL_REALTIME_INSTRUCTIONS } from "./realtime-defaults.js";
 
 // -----------------------------------------------------------------------------
 // Phone Number Validation
@@ -15,7 +18,7 @@ import { deepMergeDefined } from "./deep-merge.js";
  * E.164 phone number format: +[country code][number]
  * Examples use 555 prefix (reserved for fictional numbers)
  */
-export const E164Schema = z
+const E164Schema = z
   .string()
   .regex(/^\+[1-9]\d{1,14}$/, "Expected E.164 format, e.g. +15550001234");
 
@@ -30,14 +33,15 @@ export const E164Schema = z
  * - "pairing": Unknown callers can request pairing (future)
  * - "open": Accept all inbound calls (dangerous!)
  */
-export const InboundPolicySchema = z.enum(["disabled", "allowlist", "pairing", "open"]);
-export type InboundPolicy = z.infer<typeof InboundPolicySchema>;
+const InboundPolicySchema = z.enum(["disabled", "allowlist", "pairing", "open"]);
 
 // -----------------------------------------------------------------------------
 // Provider-Specific Configuration
 // -----------------------------------------------------------------------------
 
-export const TelnyxConfigSchema = z
+const SecretInputSchema = buildSecretInputSchema();
+
+const TelnyxConfigSchema = z
   .object({
     /** Telnyx API v2 key */
     apiKey: z.string().min(1).optional(),
@@ -49,17 +53,16 @@ export const TelnyxConfigSchema = z
   .strict();
 export type TelnyxConfig = z.infer<typeof TelnyxConfigSchema>;
 
-export const TwilioConfigSchema = z
+const TwilioConfigSchema = z
   .object({
     /** Twilio Account SID */
     accountSid: z.string().min(1).optional(),
     /** Twilio Auth Token */
-    authToken: z.string().min(1).optional(),
+    authToken: SecretInputSchema.optional(),
   })
   .strict();
-export type TwilioConfig = z.infer<typeof TwilioConfigSchema>;
 
-export const PlivoConfigSchema = z
+const PlivoConfigSchema = z
   .object({
     /** Plivo Auth ID (starts with MA/SA) */
     authId: z.string().min(1).optional(),
@@ -69,29 +72,31 @@ export const PlivoConfigSchema = z
   .strict();
 export type PlivoConfig = z.infer<typeof PlivoConfigSchema>;
 
-// -----------------------------------------------------------------------------
-// STT/TTS Configuration
-// -----------------------------------------------------------------------------
+export type VoiceCallTtsConfig = z.infer<typeof TtsConfigSchema>;
 
-export const SttConfigSchema = z
+const VoiceCallNumberRouteConfigSchema = z
   .object({
-    /** STT provider (currently only OpenAI supported) */
-    provider: z.literal("openai").default("openai"),
-    /** Whisper model to use */
-    model: z.string().min(1).default("whisper-1"),
+    /** Greeting message for inbound calls to this number. */
+    inboundGreeting: z.string().optional(),
+    /** TTS override for inbound calls to this number. Deep-merges with global voice-call TTS. */
+    tts: TtsConfigSchema,
+    /** Agent ID to use for voice response generation for this number. */
+    agentId: z.string().min(1).optional(),
+    /** Optional model override for voice responses for this number. */
+    responseModel: z.string().optional(),
+    /** System prompt for voice responses for this number. */
+    responseSystemPrompt: z.string().optional(),
+    /** Timeout for response generation in ms for this number. */
+    responseTimeoutMs: z.number().int().positive().optional(),
   })
-  .strict()
-  .default({ provider: "openai", model: "whisper-1" });
-export type SttConfig = z.infer<typeof SttConfigSchema>;
-
-export { TtsAutoSchema, TtsConfigSchema, TtsModeSchema, TtsProviderSchema };
-export type VoiceCallTtsConfig = z.infer<typeof TtsConfigSchema>;
+  .strict();
+export type VoiceCallNumberRouteConfig = z.infer<typeof VoiceCallNumberRouteConfigSchema>;
 
 // -----------------------------------------------------------------------------
 // Webhook Server Configuration
 // -----------------------------------------------------------------------------
 
-export const VoiceCallServeConfigSchema = z
+const VoiceCallServeConfigSchema = z
   .object({
     /** Port to listen on */
     port: z.number().int().positive().default(3334),
@@ -102,9 +107,8 @@ export const VoiceCallServeConfigSchema = z
   })
   .strict()
   .default({ port: 3334, bind: "127.0.0.1", path: "/voice/webhook" });
-export type VoiceCallServeConfig = z.infer<typeof VoiceCallServeConfigSchema>;
 
-export const VoiceCallTailscaleConfigSchema = z
+const VoiceCallTailscaleConfigSchema = z
   .object({
     /**
      * Tailscale exposure mode:
@@ -118,13 +122,12 @@ export const VoiceCallTailscaleConfigSchema = z
   })
   .strict()
   .default({ mode: "off", path: "/voice/webhook" });
-export type VoiceCallTailscaleConfig = z.infer<typeof VoiceCallTailscaleConfigSchema>;
 
 // -----------------------------------------------------------------------------
 // Tunnel Configuration (unified ngrok/tailscale)
 // -----------------------------------------------------------------------------
 
-export const VoiceCallTunnelConfigSchema = z
+const VoiceCallTunnelConfigSchema = z
   .object({
     /**
      * Tunnel provider:
@@ -149,13 +152,12 @@ export const VoiceCallTunnelConfigSchema = z
   })
   .strict()
   .default({ provider: "none", allowNgrokFreeTierLoopbackBypass: false });
-export type VoiceCallTunnelConfig = z.infer<typeof VoiceCallTunnelConfigSchema>;
 
 // -----------------------------------------------------------------------------
 // Webhook Security Configuration
 // -----------------------------------------------------------------------------
 
-export const VoiceCallWebhookSecurityConfigSchema = z
+const VoiceCallWebhookSecurityConfigSchema = z
   .object({
     /**
      * Allowed hostnames for webhook URL reconstruction.
@@ -186,10 +188,13 @@ export type WebhookSecurityConfig = z.infer<typeof VoiceCallWebhookSecurityConfi
  * - "notify": Deliver message and auto-hangup after delay (one-way notification)
  * - "conversation": Stay open for back-and-forth until explicit end or timeout
  */
-export const CallModeSchema = z.enum(["notify", "conversation"]);
+const CallModeSchema = z.enum(["notify", "conversation"]);
 export type CallMode = z.infer<typeof CallModeSchema>;
 
-export const OutboundConfigSchema = z
+const VoiceCallSessionScopeSchema = z.enum(["per-phone", "per-call"]);
+export type VoiceCallSessionScope = z.infer<typeof VoiceCallSessionScopeSchema>;
+
+const OutboundConfigSchema = z
   .object({
     /** Default call mode for outbound calls */
     defaultMode: CallModeSchema.default("notify"),
@@ -198,28 +203,115 @@ export const OutboundConfigSchema = z
   })
   .strict()
   .default({ defaultMode: "notify", notifyHangupDelaySec: 3 });
-export type OutboundConfig = z.infer<typeof OutboundConfigSchema>;
 
 // -----------------------------------------------------------------------------
-// Streaming Configuration (OpenAI Realtime STT)
+// Realtime Voice Configuration
+// -----------------------------------------------------------------------------
+
+const RealtimeToolSchema = z
+  .object({
+    type: z.literal("function"),
+    name: z.string().min(1),
+    description: z.string(),
+    parameters: z.object({
+      type: z.literal("object"),
+      properties: z.record(z.string(), z.unknown()),
+      required: z.array(z.string()).optional(),
+    }),
+  })
+  .strict();
+type RealtimeToolConfig = z.infer<typeof RealtimeToolSchema>;
+
+const VoiceCallRealtimeProvidersConfigSchema = z
+  .record(z.string(), z.record(z.string(), z.unknown()))
+  .default({});
+
+const VoiceCallRealtimeToolPolicySchema = z.enum(REALTIME_VOICE_AGENT_CONSULT_TOOL_POLICIES);
+
+const VoiceCallRealtimeFastContextSourceSchema = z.enum(["memory", "sessions"]);
+
+const VoiceCallRealtimeFastContextConfigSchema = z
+  .object({
+    /** Enable bounded memory/session lookup before the full consult agent. */
+    enabled: z.boolean().default(false),
+    /** Hard deadline for the fast context lookup. */
+    timeoutMs: z.number().int().positive().default(800),
+    /** Maximum memory/session hits to inject into the realtime tool result. */
+    maxResults: z.number().int().positive().default(3),
+    /** Indexed sources used by the fast context lookup. */
+    sources: z
+      .array(VoiceCallRealtimeFastContextSourceSchema)
+      .min(1)
+      .default(["memory", "sessions"]),
+    /** Fall back to the full agent consult when fast context has no answer. */
+    fallbackToConsult: z.boolean().default(false),
+  })
+  .strict()
+  .default({
+    enabled: false,
+    timeoutMs: 800,
+    maxResults: 3,
+    sources: ["memory", "sessions"],
+    fallbackToConsult: false,
+  });
+export type VoiceCallRealtimeFastContextConfig = z.infer<
+  typeof VoiceCallRealtimeFastContextConfigSchema
+>;
+
+const VoiceCallStreamingProvidersConfigSchema = z
+  .record(z.string(), z.record(z.string(), z.unknown()))
+  .default({});
+
+const VoiceCallRealtimeConfigSchema = z
+  .object({
+    /** Enable realtime voice-to-voice mode. */
+    enabled: z.boolean().default(false),
+    /** Provider id from registered realtime voice providers. */
+    provider: z.string().min(1).optional(),
+    /** Optional override for the local WebSocket route path. */
+    streamPath: z.string().min(1).optional(),
+    /** System instructions passed to the realtime provider. */
+    instructions: z.string().default(DEFAULT_VOICE_CALL_REALTIME_INSTRUCTIONS),
+    /** Tool policy for the shared OpenClaw agent consult tool. */
+    toolPolicy: VoiceCallRealtimeToolPolicySchema.default("safe-read-only"),
+    /** Tool definitions exposed to the realtime provider. */
+    tools: z.array(RealtimeToolSchema).default([]),
+    /** Low-latency memory/session context for the consult tool. */
+    fastContext: VoiceCallRealtimeFastContextConfigSchema,
+    /** Provider-owned raw config blobs keyed by provider id. */
+    providers: VoiceCallRealtimeProvidersConfigSchema,
+  })
+  .strict()
+  .default({
+    enabled: false,
+    instructions: DEFAULT_VOICE_CALL_REALTIME_INSTRUCTIONS,
+    toolPolicy: "safe-read-only",
+    tools: [],
+    fastContext: {
+      enabled: false,
+      timeoutMs: 800,
+      maxResults: 3,
+      sources: ["memory", "sessions"],
+      fallbackToConsult: false,
+    },
+    providers: {},
+  });
+export type VoiceCallRealtimeConfig = z.infer<typeof VoiceCallRealtimeConfigSchema>;
+
+// -----------------------------------------------------------------------------
+// Streaming Configuration (Realtime Transcription)
 // -----------------------------------------------------------------------------
 
-export const VoiceCallStreamingConfigSchema = z
+const VoiceCallStreamingConfigSchema = z
   .object({
     /** Enable real-time audio streaming (requires WebSocket support) */
     enabled: z.boolean().default(false),
-    /** STT provider for real-time transcription */
-    sttProvider: z.enum(["openai-realtime"]).default("openai-realtime"),
-    /** OpenAI API key for Realtime API (uses OPENAI_API_KEY env if not set) */
-    openaiApiKey: z.string().min(1).optional(),
-    /** OpenAI transcription model (default: gpt-4o-transcribe) */
-    sttModel: z.string().min(1).default("gpt-4o-transcribe"),
-    /** VAD silence duration in ms before considering speech ended */
-    silenceDurationMs: z.number().int().positive().default(800),
-    /** VAD threshold 0-1 (higher = less sensitive) */
-    vadThreshold: z.number().min(0).max(1).default(0.5),
+    /** Provider id from registered realtime transcription providers. */
+    provider: z.string().min(1).optional(),
     /** WebSocket path for media stream connections */
     streamPath: z.string().min(1).default("/voice/stream"),
+    /** Provider-owned raw config blobs keyed by provider id. */
+    providers: VoiceCallStreamingProvidersConfigSchema,
     /**
      * Close unauthenticated media stream sockets if no valid `start` frame arrives in time.
      * Protects against pre-auth idle connection hold attacks.
@@ -235,17 +327,13 @@ export const VoiceCallStreamingConfigSchema = z
   .strict()
   .default({
     enabled: false,
-    sttProvider: "openai-realtime",
-    sttModel: "gpt-4o-transcribe",
-    silenceDurationMs: 800,
-    vadThreshold: 0.5,
     streamPath: "/voice/stream",
+    providers: {},
     preStartTimeoutMs: 5000,
     maxPendingConnections: 32,
     maxPendingConnectionsPerIp: 4,
     maxConnections: 128,
   });
-export type VoiceCallStreamingConfig = z.infer<typeof VoiceCallStreamingConfigSchema>;
 
 // -----------------------------------------------------------------------------
 // Main Voice Call Configuration
@@ -283,6 +371,9 @@ export const VoiceCallConfigSchema = z
     /** Greeting message for inbound calls */
     inboundGreeting: z.string().optional(),
 
+    /** Per-dialed-number overrides for inbound calls. Keys are E.164 numbers. */
+    numbers: z.record(E164Schema, VoiceCallNumberRouteConfigSchema).default({}),
+
     /** Outbound call configuration */
     outbound: OutboundConfigSchema,
 
@@ -291,11 +382,10 @@ export const VoiceCallConfigSchema = z
 
     /**
      * Maximum age of a call in seconds before it is automatically reaped.
-     * Catches calls stuck in unexpected states (e.g., notify-mode calls that
-     * never receive a terminal webhook). Set to 0 to disable.
-     * Default: 0 (disabled). Recommended: 120-300 for production.
+     * Catches calls stuck before answer (for example, local mock calls that
+     * never receive provider webhooks). Set to 0 to disable.
      */
-    staleCallReaperSeconds: z.number().int().nonnegative().default(0),
+    staleCallReaperSeconds: z.number().int().nonnegative().default(120),
 
     /** Silence timeout for end-of-speech detection (ms) */
     silenceTimeoutMs: z.number().int().positive().default(800),
@@ -312,7 +402,7 @@ export const VoiceCallConfigSchema = z
     /** Webhook server configuration */
     serve: VoiceCallServeConfigSchema,
 
-    /** Tailscale exposure configuration (legacy, prefer tunnel config) */
+    /** @deprecated Prefer tunnel config. */
     tailscale: VoiceCallTailscaleConfigSchema,
 
     /** Tunnel configuration (unified ngrok/tailscale) */
@@ -324,23 +414,29 @@ export const VoiceCallConfigSchema = z
     /** Real-time audio streaming configuration */
     streaming: VoiceCallStreamingConfigSchema,
 
+    /** Realtime voice-to-voice configuration */
+    realtime: VoiceCallRealtimeConfigSchema,
+
+    /** Session memory scope for voice conversations. */
+    sessionScope: VoiceCallSessionScopeSchema.default("per-phone"),
+
     /** Public webhook URL override (if set, bypasses tunnel auto-detection) */
     publicUrl: z.string().url().optional(),
 
     /** Skip webhook signature verification (development only, NOT for production) */
     skipSignatureVerification: z.boolean().default(false),
 
-    /** STT configuration */
-    stt: SttConfigSchema,
-
     /** TTS override (deep-merges with core messages.tts) */
     tts: TtsConfigSchema,
 
     /** Store path for call logs */
     store: z.string().optional(),
 
-    /** Model for generating voice responses (e.g., "anthropic/claude-sonnet-4", "openai/gpt-4o") */
-    responseModel: z.string().default("openai/gpt-4o-mini"),
+    /** Agent ID to use for voice response generation. Defaults to "main". */
+    agentId: z.string().min(1).optional(),
+
+    /** Optional model override for generating voice responses. */
+    responseModel: z.string().optional(),
 
     /** System prompt for voice responses */
     responseSystemPrompt: z.string().optional(),
@@ -351,13 +447,19 @@ export const VoiceCallConfigSchema = z
   .strict();
 
 export type VoiceCallConfig = z.infer<typeof VoiceCallConfigSchema>;
-type DeepPartial<T> =
-  T extends Array<infer U>
+export type VoiceCallEffectiveConfigResult = {
+  config: VoiceCallConfig;
+  numberRouteKey?: string;
+};
+type DeepPartial<T> = T extends SecretInput
+  ? T
+  : T extends Array<infer U>
     ? DeepPartial<U>[]
     : T extends object
       ? { [K in keyof T]?: DeepPartial<T[K]> }
       : T;
 export type VoiceCallConfigInput = DeepPartial<VoiceCallConfig>;
+const TWILIO_AUTH_TOKEN_PATH = "plugins.entries.voice-call.config.twilio.authToken";
 
 // -----------------------------------------------------------------------------
 // Configuration Helpers
@@ -369,6 +471,29 @@ function cloneDefaultVoiceCallConfig(): VoiceCallConfig {
   return structuredClone(DEFAULT_VOICE_CALL_CONFIG);
 }
 
+function normalizeWebhookLikePath(pathname: string): string {
+  const trimmed = pathname.trim();
+  if (!trimmed) {
+    return "/";
+  }
+  const prefixed = trimmed.startsWith("/") ? trimmed : `/${trimmed}`;
+  if (prefixed === "/") {
+    return prefixed;
+  }
+  return prefixed.endsWith("/") ? prefixed.slice(0, -1) : prefixed;
+}
+
+function defaultRealtimeStreamPathForServePath(servePath: string): string {
+  const normalized = normalizeWebhookLikePath(servePath);
+  if (normalized.endsWith("/webhook")) {
+    return `${normalized.slice(0, -"/webhook".length)}/stream/realtime`;
+  }
+  if (normalized === "/") {
+    return "/voice/stream/realtime";
+  }
+  return `${normalized}/stream/realtime`;
+}
+
 function normalizeVoiceCallTtsConfig(
   defaults: VoiceCallTtsConfig,
   overrides: DeepPartial<NonNullable<VoiceCallTtsConfig>> | undefined,
@@ -380,14 +505,116 @@ function normalizeVoiceCallTtsConfig(
   return TtsConfigSchema.parse(deepMergeDefined(defaults ?? {}, overrides ?? {}));
 }
 
+function normalizePhoneRouteKey(phone: string | undefined): string {
+  return phone?.replace(/\D/g, "") ?? "";
+}
+
+export function resolveVoiceCallNumberRouteKey(
+  config: Pick<VoiceCallConfig, "numbers">,
+  phone: string | undefined,
+): string | undefined {
+  const routes = config.numbers;
+  if (!routes) {
+    return undefined;
+  }
+  if (phone && Object.prototype.hasOwnProperty.call(routes, phone)) {
+    return phone;
+  }
+
+  const normalizedPhone = normalizePhoneRouteKey(phone);
+  if (!normalizedPhone) {
+    return undefined;
+  }
+  return Object.keys(routes).find(
+    (routeKey) => normalizePhoneRouteKey(routeKey) === normalizedPhone,
+  );
+}
+
+export function resolveVoiceCallEffectiveConfig(
+  config: VoiceCallConfig,
+  phoneOrRouteKey: string | undefined,
+): VoiceCallEffectiveConfigResult {
+  const numberRouteKey = resolveVoiceCallNumberRouteKey(config, phoneOrRouteKey);
+  if (!numberRouteKey) {
+    return { config };
+  }
+
+  const route = config.numbers[numberRouteKey];
+  if (!route) {
+    return { config };
+  }
+
+  return {
+    numberRouteKey,
+    config: {
+      ...config,
+      ...route,
+      tts: normalizeVoiceCallTtsConfig(config.tts, route.tts),
+      numbers: config.numbers,
+    },
+  };
+}
+
+function sanitizeVoiceCallProviderConfigs(
+  value: Record<string, Record<string, unknown> | undefined> | undefined,
+): Record<string, Record<string, unknown>> {
+  if (!value) {
+    return {};
+  }
+  return Object.fromEntries(
+    Object.entries(value).filter(
+      (entry): entry is [string, Record<string, unknown>] => entry[1] !== undefined,
+    ),
+  );
+}
+
+function sanitizeVoiceCallNumberRoutes(
+  value: Record<string, unknown> | undefined,
+): Record<string, VoiceCallNumberRouteConfig> {
+  if (!value) {
+    return {};
+  }
+  return Object.fromEntries(
+    Object.entries(value)
+      .filter((entry): entry is [string, unknown] => entry[1] !== undefined)
+      .map(([key, route]) => [key, VoiceCallNumberRouteConfigSchema.parse(route)]),
+  );
+}
+
+export function resolveTwilioAuthToken(
+  config: Pick<VoiceCallConfig, "twilio">,
+): string | undefined {
+  return normalizeResolvedSecretInputString({
+    value: config.twilio?.authToken,
+    path: TWILIO_AUTH_TOKEN_PATH,
+  });
+}
+
 export function normalizeVoiceCallConfig(config: VoiceCallConfigInput): VoiceCallConfig {
   const defaults = cloneDefaultVoiceCallConfig();
+  const serve = { ...defaults.serve, ...config.serve };
+  const streamingProvider = config.streaming?.provider;
+  const streamingProviders = sanitizeVoiceCallProviderConfigs(
+    config.streaming?.providers ?? defaults.streaming.providers,
+  );
+  const realtimeProvider = config.realtime?.provider ?? defaults.realtime.provider;
+  const realtimeProviders = sanitizeVoiceCallProviderConfigs(
+    config.realtime?.providers ?? defaults.realtime.providers,
+  );
+  const realtimeFastContext = {
+    ...defaults.realtime.fastContext,
+    ...config.realtime?.fastContext,
+    sources: config.realtime?.fastContext?.sources ?? defaults.realtime.fastContext.sources,
+  };
   return {
     ...defaults,
     ...config,
     allowFrom: config.allowFrom ?? defaults.allowFrom,
+    numbers: sanitizeVoiceCallNumberRoutes(
+      (config.numbers ?? defaults.numbers) as Record<string, unknown>,
+    ),
     outbound: { ...defaults.outbound, ...config.outbound },
-    serve: { ...defaults.serve, ...config.serve },
+    serve,
     tailscale: { ...defaults.tailscale, ...config.tailscale },
     tunnel: { ...defaults.tunnel, ...config.tunnel },
     webhookSecurity: {
@@ -397,12 +624,45 @@ export function normalizeVoiceCallConfig(config: VoiceCallConfigInput): VoiceCal
       trustedProxyIPs:
         config.webhookSecurity?.trustedProxyIPs ?? defaults.webhookSecurity.trustedProxyIPs,
     },
-    streaming: { ...defaults.streaming, ...config.streaming },
-    stt: { ...defaults.stt, ...config.stt },
+    streaming: {
+      ...defaults.streaming,
+      ...config.streaming,
+      provider: streamingProvider,
+      providers: streamingProviders,
+    },
+    realtime: {
+      ...defaults.realtime,
+      ...config.realtime,
+      provider: realtimeProvider,
+      streamPath:
+        config.realtime?.streamPath ??
+        defaultRealtimeStreamPathForServePath(serve.path ?? defaults.serve.path),
+      tools:
+        (config.realtime?.tools as RealtimeToolConfig[] | undefined) ?? defaults.realtime.tools,
+      fastContext: realtimeFastContext,
+      providers: realtimeProviders,
+    },
     tts: normalizeVoiceCallTtsConfig(defaults.tts, config.tts),
   };
 }
 
+export function resolveVoiceCallSessionKey(params: {
+  config: Pick<VoiceCallConfig, "sessionScope">;
+  callId: string;
+  phone?: string;
+  explicitSessionKey?: string;
+}): string {
+  const explicit = params.explicitSessionKey?.trim();
+  if (explicit) {
+    return explicit;
+  }
+  if (params.config.sessionScope === "per-call") {
+    return `voice:call:${params.callId}`;
+  }
+  const normalizedPhone = params.phone?.replace(/\D/g, "");
+  return normalizedPhone ? `voice:${normalizedPhone}` : `voice:${params.callId}`;
+}
+
 /**
  * Resolves the configuration by merging environment variables into missing fields.
  * Returns a new configuration object with environment variables applied.
@@ -420,6 +680,7 @@ export function resolveVoiceCallConfig(config: VoiceCallConfigInput): VoiceCallC
 
   // Twilio
   if (resolved.provider === "twilio") {
+    resolved.fromNumber = resolved.fromNumber ?? process.env.TWILIO_FROM_NUMBER;
     resolved.twilio = resolved.twilio ?? {};
     resolved.twilio.accountSid = resolved.twilio.accountSid ?? process.env.TWILIO_ACCOUNT_SID;
     resolved.twilio.authToken = resolved.twilio.authToken ?? process.env.TWILIO_AUTH_TOKEN;
@@ -474,7 +735,11 @@ export function validateProviderConfig(config: VoiceCallConfig): {
   }
 
   if (!config.fromNumber && config.provider !== "mock") {
-    errors.push("plugins.entries.voice-call.config.fromNumber is required");
+    errors.push(
+      config.provider === "twilio"
+        ? "plugins.entries.voice-call.config.fromNumber is required (or set TWILIO_FROM_NUMBER env)"
+        : "plugins.entries.voice-call.config.fromNumber is required",
+    );
   }
 
   if (config.provider === "telnyx") {
@@ -501,7 +766,7 @@ export function validateProviderConfig(config: VoiceCallConfig): {
         "plugins.entries.voice-call.config.twilio.accountSid is required (or set TWILIO_ACCOUNT_SID env)",
       );
     }
-    if (!config.twilio?.authToken) {
+    if (!hasConfiguredSecretInput(config.twilio?.authToken)) {
       errors.push(
         "plugins.entries.voice-call.config.twilio.authToken is required (or set TWILIO_AUTH_TOKEN env)",
       );
@@ -521,5 +786,23 @@ export function validateProviderConfig(config: VoiceCallConfig): {
     }
   }
 
+  if (config.realtime.enabled && config.inboundPolicy === "disabled") {
+    errors.push(
+      'plugins.entries.voice-call.config.inboundPolicy must not be "disabled" when realtime.enabled is true',
+    );
+  }
+
+  if (config.realtime.enabled && config.streaming.enabled) {
+    errors.push(
+      "plugins.entries.voice-call.config.realtime.enabled and plugins.entries.voice-call.config.streaming.enabled cannot both be true",
+    );
+  }
+
+  if (config.realtime.enabled && config.provider && config.provider !== "twilio") {
+    errors.push(
+      'plugins.entries.voice-call.config.provider must be "twilio" when realtime.enabled is true',
+    );
+  }
+
   return { valid: errors.length === 0, errors };
 }