@agenticmail/core 0.9.39 → 0.9.40

package/dist/index.cjs

@@ -1644,6 +1644,7 @@ __export(index_exports, {
   personaPathFor: () => personaPathFor,
   planBridgeWake: () => planBridgeWake,
   pollForOperatorAnswer: () => pollForOperatorAnswer,
+  readAgentPersonaFile: () => readAgentPersonaFile,
   recallMemory: () => recallMemory,
   recordToolCall: () => recordToolCall,
   redactBotToken: () => redactBotToken,
@@ -1682,6 +1683,7 @@ __export(index_exports, {
   threadIdFor: () => threadIdFor,
   tokenize: () => tokenize,
   tryJoin: () => tryJoin,
+  updateAgentPersonaFrontmatter: () => updateAgentPersonaFrontmatter,
   userSkillsDir: () => userSkillsDir,
   validateApiUrl: () => validateApiUrl,
   validatePhoneMissionPolicy: () => validatePhoneMissionPolicy,
@@ -7813,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: []
   };
@@ -12267,13 +12276,42 @@ function resolveVoiceRuntime(providerId, config, options = {}) {
   }
   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
+    apiKeySource,
+    voice,
+    voiceSource
   };
 }
 
@@ -12289,7 +12327,13 @@ registerVoiceProvider({
   // 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."
+  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
@@ -12299,7 +12343,18 @@ registerVoiceProvider({
   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.'
+  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
@@ -16435,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 {
   }
@@ -16456,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,
@@ -16650,6 +16771,7 @@ function saveAgentPersona(agentName, content) {
   personaPathFor,
   planBridgeWake,
   pollForOperatorAnswer,
+  readAgentPersonaFile,
   recallMemory,
   recordToolCall,
   redactBotToken,
@@ -16688,6 +16810,7 @@ function saveAgentPersona(agentName, content) {
   threadIdFor,
   tokenize,
   tryJoin,
+  updateAgentPersonaFrontmatter,
   userSkillsDir,
   validateApiUrl,
   validatePhoneMissionPolicy,

package/dist/index.d.cts

@@ -238,6 +238,15 @@ interface AgenticMailConfig {
      * 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
@@ -2764,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;
@@ -3908,6 +3936,28 @@ interface VoiceProvider {
      * 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
@@ -3925,6 +3975,17 @@ interface VoiceRuntimeConnection {
     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;
 }
 
 /**
@@ -3959,6 +4020,7 @@ declare function getVoiceProvider(id: string): VoiceProvider | undefined;
  */
 declare function resolveVoiceRuntime(providerId: string | undefined, config: AgenticMailConfig, options?: {
     model?: string;
+    voice?: string;
 }): VoiceRuntimeConnection;
 
 type PhoneTransportProvider = '46elks' | 'twilio';
@@ -6372,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;
 /**
@@ -6384,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, 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 };
+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

@@ -238,6 +238,15 @@ interface AgenticMailConfig {
      * 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
@@ -2764,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;
@@ -3908,6 +3936,28 @@ interface VoiceProvider {
      * 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
@@ -3925,6 +3975,17 @@ interface VoiceRuntimeConnection {
     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;
 }
 
 /**
@@ -3959,6 +4020,7 @@ declare function getVoiceProvider(id: string): VoiceProvider | undefined;
  */
 declare function resolveVoiceRuntime(providerId: string | undefined, config: AgenticMailConfig, options?: {
     model?: string;
+    voice?: string;
 }): VoiceRuntimeConnection;
 
 type PhoneTransportProvider = '46elks' | 'twilio';
@@ -6372,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;
 /**
@@ -6384,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, 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 };
+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

@@ -6136,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: []
   };
@@ -10590,13 +10597,42 @@ function resolveVoiceRuntime(providerId, config, options = {}) {
   }
   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
+    apiKeySource,
+    voice,
+    voiceSource
   };
 }
 
@@ -10612,7 +10648,13 @@ registerVoiceProvider({
   // 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."
+  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
@@ -10622,7 +10664,18 @@ registerVoiceProvider({
   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.'
+  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
@@ -14774,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 {
   }
@@ -14795,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,
@@ -14988,6 +15107,7 @@ export {
   personaPathFor,
   planBridgeWake,
   pollForOperatorAnswer,
+  readAgentPersonaFile,
   recallMemory,
   recordToolCall,
   redactBotToken,
@@ -15026,6 +15146,7 @@ export {
   threadIdFor,
   tokenize,
   tryJoin,
+  updateAgentPersonaFrontmatter,
   userSkillsDir,
   validateApiUrl,
   validatePhoneMissionPolicy,

package/package.json

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