@agenticmail/core 0.9.38 → 0.9.40

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,
@@ -1642,6 +1644,7 @@ __export(index_exports, {
   personaPathFor: () => personaPathFor,
   planBridgeWake: () => planBridgeWake,
   pollForOperatorAnswer: () => pollForOperatorAnswer,
+  readAgentPersonaFile: () => readAgentPersonaFile,
   recallMemory: () => recallMemory,
   recordToolCall: () => recordToolCall,
   redactBotToken: () => redactBotToken,
@@ -1650,6 +1653,7 @@ __export(index_exports, {
   redactSecret: () => redactSecret,
   redactSmsConfig: () => redactSmsConfig,
   redactTelegramConfig: () => redactTelegramConfig,
+  registerVoiceProvider: () => registerVoiceProvider,
   renderSkillAsPrompt: () => renderSkillAsPrompt,
   requireBinary: () => requireBinary,
   requireWhisperModel: () => requireWhisperModel,
@@ -1657,6 +1661,7 @@ __export(index_exports, {
   resolveConfig: () => resolveConfig,
   resolveExtensionPolicy: () => resolveExtensionPolicy,
   resolveTlsRejectUnauthorized: () => resolveTlsRejectUnauthorized,
+  resolveVoiceRuntime: () => resolveVoiceRuntime,
   safeJoin: () => safeJoin,
   sanitizeEmail: () => sanitizeEmail,
   saveAgentPersona: () => saveAgentPersona,
@@ -1678,6 +1683,7 @@ __export(index_exports, {
   threadIdFor: () => threadIdFor,
   tokenize: () => tokenize,
   tryJoin: () => tryJoin,
+  updateAgentPersonaFrontmatter: () => updateAgentPersonaFrontmatter,
   userSkillsDir: () => userSkillsDir,
   validateApiUrl: () => validateApiUrl,
   validatePhoneMissionPolicy: () => validatePhoneMissionPolicy,
@@ -2588,6 +2594,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 {
@@ -7802,7 +7815,14 @@ function validatePhoneMissionPolicy(policy) {
       // manager) can read a concrete value without juggling undefined.
       // Caller-omitted → DEFAULT_*. Caller-set → clamped to server caps.
       extensionPolicy: resolveExtensionPolicy(policy.extensionPolicy),
-      callbackPolicy: resolveCallbackPolicy(policy.callbackPolicy)
+      callbackPolicy: resolveCallbackPolicy(policy.callbackPolicy),
+      // v0.9.95 — voice-runtime overrides. Pass-through; the registry
+      // validates the provider id and voice-against-catalogue at
+      // session-open time so we don't have to import the registry
+      // here (would create a cycle with realtime-bridge.ts).
+      voiceRuntime: typeof policy.voiceRuntime === "string" && policy.voiceRuntime.trim() ? policy.voiceRuntime.trim() : void 0,
+      voiceModel: typeof policy.voiceModel === "string" && policy.voiceModel.trim() ? policy.voiceModel.trim() : void 0,
+      voice: typeof policy.voice === "string" && policy.voice.trim() ? policy.voice.trim() : void 0
     },
     issues: []
   };
@@ -12203,6 +12223,140 @@ 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)}`;
+  let voice = "";
+  let voiceSource = "";
+  const requested = (options.voice || "").trim();
+  if (requested) {
+    if (provider.voices.includes(requested) || provider.customVoicesSupported) {
+      voice = requested;
+      voiceSource = "mission policy";
+    } else {
+      console.warn(
+        `[voice-providers] Voice "${requested}" is not in ${provider.id}'s catalogue (${provider.voices.join(", ")}). Falling through to ${provider.defaultVoice}.`
+      );
+    }
+  }
+  if (!voice) {
+    const installDefault = config.voiceProviderVoices?.[provider.id];
+    if (installDefault && installDefault.trim()) {
+      const v = installDefault.trim();
+      if (provider.voices.includes(v) || provider.customVoicesSupported) {
+        voice = v;
+        voiceSource = `config.voiceProviderVoices.${provider.id}`;
+      }
+    }
+  }
+  if (!voice) {
+    voice = provider.defaultVoice;
+    voiceSource = `${provider.id} default`;
+  }
+  return {
+    providerId: provider.id,
+    providerDisplayName: provider.displayName,
+    url,
+    model,
+    apiKey,
+    apiKeySource,
+    voice,
+    voiceSource
+  };
+}
+
+// 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.",
+  // v0.9.95 — voice catalogue. Names match what the Realtime session
+  // accepts under `audio.output.voice`. `marin` and `cedar` are the
+  // GA gpt-realtime additions; the rest are the legacy roster carried
+  // forward from gpt-4o-realtime-preview.
+  voices: ["alloy", "ash", "ballad", "cedar", "coral", "echo", "marin", "sage", "shimmer", "verse"],
+  defaultVoice: "marin"
+});
+
+// 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.',
+  // v0.9.95 — voice catalogue. xAI ships 5 expressive built-in
+  // voices for the realtime Voice Agent. Three are explicitly named
+  // in the announcement (Ara, Eve, Leo); the other two are
+  // browsable in console.x.ai's Voice Library along with the
+  // broader 80+ voice catalogue. The full live list is at
+  // GET /v1/tts/voices. We don't try to enumerate all 80+ here —
+  // customVoicesSupported lets operators paste any voice_id from
+  // their console.
+  voices: ["ara", "eve", "leo"],
+  defaultVoice: "ara",
+  customVoicesSupported: true
+});
+
 // src/telemetry.ts
 var import_crypto = require("crypto");
 var import_fs = require("fs");
@@ -16336,8 +16490,19 @@ function loadAgentPersona(agentName) {
   const path2 = personaPathFor(agentName);
   try {
     if ((0, import_node_fs15.existsSync)(path2)) {
-      const content = (0, import_node_fs15.readFileSync)(path2, "utf-8").trim();
-      if (content) return content;
+      const raw = (0, import_node_fs15.readFileSync)(path2, "utf-8");
+      if (raw.trim()) {
+        const text = raw.replace(/\r\n/g, "\n");
+        if (text.startsWith("---\n")) {
+          const close = text.indexOf("\n---", 4);
+          if (close > 0) {
+            let cursor = close + 4;
+            while (cursor < text.length && (text[cursor] === "\n" || text[cursor] === "\r")) cursor++;
+            return text.slice(cursor).trim();
+          }
+        }
+        return text.trim();
+      }
     }
   } catch {
   }
@@ -16357,6 +16522,61 @@ function saveAgentPersona(agentName, content) {
   (0, import_node_fs15.writeFileSync)(path2, content.trim() + "\n", { mode: 420 });
   return path2;
 }
+function readAgentPersonaFile(agentName) {
+  const path2 = personaPathFor(agentName);
+  let raw = "";
+  try {
+    if ((0, import_node_fs15.existsSync)(path2)) raw = (0, import_node_fs15.readFileSync)(path2, "utf-8");
+  } catch {
+  }
+  if (!raw.trim()) {
+    return { frontmatter: {}, body: loadAgentPersona(agentName) };
+  }
+  const text = raw.replace(/\r\n/g, "\n");
+  if (!text.startsWith("---\n")) {
+    return { frontmatter: {}, body: text.trim() };
+  }
+  const close = text.indexOf("\n---", 4);
+  if (close < 0) {
+    return { frontmatter: {}, body: text.trim() };
+  }
+  const yamlBlock = text.slice(4, close);
+  const bodyStart = close + 4;
+  let cursor = bodyStart;
+  while (cursor < text.length && (text[cursor] === "\n" || text[cursor] === "\r")) cursor++;
+  const body = text.slice(cursor).trim();
+  const frontmatter = {};
+  for (const line of yamlBlock.split("\n")) {
+    const m = /^\s*([A-Za-z][A-Za-z0-9_-]*)\s*:\s*(.*?)\s*$/.exec(line);
+    if (!m) continue;
+    const key = m[1];
+    const value = m[2].replace(/^["']|["']$/g, "");
+    if (key === "voice") frontmatter.voice = value;
+    else if (key === "voiceRuntime") frontmatter.voiceRuntime = value;
+  }
+  return { frontmatter, body };
+}
+function updateAgentPersonaFrontmatter(agentName, patch) {
+  const { frontmatter, body } = readAgentPersonaFile(agentName);
+  const merged = { ...frontmatter };
+  if (patch.voice !== void 0) merged.voice = patch.voice;
+  if (patch.voiceRuntime !== void 0) merged.voiceRuntime = patch.voiceRuntime;
+  const lines = [];
+  if (merged.voice && merged.voice.trim()) lines.push(`voice: ${merged.voice.trim()}`);
+  if (merged.voiceRuntime && merged.voiceRuntime.trim()) lines.push(`voiceRuntime: ${merged.voiceRuntime.trim()}`);
+  const path2 = personaPathFor(agentName);
+  const dir2 = path2.substring(0, path2.lastIndexOf("/"));
+  if (!(0, import_node_fs15.existsSync)(dir2)) (0, import_node_fs15.mkdirSync)(dir2, { recursive: true });
+  const content = lines.length > 0 ? `---
+${lines.join("\n")}
+---
+
+${body}
+` : `${body}
+`;
+  (0, import_node_fs15.writeFileSync)(path2, content, { mode: 420 });
+  return path2;
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   AGENT_ROLES,
@@ -16517,6 +16737,7 @@ function saveAgentPersona(agentName, content) {
   getTelegramMe,
   getTelegramUpdates,
   getTelegramWebhookInfo,
+  getVoiceProvider,
   hostSessionStoragePath,
   inferPhoneRegion,
   invalidateSkillCache,
@@ -16529,6 +16750,7 @@ function saveAgentPersona(agentName, content) {
   isTelegramStopCommand,
   isValidPhoneNumber,
   listSkills,
+  listVoiceProviders,
   loadAgentPersona,
   loadHostSession,
   loadSkill,
@@ -16549,6 +16771,7 @@ function saveAgentPersona(agentName, content) {
   personaPathFor,
   planBridgeWake,
   pollForOperatorAnswer,
+  readAgentPersonaFile,
   recallMemory,
   recordToolCall,
   redactBotToken,
@@ -16557,6 +16780,7 @@ function saveAgentPersona(agentName, content) {
   redactSecret,
   redactSmsConfig,
   redactTelegramConfig,
+  registerVoiceProvider,
   renderSkillAsPrompt,
   requireBinary,
   requireWhisperModel,
@@ -16564,6 +16788,7 @@ function saveAgentPersona(agentName, content) {
   resolveConfig,
   resolveExtensionPolicy,
   resolveTlsRejectUnauthorized,
+  resolveVoiceRuntime,
   safeJoin,
   sanitizeEmail,
   saveAgentPersona,
@@ -16585,6 +16810,7 @@ function saveAgentPersona(agentName, content) {
   threadIdFor,
   tokenize,
   tryJoin,
+  updateAgentPersonaFrontmatter,
   userSkillsDir,
   validateApiUrl,
   validatePhoneMissionPolicy,

package/dist/index.d.cts

@@ -229,6 +229,31 @@ 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.95 — install-wide default voice CHARACTER per provider
+     * (e.g. `{ openai: 'cedar', grok: 'ara' }`). Optional — when a
+     * provider's slot is empty, the bridge falls back to the
+     * provider's own `defaultVoice`. Per-agent persona + per-call
+     * mission policy still beat this. The CLI's `agenticmail
+     * setup-voice` voice picker writes here.
+     */
+    voiceProviderVoices?: 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;
 }
@@ -2748,6 +2773,25 @@ interface OpenClawPhoneMissionPolicy {
      * {@link DEFAULT_CALLBACK_POLICY} when omitted.
      */
     callbackPolicy?: PhoneCallbackPolicy;
+    /**
+     * v0.9.95 — voice-runtime provider id ('openai', 'grok', any
+     * future plugin). Per-call override that beats agent persona
+     * frontmatter, install default, and bridge default. Optional.
+     */
+    voiceRuntime?: string;
+    /**
+     * v0.9.95 — model name override (e.g. `'gpt-realtime-mini'` for
+     * cost-tuning, `'grok-voice-fast'` for latency). Optional.
+     */
+    voiceModel?: string;
+    /**
+     * v0.9.95 — voice CHARACTER override (e.g. `'cedar'`, `'ara'`, or
+     * a custom-voice id from Grok). Optional. Validated against the
+     * provider's catalogue at session-open time; unknown names against
+     * a fixed-catalogue provider fall through to the provider default
+     * with a log warning.
+     */
+    voice?: string;
 }
 interface StartPhoneMissionInput {
     to: string;
@@ -3824,6 +3868,161 @@ 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;
+    /**
+     * v0.9.95 — built-in voice catalogue. The names the operator can
+     * pick when configuring a default voice for the agent or pinning
+     * one per-call. Empty array means "use whatever defaultVoice we
+     * ship" — used by providers like Grok that support arbitrary
+     * voice ids (cloned voices) instead of a fixed list.
+     */
+    voices: string[];
+    /**
+     * v0.9.95 — default voice the bridge picks when neither the
+     * mission policy nor the agent persona pins one. Per-provider:
+     * OpenAI defaults to "marin"; Grok lets the provider pick.
+     */
+    defaultVoice: string;
+    /**
+     * v0.9.95 — true when the provider accepts arbitrary voice ids
+     * beyond `voices` (e.g. Grok's Custom Voices API returns a
+     * `voice_id` that plugs in here). Tells the CLI picker to show a
+     * free-text input + a "paste a custom voice id" option after the
+     * built-in list.
+     */
+    customVoicesSupported?: boolean;
+}
+/**
+ * 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;
+    /**
+     * v0.9.95 — resolved voice name (sent in session.update under
+     * `audio.output.voice`). Picked from (in order):
+     *   1. caller-passed `options.voice` (mission policy)
+     *   2. agent persona's `voice:` frontmatter
+     *   3. install default in `config.voiceProviderVoices[<providerId>]`
+     *   4. provider's `defaultVoice` (e.g. OpenAI "marin", Grok "ara")
+     */
+    voice: string;
+    /** Human-readable source of the voice pick, for boot logs / audit. */
+    voiceSource: 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;
+    voice?: string;
+}): VoiceRuntimeConnection;
+
 type PhoneTransportProvider = '46elks' | 'twilio';
 /** Providers that support starting outbound call-control missions. */
 declare const PHONE_CALL_CONTROL_PROVIDERS: readonly PhoneTransportProvider[];
@@ -6235,11 +6434,16 @@ declare function buildDefaultPersona(agentName: string): string;
 /** Resolve the per-agent persona path on disk. */
 declare function personaPathFor(agentName: string): string;
 /**
- * Load the persona for {@link agentName}. Auto-creates the file with
- * {@link buildDefaultPersona} content on first read. Idempotent: a
- * second call returns whatever's on disk. Never throws — a permission
- * error or filesystem quirk falls back to the in-memory default so the
- * voice / email / telegram path is never crashed by a missing file.
+ * Load the persona BODY for {@link agentName}. Auto-creates the file
+ * with {@link buildDefaultPersona} content on first read. Idempotent.
+ * Never throws — a permission error or filesystem quirk falls back
+ * to the in-memory default so the voice / email / telegram path is
+ * never crashed by a missing file.
+ *
+ * v0.9.95 — if the file has YAML frontmatter (voice / voiceRuntime
+ * keys, written by `agenticmail persona --voice <name>`), the
+ * frontmatter is stripped from the returned string. Use
+ * {@link readAgentPersonaFile} to get the parsed frontmatter too.
  */
 declare function loadAgentPersona(agentName: string): string;
 /**
@@ -6247,5 +6451,43 @@ declare function loadAgentPersona(agentName: string): string;
  * edit command. Returns the path written to.
  */
 declare function saveAgentPersona(agentName: string, content: string): string;
+/**
+ * v0.9.95 — structured per-agent voice preferences. Stored as YAML
+ * frontmatter at the top of the persona file:
+ *
+ *   ---
+ *   voice: cedar
+ *   voiceRuntime: openai
+ *   ---
+ *   # Who you are
+ *   ...
+ *
+ * Both fields optional. Unknown keys are ignored on read. The CLI's
+ * `agenticmail persona --voice <name>` writes here. The realtime
+ * bridge consults this between the mission policy and the install
+ * default so an agent can have a consistent voice across every call
+ * without the caller pinning it on every invocation.
+ */
+interface AgentPersonaFrontmatter {
+    voice?: string;
+    voiceRuntime?: string;
+}
+/**
+ * Read frontmatter + body from the persona file. Best-effort; missing
+ * file returns empty frontmatter + an auto-seeded body. Robust to:
+ *   - No frontmatter at all (legacy files written before 0.9.95).
+ *   - Frontmatter with leading whitespace / CRLF.
+ *   - Junk lines in the YAML block — we only pick the keys we know.
+ */
+declare function readAgentPersonaFile(agentName: string): {
+    frontmatter: AgentPersonaFrontmatter;
+    body: string;
+};
+/**
+ * Update one or more frontmatter keys on an agent's persona file.
+ * Preserves the existing body. Auto-seeds the body if the file
+ * didn't exist yet.
+ */
+declare function updateAgentPersonaFrontmatter(agentName: string, patch: AgentPersonaFrontmatter): 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 AgentPersonaFrontmatter, 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, readAgentPersonaFile, 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, updateAgentPersonaFrontmatter, userSkillsDir, validateApiUrl, validatePhoneMissionPolicy, validatePhoneMissionStart, validatePhoneTransportProfile, validateSkill, validateTwilioSignature, webSearch };

package/dist/index.d.ts

@@ -229,6 +229,31 @@ 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.95 — install-wide default voice CHARACTER per provider
+     * (e.g. `{ openai: 'cedar', grok: 'ara' }`). Optional — when a
+     * provider's slot is empty, the bridge falls back to the
+     * provider's own `defaultVoice`. Per-agent persona + per-call
+     * mission policy still beat this. The CLI's `agenticmail
+     * setup-voice` voice picker writes here.
+     */
+    voiceProviderVoices?: 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;
 }
@@ -2748,6 +2773,25 @@ interface OpenClawPhoneMissionPolicy {
      * {@link DEFAULT_CALLBACK_POLICY} when omitted.
      */
     callbackPolicy?: PhoneCallbackPolicy;
+    /**
+     * v0.9.95 — voice-runtime provider id ('openai', 'grok', any
+     * future plugin). Per-call override that beats agent persona
+     * frontmatter, install default, and bridge default. Optional.
+     */
+    voiceRuntime?: string;
+    /**
+     * v0.9.95 — model name override (e.g. `'gpt-realtime-mini'` for
+     * cost-tuning, `'grok-voice-fast'` for latency). Optional.
+     */
+    voiceModel?: string;
+    /**
+     * v0.9.95 — voice CHARACTER override (e.g. `'cedar'`, `'ara'`, or
+     * a custom-voice id from Grok). Optional. Validated against the
+     * provider's catalogue at session-open time; unknown names against
+     * a fixed-catalogue provider fall through to the provider default
+     * with a log warning.
+     */
+    voice?: string;
 }
 interface StartPhoneMissionInput {
     to: string;
@@ -3824,6 +3868,161 @@ 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;
+    /**
+     * v0.9.95 — built-in voice catalogue. The names the operator can
+     * pick when configuring a default voice for the agent or pinning
+     * one per-call. Empty array means "use whatever defaultVoice we
+     * ship" — used by providers like Grok that support arbitrary
+     * voice ids (cloned voices) instead of a fixed list.
+     */
+    voices: string[];
+    /**
+     * v0.9.95 — default voice the bridge picks when neither the
+     * mission policy nor the agent persona pins one. Per-provider:
+     * OpenAI defaults to "marin"; Grok lets the provider pick.
+     */
+    defaultVoice: string;
+    /**
+     * v0.9.95 — true when the provider accepts arbitrary voice ids
+     * beyond `voices` (e.g. Grok's Custom Voices API returns a
+     * `voice_id` that plugs in here). Tells the CLI picker to show a
+     * free-text input + a "paste a custom voice id" option after the
+     * built-in list.
+     */
+    customVoicesSupported?: boolean;
+}
+/**
+ * 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;
+    /**
+     * v0.9.95 — resolved voice name (sent in session.update under
+     * `audio.output.voice`). Picked from (in order):
+     *   1. caller-passed `options.voice` (mission policy)
+     *   2. agent persona's `voice:` frontmatter
+     *   3. install default in `config.voiceProviderVoices[<providerId>]`
+     *   4. provider's `defaultVoice` (e.g. OpenAI "marin", Grok "ara")
+     */
+    voice: string;
+    /** Human-readable source of the voice pick, for boot logs / audit. */
+    voiceSource: 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;
+    voice?: string;
+}): VoiceRuntimeConnection;
+
 type PhoneTransportProvider = '46elks' | 'twilio';
 /** Providers that support starting outbound call-control missions. */
 declare const PHONE_CALL_CONTROL_PROVIDERS: readonly PhoneTransportProvider[];
@@ -6235,11 +6434,16 @@ declare function buildDefaultPersona(agentName: string): string;
 /** Resolve the per-agent persona path on disk. */
 declare function personaPathFor(agentName: string): string;
 /**
- * Load the persona for {@link agentName}. Auto-creates the file with
- * {@link buildDefaultPersona} content on first read. Idempotent: a
- * second call returns whatever's on disk. Never throws — a permission
- * error or filesystem quirk falls back to the in-memory default so the
- * voice / email / telegram path is never crashed by a missing file.
+ * Load the persona BODY for {@link agentName}. Auto-creates the file
+ * with {@link buildDefaultPersona} content on first read. Idempotent.
+ * Never throws — a permission error or filesystem quirk falls back
+ * to the in-memory default so the voice / email / telegram path is
+ * never crashed by a missing file.
+ *
+ * v0.9.95 — if the file has YAML frontmatter (voice / voiceRuntime
+ * keys, written by `agenticmail persona --voice <name>`), the
+ * frontmatter is stripped from the returned string. Use
+ * {@link readAgentPersonaFile} to get the parsed frontmatter too.
  */
 declare function loadAgentPersona(agentName: string): string;
 /**
@@ -6247,5 +6451,43 @@ declare function loadAgentPersona(agentName: string): string;
  * edit command. Returns the path written to.
  */
 declare function saveAgentPersona(agentName: string, content: string): string;
+/**
+ * v0.9.95 — structured per-agent voice preferences. Stored as YAML
+ * frontmatter at the top of the persona file:
+ *
+ *   ---
+ *   voice: cedar
+ *   voiceRuntime: openai
+ *   ---
+ *   # Who you are
+ *   ...
+ *
+ * Both fields optional. Unknown keys are ignored on read. The CLI's
+ * `agenticmail persona --voice <name>` writes here. The realtime
+ * bridge consults this between the mission policy and the install
+ * default so an agent can have a consistent voice across every call
+ * without the caller pinning it on every invocation.
+ */
+interface AgentPersonaFrontmatter {
+    voice?: string;
+    voiceRuntime?: string;
+}
+/**
+ * Read frontmatter + body from the persona file. Best-effort; missing
+ * file returns empty frontmatter + an auto-seeded body. Robust to:
+ *   - No frontmatter at all (legacy files written before 0.9.95).
+ *   - Frontmatter with leading whitespace / CRLF.
+ *   - Junk lines in the YAML block — we only pick the keys we know.
+ */
+declare function readAgentPersonaFile(agentName: string): {
+    frontmatter: AgentPersonaFrontmatter;
+    body: string;
+};
+/**
+ * Update one or more frontmatter keys on an agent's persona file.
+ * Preserves the existing body. Auto-seeds the body if the file
+ * didn't exist yet.
+ */
+declare function updateAgentPersonaFrontmatter(agentName: string, patch: AgentPersonaFrontmatter): 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 AgentPersonaFrontmatter, 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, readAgentPersonaFile, 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, updateAgentPersonaFrontmatter, 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 {
@@ -6129,7 +6136,14 @@ function validatePhoneMissionPolicy(policy) {
       // manager) can read a concrete value without juggling undefined.
       // Caller-omitted → DEFAULT_*. Caller-set → clamped to server caps.
       extensionPolicy: resolveExtensionPolicy(policy.extensionPolicy),
-      callbackPolicy: resolveCallbackPolicy(policy.callbackPolicy)
+      callbackPolicy: resolveCallbackPolicy(policy.callbackPolicy),
+      // v0.9.95 — voice-runtime overrides. Pass-through; the registry
+      // validates the provider id and voice-against-catalogue at
+      // session-open time so we don't have to import the registry
+      // here (would create a cycle with realtime-bridge.ts).
+      voiceRuntime: typeof policy.voiceRuntime === "string" && policy.voiceRuntime.trim() ? policy.voiceRuntime.trim() : void 0,
+      voiceModel: typeof policy.voiceModel === "string" && policy.voiceModel.trim() ? policy.voiceModel.trim() : void 0,
+      voice: typeof policy.voice === "string" && policy.voice.trim() ? policy.voice.trim() : void 0
     },
     issues: []
   };
@@ -10530,6 +10544,140 @@ 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)}`;
+  let voice = "";
+  let voiceSource = "";
+  const requested = (options.voice || "").trim();
+  if (requested) {
+    if (provider.voices.includes(requested) || provider.customVoicesSupported) {
+      voice = requested;
+      voiceSource = "mission policy";
+    } else {
+      console.warn(
+        `[voice-providers] Voice "${requested}" is not in ${provider.id}'s catalogue (${provider.voices.join(", ")}). Falling through to ${provider.defaultVoice}.`
+      );
+    }
+  }
+  if (!voice) {
+    const installDefault = config.voiceProviderVoices?.[provider.id];
+    if (installDefault && installDefault.trim()) {
+      const v = installDefault.trim();
+      if (provider.voices.includes(v) || provider.customVoicesSupported) {
+        voice = v;
+        voiceSource = `config.voiceProviderVoices.${provider.id}`;
+      }
+    }
+  }
+  if (!voice) {
+    voice = provider.defaultVoice;
+    voiceSource = `${provider.id} default`;
+  }
+  return {
+    providerId: provider.id,
+    providerDisplayName: provider.displayName,
+    url,
+    model,
+    apiKey,
+    apiKeySource,
+    voice,
+    voiceSource
+  };
+}
+
+// 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.",
+  // v0.9.95 — voice catalogue. Names match what the Realtime session
+  // accepts under `audio.output.voice`. `marin` and `cedar` are the
+  // GA gpt-realtime additions; the rest are the legacy roster carried
+  // forward from gpt-4o-realtime-preview.
+  voices: ["alloy", "ash", "ballad", "cedar", "coral", "echo", "marin", "sage", "shimmer", "verse"],
+  defaultVoice: "marin"
+});
+
+// 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.',
+  // v0.9.95 — voice catalogue. xAI ships 5 expressive built-in
+  // voices for the realtime Voice Agent. Three are explicitly named
+  // in the announcement (Ara, Eve, Leo); the other two are
+  // browsable in console.x.ai's Voice Library along with the
+  // broader 80+ voice catalogue. The full live list is at
+  // GET /v1/tts/voices. We don't try to enumerate all 80+ here —
+  // customVoicesSupported lets operators paste any voice_id from
+  // their console.
+  voices: ["ara", "eve", "leo"],
+  defaultVoice: "ara",
+  customVoicesSupported: true
+});
+
 // src/telemetry.ts
 import { randomUUID as randomUUID2 } from "crypto";
 import { readFileSync as readFileSync2, writeFileSync as writeFileSync3, mkdirSync as mkdirSync3, existsSync as existsSync3 } from "fs";
@@ -14679,8 +14827,19 @@ function loadAgentPersona(agentName) {
   const path2 = personaPathFor(agentName);
   try {
     if (existsSync14(path2)) {
-      const content = readFileSync10(path2, "utf-8").trim();
-      if (content) return content;
+      const raw = readFileSync10(path2, "utf-8");
+      if (raw.trim()) {
+        const text = raw.replace(/\r\n/g, "\n");
+        if (text.startsWith("---\n")) {
+          const close = text.indexOf("\n---", 4);
+          if (close > 0) {
+            let cursor = close + 4;
+            while (cursor < text.length && (text[cursor] === "\n" || text[cursor] === "\r")) cursor++;
+            return text.slice(cursor).trim();
+          }
+        }
+        return text.trim();
+      }
     }
   } catch {
   }
@@ -14700,6 +14859,61 @@ function saveAgentPersona(agentName, content) {
   writeFileSync11(path2, content.trim() + "\n", { mode: 420 });
   return path2;
 }
+function readAgentPersonaFile(agentName) {
+  const path2 = personaPathFor(agentName);
+  let raw = "";
+  try {
+    if (existsSync14(path2)) raw = readFileSync10(path2, "utf-8");
+  } catch {
+  }
+  if (!raw.trim()) {
+    return { frontmatter: {}, body: loadAgentPersona(agentName) };
+  }
+  const text = raw.replace(/\r\n/g, "\n");
+  if (!text.startsWith("---\n")) {
+    return { frontmatter: {}, body: text.trim() };
+  }
+  const close = text.indexOf("\n---", 4);
+  if (close < 0) {
+    return { frontmatter: {}, body: text.trim() };
+  }
+  const yamlBlock = text.slice(4, close);
+  const bodyStart = close + 4;
+  let cursor = bodyStart;
+  while (cursor < text.length && (text[cursor] === "\n" || text[cursor] === "\r")) cursor++;
+  const body = text.slice(cursor).trim();
+  const frontmatter = {};
+  for (const line of yamlBlock.split("\n")) {
+    const m = /^\s*([A-Za-z][A-Za-z0-9_-]*)\s*:\s*(.*?)\s*$/.exec(line);
+    if (!m) continue;
+    const key = m[1];
+    const value = m[2].replace(/^["']|["']$/g, "");
+    if (key === "voice") frontmatter.voice = value;
+    else if (key === "voiceRuntime") frontmatter.voiceRuntime = value;
+  }
+  return { frontmatter, body };
+}
+function updateAgentPersonaFrontmatter(agentName, patch) {
+  const { frontmatter, body } = readAgentPersonaFile(agentName);
+  const merged = { ...frontmatter };
+  if (patch.voice !== void 0) merged.voice = patch.voice;
+  if (patch.voiceRuntime !== void 0) merged.voiceRuntime = patch.voiceRuntime;
+  const lines = [];
+  if (merged.voice && merged.voice.trim()) lines.push(`voice: ${merged.voice.trim()}`);
+  if (merged.voiceRuntime && merged.voiceRuntime.trim()) lines.push(`voiceRuntime: ${merged.voiceRuntime.trim()}`);
+  const path2 = personaPathFor(agentName);
+  const dir2 = path2.substring(0, path2.lastIndexOf("/"));
+  if (!existsSync14(dir2)) mkdirSync12(dir2, { recursive: true });
+  const content = lines.length > 0 ? `---
+${lines.join("\n")}
+---
+
+${body}
+` : `${body}
+`;
+  writeFileSync11(path2, content, { mode: 420 });
+  return path2;
+}
 export {
   AGENT_ROLES,
   AGENT_STATE_ROOT,
@@ -14859,6 +15073,7 @@ export {
   getTelegramMe,
   getTelegramUpdates,
   getTelegramWebhookInfo,
+  getVoiceProvider,
   hostSessionStoragePath,
   inferPhoneRegion,
   invalidateSkillCache,
@@ -14871,6 +15086,7 @@ export {
   isTelegramStopCommand,
   isValidPhoneNumber,
   listSkills,
+  listVoiceProviders,
   loadAgentPersona,
   loadHostSession,
   loadSkill,
@@ -14891,6 +15107,7 @@ export {
   personaPathFor,
   planBridgeWake,
   pollForOperatorAnswer,
+  readAgentPersonaFile,
   recallMemory,
   recordToolCall,
   redactBotToken,
@@ -14899,6 +15116,7 @@ export {
   redactSecret,
   redactSmsConfig,
   redactTelegramConfig,
+  registerVoiceProvider,
   renderSkillAsPrompt,
   requireBinary,
   requireWhisperModel,
@@ -14906,6 +15124,7 @@ export {
   resolveConfig,
   resolveExtensionPolicy,
   resolveTlsRejectUnauthorized,
+  resolveVoiceRuntime,
   safeJoin,
   sanitizeEmail,
   saveAgentPersona,
@@ -14927,6 +15146,7 @@ export {
   threadIdFor,
   tokenize,
   tryJoin,
+  updateAgentPersonaFrontmatter,
   userSkillsDir,
   validateApiUrl,
   validatePhoneMissionPolicy,

package/package.json

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