@agenticmail/core 0.9.38 → 0.9.39

package/dist/index.cjs

@@ -1610,6 +1610,7 @@ __export(index_exports, {
   getTelegramMe: () => getTelegramMe,
   getTelegramUpdates: () => getTelegramUpdates,
   getTelegramWebhookInfo: () => getTelegramWebhookInfo,
+  getVoiceProvider: () => getVoiceProvider,
   hostSessionStoragePath: () => hostSessionStoragePath,
   inferPhoneRegion: () => inferPhoneRegion,
   invalidateSkillCache: () => invalidateSkillCache,
@@ -1622,6 +1623,7 @@ __export(index_exports, {
   isTelegramStopCommand: () => isTelegramStopCommand,
   isValidPhoneNumber: () => isValidPhoneNumber,
   listSkills: () => listSkills,
+  listVoiceProviders: () => listVoiceProviders,
   loadAgentPersona: () => loadAgentPersona,
   loadHostSession: () => loadHostSession,
   loadSkill: () => loadSkill,
@@ -1650,6 +1652,7 @@ __export(index_exports, {
   redactSecret: () => redactSecret,
   redactSmsConfig: () => redactSmsConfig,
   redactTelegramConfig: () => redactTelegramConfig,
+  registerVoiceProvider: () => registerVoiceProvider,
   renderSkillAsPrompt: () => renderSkillAsPrompt,
   requireBinary: () => requireBinary,
   requireWhisperModel: () => requireWhisperModel,
@@ -1657,6 +1660,7 @@ __export(index_exports, {
   resolveConfig: () => resolveConfig,
   resolveExtensionPolicy: () => resolveExtensionPolicy,
   resolveTlsRejectUnauthorized: () => resolveTlsRejectUnauthorized,
+  resolveVoiceRuntime: () => resolveVoiceRuntime,
   safeJoin: () => safeJoin,
   sanitizeEmail: () => sanitizeEmail,
   saveAgentPersona: () => saveAgentPersona,
@@ -2588,6 +2592,13 @@ function resolveConfig(overrides) {
     dataDir: env.AGENTICMAIL_DATA_DIR?.replace(/^~(?=\/|$)/, (0, import_node_os.homedir)()) ?? DEFAULT_CONFIG.dataDir
   };
   if (env.OPENAI_API_KEY) config.openaiApiKey = env.OPENAI_API_KEY;
+  if (env.XAI_API_KEY) {
+    config.voiceProviderKeys = config.voiceProviderKeys ?? {};
+    config.voiceProviderKeys.grok = env.XAI_API_KEY;
+  }
+  if (env.AGENTICMAIL_VOICE_RUNTIME && env.AGENTICMAIL_VOICE_RUNTIME.trim()) {
+    config.voiceRuntime = env.AGENTICMAIL_VOICE_RUNTIME.trim();
+  }
   const configPath = (0, import_node_path.join)(config.dataDir, "config.json");
   if ((0, import_node_fs.existsSync)(configPath)) {
     try {
@@ -12203,6 +12214,94 @@ function withTimeout(promise, ms) {
   return Promise.race([promise, timeout]).finally(() => clearTimeout(timer));
 }
 
+// src/phone/voice-providers/registry.ts
+var PROVIDERS2 = /* @__PURE__ */ new Map();
+function registerVoiceProvider(provider) {
+  if (PROVIDERS2.has(provider.id)) {
+    throw new Error(`Voice provider "${provider.id}" registered twice \u2014 id collision.`);
+  }
+  PROVIDERS2.set(provider.id, provider);
+}
+function listVoiceProviders() {
+  return Array.from(PROVIDERS2.values());
+}
+function getVoiceProvider(id) {
+  return PROVIDERS2.get(id);
+}
+function resolveVoiceRuntime(providerId, config, options = {}) {
+  const id = (providerId || "openai").trim() || "openai";
+  const provider = PROVIDERS2.get(id);
+  if (!provider) {
+    const known = Array.from(PROVIDERS2.keys()).join(", ") || "(none registered)";
+    throw new Error(
+      `Unknown voice runtime "${id}". Known providers: ${known}. Add a new one by dropping a file into packages/core/src/phone/voice-providers/.`
+    );
+  }
+  let apiKey = "";
+  let apiKeySource = "";
+  if (provider.apiKeyConfigField) {
+    const legacy = config[provider.apiKeyConfigField];
+    if (legacy && legacy.trim()) {
+      apiKey = legacy.trim();
+      apiKeySource = `config.${provider.apiKeyConfigField}`;
+    }
+  }
+  if (!apiKey) {
+    const fromMap = config.voiceProviderKeys?.[provider.id];
+    if (fromMap && fromMap.trim()) {
+      apiKey = fromMap.trim();
+      apiKeySource = `config.voiceProviderKeys.${provider.id}`;
+    }
+  }
+  if (!apiKey) {
+    const fromEnv = process.env[provider.apiKeyEnvVar];
+    if (fromEnv && fromEnv.trim()) {
+      apiKey = fromEnv.trim();
+      apiKeySource = `env ${provider.apiKeyEnvVar}`;
+    }
+  }
+  if (!apiKey) {
+    throw new Error(
+      `Voice provider "${provider.id}" (${provider.displayName}) selected, but no API key is configured. Set ${provider.apiKeyEnvVar} in your environment or save it to ~/.agenticmail/config.json under voiceProviderKeys.${provider.id}.`
+    );
+  }
+  const model = options.model && options.model.trim() || provider.defaultModel;
+  const url = `${provider.websocketBaseUrl}?model=${encodeURIComponent(model)}`;
+  return {
+    providerId: provider.id,
+    providerDisplayName: provider.displayName,
+    url,
+    model,
+    apiKey,
+    apiKeySource
+  };
+}
+
+// src/phone/voice-providers/openai.ts
+registerVoiceProvider({
+  id: "openai",
+  displayName: "OpenAI Realtime (gpt-realtime)",
+  websocketBaseUrl: "wss://api.openai.com/v1/realtime",
+  defaultModel: "gpt-realtime",
+  apiKeyEnvVar: "OPENAI_API_KEY",
+  // Legacy: the original config.json schema used a dedicated
+  // `openaiApiKey` field for this key. The resolver checks that field
+  // before the generic voiceProviderKeys map so existing installs
+  // continue to work without migration.
+  apiKeyConfigField: "openaiApiKey",
+  description: "OpenAI Realtime (gpt-realtime). Default voice runtime; supports linear PCM @ 24 kHz (46elks) and G.711 \xB5-law @ 8 kHz (Twilio) without transcoding."
+});
+
+// src/phone/voice-providers/grok.ts
+registerVoiceProvider({
+  id: "grok",
+  displayName: "xAI Grok Voice Agent",
+  websocketBaseUrl: "wss://api.x.ai/v1/realtime",
+  defaultModel: "grok-voice-latest",
+  apiKeyEnvVar: "XAI_API_KEY",
+  description: 'xAI Grok Voice Agent \u2014 OpenAI-Realtime-compatible WebSocket protocol; select via mission policy.voiceRuntime="grok" or env AGENTICMAIL_VOICE_RUNTIME=grok.'
+});
+
 // src/telemetry.ts
 var import_crypto = require("crypto");
 var import_fs = require("fs");
@@ -16517,6 +16616,7 @@ function saveAgentPersona(agentName, content) {
   getTelegramMe,
   getTelegramUpdates,
   getTelegramWebhookInfo,
+  getVoiceProvider,
   hostSessionStoragePath,
   inferPhoneRegion,
   invalidateSkillCache,
@@ -16529,6 +16629,7 @@ function saveAgentPersona(agentName, content) {
   isTelegramStopCommand,
   isValidPhoneNumber,
   listSkills,
+  listVoiceProviders,
   loadAgentPersona,
   loadHostSession,
   loadSkill,
@@ -16557,6 +16658,7 @@ function saveAgentPersona(agentName, content) {
   redactSecret,
   redactSmsConfig,
   redactTelegramConfig,
+  registerVoiceProvider,
   renderSkillAsPrompt,
   requireBinary,
   requireWhisperModel,
@@ -16564,6 +16666,7 @@ function saveAgentPersona(agentName, content) {
   resolveConfig,
   resolveExtensionPolicy,
   resolveTlsRejectUnauthorized,
+  resolveVoiceRuntime,
   safeJoin,
   sanitizeEmail,
   saveAgentPersona,

package/dist/index.d.cts

@@ -229,6 +229,22 @@ interface AgenticMailConfig {
      * `config.json`. Optional — no other feature depends on it.
      */
     openaiApiKey?: string;
+    /**
+     * v0.9.93 — voice-runtime provider keys. Each is a thin Bearer-token
+     * for a provider's realtime API; required only when that provider
+     * is selected as the runtime for a call. New providers register
+     * themselves in `packages/core/src/phone/voice-providers/` and
+     * declare which key field they consume — this record is the central
+     * pool. Read from per-provider env vars (e.g. `XAI_API_KEY`) at boot.
+     */
+    voiceProviderKeys?: Record<string, string>;
+    /**
+     * v0.9.93 — default voice-runtime provider id for phone missions
+     * that don't pin one on their own policy. `'openai'` (the existing
+     * default) or any provider registered in `voice-providers/`.
+     * Read from `AGENTICMAIL_VOICE_RUNTIME` env var or `config.json`.
+     */
+    voiceRuntime?: string;
     masterKey: string;
     dataDir: string;
 }
@@ -3824,6 +3840,127 @@ declare class RealtimeVoiceBridge {
     private safeSend;
 }
 
+/**
+ * Voice-runtime provider plugin interface.
+ *
+ * Each backend (OpenAI Realtime, Grok Voice Agent, future Anthropic
+ * realtime, Cartesia, ElevenLabs ConvAI, etc.) lives in its own file
+ * under `packages/core/src/phone/voice-providers/` and registers
+ * itself with the registry by calling {@link registerVoiceProvider}
+ * at module load.
+ *
+ * Adding a new provider is meant to be a literal FILE DROP:
+ *
+ *   1. Create `voice-providers/<id>.ts` exporting a {@link VoiceProvider}.
+ *   2. Add a single `import './<id>.js';` line to `voice-providers/index.ts`
+ *      so the side-effect registration runs.
+ *   3. (Optional) document the env var the provider expects.
+ *
+ * No other file in the codebase needs to know about the new provider —
+ * the realtime bridge looks providers up by id through the registry.
+ *
+ * Currently every supported provider is an OpenAI-Realtime-compatible
+ * WebSocket. If a future provider diverges enough to need its own wire
+ * protocol (custom event shape, gRPC, WebRTC SDP, etc.), the seam to
+ * extend is here: add `buildSessionUpdate` / `parseInboundEvent` /
+ * etc. hooks to {@link VoiceProvider}, then make `realtime-bridge.ts`
+ * route through them instead of speaking OpenAI Realtime directly.
+ */
+/**
+ * One voice-runtime provider. Carries enough information for the
+ * bridge to open the right WebSocket with the right auth + model.
+ */
+interface VoiceProvider {
+    /**
+     * Stable identifier used in mission policy / config (`'openai'`,
+     * `'grok'`, …). Keep lowercase, no spaces — this is what operators
+     * type into `AGENTICMAIL_VOICE_RUNTIME=` or pass via mission policy.
+     */
+    id: string;
+    /** Human-readable display name for logs + the web UI. */
+    displayName: string;
+    /** WebSocket base URL (the bridge appends `?model=…`). */
+    websocketBaseUrl: string;
+    /**
+     * Default model when the caller doesn't pin one. Sent as the
+     * `?model=…` query string AND echoed in the session.update.
+     */
+    defaultModel: string;
+    /**
+     * The env var the operator sets for this provider's API key
+     * (`OPENAI_API_KEY`, `XAI_API_KEY`, …). The bootstrap / config
+     * loader reads from this name and stores into
+     * `AgenticMailConfig.voiceProviderKeys[<id>]`. Used in the
+     * "you didn't set the key" error message too.
+     */
+    apiKeyEnvVar: string;
+    /**
+     * Optional fallback config-field name. When the provider's API key
+     * has a long-standing dedicated config field (e.g. OpenAI's
+     * `config.openaiApiKey`), this lets the resolver check that field
+     * BEFORE looking in the generic `voiceProviderKeys` map — so
+     * existing installs don't need to migrate. Leave undefined for
+     * new providers.
+     */
+    apiKeyConfigField?: 'openaiApiKey';
+    /**
+     * Per-provider notes that surface in error / boot-log messages.
+     * Optional — defaults are fine for the standard providers.
+     */
+    description?: string;
+}
+/**
+ * The bridge needs all the inputs needed to open a session in one
+ * resolved struct — URL with model encoded, the API key, the source
+ * for logging. {@link resolveVoiceRuntime} produces this.
+ */
+interface VoiceRuntimeConnection {
+    providerId: string;
+    providerDisplayName: string;
+    /** Full WebSocket URL including `?model=…`. */
+    url: string;
+    /** Resolved model name (also passed in the URL). */
+    model: string;
+    /** Bearer token for the `Authorization` header. */
+    apiKey: string;
+    /** Human-readable source of the key, for boot logs only (e.g. `"env XAI_API_KEY"`). */
+    apiKeySource: string;
+}
+
+/**
+ * Voice-provider registry — drop-in plugin discovery.
+ *
+ * Providers register themselves at module-load time via
+ * {@link registerVoiceProvider}. The barrel `voice-providers/index.ts`
+ * imports each provider file for its side effect, populating this map
+ * before any caller asks for one.
+ *
+ * No reflection, no filesystem scan, no decorator magic — adding a
+ * provider is "create a file + add one import line". That gives us
+ * both first-class TypeScript types AND the file-drop ergonomics.
+ */
+
+/**
+ * Register a provider. Called once per file at module load. Throws on
+ * duplicate id so an accidental copy-paste collision is loud, not
+ * silently overriding.
+ */
+declare function registerVoiceProvider(provider: VoiceProvider): void;
+/** All registered providers — for `agenticmail voice list` / web UI menus. */
+declare function listVoiceProviders(): VoiceProvider[];
+/** Look up a provider by id. Returns undefined for unknown ids. */
+declare function getVoiceProvider(id: string): VoiceProvider | undefined;
+/**
+ * Resolve a provider id + the runtime's config / overrides into the
+ * connection struct the bridge consumes (URL with model, api key,
+ * source). Throws if the provider id is unknown or its API key isn't
+ * configured — the realtime-ws layer turns the throw into a clear
+ * startup error instead of a mid-call surprise.
+ */
+declare function resolveVoiceRuntime(providerId: string | undefined, config: AgenticMailConfig, options?: {
+    model?: string;
+}): VoiceRuntimeConnection;
+
 type PhoneTransportProvider = '46elks' | 'twilio';
 /** Providers that support starting outbound call-control missions. */
 declare const PHONE_CALL_CONTROL_PROVIDERS: readonly PhoneTransportProvider[];
@@ -6248,4 +6385,4 @@ declare function loadAgentPersona(agentName: string): string;
  */
 declare function saveAgentPersona(agentName: string, content: string): string;
 
-export { AGENT_ROLES, AGENT_STATE_ROOT, ASK_OPERATOR_TOOL, AccountManager, type AddressInfo, type Agent, AgentDeletionService, type AgentMemoryEntry, type AgentMemoryFields, AgentMemoryManager, type AgentMemoryOptions, type AgentMemoryRead, AgentMemoryStore, type AgentRole, AgenticMailClient, type AgenticMailClientOptions, type AgenticMailConfig, type ArchiveAndDeleteOptions, type ArchivedEmail, type Attachment, type AttachmentAdvisory, type AudioAction, type AudioEditOptions, BRIDGE_OPERATOR_LIVE_WINDOW_MS, type BridgeMailContext, type BridgeWakeError, type BridgeWakePromptArgs, type BridgeWakeResult, type BridgeWakeRoute, type CachedMessage, CloudflareClient, type CreateAgentOptions, type CreateMemoryInput, DEFAULT_AGENT_NAME, DEFAULT_AGENT_ROLE, DEFAULT_CALLBACK_POLICY, DEFAULT_EXTENSION_POLICY, DEFAULT_REALTIME_AUDIO_FORMAT, DEFAULT_REALTIME_MODEL, DEFAULT_REALTIME_VOICE, DEFAULT_SESSION_MAX_AGE_MS, DEFAULT_WEB_SEARCH_ENDPOINT, DNSConfigurator, type Database, type DeletionReport, type DeletionSummary, DependencyChecker, DependencyInstaller, type DependencyStatus, type DnsRecord, type DnsSetupResult, type DomainInfo, DomainManager, type DomainModeConfig, type DomainPurchaseResult, DomainPurchaser, type DomainSearchResult, type DomainSetupResult, ELKS_REALTIME_AUDIO_FORMATS, ELKS_REALTIME_WS_PATH, END_CALL_TOOL, EXTEND_CALL_TIME_TOOL, type ElksRealtimeAudioFormat, type ElksRealtimeAudioMessage, type ElksRealtimeByeMessage, type ElksRealtimeHelloMessage, type ElksRealtimeInboundMessage, type ElksRealtimeOutboundMessage, ElksRealtimeTransport, type EmailEnvelope, type EmailRouteAction, type EmailRouteClass, type EmailRouteClassification, type EmailRouteInput, EmailSearchIndex, type FolderInfo, GET_CALL_STATUS_TOOL, GET_DATETIME_TOOL, type GatewayConfig, GatewayManager, type GatewayManagerOptions, type GatewayMode, type GatewayStatus, type GetDatetimeOptions, type GetUpdatesOptions, type HostName, type HostSession, type HostSessionResumeMode, type ImageAction, type ImageEditOptions, type InboundEmail, type InboundSmsEvent, type InboxEvent, type InboxExpungeEvent, type InboxFlagsEvent, type InboxNewEvent, InboxWatcher, type InboxWatcherOptions, type InstallProgress, LOAD_SKILL_TOOL, type LinkAdvisory, type LocalSmtpConfig, MEMORY_CATEGORIES, MailReceiver, type MailReceiverOptions, MailSender, type MailSenderOptions, type MailboxInfo, type MediaBinary, type MediaCapability, type MediaCapabilityReport, type MediaFileResult, type MediaInfoResult, MediaManager, type MediaManagerOptions, type MediaStreamInfo, type MemoryCategory, type MemoryImportance, type MemoryQueryOptions, type MemoryRecaller, MemorySearchIndex, type MemorySource, type MemoryStats, OPENAI_REALTIME_URL, OPERATOR_QUERY_POLL_INTERVAL_MS, OPERATOR_QUERY_SUBJECT_TAG, OPERATOR_QUERY_TIMEOUT_MS, OPERATOR_QUERY_TIMEOUT_SENTINEL, type OpenClawPhoneMissionPolicy, type OperatorQueryNotificationInput, type OperatorQueryPollOptions, type OperatorQueryUrgency, type OperatorReplyKind, type OutboundCategory, type OutboundScanInput, type OutboundScanResult, type OutboundWarning, PERSONA_FILENAME, PHONE_CALLBACK_MAX_DELAY_SECONDS, PHONE_CALLBACK_MIN_DELAY_SECONDS, PHONE_CALL_CONTROL_PROVIDERS, PHONE_MAX_CONCURRENT_MISSIONS, PHONE_MIN_WEBHOOK_SECRET_LENGTH, PHONE_MISSION_STATES, PHONE_RATE_LIMIT_PER_HOUR, PHONE_RATE_LIMIT_PER_MINUTE, PHONE_REGION_SCOPES, PHONE_SERVER_MAX_ATTEMPTS, PHONE_SERVER_MAX_CALLBACK_CHAIN, PHONE_SERVER_MAX_CALL_DURATION_SECONDS, PHONE_SERVER_MAX_COST_PER_MISSION, PHONE_SERVER_MAX_EXTENSION_REQUESTS_PER_CALL, PHONE_SERVER_MAX_EXTENSION_SECONDS_PER_REQUEST, PHONE_SERVER_MAX_TOTAL_EXTENSION_SECONDS, PHONE_TASK_MAX_LENGTH, type ParsedAttachment, type ParsedEmail, type ParsedOperatorReply, type ParsedSms, type ParsedTelegramMessage, PathTraversalError, type PhoneAlternativePolicy, type PhoneCallMission, type PhoneCallbackPolicy, type PhoneConfirmPolicy, type PhoneExtensionPolicy, PhoneManager, type PhoneMissionStartValidationResult, type PhoneMissionState, type PhoneMissionTranscriptEntry, type PhoneMissionValidationIssue, type PhoneMissionValidationResult, type PhoneNumberRisk, type PhoneOperatorQuery, PhoneRateLimitError, type PhoneRegionScope, type PhoneScheduledCallback, type PhoneTransportConfig, type PhoneTransportProfile, type PhoneTransportProvider, type PhoneTransportValidationResult, PhoneWebhookAuthError, type PhoneWebhookResult, type PlanBridgeWakeArgs, type PurchasedDomain, REALTIME_AUDIO_SAMPLE_RATE, REALTIME_MAX_AUDIO_FRAME_BASE64, REALTIME_TOOL_CALL_TIMEOUT_MS, REALTIME_TOOL_DEFINITIONS, RECALL_MEMORY_TOOL, REDACTED, RELAY_PRESETS, type RealtimeBridgePort, type RealtimeBridgeTranscriptEntry, type RealtimeInboundEvent, type RealtimeInstructionOptions, type RealtimeSessionConfigOptions, type RealtimeToolCall, type RealtimeToolDefinition, type RealtimeToolHandler, type RealtimeToolResult, type RealtimeTransportAdapter, type RealtimeTransportProvider, RealtimeVoiceBridge, type RealtimeVoiceBridgeOptions, RelayBridge, type RelayBridgeOptions, type RelayConfig, RelayGateway, type RelayProvider, type RelaySearchResult, type ResumeErrorClassificationOptions, SCHEDULE_CALLBACK_TOOL, SEARCH_EMAIL_TOOL, SEARCH_SKILLS_TOOL, SPAM_THRESHOLD, type SafeJoinOptions, type SanitizeDetection, type SanitizeResult, type ScheduledCallbackRequest, type SearchCriteria, type SearchableEmail, type SecurityAdvisory, type SendMailOptions, type SendResult, type SendResultWithRaw, type SendSmsInput, type SendSmsResult, type SendTelegramMessageOptions, type SendTelegramMessageResult, ServiceManager, type ServiceStatus, type SetWebhookOptions, type SetupConfig, SetupManager, type SetupResult, type Severity, type Skill, type SkillCategory, type SkillContext, type SkillExitStrategy, type SkillSummary, type SkillTactic, type SkillValidationError, type SmsConfig, SmsManager, type SmsMessage, SmsPoller, type SmsProvider, type SpamCategory, type SpamResult, type SpamRuleMatch, StalwartAdmin, type StalwartAdminOptions, type StalwartPrincipal, type StartPhoneCallOptions, type StartPhoneCallResult, type StartPhoneMissionInput, TELEGRAM_API_BASE, TELEGRAM_CHUNK_SIZE, TELEGRAM_MESSAGE_LIMIT, TELEGRAM_MIN_WEBHOOK_SECRET_LENGTH, TELEGRAM_OPERATOR_QUERY_TAG, TELEGRAM_STOP_WORDS, TELEGRAM_WEBHOOK_SECRET_RE, TELEPHONY_TRANSPORT_CAPABILITIES, TWILIO_MEDIA_SAMPLE_RATE, TWILIO_REALTIME_WS_PATH, TelegramApiError, type TelegramApiOptions, type TelegramBotInfo, type TelegramChatType, type TelegramConfig, TelegramManager, type TelegramMessage, type TelegramMode, type TelephonyTransportCapability, ThreadCache, type ThreadCacheEntry, type ThreadCacheOptions, type ThreadIdInput, type ToolExecutor, type TtsGenerateOptions, type TunnelConfig, TunnelManager, type TwilioConnectedMessage, type TwilioMarkMessage, type TwilioMediaMessage, type TwilioRealtimeInboundMessage, type TwilioRealtimeOutboundMessage, TwilioRealtimeTransport, type TwilioStartMessage, type TwilioStopMessage, type TwilioStreamTwiMLOptions, UnsafeApiUrlError, type UpdateMemoryInput, type ValidatedPhoneMissionStart, type VideoAction, type VideoEditOptions, type VideoTimelineEntry, type VideoUnderstandOptions, type VideoUnderstandResult, type VoiceCloneOptions, WARNING_THRESHOLD, WEB_SEARCH_TOOL, WEB_SEARCH_UNTRUSTED_PREFIX, type WatcherOptions, type WebSearchOptions, assertWithinBase, bridgeWakeErrorMessage, bridgeWakeLastSeenAgeMs, buildApiUrl, buildDefaultPersona, buildElksAudioMessage, buildElksByeMessage, buildElksHandshakeMessages, buildElksInterruptMessage, buildElksListeningMessage, buildElksSendingMessage, buildInboundSecurityAdvisory, buildOpenAIRealtimeUrl, buildPhoneTransportConfig, buildRealtimeInstructions, buildRealtimeSessionConfig, buildRealtimeToolGuidance, buildTwilioClearMessage, buildTwilioMarkMessage, buildTwilioMediaMessage, buildTwilioSayTwiML, buildTwilioSignature, buildTwilioStreamTwiML, callTelegramApi, classifyEmailRoute, classifyPhoneNumberRisk, classifyResumeError, clearMediaCapabilityCache, closeDatabase, composeBridgeWakePrompt, createRealtimeTransport, createTestDatabase, createToolExecutor, debug, debugWarn, deleteTelegramWebhook, detectBinary, ensureDataDir, escapeXml, extractEmailAddress, extractVerificationCode, flushTelemetry, forgetHostSession, formatOperatorQueryTelegramMessage, getDatabase, getDatetime, getMediaCapabilities, getOperatorEmail, getSmsProvider, getTelegramChat, getTelegramMe, getTelegramUpdates, getTelegramWebhookInfo, hostSessionStoragePath, inferPhoneRegion, invalidateSkillCache, isInternalEmail, isLoopbackMailHost, isOperatorReplySender, isPhoneRegionAllowed, isSessionFresh, isTelegramChatAllowed, isTelegramStopCommand, isValidPhoneNumber, listSkills, loadAgentPersona, loadHostSession, loadSkill, mapProviderSmsStatus, nextTelegramOffset, normalizeAddress, normalizePhoneNumber, normalizeSubject, operatorPrefsStoragePath, operatorQuerySubject, parseElksRealtimeMessage, parseEmail, parseGoogleVoiceSms, parseOperatorQueryReply, parseTelegramOperatorReply, parseTelegramUpdate, parseTwilioRealtimeMessage, personaPathFor, planBridgeWake, pollForOperatorAnswer, recallMemory, recordToolCall, redactBotToken, redactObject, redactPhoneTransportConfig, redactSecret, redactSmsConfig, redactTelegramConfig, renderSkillAsPrompt, requireBinary, requireWhisperModel, resolveCallbackPolicy, resolveConfig, resolveExtensionPolicy, resolveTlsRejectUnauthorized, safeJoin, sanitizeEmail, saveAgentPersona, saveConfig, saveHostSession, saveUserSkill, scanOutboundEmail, scoreEmail, searchSkills, sendTelegramMessage, setOperatorEmail, setTelegramWebhook, setTelemetryVersion, shouldSkipBridgeWakeForLiveOperator, splitTelegramMessage, startRelayBridge, stem, stripTelegramMarkdown, threadIdFor, tokenize, tryJoin, userSkillsDir, validateApiUrl, validatePhoneMissionPolicy, validatePhoneMissionStart, validatePhoneTransportProfile, validateSkill, validateTwilioSignature, webSearch };
+export { AGENT_ROLES, AGENT_STATE_ROOT, ASK_OPERATOR_TOOL, AccountManager, type AddressInfo, type Agent, AgentDeletionService, type AgentMemoryEntry, type AgentMemoryFields, AgentMemoryManager, type AgentMemoryOptions, type AgentMemoryRead, AgentMemoryStore, type AgentRole, AgenticMailClient, type AgenticMailClientOptions, type AgenticMailConfig, type ArchiveAndDeleteOptions, type ArchivedEmail, type Attachment, type AttachmentAdvisory, type AudioAction, type AudioEditOptions, BRIDGE_OPERATOR_LIVE_WINDOW_MS, type BridgeMailContext, type BridgeWakeError, type BridgeWakePromptArgs, type BridgeWakeResult, type BridgeWakeRoute, type CachedMessage, CloudflareClient, type CreateAgentOptions, type CreateMemoryInput, DEFAULT_AGENT_NAME, DEFAULT_AGENT_ROLE, DEFAULT_CALLBACK_POLICY, DEFAULT_EXTENSION_POLICY, DEFAULT_REALTIME_AUDIO_FORMAT, DEFAULT_REALTIME_MODEL, DEFAULT_REALTIME_VOICE, DEFAULT_SESSION_MAX_AGE_MS, DEFAULT_WEB_SEARCH_ENDPOINT, DNSConfigurator, type Database, type DeletionReport, type DeletionSummary, DependencyChecker, DependencyInstaller, type DependencyStatus, type DnsRecord, type DnsSetupResult, type DomainInfo, DomainManager, type DomainModeConfig, type DomainPurchaseResult, DomainPurchaser, type DomainSearchResult, type DomainSetupResult, ELKS_REALTIME_AUDIO_FORMATS, ELKS_REALTIME_WS_PATH, END_CALL_TOOL, EXTEND_CALL_TIME_TOOL, type ElksRealtimeAudioFormat, type ElksRealtimeAudioMessage, type ElksRealtimeByeMessage, type ElksRealtimeHelloMessage, type ElksRealtimeInboundMessage, type ElksRealtimeOutboundMessage, ElksRealtimeTransport, type EmailEnvelope, type EmailRouteAction, type EmailRouteClass, type EmailRouteClassification, type EmailRouteInput, EmailSearchIndex, type FolderInfo, GET_CALL_STATUS_TOOL, GET_DATETIME_TOOL, type GatewayConfig, GatewayManager, type GatewayManagerOptions, type GatewayMode, type GatewayStatus, type GetDatetimeOptions, type GetUpdatesOptions, type HostName, type HostSession, type HostSessionResumeMode, type ImageAction, type ImageEditOptions, type InboundEmail, type InboundSmsEvent, type InboxEvent, type InboxExpungeEvent, type InboxFlagsEvent, type InboxNewEvent, InboxWatcher, type InboxWatcherOptions, type InstallProgress, LOAD_SKILL_TOOL, type LinkAdvisory, type LocalSmtpConfig, MEMORY_CATEGORIES, MailReceiver, type MailReceiverOptions, MailSender, type MailSenderOptions, type MailboxInfo, type MediaBinary, type MediaCapability, type MediaCapabilityReport, type MediaFileResult, type MediaInfoResult, MediaManager, type MediaManagerOptions, type MediaStreamInfo, type MemoryCategory, type MemoryImportance, type MemoryQueryOptions, type MemoryRecaller, MemorySearchIndex, type MemorySource, type MemoryStats, OPENAI_REALTIME_URL, OPERATOR_QUERY_POLL_INTERVAL_MS, OPERATOR_QUERY_SUBJECT_TAG, OPERATOR_QUERY_TIMEOUT_MS, OPERATOR_QUERY_TIMEOUT_SENTINEL, type OpenClawPhoneMissionPolicy, type OperatorQueryNotificationInput, type OperatorQueryPollOptions, type OperatorQueryUrgency, type OperatorReplyKind, type OutboundCategory, type OutboundScanInput, type OutboundScanResult, type OutboundWarning, PERSONA_FILENAME, PHONE_CALLBACK_MAX_DELAY_SECONDS, PHONE_CALLBACK_MIN_DELAY_SECONDS, PHONE_CALL_CONTROL_PROVIDERS, PHONE_MAX_CONCURRENT_MISSIONS, PHONE_MIN_WEBHOOK_SECRET_LENGTH, PHONE_MISSION_STATES, PHONE_RATE_LIMIT_PER_HOUR, PHONE_RATE_LIMIT_PER_MINUTE, PHONE_REGION_SCOPES, PHONE_SERVER_MAX_ATTEMPTS, PHONE_SERVER_MAX_CALLBACK_CHAIN, PHONE_SERVER_MAX_CALL_DURATION_SECONDS, PHONE_SERVER_MAX_COST_PER_MISSION, PHONE_SERVER_MAX_EXTENSION_REQUESTS_PER_CALL, PHONE_SERVER_MAX_EXTENSION_SECONDS_PER_REQUEST, PHONE_SERVER_MAX_TOTAL_EXTENSION_SECONDS, PHONE_TASK_MAX_LENGTH, type ParsedAttachment, type ParsedEmail, type ParsedOperatorReply, type ParsedSms, type ParsedTelegramMessage, PathTraversalError, type PhoneAlternativePolicy, type PhoneCallMission, type PhoneCallbackPolicy, type PhoneConfirmPolicy, type PhoneExtensionPolicy, PhoneManager, type PhoneMissionStartValidationResult, type PhoneMissionState, type PhoneMissionTranscriptEntry, type PhoneMissionValidationIssue, type PhoneMissionValidationResult, type PhoneNumberRisk, type PhoneOperatorQuery, PhoneRateLimitError, type PhoneRegionScope, type PhoneScheduledCallback, type PhoneTransportConfig, type PhoneTransportProfile, type PhoneTransportProvider, type PhoneTransportValidationResult, PhoneWebhookAuthError, type PhoneWebhookResult, type PlanBridgeWakeArgs, type PurchasedDomain, REALTIME_AUDIO_SAMPLE_RATE, REALTIME_MAX_AUDIO_FRAME_BASE64, REALTIME_TOOL_CALL_TIMEOUT_MS, REALTIME_TOOL_DEFINITIONS, RECALL_MEMORY_TOOL, REDACTED, RELAY_PRESETS, type RealtimeBridgePort, type RealtimeBridgeTranscriptEntry, type RealtimeInboundEvent, type RealtimeInstructionOptions, type RealtimeSessionConfigOptions, type RealtimeToolCall, type RealtimeToolDefinition, type RealtimeToolHandler, type RealtimeToolResult, type RealtimeTransportAdapter, type RealtimeTransportProvider, RealtimeVoiceBridge, type RealtimeVoiceBridgeOptions, RelayBridge, type RelayBridgeOptions, type RelayConfig, RelayGateway, type RelayProvider, type RelaySearchResult, type ResumeErrorClassificationOptions, SCHEDULE_CALLBACK_TOOL, SEARCH_EMAIL_TOOL, SEARCH_SKILLS_TOOL, SPAM_THRESHOLD, type SafeJoinOptions, type SanitizeDetection, type SanitizeResult, type ScheduledCallbackRequest, type SearchCriteria, type SearchableEmail, type SecurityAdvisory, type SendMailOptions, type SendResult, type SendResultWithRaw, type SendSmsInput, type SendSmsResult, type SendTelegramMessageOptions, type SendTelegramMessageResult, ServiceManager, type ServiceStatus, type SetWebhookOptions, type SetupConfig, SetupManager, type SetupResult, type Severity, type Skill, type SkillCategory, type SkillContext, type SkillExitStrategy, type SkillSummary, type SkillTactic, type SkillValidationError, type SmsConfig, SmsManager, type SmsMessage, SmsPoller, type SmsProvider, type SpamCategory, type SpamResult, type SpamRuleMatch, StalwartAdmin, type StalwartAdminOptions, type StalwartPrincipal, type StartPhoneCallOptions, type StartPhoneCallResult, type StartPhoneMissionInput, TELEGRAM_API_BASE, TELEGRAM_CHUNK_SIZE, TELEGRAM_MESSAGE_LIMIT, TELEGRAM_MIN_WEBHOOK_SECRET_LENGTH, TELEGRAM_OPERATOR_QUERY_TAG, TELEGRAM_STOP_WORDS, TELEGRAM_WEBHOOK_SECRET_RE, TELEPHONY_TRANSPORT_CAPABILITIES, TWILIO_MEDIA_SAMPLE_RATE, TWILIO_REALTIME_WS_PATH, TelegramApiError, type TelegramApiOptions, type TelegramBotInfo, type TelegramChatType, type TelegramConfig, TelegramManager, type TelegramMessage, type TelegramMode, type TelephonyTransportCapability, ThreadCache, type ThreadCacheEntry, type ThreadCacheOptions, type ThreadIdInput, type ToolExecutor, type TtsGenerateOptions, type TunnelConfig, TunnelManager, type TwilioConnectedMessage, type TwilioMarkMessage, type TwilioMediaMessage, type TwilioRealtimeInboundMessage, type TwilioRealtimeOutboundMessage, TwilioRealtimeTransport, type TwilioStartMessage, type TwilioStopMessage, type TwilioStreamTwiMLOptions, UnsafeApiUrlError, type UpdateMemoryInput, type ValidatedPhoneMissionStart, type VideoAction, type VideoEditOptions, type VideoTimelineEntry, type VideoUnderstandOptions, type VideoUnderstandResult, type VoiceCloneOptions, type VoiceProvider, type VoiceRuntimeConnection, WARNING_THRESHOLD, WEB_SEARCH_TOOL, WEB_SEARCH_UNTRUSTED_PREFIX, type WatcherOptions, type WebSearchOptions, assertWithinBase, bridgeWakeErrorMessage, bridgeWakeLastSeenAgeMs, buildApiUrl, buildDefaultPersona, buildElksAudioMessage, buildElksByeMessage, buildElksHandshakeMessages, buildElksInterruptMessage, buildElksListeningMessage, buildElksSendingMessage, buildInboundSecurityAdvisory, buildOpenAIRealtimeUrl, buildPhoneTransportConfig, buildRealtimeInstructions, buildRealtimeSessionConfig, buildRealtimeToolGuidance, buildTwilioClearMessage, buildTwilioMarkMessage, buildTwilioMediaMessage, buildTwilioSayTwiML, buildTwilioSignature, buildTwilioStreamTwiML, callTelegramApi, classifyEmailRoute, classifyPhoneNumberRisk, classifyResumeError, clearMediaCapabilityCache, closeDatabase, composeBridgeWakePrompt, createRealtimeTransport, createTestDatabase, createToolExecutor, debug, debugWarn, deleteTelegramWebhook, detectBinary, ensureDataDir, escapeXml, extractEmailAddress, extractVerificationCode, flushTelemetry, forgetHostSession, formatOperatorQueryTelegramMessage, getDatabase, getDatetime, getMediaCapabilities, getOperatorEmail, getSmsProvider, getTelegramChat, getTelegramMe, getTelegramUpdates, getTelegramWebhookInfo, getVoiceProvider, hostSessionStoragePath, inferPhoneRegion, invalidateSkillCache, isInternalEmail, isLoopbackMailHost, isOperatorReplySender, isPhoneRegionAllowed, isSessionFresh, isTelegramChatAllowed, isTelegramStopCommand, isValidPhoneNumber, listSkills, listVoiceProviders, loadAgentPersona, loadHostSession, loadSkill, mapProviderSmsStatus, nextTelegramOffset, normalizeAddress, normalizePhoneNumber, normalizeSubject, operatorPrefsStoragePath, operatorQuerySubject, parseElksRealtimeMessage, parseEmail, parseGoogleVoiceSms, parseOperatorQueryReply, parseTelegramOperatorReply, parseTelegramUpdate, parseTwilioRealtimeMessage, personaPathFor, planBridgeWake, pollForOperatorAnswer, recallMemory, recordToolCall, redactBotToken, redactObject, redactPhoneTransportConfig, redactSecret, redactSmsConfig, redactTelegramConfig, registerVoiceProvider, renderSkillAsPrompt, requireBinary, requireWhisperModel, resolveCallbackPolicy, resolveConfig, resolveExtensionPolicy, resolveTlsRejectUnauthorized, resolveVoiceRuntime, safeJoin, sanitizeEmail, saveAgentPersona, saveConfig, saveHostSession, saveUserSkill, scanOutboundEmail, scoreEmail, searchSkills, sendTelegramMessage, setOperatorEmail, setTelegramWebhook, setTelemetryVersion, shouldSkipBridgeWakeForLiveOperator, splitTelegramMessage, startRelayBridge, stem, stripTelegramMarkdown, threadIdFor, tokenize, tryJoin, userSkillsDir, validateApiUrl, validatePhoneMissionPolicy, validatePhoneMissionStart, validatePhoneTransportProfile, validateSkill, validateTwilioSignature, webSearch };

package/dist/index.d.ts

@@ -229,6 +229,22 @@ interface AgenticMailConfig {
      * `config.json`. Optional — no other feature depends on it.
      */
     openaiApiKey?: string;
+    /**
+     * v0.9.93 — voice-runtime provider keys. Each is a thin Bearer-token
+     * for a provider's realtime API; required only when that provider
+     * is selected as the runtime for a call. New providers register
+     * themselves in `packages/core/src/phone/voice-providers/` and
+     * declare which key field they consume — this record is the central
+     * pool. Read from per-provider env vars (e.g. `XAI_API_KEY`) at boot.
+     */
+    voiceProviderKeys?: Record<string, string>;
+    /**
+     * v0.9.93 — default voice-runtime provider id for phone missions
+     * that don't pin one on their own policy. `'openai'` (the existing
+     * default) or any provider registered in `voice-providers/`.
+     * Read from `AGENTICMAIL_VOICE_RUNTIME` env var or `config.json`.
+     */
+    voiceRuntime?: string;
     masterKey: string;
     dataDir: string;
 }
@@ -3824,6 +3840,127 @@ declare class RealtimeVoiceBridge {
     private safeSend;
 }
 
+/**
+ * Voice-runtime provider plugin interface.
+ *
+ * Each backend (OpenAI Realtime, Grok Voice Agent, future Anthropic
+ * realtime, Cartesia, ElevenLabs ConvAI, etc.) lives in its own file
+ * under `packages/core/src/phone/voice-providers/` and registers
+ * itself with the registry by calling {@link registerVoiceProvider}
+ * at module load.
+ *
+ * Adding a new provider is meant to be a literal FILE DROP:
+ *
+ *   1. Create `voice-providers/<id>.ts` exporting a {@link VoiceProvider}.
+ *   2. Add a single `import './<id>.js';` line to `voice-providers/index.ts`
+ *      so the side-effect registration runs.
+ *   3. (Optional) document the env var the provider expects.
+ *
+ * No other file in the codebase needs to know about the new provider —
+ * the realtime bridge looks providers up by id through the registry.
+ *
+ * Currently every supported provider is an OpenAI-Realtime-compatible
+ * WebSocket. If a future provider diverges enough to need its own wire
+ * protocol (custom event shape, gRPC, WebRTC SDP, etc.), the seam to
+ * extend is here: add `buildSessionUpdate` / `parseInboundEvent` /
+ * etc. hooks to {@link VoiceProvider}, then make `realtime-bridge.ts`
+ * route through them instead of speaking OpenAI Realtime directly.
+ */
+/**
+ * One voice-runtime provider. Carries enough information for the
+ * bridge to open the right WebSocket with the right auth + model.
+ */
+interface VoiceProvider {
+    /**
+     * Stable identifier used in mission policy / config (`'openai'`,
+     * `'grok'`, …). Keep lowercase, no spaces — this is what operators
+     * type into `AGENTICMAIL_VOICE_RUNTIME=` or pass via mission policy.
+     */
+    id: string;
+    /** Human-readable display name for logs + the web UI. */
+    displayName: string;
+    /** WebSocket base URL (the bridge appends `?model=…`). */
+    websocketBaseUrl: string;
+    /**
+     * Default model when the caller doesn't pin one. Sent as the
+     * `?model=…` query string AND echoed in the session.update.
+     */
+    defaultModel: string;
+    /**
+     * The env var the operator sets for this provider's API key
+     * (`OPENAI_API_KEY`, `XAI_API_KEY`, …). The bootstrap / config
+     * loader reads from this name and stores into
+     * `AgenticMailConfig.voiceProviderKeys[<id>]`. Used in the
+     * "you didn't set the key" error message too.
+     */
+    apiKeyEnvVar: string;
+    /**
+     * Optional fallback config-field name. When the provider's API key
+     * has a long-standing dedicated config field (e.g. OpenAI's
+     * `config.openaiApiKey`), this lets the resolver check that field
+     * BEFORE looking in the generic `voiceProviderKeys` map — so
+     * existing installs don't need to migrate. Leave undefined for
+     * new providers.
+     */
+    apiKeyConfigField?: 'openaiApiKey';
+    /**
+     * Per-provider notes that surface in error / boot-log messages.
+     * Optional — defaults are fine for the standard providers.
+     */
+    description?: string;
+}
+/**
+ * The bridge needs all the inputs needed to open a session in one
+ * resolved struct — URL with model encoded, the API key, the source
+ * for logging. {@link resolveVoiceRuntime} produces this.
+ */
+interface VoiceRuntimeConnection {
+    providerId: string;
+    providerDisplayName: string;
+    /** Full WebSocket URL including `?model=…`. */
+    url: string;
+    /** Resolved model name (also passed in the URL). */
+    model: string;
+    /** Bearer token for the `Authorization` header. */
+    apiKey: string;
+    /** Human-readable source of the key, for boot logs only (e.g. `"env XAI_API_KEY"`). */
+    apiKeySource: string;
+}
+
+/**
+ * Voice-provider registry — drop-in plugin discovery.
+ *
+ * Providers register themselves at module-load time via
+ * {@link registerVoiceProvider}. The barrel `voice-providers/index.ts`
+ * imports each provider file for its side effect, populating this map
+ * before any caller asks for one.
+ *
+ * No reflection, no filesystem scan, no decorator magic — adding a
+ * provider is "create a file + add one import line". That gives us
+ * both first-class TypeScript types AND the file-drop ergonomics.
+ */
+
+/**
+ * Register a provider. Called once per file at module load. Throws on
+ * duplicate id so an accidental copy-paste collision is loud, not
+ * silently overriding.
+ */
+declare function registerVoiceProvider(provider: VoiceProvider): void;
+/** All registered providers — for `agenticmail voice list` / web UI menus. */
+declare function listVoiceProviders(): VoiceProvider[];
+/** Look up a provider by id. Returns undefined for unknown ids. */
+declare function getVoiceProvider(id: string): VoiceProvider | undefined;
+/**
+ * Resolve a provider id + the runtime's config / overrides into the
+ * connection struct the bridge consumes (URL with model, api key,
+ * source). Throws if the provider id is unknown or its API key isn't
+ * configured — the realtime-ws layer turns the throw into a clear
+ * startup error instead of a mid-call surprise.
+ */
+declare function resolveVoiceRuntime(providerId: string | undefined, config: AgenticMailConfig, options?: {
+    model?: string;
+}): VoiceRuntimeConnection;
+
 type PhoneTransportProvider = '46elks' | 'twilio';
 /** Providers that support starting outbound call-control missions. */
 declare const PHONE_CALL_CONTROL_PROVIDERS: readonly PhoneTransportProvider[];
@@ -6248,4 +6385,4 @@ declare function loadAgentPersona(agentName: string): string;
  */
 declare function saveAgentPersona(agentName: string, content: string): string;
 
-export { AGENT_ROLES, AGENT_STATE_ROOT, ASK_OPERATOR_TOOL, AccountManager, type AddressInfo, type Agent, AgentDeletionService, type AgentMemoryEntry, type AgentMemoryFields, AgentMemoryManager, type AgentMemoryOptions, type AgentMemoryRead, AgentMemoryStore, type AgentRole, AgenticMailClient, type AgenticMailClientOptions, type AgenticMailConfig, type ArchiveAndDeleteOptions, type ArchivedEmail, type Attachment, type AttachmentAdvisory, type AudioAction, type AudioEditOptions, BRIDGE_OPERATOR_LIVE_WINDOW_MS, type BridgeMailContext, type BridgeWakeError, type BridgeWakePromptArgs, type BridgeWakeResult, type BridgeWakeRoute, type CachedMessage, CloudflareClient, type CreateAgentOptions, type CreateMemoryInput, DEFAULT_AGENT_NAME, DEFAULT_AGENT_ROLE, DEFAULT_CALLBACK_POLICY, DEFAULT_EXTENSION_POLICY, DEFAULT_REALTIME_AUDIO_FORMAT, DEFAULT_REALTIME_MODEL, DEFAULT_REALTIME_VOICE, DEFAULT_SESSION_MAX_AGE_MS, DEFAULT_WEB_SEARCH_ENDPOINT, DNSConfigurator, type Database, type DeletionReport, type DeletionSummary, DependencyChecker, DependencyInstaller, type DependencyStatus, type DnsRecord, type DnsSetupResult, type DomainInfo, DomainManager, type DomainModeConfig, type DomainPurchaseResult, DomainPurchaser, type DomainSearchResult, type DomainSetupResult, ELKS_REALTIME_AUDIO_FORMATS, ELKS_REALTIME_WS_PATH, END_CALL_TOOL, EXTEND_CALL_TIME_TOOL, type ElksRealtimeAudioFormat, type ElksRealtimeAudioMessage, type ElksRealtimeByeMessage, type ElksRealtimeHelloMessage, type ElksRealtimeInboundMessage, type ElksRealtimeOutboundMessage, ElksRealtimeTransport, type EmailEnvelope, type EmailRouteAction, type EmailRouteClass, type EmailRouteClassification, type EmailRouteInput, EmailSearchIndex, type FolderInfo, GET_CALL_STATUS_TOOL, GET_DATETIME_TOOL, type GatewayConfig, GatewayManager, type GatewayManagerOptions, type GatewayMode, type GatewayStatus, type GetDatetimeOptions, type GetUpdatesOptions, type HostName, type HostSession, type HostSessionResumeMode, type ImageAction, type ImageEditOptions, type InboundEmail, type InboundSmsEvent, type InboxEvent, type InboxExpungeEvent, type InboxFlagsEvent, type InboxNewEvent, InboxWatcher, type InboxWatcherOptions, type InstallProgress, LOAD_SKILL_TOOL, type LinkAdvisory, type LocalSmtpConfig, MEMORY_CATEGORIES, MailReceiver, type MailReceiverOptions, MailSender, type MailSenderOptions, type MailboxInfo, type MediaBinary, type MediaCapability, type MediaCapabilityReport, type MediaFileResult, type MediaInfoResult, MediaManager, type MediaManagerOptions, type MediaStreamInfo, type MemoryCategory, type MemoryImportance, type MemoryQueryOptions, type MemoryRecaller, MemorySearchIndex, type MemorySource, type MemoryStats, OPENAI_REALTIME_URL, OPERATOR_QUERY_POLL_INTERVAL_MS, OPERATOR_QUERY_SUBJECT_TAG, OPERATOR_QUERY_TIMEOUT_MS, OPERATOR_QUERY_TIMEOUT_SENTINEL, type OpenClawPhoneMissionPolicy, type OperatorQueryNotificationInput, type OperatorQueryPollOptions, type OperatorQueryUrgency, type OperatorReplyKind, type OutboundCategory, type OutboundScanInput, type OutboundScanResult, type OutboundWarning, PERSONA_FILENAME, PHONE_CALLBACK_MAX_DELAY_SECONDS, PHONE_CALLBACK_MIN_DELAY_SECONDS, PHONE_CALL_CONTROL_PROVIDERS, PHONE_MAX_CONCURRENT_MISSIONS, PHONE_MIN_WEBHOOK_SECRET_LENGTH, PHONE_MISSION_STATES, PHONE_RATE_LIMIT_PER_HOUR, PHONE_RATE_LIMIT_PER_MINUTE, PHONE_REGION_SCOPES, PHONE_SERVER_MAX_ATTEMPTS, PHONE_SERVER_MAX_CALLBACK_CHAIN, PHONE_SERVER_MAX_CALL_DURATION_SECONDS, PHONE_SERVER_MAX_COST_PER_MISSION, PHONE_SERVER_MAX_EXTENSION_REQUESTS_PER_CALL, PHONE_SERVER_MAX_EXTENSION_SECONDS_PER_REQUEST, PHONE_SERVER_MAX_TOTAL_EXTENSION_SECONDS, PHONE_TASK_MAX_LENGTH, type ParsedAttachment, type ParsedEmail, type ParsedOperatorReply, type ParsedSms, type ParsedTelegramMessage, PathTraversalError, type PhoneAlternativePolicy, type PhoneCallMission, type PhoneCallbackPolicy, type PhoneConfirmPolicy, type PhoneExtensionPolicy, PhoneManager, type PhoneMissionStartValidationResult, type PhoneMissionState, type PhoneMissionTranscriptEntry, type PhoneMissionValidationIssue, type PhoneMissionValidationResult, type PhoneNumberRisk, type PhoneOperatorQuery, PhoneRateLimitError, type PhoneRegionScope, type PhoneScheduledCallback, type PhoneTransportConfig, type PhoneTransportProfile, type PhoneTransportProvider, type PhoneTransportValidationResult, PhoneWebhookAuthError, type PhoneWebhookResult, type PlanBridgeWakeArgs, type PurchasedDomain, REALTIME_AUDIO_SAMPLE_RATE, REALTIME_MAX_AUDIO_FRAME_BASE64, REALTIME_TOOL_CALL_TIMEOUT_MS, REALTIME_TOOL_DEFINITIONS, RECALL_MEMORY_TOOL, REDACTED, RELAY_PRESETS, type RealtimeBridgePort, type RealtimeBridgeTranscriptEntry, type RealtimeInboundEvent, type RealtimeInstructionOptions, type RealtimeSessionConfigOptions, type RealtimeToolCall, type RealtimeToolDefinition, type RealtimeToolHandler, type RealtimeToolResult, type RealtimeTransportAdapter, type RealtimeTransportProvider, RealtimeVoiceBridge, type RealtimeVoiceBridgeOptions, RelayBridge, type RelayBridgeOptions, type RelayConfig, RelayGateway, type RelayProvider, type RelaySearchResult, type ResumeErrorClassificationOptions, SCHEDULE_CALLBACK_TOOL, SEARCH_EMAIL_TOOL, SEARCH_SKILLS_TOOL, SPAM_THRESHOLD, type SafeJoinOptions, type SanitizeDetection, type SanitizeResult, type ScheduledCallbackRequest, type SearchCriteria, type SearchableEmail, type SecurityAdvisory, type SendMailOptions, type SendResult, type SendResultWithRaw, type SendSmsInput, type SendSmsResult, type SendTelegramMessageOptions, type SendTelegramMessageResult, ServiceManager, type ServiceStatus, type SetWebhookOptions, type SetupConfig, SetupManager, type SetupResult, type Severity, type Skill, type SkillCategory, type SkillContext, type SkillExitStrategy, type SkillSummary, type SkillTactic, type SkillValidationError, type SmsConfig, SmsManager, type SmsMessage, SmsPoller, type SmsProvider, type SpamCategory, type SpamResult, type SpamRuleMatch, StalwartAdmin, type StalwartAdminOptions, type StalwartPrincipal, type StartPhoneCallOptions, type StartPhoneCallResult, type StartPhoneMissionInput, TELEGRAM_API_BASE, TELEGRAM_CHUNK_SIZE, TELEGRAM_MESSAGE_LIMIT, TELEGRAM_MIN_WEBHOOK_SECRET_LENGTH, TELEGRAM_OPERATOR_QUERY_TAG, TELEGRAM_STOP_WORDS, TELEGRAM_WEBHOOK_SECRET_RE, TELEPHONY_TRANSPORT_CAPABILITIES, TWILIO_MEDIA_SAMPLE_RATE, TWILIO_REALTIME_WS_PATH, TelegramApiError, type TelegramApiOptions, type TelegramBotInfo, type TelegramChatType, type TelegramConfig, TelegramManager, type TelegramMessage, type TelegramMode, type TelephonyTransportCapability, ThreadCache, type ThreadCacheEntry, type ThreadCacheOptions, type ThreadIdInput, type ToolExecutor, type TtsGenerateOptions, type TunnelConfig, TunnelManager, type TwilioConnectedMessage, type TwilioMarkMessage, type TwilioMediaMessage, type TwilioRealtimeInboundMessage, type TwilioRealtimeOutboundMessage, TwilioRealtimeTransport, type TwilioStartMessage, type TwilioStopMessage, type TwilioStreamTwiMLOptions, UnsafeApiUrlError, type UpdateMemoryInput, type ValidatedPhoneMissionStart, type VideoAction, type VideoEditOptions, type VideoTimelineEntry, type VideoUnderstandOptions, type VideoUnderstandResult, type VoiceCloneOptions, WARNING_THRESHOLD, WEB_SEARCH_TOOL, WEB_SEARCH_UNTRUSTED_PREFIX, type WatcherOptions, type WebSearchOptions, assertWithinBase, bridgeWakeErrorMessage, bridgeWakeLastSeenAgeMs, buildApiUrl, buildDefaultPersona, buildElksAudioMessage, buildElksByeMessage, buildElksHandshakeMessages, buildElksInterruptMessage, buildElksListeningMessage, buildElksSendingMessage, buildInboundSecurityAdvisory, buildOpenAIRealtimeUrl, buildPhoneTransportConfig, buildRealtimeInstructions, buildRealtimeSessionConfig, buildRealtimeToolGuidance, buildTwilioClearMessage, buildTwilioMarkMessage, buildTwilioMediaMessage, buildTwilioSayTwiML, buildTwilioSignature, buildTwilioStreamTwiML, callTelegramApi, classifyEmailRoute, classifyPhoneNumberRisk, classifyResumeError, clearMediaCapabilityCache, closeDatabase, composeBridgeWakePrompt, createRealtimeTransport, createTestDatabase, createToolExecutor, debug, debugWarn, deleteTelegramWebhook, detectBinary, ensureDataDir, escapeXml, extractEmailAddress, extractVerificationCode, flushTelemetry, forgetHostSession, formatOperatorQueryTelegramMessage, getDatabase, getDatetime, getMediaCapabilities, getOperatorEmail, getSmsProvider, getTelegramChat, getTelegramMe, getTelegramUpdates, getTelegramWebhookInfo, hostSessionStoragePath, inferPhoneRegion, invalidateSkillCache, isInternalEmail, isLoopbackMailHost, isOperatorReplySender, isPhoneRegionAllowed, isSessionFresh, isTelegramChatAllowed, isTelegramStopCommand, isValidPhoneNumber, listSkills, loadAgentPersona, loadHostSession, loadSkill, mapProviderSmsStatus, nextTelegramOffset, normalizeAddress, normalizePhoneNumber, normalizeSubject, operatorPrefsStoragePath, operatorQuerySubject, parseElksRealtimeMessage, parseEmail, parseGoogleVoiceSms, parseOperatorQueryReply, parseTelegramOperatorReply, parseTelegramUpdate, parseTwilioRealtimeMessage, personaPathFor, planBridgeWake, pollForOperatorAnswer, recallMemory, recordToolCall, redactBotToken, redactObject, redactPhoneTransportConfig, redactSecret, redactSmsConfig, redactTelegramConfig, renderSkillAsPrompt, requireBinary, requireWhisperModel, resolveCallbackPolicy, resolveConfig, resolveExtensionPolicy, resolveTlsRejectUnauthorized, safeJoin, sanitizeEmail, saveAgentPersona, saveConfig, saveHostSession, saveUserSkill, scanOutboundEmail, scoreEmail, searchSkills, sendTelegramMessage, setOperatorEmail, setTelegramWebhook, setTelemetryVersion, shouldSkipBridgeWakeForLiveOperator, splitTelegramMessage, startRelayBridge, stem, stripTelegramMarkdown, threadIdFor, tokenize, tryJoin, userSkillsDir, validateApiUrl, validatePhoneMissionPolicy, validatePhoneMissionStart, validatePhoneTransportProfile, validateSkill, validateTwilioSignature, webSearch };
+export { AGENT_ROLES, AGENT_STATE_ROOT, ASK_OPERATOR_TOOL, AccountManager, type AddressInfo, type Agent, AgentDeletionService, type AgentMemoryEntry, type AgentMemoryFields, AgentMemoryManager, type AgentMemoryOptions, type AgentMemoryRead, AgentMemoryStore, type AgentRole, AgenticMailClient, type AgenticMailClientOptions, type AgenticMailConfig, type ArchiveAndDeleteOptions, type ArchivedEmail, type Attachment, type AttachmentAdvisory, type AudioAction, type AudioEditOptions, BRIDGE_OPERATOR_LIVE_WINDOW_MS, type BridgeMailContext, type BridgeWakeError, type BridgeWakePromptArgs, type BridgeWakeResult, type BridgeWakeRoute, type CachedMessage, CloudflareClient, type CreateAgentOptions, type CreateMemoryInput, DEFAULT_AGENT_NAME, DEFAULT_AGENT_ROLE, DEFAULT_CALLBACK_POLICY, DEFAULT_EXTENSION_POLICY, DEFAULT_REALTIME_AUDIO_FORMAT, DEFAULT_REALTIME_MODEL, DEFAULT_REALTIME_VOICE, DEFAULT_SESSION_MAX_AGE_MS, DEFAULT_WEB_SEARCH_ENDPOINT, DNSConfigurator, type Database, type DeletionReport, type DeletionSummary, DependencyChecker, DependencyInstaller, type DependencyStatus, type DnsRecord, type DnsSetupResult, type DomainInfo, DomainManager, type DomainModeConfig, type DomainPurchaseResult, DomainPurchaser, type DomainSearchResult, type DomainSetupResult, ELKS_REALTIME_AUDIO_FORMATS, ELKS_REALTIME_WS_PATH, END_CALL_TOOL, EXTEND_CALL_TIME_TOOL, type ElksRealtimeAudioFormat, type ElksRealtimeAudioMessage, type ElksRealtimeByeMessage, type ElksRealtimeHelloMessage, type ElksRealtimeInboundMessage, type ElksRealtimeOutboundMessage, ElksRealtimeTransport, type EmailEnvelope, type EmailRouteAction, type EmailRouteClass, type EmailRouteClassification, type EmailRouteInput, EmailSearchIndex, type FolderInfo, GET_CALL_STATUS_TOOL, GET_DATETIME_TOOL, type GatewayConfig, GatewayManager, type GatewayManagerOptions, type GatewayMode, type GatewayStatus, type GetDatetimeOptions, type GetUpdatesOptions, type HostName, type HostSession, type HostSessionResumeMode, type ImageAction, type ImageEditOptions, type InboundEmail, type InboundSmsEvent, type InboxEvent, type InboxExpungeEvent, type InboxFlagsEvent, type InboxNewEvent, InboxWatcher, type InboxWatcherOptions, type InstallProgress, LOAD_SKILL_TOOL, type LinkAdvisory, type LocalSmtpConfig, MEMORY_CATEGORIES, MailReceiver, type MailReceiverOptions, MailSender, type MailSenderOptions, type MailboxInfo, type MediaBinary, type MediaCapability, type MediaCapabilityReport, type MediaFileResult, type MediaInfoResult, MediaManager, type MediaManagerOptions, type MediaStreamInfo, type MemoryCategory, type MemoryImportance, type MemoryQueryOptions, type MemoryRecaller, MemorySearchIndex, type MemorySource, type MemoryStats, OPENAI_REALTIME_URL, OPERATOR_QUERY_POLL_INTERVAL_MS, OPERATOR_QUERY_SUBJECT_TAG, OPERATOR_QUERY_TIMEOUT_MS, OPERATOR_QUERY_TIMEOUT_SENTINEL, type OpenClawPhoneMissionPolicy, type OperatorQueryNotificationInput, type OperatorQueryPollOptions, type OperatorQueryUrgency, type OperatorReplyKind, type OutboundCategory, type OutboundScanInput, type OutboundScanResult, type OutboundWarning, PERSONA_FILENAME, PHONE_CALLBACK_MAX_DELAY_SECONDS, PHONE_CALLBACK_MIN_DELAY_SECONDS, PHONE_CALL_CONTROL_PROVIDERS, PHONE_MAX_CONCURRENT_MISSIONS, PHONE_MIN_WEBHOOK_SECRET_LENGTH, PHONE_MISSION_STATES, PHONE_RATE_LIMIT_PER_HOUR, PHONE_RATE_LIMIT_PER_MINUTE, PHONE_REGION_SCOPES, PHONE_SERVER_MAX_ATTEMPTS, PHONE_SERVER_MAX_CALLBACK_CHAIN, PHONE_SERVER_MAX_CALL_DURATION_SECONDS, PHONE_SERVER_MAX_COST_PER_MISSION, PHONE_SERVER_MAX_EXTENSION_REQUESTS_PER_CALL, PHONE_SERVER_MAX_EXTENSION_SECONDS_PER_REQUEST, PHONE_SERVER_MAX_TOTAL_EXTENSION_SECONDS, PHONE_TASK_MAX_LENGTH, type ParsedAttachment, type ParsedEmail, type ParsedOperatorReply, type ParsedSms, type ParsedTelegramMessage, PathTraversalError, type PhoneAlternativePolicy, type PhoneCallMission, type PhoneCallbackPolicy, type PhoneConfirmPolicy, type PhoneExtensionPolicy, PhoneManager, type PhoneMissionStartValidationResult, type PhoneMissionState, type PhoneMissionTranscriptEntry, type PhoneMissionValidationIssue, type PhoneMissionValidationResult, type PhoneNumberRisk, type PhoneOperatorQuery, PhoneRateLimitError, type PhoneRegionScope, type PhoneScheduledCallback, type PhoneTransportConfig, type PhoneTransportProfile, type PhoneTransportProvider, type PhoneTransportValidationResult, PhoneWebhookAuthError, type PhoneWebhookResult, type PlanBridgeWakeArgs, type PurchasedDomain, REALTIME_AUDIO_SAMPLE_RATE, REALTIME_MAX_AUDIO_FRAME_BASE64, REALTIME_TOOL_CALL_TIMEOUT_MS, REALTIME_TOOL_DEFINITIONS, RECALL_MEMORY_TOOL, REDACTED, RELAY_PRESETS, type RealtimeBridgePort, type RealtimeBridgeTranscriptEntry, type RealtimeInboundEvent, type RealtimeInstructionOptions, type RealtimeSessionConfigOptions, type RealtimeToolCall, type RealtimeToolDefinition, type RealtimeToolHandler, type RealtimeToolResult, type RealtimeTransportAdapter, type RealtimeTransportProvider, RealtimeVoiceBridge, type RealtimeVoiceBridgeOptions, RelayBridge, type RelayBridgeOptions, type RelayConfig, RelayGateway, type RelayProvider, type RelaySearchResult, type ResumeErrorClassificationOptions, SCHEDULE_CALLBACK_TOOL, SEARCH_EMAIL_TOOL, SEARCH_SKILLS_TOOL, SPAM_THRESHOLD, type SafeJoinOptions, type SanitizeDetection, type SanitizeResult, type ScheduledCallbackRequest, type SearchCriteria, type SearchableEmail, type SecurityAdvisory, type SendMailOptions, type SendResult, type SendResultWithRaw, type SendSmsInput, type SendSmsResult, type SendTelegramMessageOptions, type SendTelegramMessageResult, ServiceManager, type ServiceStatus, type SetWebhookOptions, type SetupConfig, SetupManager, type SetupResult, type Severity, type Skill, type SkillCategory, type SkillContext, type SkillExitStrategy, type SkillSummary, type SkillTactic, type SkillValidationError, type SmsConfig, SmsManager, type SmsMessage, SmsPoller, type SmsProvider, type SpamCategory, type SpamResult, type SpamRuleMatch, StalwartAdmin, type StalwartAdminOptions, type StalwartPrincipal, type StartPhoneCallOptions, type StartPhoneCallResult, type StartPhoneMissionInput, TELEGRAM_API_BASE, TELEGRAM_CHUNK_SIZE, TELEGRAM_MESSAGE_LIMIT, TELEGRAM_MIN_WEBHOOK_SECRET_LENGTH, TELEGRAM_OPERATOR_QUERY_TAG, TELEGRAM_STOP_WORDS, TELEGRAM_WEBHOOK_SECRET_RE, TELEPHONY_TRANSPORT_CAPABILITIES, TWILIO_MEDIA_SAMPLE_RATE, TWILIO_REALTIME_WS_PATH, TelegramApiError, type TelegramApiOptions, type TelegramBotInfo, type TelegramChatType, type TelegramConfig, TelegramManager, type TelegramMessage, type TelegramMode, type TelephonyTransportCapability, ThreadCache, type ThreadCacheEntry, type ThreadCacheOptions, type ThreadIdInput, type ToolExecutor, type TtsGenerateOptions, type TunnelConfig, TunnelManager, type TwilioConnectedMessage, type TwilioMarkMessage, type TwilioMediaMessage, type TwilioRealtimeInboundMessage, type TwilioRealtimeOutboundMessage, TwilioRealtimeTransport, type TwilioStartMessage, type TwilioStopMessage, type TwilioStreamTwiMLOptions, UnsafeApiUrlError, type UpdateMemoryInput, type ValidatedPhoneMissionStart, type VideoAction, type VideoEditOptions, type VideoTimelineEntry, type VideoUnderstandOptions, type VideoUnderstandResult, type VoiceCloneOptions, type VoiceProvider, type VoiceRuntimeConnection, WARNING_THRESHOLD, WEB_SEARCH_TOOL, WEB_SEARCH_UNTRUSTED_PREFIX, type WatcherOptions, type WebSearchOptions, assertWithinBase, bridgeWakeErrorMessage, bridgeWakeLastSeenAgeMs, buildApiUrl, buildDefaultPersona, buildElksAudioMessage, buildElksByeMessage, buildElksHandshakeMessages, buildElksInterruptMessage, buildElksListeningMessage, buildElksSendingMessage, buildInboundSecurityAdvisory, buildOpenAIRealtimeUrl, buildPhoneTransportConfig, buildRealtimeInstructions, buildRealtimeSessionConfig, buildRealtimeToolGuidance, buildTwilioClearMessage, buildTwilioMarkMessage, buildTwilioMediaMessage, buildTwilioSayTwiML, buildTwilioSignature, buildTwilioStreamTwiML, callTelegramApi, classifyEmailRoute, classifyPhoneNumberRisk, classifyResumeError, clearMediaCapabilityCache, closeDatabase, composeBridgeWakePrompt, createRealtimeTransport, createTestDatabase, createToolExecutor, debug, debugWarn, deleteTelegramWebhook, detectBinary, ensureDataDir, escapeXml, extractEmailAddress, extractVerificationCode, flushTelemetry, forgetHostSession, formatOperatorQueryTelegramMessage, getDatabase, getDatetime, getMediaCapabilities, getOperatorEmail, getSmsProvider, getTelegramChat, getTelegramMe, getTelegramUpdates, getTelegramWebhookInfo, getVoiceProvider, hostSessionStoragePath, inferPhoneRegion, invalidateSkillCache, isInternalEmail, isLoopbackMailHost, isOperatorReplySender, isPhoneRegionAllowed, isSessionFresh, isTelegramChatAllowed, isTelegramStopCommand, isValidPhoneNumber, listSkills, listVoiceProviders, loadAgentPersona, loadHostSession, loadSkill, mapProviderSmsStatus, nextTelegramOffset, normalizeAddress, normalizePhoneNumber, normalizeSubject, operatorPrefsStoragePath, operatorQuerySubject, parseElksRealtimeMessage, parseEmail, parseGoogleVoiceSms, parseOperatorQueryReply, parseTelegramOperatorReply, parseTelegramUpdate, parseTwilioRealtimeMessage, personaPathFor, planBridgeWake, pollForOperatorAnswer, recallMemory, recordToolCall, redactBotToken, redactObject, redactPhoneTransportConfig, redactSecret, redactSmsConfig, redactTelegramConfig, registerVoiceProvider, renderSkillAsPrompt, requireBinary, requireWhisperModel, resolveCallbackPolicy, resolveConfig, resolveExtensionPolicy, resolveTlsRejectUnauthorized, resolveVoiceRuntime, safeJoin, sanitizeEmail, saveAgentPersona, saveConfig, saveHostSession, saveUserSkill, scanOutboundEmail, scoreEmail, searchSkills, sendTelegramMessage, setOperatorEmail, setTelegramWebhook, setTelemetryVersion, shouldSkipBridgeWakeForLiveOperator, splitTelegramMessage, startRelayBridge, stem, stripTelegramMarkdown, threadIdFor, tokenize, tryJoin, userSkillsDir, validateApiUrl, validatePhoneMissionPolicy, validatePhoneMissionStart, validatePhoneTransportProfile, validateSkill, validateTwilioSignature, webSearch };

package/dist/index.js

@@ -920,6 +920,13 @@ function resolveConfig(overrides) {
     dataDir: env.AGENTICMAIL_DATA_DIR?.replace(/^~(?=\/|$)/, homedir()) ?? DEFAULT_CONFIG.dataDir
   };
   if (env.OPENAI_API_KEY) config.openaiApiKey = env.OPENAI_API_KEY;
+  if (env.XAI_API_KEY) {
+    config.voiceProviderKeys = config.voiceProviderKeys ?? {};
+    config.voiceProviderKeys.grok = env.XAI_API_KEY;
+  }
+  if (env.AGENTICMAIL_VOICE_RUNTIME && env.AGENTICMAIL_VOICE_RUNTIME.trim()) {
+    config.voiceRuntime = env.AGENTICMAIL_VOICE_RUNTIME.trim();
+  }
   const configPath = join(config.dataDir, "config.json");
   if (existsSync(configPath)) {
     try {
@@ -10530,6 +10537,94 @@ function withTimeout(promise, ms) {
   return Promise.race([promise, timeout]).finally(() => clearTimeout(timer));
 }
 
+// src/phone/voice-providers/registry.ts
+var PROVIDERS2 = /* @__PURE__ */ new Map();
+function registerVoiceProvider(provider) {
+  if (PROVIDERS2.has(provider.id)) {
+    throw new Error(`Voice provider "${provider.id}" registered twice \u2014 id collision.`);
+  }
+  PROVIDERS2.set(provider.id, provider);
+}
+function listVoiceProviders() {
+  return Array.from(PROVIDERS2.values());
+}
+function getVoiceProvider(id) {
+  return PROVIDERS2.get(id);
+}
+function resolveVoiceRuntime(providerId, config, options = {}) {
+  const id = (providerId || "openai").trim() || "openai";
+  const provider = PROVIDERS2.get(id);
+  if (!provider) {
+    const known = Array.from(PROVIDERS2.keys()).join(", ") || "(none registered)";
+    throw new Error(
+      `Unknown voice runtime "${id}". Known providers: ${known}. Add a new one by dropping a file into packages/core/src/phone/voice-providers/.`
+    );
+  }
+  let apiKey = "";
+  let apiKeySource = "";
+  if (provider.apiKeyConfigField) {
+    const legacy = config[provider.apiKeyConfigField];
+    if (legacy && legacy.trim()) {
+      apiKey = legacy.trim();
+      apiKeySource = `config.${provider.apiKeyConfigField}`;
+    }
+  }
+  if (!apiKey) {
+    const fromMap = config.voiceProviderKeys?.[provider.id];
+    if (fromMap && fromMap.trim()) {
+      apiKey = fromMap.trim();
+      apiKeySource = `config.voiceProviderKeys.${provider.id}`;
+    }
+  }
+  if (!apiKey) {
+    const fromEnv = process.env[provider.apiKeyEnvVar];
+    if (fromEnv && fromEnv.trim()) {
+      apiKey = fromEnv.trim();
+      apiKeySource = `env ${provider.apiKeyEnvVar}`;
+    }
+  }
+  if (!apiKey) {
+    throw new Error(
+      `Voice provider "${provider.id}" (${provider.displayName}) selected, but no API key is configured. Set ${provider.apiKeyEnvVar} in your environment or save it to ~/.agenticmail/config.json under voiceProviderKeys.${provider.id}.`
+    );
+  }
+  const model = options.model && options.model.trim() || provider.defaultModel;
+  const url = `${provider.websocketBaseUrl}?model=${encodeURIComponent(model)}`;
+  return {
+    providerId: provider.id,
+    providerDisplayName: provider.displayName,
+    url,
+    model,
+    apiKey,
+    apiKeySource
+  };
+}
+
+// src/phone/voice-providers/openai.ts
+registerVoiceProvider({
+  id: "openai",
+  displayName: "OpenAI Realtime (gpt-realtime)",
+  websocketBaseUrl: "wss://api.openai.com/v1/realtime",
+  defaultModel: "gpt-realtime",
+  apiKeyEnvVar: "OPENAI_API_KEY",
+  // Legacy: the original config.json schema used a dedicated
+  // `openaiApiKey` field for this key. The resolver checks that field
+  // before the generic voiceProviderKeys map so existing installs
+  // continue to work without migration.
+  apiKeyConfigField: "openaiApiKey",
+  description: "OpenAI Realtime (gpt-realtime). Default voice runtime; supports linear PCM @ 24 kHz (46elks) and G.711 \xB5-law @ 8 kHz (Twilio) without transcoding."
+});
+
+// src/phone/voice-providers/grok.ts
+registerVoiceProvider({
+  id: "grok",
+  displayName: "xAI Grok Voice Agent",
+  websocketBaseUrl: "wss://api.x.ai/v1/realtime",
+  defaultModel: "grok-voice-latest",
+  apiKeyEnvVar: "XAI_API_KEY",
+  description: 'xAI Grok Voice Agent \u2014 OpenAI-Realtime-compatible WebSocket protocol; select via mission policy.voiceRuntime="grok" or env AGENTICMAIL_VOICE_RUNTIME=grok.'
+});
+
 // src/telemetry.ts
 import { randomUUID as randomUUID2 } from "crypto";
 import { readFileSync as readFileSync2, writeFileSync as writeFileSync3, mkdirSync as mkdirSync3, existsSync as existsSync3 } from "fs";
@@ -14859,6 +14954,7 @@ export {
   getTelegramMe,
   getTelegramUpdates,
   getTelegramWebhookInfo,
+  getVoiceProvider,
   hostSessionStoragePath,
   inferPhoneRegion,
   invalidateSkillCache,
@@ -14871,6 +14967,7 @@ export {
   isTelegramStopCommand,
   isValidPhoneNumber,
   listSkills,
+  listVoiceProviders,
   loadAgentPersona,
   loadHostSession,
   loadSkill,
@@ -14899,6 +14996,7 @@ export {
   redactSecret,
   redactSmsConfig,
   redactTelegramConfig,
+  registerVoiceProvider,
   renderSkillAsPrompt,
   requireBinary,
   requireWhisperModel,
@@ -14906,6 +15004,7 @@ export {
   resolveConfig,
   resolveExtensionPolicy,
   resolveTlsRejectUnauthorized,
+  resolveVoiceRuntime,
   safeJoin,
   sanitizeEmail,
   saveAgentPersona,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agenticmail/core",
-  "version": "0.9.38",
+  "version": "0.9.39",
   "description": "Core SDK for AgenticMail — email, SMS, and phone call-control for AI agents",
   "type": "module",
   "main": "dist/index.js",