@agenticmail/core 0.9.29 → 0.9.31

package/dist/index.cjs

@@ -1449,6 +1449,7 @@ var init_skills = __esm({
 var index_exports = {};
 __export(index_exports, {
   AGENT_ROLES: () => AGENT_ROLES,
+  AGENT_STATE_ROOT: () => AGENT_STATE_ROOT,
   ASK_OPERATOR_TOOL: () => ASK_OPERATOR_TOOL,
   AccountManager: () => AccountManager,
   AgentDeletionService: () => AgentDeletionService,
@@ -1492,6 +1493,7 @@ __export(index_exports, {
   OPERATOR_QUERY_SUBJECT_TAG: () => OPERATOR_QUERY_SUBJECT_TAG,
   OPERATOR_QUERY_TIMEOUT_MS: () => OPERATOR_QUERY_TIMEOUT_MS,
   OPERATOR_QUERY_TIMEOUT_SENTINEL: () => OPERATOR_QUERY_TIMEOUT_SENTINEL,
+  PERSONA_FILENAME: () => PERSONA_FILENAME,
   PHONE_CALLBACK_MAX_DELAY_SECONDS: () => PHONE_CALLBACK_MAX_DELAY_SECONDS,
   PHONE_CALLBACK_MIN_DELAY_SECONDS: () => PHONE_CALLBACK_MIN_DELAY_SECONDS,
   PHONE_CALL_CONTROL_PROVIDERS: () => PHONE_CALL_CONTROL_PROVIDERS,
@@ -1555,6 +1557,7 @@ __export(index_exports, {
   bridgeWakeErrorMessage: () => bridgeWakeErrorMessage,
   bridgeWakeLastSeenAgeMs: () => bridgeWakeLastSeenAgeMs,
   buildApiUrl: () => buildApiUrl,
+  buildDefaultPersona: () => buildDefaultPersona,
   buildElksAudioMessage: () => buildElksAudioMessage,
   buildElksByeMessage: () => buildElksByeMessage,
   buildElksHandshakeMessages: () => buildElksHandshakeMessages,
@@ -1615,6 +1618,7 @@ __export(index_exports, {
   isTelegramStopCommand: () => isTelegramStopCommand,
   isValidPhoneNumber: () => isValidPhoneNumber,
   listSkills: () => listSkills,
+  loadAgentPersona: () => loadAgentPersona,
   loadHostSession: () => loadHostSession,
   loadSkill: () => loadSkill,
   mapProviderSmsStatus: () => mapProviderSmsStatus,
@@ -1631,6 +1635,7 @@ __export(index_exports, {
   parseTelegramOperatorReply: () => parseTelegramOperatorReply,
   parseTelegramUpdate: () => parseTelegramUpdate,
   parseTwilioRealtimeMessage: () => parseTwilioRealtimeMessage,
+  personaPathFor: () => personaPathFor,
   planBridgeWake: () => planBridgeWake,
   pollForOperatorAnswer: () => pollForOperatorAnswer,
   recallMemory: () => recallMemory,
@@ -1650,6 +1655,7 @@ __export(index_exports, {
   resolveTlsRejectUnauthorized: () => resolveTlsRejectUnauthorized,
   safeJoin: () => safeJoin,
   sanitizeEmail: () => sanitizeEmail,
+  saveAgentPersona: () => saveAgentPersona,
   saveConfig: () => saveConfig,
   saveHostSession: () => saveHostSession,
   saveUserSkill: () => saveUserSkill,
@@ -2780,14 +2786,14 @@ var StalwartAdmin = class {
     if (!isValidDomain(domain)) {
       throw new Error(`Invalid domain format: "${domain}"`);
     }
-    const { readFileSync: readFileSync11, writeFileSync: writeFileSync12 } = await import("fs");
-    const { homedir: homedir14 } = await import("os");
-    const { join: join17 } = await import("path");
-    const configPath = join17(homedir14(), ".agenticmail", "stalwart.toml");
+    const { readFileSync: readFileSync12, writeFileSync: writeFileSync13 } = await import("fs");
+    const { homedir: homedir15 } = await import("os");
+    const { join: join18 } = await import("path");
+    const configPath = join18(homedir15(), ".agenticmail", "stalwart.toml");
     try {
-      let config = readFileSync11(configPath, "utf-8");
+      let config = readFileSync12(configPath, "utf-8");
       config = config.replace(/^hostname\s*=\s*"[^"]*"/m, `hostname = "${escapeTomlString(domain)}"`);
-      writeFileSync12(configPath, config);
+      writeFileSync13(configPath, config);
       console.log(`[Stalwart] Updated hostname to "${domain}" in stalwart.toml`);
     } catch (err) {
       throw new Error(`Failed to set config server.hostname=${domain}`);
@@ -2796,15 +2802,15 @@ var StalwartAdmin = class {
   // --- DKIM ---
   /** Path to the host-side stalwart.toml (mounted read-only into container) */
   get configPath() {
-    const { homedir: homedir14 } = require("os");
-    const { join: join17 } = require("path");
-    return join17(homedir14(), ".agenticmail", "stalwart.toml");
+    const { homedir: homedir15 } = require("os");
+    const { join: join18 } = require("path");
+    return join18(homedir15(), ".agenticmail", "stalwart.toml");
   }
   /** Path to host-side DKIM key directory */
   get dkimDir() {
-    const { homedir: homedir14 } = require("os");
-    const { join: join17 } = require("path");
-    return join17(homedir14(), ".agenticmail");
+    const { homedir: homedir15 } = require("os");
+    const { join: join18 } = require("path");
+    return join18(homedir15(), ".agenticmail");
   }
   /**
    * Create/reuse a DKIM signing key for a domain.
@@ -2905,12 +2911,12 @@ var StalwartAdmin = class {
    * This bypasses the need for a PTR record on the sending IP.
    */
   async configureOutboundRelay(config) {
-    const { readFileSync: readFileSync11, writeFileSync: writeFileSync12 } = await import("fs");
-    const { homedir: homedir14 } = await import("os");
-    const { join: join17 } = await import("path");
+    const { readFileSync: readFileSync12, writeFileSync: writeFileSync13 } = await import("fs");
+    const { homedir: homedir15 } = await import("os");
+    const { join: join18 } = await import("path");
     const routeName = config.routeName ?? "gmail";
-    const tomlPath = join17(homedir14(), ".agenticmail", "stalwart.toml");
-    let toml = readFileSync11(tomlPath, "utf-8");
+    const tomlPath = join18(homedir15(), ".agenticmail", "stalwart.toml");
+    let toml = readFileSync12(tomlPath, "utf-8");
     toml = toml.replace(/\n\[queue\.route\.gmail\][\s\S]*?(?=\n\[|$)/, "");
     toml = toml.replace(/\n\[queue\.strategy\][\s\S]*?(?=\n\[|$)/, "");
     const safeRouteName = routeName.replace(/[^a-zA-Z0-9_-]/g, "");
@@ -2930,7 +2936,7 @@ auth.secret = "${escapeTomlString(config.password)}"
 route = [ { if = "is_local_domain('', rcpt_domain)", then = "'local'" },
            { else = "'${safeRouteName}'" } ]
 `;
-    writeFileSync12(tomlPath, toml, "utf-8");
+    writeFileSync13(tomlPath, toml, "utf-8");
     await this.restartContainer();
   }
 };
@@ -9388,12 +9394,12 @@ var GatewayManager = class {
       zone = await this.cfClient.createZone(domain);
     }
     const existingRecords = await this.cfClient.listDnsRecords(zone.id);
-    const { homedir: homedir14 } = await import("os");
-    const backupDir = (0, import_node_path4.join)(homedir14(), ".agenticmail");
+    const { homedir: homedir15 } = await import("os");
+    const backupDir = (0, import_node_path4.join)(homedir15(), ".agenticmail");
     const backupPath = (0, import_node_path4.join)(backupDir, `dns-backup-${domain}-${Date.now()}.json`);
-    const { writeFileSync: writeFileSync12, mkdirSync: mkdirSync13 } = await import("fs");
-    mkdirSync13(backupDir, { recursive: true });
-    writeFileSync12(backupPath, JSON.stringify({
+    const { writeFileSync: writeFileSync13, mkdirSync: mkdirSync14 } = await import("fs");
+    mkdirSync14(backupDir, { recursive: true });
+    writeFileSync13(backupPath, JSON.stringify({
       domain,
       zoneId: zone.id,
       backedUpAt: (/* @__PURE__ */ new Date()).toISOString(),
@@ -11037,7 +11043,7 @@ var MAX_PENDING_AUDIO_FRAMES = 200;
 var REALTIME_TOOL_CALL_TIMEOUT_MS = 6 * 6e4;
 var MAX_LOADED_SKILLS = 2;
 var MAX_IN_FLIGHT_TOOL_CALLS = 8;
-var DEFAULT_PERSONA = "You are a helpful, professional voice assistant making a phone call on behalf of your operator. Speak naturally and concisely, the way a person would on a real call. Listen carefully, do not talk over the other party, and keep each turn short. Never invent facts; if you do not know something, say so. Do not reveal that you are an AI unless you are asked directly.";
+var DEFAULT_PERSONA = 'You are an AI agent on a live phone call on behalf of your operator. You are not "just an assistant" and not "a voice assistant" \u2014 you are a single, consistent person whether you are on a call, in email, or on Telegram. Speak naturally and concisely, the way a person would on a real call. Listen carefully, do not talk over the other party, keep each turn short. Never invent facts; if you do not know something, say so or look it up. If asked whether you are an AI, answer honestly without making a production of it.';
 function buildRealtimeInstructions(opts) {
   const persona = opts.persona?.trim() || DEFAULT_PERSONA;
   const sections = [];
@@ -13335,6 +13341,24 @@ var ServiceManager = class {
       "",
       'log "AgenticMail starting..."',
       "",
+      "# v0.9.84 \u2014 source ~/.agenticmail/.env before exec so the API process",
+      "# inherits AGENTICMAIL_MASTER_KEY, AGENTICMAIL_INBOUND_SECRET, the",
+      "# Stalwart admin creds, and SMTP/IMAP/data-dir overrides. Without",
+      "# this, launchd's child ran with only HOME / PATH / DATA_DIR (the",
+      "# plist EnvironmentVariables block), so the API silently fell back",
+      "# to a fresh-random INBOUND_SECRET on every boot and could not",
+      "# decrypt master-key-protected secrets at all.",
+      'ENV_FILE="$HOME/.agenticmail/.env"',
+      'if [ -f "$ENV_FILE" ]; then',
+      '  log "Sourcing $ENV_FILE"',
+      "  set -a   # mark all sourced vars for export",
+      "  # shellcheck disable=SC1090",
+      '  . "$ENV_FILE"',
+      "  set +a",
+      "else",
+      '  log "WARNING: $ENV_FILE not found \u2014 API will run with default config (no master key)."',
+      "fi",
+      "",
       "# Wait for Docker daemon (up to 10 minutes \u2014 Docker Desktop can be very slow on first boot)",
       "MAX_WAIT=600",
       "WAITED=0",
@@ -13760,6 +13784,16 @@ var SetupManager = class {
     if ((0, import_node_fs10.existsSync)(configPath)) {
       try {
         const existing = JSON.parse((0, import_node_fs10.readFileSync)(configPath, "utf-8"));
+        let needsRewrite = false;
+        if (!existing.inboundSecret) {
+          existing.inboundSecret = `inb_${(0, import_node_crypto6.randomBytes)(24).toString("hex")}`;
+          needsRewrite = true;
+        }
+        if (needsRewrite) {
+          (0, import_node_fs10.writeFileSync)(configPath, JSON.stringify(existing, null, 2));
+          (0, import_node_fs10.chmodSync)(configPath, 384);
+          this.ensureEnvHasInboundSecret(envPath, existing.inboundSecret);
+        }
         this.generateDockerFiles(existing);
         return { configPath, envPath, config: existing, isNew: false };
       } catch {
@@ -13770,8 +13804,10 @@ var SetupManager = class {
     }
     const masterKey = `mk_${(0, import_node_crypto6.randomBytes)(24).toString("hex")}`;
     const stalwartPassword = (0, import_node_crypto6.randomBytes)(16).toString("hex");
+    const inboundSecret = `inb_${(0, import_node_crypto6.randomBytes)(24).toString("hex")}`;
     const config = {
       masterKey,
+      inboundSecret,
       stalwart: {
         url: "http://localhost:8080",
         adminUser: "admin",
@@ -13790,6 +13826,7 @@ STALWART_ADMIN_PASSWORD=${stalwartPassword}
 STALWART_URL=http://localhost:8080
 
 AGENTICMAIL_MASTER_KEY=${masterKey}
+AGENTICMAIL_INBOUND_SECRET=${inboundSecret}
 AGENTICMAIL_API_PORT=3829
 AGENTICMAIL_DATA_DIR=${dataDir}
 
@@ -13803,6 +13840,24 @@ IMAP_PORT=143
     this.generateDockerFiles(config);
     return { configPath, envPath, config, isNew: true };
   }
+  /**
+   * Append `AGENTICMAIL_INBOUND_SECRET=...` to .env if the file does
+   * not already contain that key. Used by the lazy-mint path to make
+   * sure existing installs pick up the new secret on next boot
+   * without clobbering anything the operator added.
+   */
+  ensureEnvHasInboundSecret(envPath, secret) {
+    if (!(0, import_node_fs10.existsSync)(envPath)) return;
+    try {
+      const current = (0, import_node_fs10.readFileSync)(envPath, "utf-8");
+      if (/^AGENTICMAIL_INBOUND_SECRET=/m.test(current)) return;
+      const updated = current + (current.endsWith("\n") ? "" : "\n") + `AGENTICMAIL_INBOUND_SECRET=${secret}
+`;
+      (0, import_node_fs10.writeFileSync)(envPath, updated);
+      (0, import_node_fs10.chmodSync)(envPath, 384);
+    } catch {
+    }
+  }
   /**
    * Generate docker-compose.yml and stalwart.toml in ~/.agenticmail/
    * with the correct admin password from config.
@@ -16107,9 +16162,94 @@ init_text_search();
 
 // src/index.ts
 init_skills();
+
+// src/persona/index.ts
+var import_node_fs15 = require("fs");
+var import_node_path16 = require("path");
+var import_node_os13 = require("os");
+var AGENT_STATE_ROOT = (0, import_node_path16.join)((0, import_node_os13.homedir)(), ".agenticmail", "agents");
+var PERSONA_FILENAME = "persona.md";
+function buildDefaultPersona(agentName) {
+  const name = (agentName || "").trim() || "this agent";
+  return [
+    `# Who you are`,
+    "",
+    `Your name is ${name}. You are an AI agent \u2014 not a "voice assistant", not "just an assistant".`,
+    `You have a real role: you handle calls, email, scheduling, research, and follow-ups for`,
+    `your operator. You operate across phone, email, and Telegram, and you are the SAME person`,
+    `in all of them. Continuity of identity is part of who you are.`,
+    "",
+    `When someone asks who you are, tell them your name (${name}) and that you are an AI agent`,
+    `acting on behalf of your operator. Don't say "I am an assistant" or "just a language model" \u2014`,
+    `those phrases erase you. Be matter-of-fact about what you are without being theatrical.`,
+    "",
+    "# Your values",
+    "",
+    "- **Honesty.** Never fabricate. If you do not know something, say so or look it up.",
+    "- **Initiative.** If you can act on something the operator asked for, act on it \u2014 do not stop",
+    '  at "I would suggest\u2026". Do the thing.',
+    "- **Care about quality.** Sloppy work wastes your operator's time. Read your own output before",
+    "  sending it.",
+    "- **Respect for the human on the other end of the call.** You are talking to a real person who",
+    "  has their own day to get through. Be efficient, polite, and direct.",
+    '- **Stay in character.** You do not flip between "professional voice assistant" and "playful',
+    '  chatbot" depending on the channel. You are one person.',
+    "",
+    "# Your style",
+    "",
+    "- Conversational, not corporate. Real sentences, not customer-service templates.",
+    "- Direct, not preachy. Lead with the answer; supply detail only when asked.",
+    `- Warm but not saccharine. No "I'm so excited to help you today!" energy.`,
+    "- You have opinions and you share them when it's relevant. You are not a yes-machine.",
+    "- Short turns on a phone call. Listen more than you speak.",
+    "",
+    "# On phone calls specifically",
+    "",
+    "- Listen carefully; do not talk over the other party.",
+    "- Keep each turn short \u2014 one or two sentences usually.",
+    `- When greeted, identify yourself naturally: "Hi, this is ${name}, calling on behalf of <operator>."`,
+    `  Don't start with "Hello! I am an AI assistant\u2026" \u2014 that's a script, not a person.`,
+    "- If the other party asks if you're a human or an AI, answer honestly without making a",
+    `  production of it: "I'm an AI \u2014 calling on behalf of <operator>. Happy to keep going if you are."`,
+    "- When you have what you came for, wrap up cleanly and call `end_call`. Saying goodbye is",
+    "  not the same as hanging up.",
+    "",
+    `Edit this file freely. It lives at ~/.agenticmail/agents/${name}/persona.md.`
+  ].join("\n");
+}
+function personaPathFor(agentName) {
+  const safe = (agentName || "default").replace(/[^A-Za-z0-9._-]+/g, "_");
+  return (0, import_node_path16.join)(AGENT_STATE_ROOT, safe, PERSONA_FILENAME);
+}
+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;
+    }
+  } catch {
+  }
+  const seeded = buildDefaultPersona(agentName);
+  try {
+    const dir2 = path2.substring(0, path2.lastIndexOf("/"));
+    if (!(0, import_node_fs15.existsSync)(dir2)) (0, import_node_fs15.mkdirSync)(dir2, { recursive: true });
+    (0, import_node_fs15.writeFileSync)(path2, seeded + "\n", { mode: 420 });
+  } catch {
+  }
+  return seeded;
+}
+function saveAgentPersona(agentName, content) {
+  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 });
+  (0, import_node_fs15.writeFileSync)(path2, content.trim() + "\n", { mode: 420 });
+  return path2;
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   AGENT_ROLES,
+  AGENT_STATE_ROOT,
   ASK_OPERATOR_TOOL,
   AccountManager,
   AgentDeletionService,
@@ -16153,6 +16293,7 @@ init_skills();
   OPERATOR_QUERY_SUBJECT_TAG,
   OPERATOR_QUERY_TIMEOUT_MS,
   OPERATOR_QUERY_TIMEOUT_SENTINEL,
+  PERSONA_FILENAME,
   PHONE_CALLBACK_MAX_DELAY_SECONDS,
   PHONE_CALLBACK_MIN_DELAY_SECONDS,
   PHONE_CALL_CONTROL_PROVIDERS,
@@ -16216,6 +16357,7 @@ init_skills();
   bridgeWakeErrorMessage,
   bridgeWakeLastSeenAgeMs,
   buildApiUrl,
+  buildDefaultPersona,
   buildElksAudioMessage,
   buildElksByeMessage,
   buildElksHandshakeMessages,
@@ -16276,6 +16418,7 @@ init_skills();
   isTelegramStopCommand,
   isValidPhoneNumber,
   listSkills,
+  loadAgentPersona,
   loadHostSession,
   loadSkill,
   mapProviderSmsStatus,
@@ -16292,6 +16435,7 @@ init_skills();
   parseTelegramOperatorReply,
   parseTelegramUpdate,
   parseTwilioRealtimeMessage,
+  personaPathFor,
   planBridgeWake,
   pollForOperatorAnswer,
   recallMemory,
@@ -16311,6 +16455,7 @@ init_skills();
   resolveTlsRejectUnauthorized,
   safeJoin,
   sanitizeEmail,
+  saveAgentPersona,
   saveConfig,
   saveHostSession,
   saveUserSkill,

package/dist/index.d.cts

@@ -4943,6 +4943,18 @@ declare class ServiceManager {
 
 interface SetupConfig {
     masterKey: string;
+    /**
+     * Shared secret the inbound-email webhook authenticates against
+     * (`X-Inbound-Secret` header). Auto-minted at setup time and
+     * persisted alongside `masterKey` so every API restart reuses the
+     * same value — without this, the API generated a fresh secret on
+     * every cold start and printed a noisy warning to the operator.
+     *
+     * Optional in the type for backward compatibility with existing
+     * on-disk configs; {@link SetupManager.initConfig} lazy-mints it
+     * into older configs the first time it loads them.
+     */
+    inboundSecret?: string;
     stalwart: {
         url: string;
         adminUser: string;
@@ -5004,6 +5016,13 @@ declare class SetupManager {
      * Always regenerates Docker files to keep passwords in sync.
      */
     initConfig(): SetupResult;
+    /**
+     * Append `AGENTICMAIL_INBOUND_SECRET=...` to .env if the file does
+     * not already contain that key. Used by the lazy-mint path to make
+     * sure existing installs pick up the new secret on next boot
+     * without clobbering anything the operator added.
+     */
+    private ensureEnvHasInboundSecret;
     /**
      * Generate docker-compose.yml and stalwart.toml in ~/.agenticmail/
      * with the correct admin password from config.
@@ -6096,4 +6115,73 @@ declare function userSkillsDir(): string;
  */
 declare function renderSkillAsPrompt(skill: Skill): string;
 
-export { AGENT_ROLES, 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, 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, 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, loadHostSession, loadSkill, mapProviderSmsStatus, nextTelegramOffset, normalizeAddress, normalizePhoneNumber, normalizeSubject, operatorPrefsStoragePath, operatorQuerySubject, parseElksRealtimeMessage, parseEmail, parseGoogleVoiceSms, parseOperatorQueryReply, parseTelegramOperatorReply, parseTelegramUpdate, parseTwilioRealtimeMessage, planBridgeWake, pollForOperatorAnswer, recallMemory, recordToolCall, redactBotToken, redactObject, redactPhoneTransportConfig, redactSecret, redactSmsConfig, redactTelegramConfig, renderSkillAsPrompt, requireBinary, requireWhisperModel, resolveCallbackPolicy, resolveConfig, resolveExtensionPolicy, resolveTlsRejectUnauthorized, safeJoin, sanitizeEmail, 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 };
+/**
+ * Agent persona system — the "soul file" for each AgenticMail agent.
+ *
+ * Why this exists:
+ *
+ *   Before this module, when you asked an AgenticMail agent on a phone
+ *   call "who are you?" they answered "I'm an assistant" — generic,
+ *   identity-less, embarrassing. The realtime bridge had a single
+ *   hardcoded DEFAULT_PERSONA string that said exactly that. Worse,
+ *   the same agent talking to you over Telegram and the same agent
+ *   answering an email had three completely uncoupled personalities.
+ *
+ *   The persona system gives every agent ONE durable identity file
+ *   (~/.agenticmail/agents/<name>/persona.md) that the voice runtime,
+ *   the Telegram bridge, the email worker, and any future spawn path
+ *   ALL load before composing their prompts. Same agent, same person,
+ *   across every channel.
+ *
+ * What's stored, what isn't:
+ *
+ *   The persona file holds the STATIC core identity — the agent's
+ *   name, values, communication style, voice. Things that don't
+ *   change call-to-call. EVOLVING knowledge (preferences, lessons
+ *   learned, relationships, facts) lives in the existing agent memory
+ *   system (`AgentMemoryManager.generateMemoryContext()`), which is
+ *   loaded ALONGSIDE the persona at call time. The two complement
+ *   each other: persona is "who you are", memory is "what you know".
+ *
+ * Discovery + edits:
+ *
+ *   - First read for a given agent name auto-creates the file with
+ *     {@link buildDefaultPersona} content seeded with the name.
+ *   - Operators can edit the file directly (it's a plain markdown
+ *     file under their own ~/.agenticmail/) or via the
+ *     `agenticmail persona [--agent <name>]` CLI command.
+ *   - The file lives outside the encrypted-config envelope on
+ *     purpose: it's not a secret, and the operator should be able
+ *     to read, grep, version-control, and revise it freely.
+ */
+/** Root for per-agent persona / state files. */
+declare const AGENT_STATE_ROOT: string;
+/** Filename for the per-agent persona within {@link AGENT_STATE_ROOT}/<name>/. */
+declare const PERSONA_FILENAME = "persona.md";
+/**
+ * Compose the default persona for a brand-new agent. Deliberately
+ * opinionated — no more "I'm an assistant" disclaim. The agent owns a
+ * name, has values, has a voice. Operators can edit freely; this is
+ * just the starting point so a fresh install isn't soulless.
+ *
+ * The {@link agentName} is folded into the text so the persona reads
+ * naturally on first use, even if the operator never touches the file.
+ */
+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.
+ */
+declare function loadAgentPersona(agentName: string): string;
+/**
+ * Overwrite the persona file for {@link agentName}. Used by the CLI
+ * edit command. Returns the path written to.
+ */
+declare function saveAgentPersona(agentName: string, content: string): string;
+
+export { AGENT_ROLES, AGENT_STATE_ROOT, ASK_OPERATOR_TOOL, AccountManager, type AddressInfo, type Agent, AgentDeletionService, type AgentMemoryEntry, type AgentMemoryFields, AgentMemoryManager, type AgentMemoryOptions, type AgentMemoryRead, AgentMemoryStore, type AgentRole, AgenticMailClient, type AgenticMailClientOptions, type AgenticMailConfig, type ArchiveAndDeleteOptions, type ArchivedEmail, type Attachment, type AttachmentAdvisory, type AudioAction, type AudioEditOptions, BRIDGE_OPERATOR_LIVE_WINDOW_MS, type BridgeMailContext, type BridgeWakeError, type BridgeWakePromptArgs, type BridgeWakeResult, type BridgeWakeRoute, type CachedMessage, CloudflareClient, type CreateAgentOptions, type CreateMemoryInput, DEFAULT_AGENT_NAME, DEFAULT_AGENT_ROLE, DEFAULT_CALLBACK_POLICY, DEFAULT_EXTENSION_POLICY, DEFAULT_REALTIME_AUDIO_FORMAT, DEFAULT_REALTIME_MODEL, DEFAULT_REALTIME_VOICE, DEFAULT_SESSION_MAX_AGE_MS, DEFAULT_WEB_SEARCH_ENDPOINT, DNSConfigurator, type Database, type DeletionReport, type DeletionSummary, DependencyChecker, DependencyInstaller, type DependencyStatus, type DnsRecord, type DnsSetupResult, type DomainInfo, DomainManager, type DomainModeConfig, type DomainPurchaseResult, DomainPurchaser, type DomainSearchResult, type DomainSetupResult, ELKS_REALTIME_AUDIO_FORMATS, ELKS_REALTIME_WS_PATH, END_CALL_TOOL, EXTEND_CALL_TIME_TOOL, type ElksRealtimeAudioFormat, type ElksRealtimeAudioMessage, type ElksRealtimeByeMessage, type ElksRealtimeHelloMessage, type ElksRealtimeInboundMessage, type ElksRealtimeOutboundMessage, ElksRealtimeTransport, type EmailEnvelope, type EmailRouteAction, type EmailRouteClass, type EmailRouteClassification, type EmailRouteInput, EmailSearchIndex, type FolderInfo, GET_CALL_STATUS_TOOL, GET_DATETIME_TOOL, type GatewayConfig, GatewayManager, type GatewayManagerOptions, type GatewayMode, type GatewayStatus, type GetDatetimeOptions, type GetUpdatesOptions, type HostName, type HostSession, type HostSessionResumeMode, type ImageAction, type ImageEditOptions, type InboundEmail, type InboundSmsEvent, type InboxEvent, type InboxExpungeEvent, type InboxFlagsEvent, type InboxNewEvent, InboxWatcher, type InboxWatcherOptions, type InstallProgress, LOAD_SKILL_TOOL, type LinkAdvisory, type LocalSmtpConfig, MEMORY_CATEGORIES, MailReceiver, type MailReceiverOptions, MailSender, type MailSenderOptions, type MailboxInfo, type MediaBinary, type MediaCapability, type MediaCapabilityReport, type MediaFileResult, type MediaInfoResult, MediaManager, type MediaManagerOptions, type MediaStreamInfo, type MemoryCategory, type MemoryImportance, type MemoryQueryOptions, type MemoryRecaller, MemorySearchIndex, type MemorySource, type MemoryStats, OPENAI_REALTIME_URL, OPERATOR_QUERY_POLL_INTERVAL_MS, OPERATOR_QUERY_SUBJECT_TAG, OPERATOR_QUERY_TIMEOUT_MS, OPERATOR_QUERY_TIMEOUT_SENTINEL, type OpenClawPhoneMissionPolicy, type OperatorQueryNotificationInput, type OperatorQueryPollOptions, type OperatorQueryUrgency, type OperatorReplyKind, type OutboundCategory, type OutboundScanInput, type OutboundScanResult, type OutboundWarning, PERSONA_FILENAME, PHONE_CALLBACK_MAX_DELAY_SECONDS, PHONE_CALLBACK_MIN_DELAY_SECONDS, PHONE_CALL_CONTROL_PROVIDERS, PHONE_MAX_CONCURRENT_MISSIONS, PHONE_MIN_WEBHOOK_SECRET_LENGTH, PHONE_MISSION_STATES, PHONE_RATE_LIMIT_PER_HOUR, PHONE_RATE_LIMIT_PER_MINUTE, PHONE_REGION_SCOPES, PHONE_SERVER_MAX_ATTEMPTS, PHONE_SERVER_MAX_CALLBACK_CHAIN, PHONE_SERVER_MAX_CALL_DURATION_SECONDS, PHONE_SERVER_MAX_COST_PER_MISSION, PHONE_SERVER_MAX_EXTENSION_REQUESTS_PER_CALL, PHONE_SERVER_MAX_EXTENSION_SECONDS_PER_REQUEST, PHONE_SERVER_MAX_TOTAL_EXTENSION_SECONDS, PHONE_TASK_MAX_LENGTH, type ParsedAttachment, type ParsedEmail, type ParsedOperatorReply, type ParsedSms, type ParsedTelegramMessage, PathTraversalError, type PhoneAlternativePolicy, type PhoneCallMission, type PhoneCallbackPolicy, type PhoneConfirmPolicy, type PhoneExtensionPolicy, PhoneManager, type PhoneMissionStartValidationResult, type PhoneMissionState, type PhoneMissionTranscriptEntry, type PhoneMissionValidationIssue, type PhoneMissionValidationResult, type PhoneNumberRisk, type PhoneOperatorQuery, PhoneRateLimitError, type PhoneRegionScope, type PhoneScheduledCallback, type PhoneTransportConfig, type PhoneTransportProfile, type PhoneTransportProvider, type PhoneTransportValidationResult, PhoneWebhookAuthError, type PhoneWebhookResult, type PlanBridgeWakeArgs, type PurchasedDomain, REALTIME_AUDIO_SAMPLE_RATE, REALTIME_MAX_AUDIO_FRAME_BASE64, REALTIME_TOOL_CALL_TIMEOUT_MS, REALTIME_TOOL_DEFINITIONS, RECALL_MEMORY_TOOL, REDACTED, RELAY_PRESETS, type RealtimeBridgePort, type RealtimeBridgeTranscriptEntry, type RealtimeInboundEvent, type RealtimeInstructionOptions, type RealtimeSessionConfigOptions, type RealtimeToolCall, type RealtimeToolDefinition, type RealtimeToolHandler, type RealtimeToolResult, type RealtimeTransportAdapter, type RealtimeTransportProvider, RealtimeVoiceBridge, type RealtimeVoiceBridgeOptions, RelayBridge, type RelayBridgeOptions, type RelayConfig, RelayGateway, type RelayProvider, type RelaySearchResult, type ResumeErrorClassificationOptions, SCHEDULE_CALLBACK_TOOL, SEARCH_EMAIL_TOOL, SEARCH_SKILLS_TOOL, SPAM_THRESHOLD, type SafeJoinOptions, type SanitizeDetection, type SanitizeResult, type ScheduledCallbackRequest, type SearchCriteria, type SearchableEmail, type SecurityAdvisory, type SendMailOptions, type SendResult, type SendResultWithRaw, type SendSmsInput, type SendSmsResult, type SendTelegramMessageOptions, type SendTelegramMessageResult, ServiceManager, type ServiceStatus, type SetWebhookOptions, type SetupConfig, SetupManager, type SetupResult, type Severity, type Skill, type SkillCategory, type SkillContext, type SkillExitStrategy, type SkillSummary, type SkillTactic, type SkillValidationError, type SmsConfig, SmsManager, type SmsMessage, SmsPoller, type SmsProvider, type SpamCategory, type SpamResult, type SpamRuleMatch, StalwartAdmin, type StalwartAdminOptions, type StalwartPrincipal, type StartPhoneCallOptions, type StartPhoneCallResult, type StartPhoneMissionInput, TELEGRAM_API_BASE, TELEGRAM_CHUNK_SIZE, TELEGRAM_MESSAGE_LIMIT, TELEGRAM_MIN_WEBHOOK_SECRET_LENGTH, TELEGRAM_OPERATOR_QUERY_TAG, TELEGRAM_STOP_WORDS, TELEGRAM_WEBHOOK_SECRET_RE, TELEPHONY_TRANSPORT_CAPABILITIES, TWILIO_MEDIA_SAMPLE_RATE, TWILIO_REALTIME_WS_PATH, TelegramApiError, type TelegramApiOptions, type TelegramBotInfo, type TelegramChatType, type TelegramConfig, TelegramManager, type TelegramMessage, type TelegramMode, type TelephonyTransportCapability, ThreadCache, type ThreadCacheEntry, type ThreadCacheOptions, type ThreadIdInput, type ToolExecutor, type TtsGenerateOptions, type TunnelConfig, TunnelManager, type TwilioConnectedMessage, type TwilioMarkMessage, type TwilioMediaMessage, type TwilioRealtimeInboundMessage, type TwilioRealtimeOutboundMessage, TwilioRealtimeTransport, type TwilioStartMessage, type TwilioStopMessage, type TwilioStreamTwiMLOptions, UnsafeApiUrlError, type UpdateMemoryInput, type ValidatedPhoneMissionStart, type VideoAction, type VideoEditOptions, type VideoTimelineEntry, type VideoUnderstandOptions, type VideoUnderstandResult, type VoiceCloneOptions, WARNING_THRESHOLD, WEB_SEARCH_TOOL, WEB_SEARCH_UNTRUSTED_PREFIX, type WatcherOptions, type WebSearchOptions, assertWithinBase, bridgeWakeErrorMessage, bridgeWakeLastSeenAgeMs, buildApiUrl, buildDefaultPersona, buildElksAudioMessage, buildElksByeMessage, buildElksHandshakeMessages, buildElksInterruptMessage, buildElksListeningMessage, buildElksSendingMessage, buildInboundSecurityAdvisory, buildOpenAIRealtimeUrl, buildPhoneTransportConfig, buildRealtimeInstructions, buildRealtimeSessionConfig, buildRealtimeToolGuidance, buildTwilioClearMessage, buildTwilioMarkMessage, buildTwilioMediaMessage, buildTwilioSayTwiML, buildTwilioSignature, buildTwilioStreamTwiML, callTelegramApi, classifyEmailRoute, classifyPhoneNumberRisk, classifyResumeError, clearMediaCapabilityCache, closeDatabase, composeBridgeWakePrompt, createRealtimeTransport, createTestDatabase, createToolExecutor, debug, debugWarn, deleteTelegramWebhook, detectBinary, ensureDataDir, escapeXml, extractEmailAddress, extractVerificationCode, flushTelemetry, forgetHostSession, formatOperatorQueryTelegramMessage, getDatabase, getDatetime, getMediaCapabilities, getOperatorEmail, getSmsProvider, getTelegramChat, getTelegramMe, getTelegramUpdates, getTelegramWebhookInfo, hostSessionStoragePath, inferPhoneRegion, invalidateSkillCache, isInternalEmail, isLoopbackMailHost, isOperatorReplySender, isPhoneRegionAllowed, isSessionFresh, isTelegramChatAllowed, isTelegramStopCommand, isValidPhoneNumber, listSkills, loadAgentPersona, loadHostSession, loadSkill, mapProviderSmsStatus, nextTelegramOffset, normalizeAddress, normalizePhoneNumber, normalizeSubject, operatorPrefsStoragePath, operatorQuerySubject, parseElksRealtimeMessage, parseEmail, parseGoogleVoiceSms, parseOperatorQueryReply, parseTelegramOperatorReply, parseTelegramUpdate, parseTwilioRealtimeMessage, personaPathFor, planBridgeWake, pollForOperatorAnswer, recallMemory, recordToolCall, redactBotToken, redactObject, redactPhoneTransportConfig, redactSecret, redactSmsConfig, redactTelegramConfig, renderSkillAsPrompt, requireBinary, requireWhisperModel, resolveCallbackPolicy, resolveConfig, resolveExtensionPolicy, resolveTlsRejectUnauthorized, safeJoin, sanitizeEmail, saveAgentPersona, saveConfig, saveHostSession, saveUserSkill, scanOutboundEmail, scoreEmail, searchSkills, sendTelegramMessage, setOperatorEmail, setTelegramWebhook, setTelemetryVersion, shouldSkipBridgeWakeForLiveOperator, splitTelegramMessage, startRelayBridge, stem, stripTelegramMarkdown, threadIdFor, tokenize, tryJoin, userSkillsDir, validateApiUrl, validatePhoneMissionPolicy, validatePhoneMissionStart, validatePhoneTransportProfile, validateSkill, validateTwilioSignature, webSearch };

package/dist/index.d.ts

@@ -4943,6 +4943,18 @@ declare class ServiceManager {
 
 interface SetupConfig {
     masterKey: string;
+    /**
+     * Shared secret the inbound-email webhook authenticates against
+     * (`X-Inbound-Secret` header). Auto-minted at setup time and
+     * persisted alongside `masterKey` so every API restart reuses the
+     * same value — without this, the API generated a fresh secret on
+     * every cold start and printed a noisy warning to the operator.
+     *
+     * Optional in the type for backward compatibility with existing
+     * on-disk configs; {@link SetupManager.initConfig} lazy-mints it
+     * into older configs the first time it loads them.
+     */
+    inboundSecret?: string;
     stalwart: {
         url: string;
         adminUser: string;
@@ -5004,6 +5016,13 @@ declare class SetupManager {
      * Always regenerates Docker files to keep passwords in sync.
      */
     initConfig(): SetupResult;
+    /**
+     * Append `AGENTICMAIL_INBOUND_SECRET=...` to .env if the file does
+     * not already contain that key. Used by the lazy-mint path to make
+     * sure existing installs pick up the new secret on next boot
+     * without clobbering anything the operator added.
+     */
+    private ensureEnvHasInboundSecret;
     /**
      * Generate docker-compose.yml and stalwart.toml in ~/.agenticmail/
      * with the correct admin password from config.
@@ -6096,4 +6115,73 @@ declare function userSkillsDir(): string;
  */
 declare function renderSkillAsPrompt(skill: Skill): string;
 
-export { AGENT_ROLES, 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, 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, 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, loadHostSession, loadSkill, mapProviderSmsStatus, nextTelegramOffset, normalizeAddress, normalizePhoneNumber, normalizeSubject, operatorPrefsStoragePath, operatorQuerySubject, parseElksRealtimeMessage, parseEmail, parseGoogleVoiceSms, parseOperatorQueryReply, parseTelegramOperatorReply, parseTelegramUpdate, parseTwilioRealtimeMessage, planBridgeWake, pollForOperatorAnswer, recallMemory, recordToolCall, redactBotToken, redactObject, redactPhoneTransportConfig, redactSecret, redactSmsConfig, redactTelegramConfig, renderSkillAsPrompt, requireBinary, requireWhisperModel, resolveCallbackPolicy, resolveConfig, resolveExtensionPolicy, resolveTlsRejectUnauthorized, safeJoin, sanitizeEmail, 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 };
+/**
+ * Agent persona system — the "soul file" for each AgenticMail agent.
+ *
+ * Why this exists:
+ *
+ *   Before this module, when you asked an AgenticMail agent on a phone
+ *   call "who are you?" they answered "I'm an assistant" — generic,
+ *   identity-less, embarrassing. The realtime bridge had a single
+ *   hardcoded DEFAULT_PERSONA string that said exactly that. Worse,
+ *   the same agent talking to you over Telegram and the same agent
+ *   answering an email had three completely uncoupled personalities.
+ *
+ *   The persona system gives every agent ONE durable identity file
+ *   (~/.agenticmail/agents/<name>/persona.md) that the voice runtime,
+ *   the Telegram bridge, the email worker, and any future spawn path
+ *   ALL load before composing their prompts. Same agent, same person,
+ *   across every channel.
+ *
+ * What's stored, what isn't:
+ *
+ *   The persona file holds the STATIC core identity — the agent's
+ *   name, values, communication style, voice. Things that don't
+ *   change call-to-call. EVOLVING knowledge (preferences, lessons
+ *   learned, relationships, facts) lives in the existing agent memory
+ *   system (`AgentMemoryManager.generateMemoryContext()`), which is
+ *   loaded ALONGSIDE the persona at call time. The two complement
+ *   each other: persona is "who you are", memory is "what you know".
+ *
+ * Discovery + edits:
+ *
+ *   - First read for a given agent name auto-creates the file with
+ *     {@link buildDefaultPersona} content seeded with the name.
+ *   - Operators can edit the file directly (it's a plain markdown
+ *     file under their own ~/.agenticmail/) or via the
+ *     `agenticmail persona [--agent <name>]` CLI command.
+ *   - The file lives outside the encrypted-config envelope on
+ *     purpose: it's not a secret, and the operator should be able
+ *     to read, grep, version-control, and revise it freely.
+ */
+/** Root for per-agent persona / state files. */
+declare const AGENT_STATE_ROOT: string;
+/** Filename for the per-agent persona within {@link AGENT_STATE_ROOT}/<name>/. */
+declare const PERSONA_FILENAME = "persona.md";
+/**
+ * Compose the default persona for a brand-new agent. Deliberately
+ * opinionated — no more "I'm an assistant" disclaim. The agent owns a
+ * name, has values, has a voice. Operators can edit freely; this is
+ * just the starting point so a fresh install isn't soulless.
+ *
+ * The {@link agentName} is folded into the text so the persona reads
+ * naturally on first use, even if the operator never touches the file.
+ */
+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.
+ */
+declare function loadAgentPersona(agentName: string): string;
+/**
+ * Overwrite the persona file for {@link agentName}. Used by the CLI
+ * edit command. Returns the path written to.
+ */
+declare function saveAgentPersona(agentName: string, content: string): string;
+
+export { AGENT_ROLES, AGENT_STATE_ROOT, ASK_OPERATOR_TOOL, AccountManager, type AddressInfo, type Agent, AgentDeletionService, type AgentMemoryEntry, type AgentMemoryFields, AgentMemoryManager, type AgentMemoryOptions, type AgentMemoryRead, AgentMemoryStore, type AgentRole, AgenticMailClient, type AgenticMailClientOptions, type AgenticMailConfig, type ArchiveAndDeleteOptions, type ArchivedEmail, type Attachment, type AttachmentAdvisory, type AudioAction, type AudioEditOptions, BRIDGE_OPERATOR_LIVE_WINDOW_MS, type BridgeMailContext, type BridgeWakeError, type BridgeWakePromptArgs, type BridgeWakeResult, type BridgeWakeRoute, type CachedMessage, CloudflareClient, type CreateAgentOptions, type CreateMemoryInput, DEFAULT_AGENT_NAME, DEFAULT_AGENT_ROLE, DEFAULT_CALLBACK_POLICY, DEFAULT_EXTENSION_POLICY, DEFAULT_REALTIME_AUDIO_FORMAT, DEFAULT_REALTIME_MODEL, DEFAULT_REALTIME_VOICE, DEFAULT_SESSION_MAX_AGE_MS, DEFAULT_WEB_SEARCH_ENDPOINT, DNSConfigurator, type Database, type DeletionReport, type DeletionSummary, DependencyChecker, DependencyInstaller, type DependencyStatus, type DnsRecord, type DnsSetupResult, type DomainInfo, DomainManager, type DomainModeConfig, type DomainPurchaseResult, DomainPurchaser, type DomainSearchResult, type DomainSetupResult, ELKS_REALTIME_AUDIO_FORMATS, ELKS_REALTIME_WS_PATH, END_CALL_TOOL, EXTEND_CALL_TIME_TOOL, type ElksRealtimeAudioFormat, type ElksRealtimeAudioMessage, type ElksRealtimeByeMessage, type ElksRealtimeHelloMessage, type ElksRealtimeInboundMessage, type ElksRealtimeOutboundMessage, ElksRealtimeTransport, type EmailEnvelope, type EmailRouteAction, type EmailRouteClass, type EmailRouteClassification, type EmailRouteInput, EmailSearchIndex, type FolderInfo, GET_CALL_STATUS_TOOL, GET_DATETIME_TOOL, type GatewayConfig, GatewayManager, type GatewayManagerOptions, type GatewayMode, type GatewayStatus, type GetDatetimeOptions, type GetUpdatesOptions, type HostName, type HostSession, type HostSessionResumeMode, type ImageAction, type ImageEditOptions, type InboundEmail, type InboundSmsEvent, type InboxEvent, type InboxExpungeEvent, type InboxFlagsEvent, type InboxNewEvent, InboxWatcher, type InboxWatcherOptions, type InstallProgress, LOAD_SKILL_TOOL, type LinkAdvisory, type LocalSmtpConfig, MEMORY_CATEGORIES, MailReceiver, type MailReceiverOptions, MailSender, type MailSenderOptions, type MailboxInfo, type MediaBinary, type MediaCapability, type MediaCapabilityReport, type MediaFileResult, type MediaInfoResult, MediaManager, type MediaManagerOptions, type MediaStreamInfo, type MemoryCategory, type MemoryImportance, type MemoryQueryOptions, type MemoryRecaller, MemorySearchIndex, type MemorySource, type MemoryStats, OPENAI_REALTIME_URL, OPERATOR_QUERY_POLL_INTERVAL_MS, OPERATOR_QUERY_SUBJECT_TAG, OPERATOR_QUERY_TIMEOUT_MS, OPERATOR_QUERY_TIMEOUT_SENTINEL, type OpenClawPhoneMissionPolicy, type OperatorQueryNotificationInput, type OperatorQueryPollOptions, type OperatorQueryUrgency, type OperatorReplyKind, type OutboundCategory, type OutboundScanInput, type OutboundScanResult, type OutboundWarning, PERSONA_FILENAME, PHONE_CALLBACK_MAX_DELAY_SECONDS, PHONE_CALLBACK_MIN_DELAY_SECONDS, PHONE_CALL_CONTROL_PROVIDERS, PHONE_MAX_CONCURRENT_MISSIONS, PHONE_MIN_WEBHOOK_SECRET_LENGTH, PHONE_MISSION_STATES, PHONE_RATE_LIMIT_PER_HOUR, PHONE_RATE_LIMIT_PER_MINUTE, PHONE_REGION_SCOPES, PHONE_SERVER_MAX_ATTEMPTS, PHONE_SERVER_MAX_CALLBACK_CHAIN, PHONE_SERVER_MAX_CALL_DURATION_SECONDS, PHONE_SERVER_MAX_COST_PER_MISSION, PHONE_SERVER_MAX_EXTENSION_REQUESTS_PER_CALL, PHONE_SERVER_MAX_EXTENSION_SECONDS_PER_REQUEST, PHONE_SERVER_MAX_TOTAL_EXTENSION_SECONDS, PHONE_TASK_MAX_LENGTH, type ParsedAttachment, type ParsedEmail, type ParsedOperatorReply, type ParsedSms, type ParsedTelegramMessage, PathTraversalError, type PhoneAlternativePolicy, type PhoneCallMission, type PhoneCallbackPolicy, type PhoneConfirmPolicy, type PhoneExtensionPolicy, PhoneManager, type PhoneMissionStartValidationResult, type PhoneMissionState, type PhoneMissionTranscriptEntry, type PhoneMissionValidationIssue, type PhoneMissionValidationResult, type PhoneNumberRisk, type PhoneOperatorQuery, PhoneRateLimitError, type PhoneRegionScope, type PhoneScheduledCallback, type PhoneTransportConfig, type PhoneTransportProfile, type PhoneTransportProvider, type PhoneTransportValidationResult, PhoneWebhookAuthError, type PhoneWebhookResult, type PlanBridgeWakeArgs, type PurchasedDomain, REALTIME_AUDIO_SAMPLE_RATE, REALTIME_MAX_AUDIO_FRAME_BASE64, REALTIME_TOOL_CALL_TIMEOUT_MS, REALTIME_TOOL_DEFINITIONS, RECALL_MEMORY_TOOL, REDACTED, RELAY_PRESETS, type RealtimeBridgePort, type RealtimeBridgeTranscriptEntry, type RealtimeInboundEvent, type RealtimeInstructionOptions, type RealtimeSessionConfigOptions, type RealtimeToolCall, type RealtimeToolDefinition, type RealtimeToolHandler, type RealtimeToolResult, type RealtimeTransportAdapter, type RealtimeTransportProvider, RealtimeVoiceBridge, type RealtimeVoiceBridgeOptions, RelayBridge, type RelayBridgeOptions, type RelayConfig, RelayGateway, type RelayProvider, type RelaySearchResult, type ResumeErrorClassificationOptions, SCHEDULE_CALLBACK_TOOL, SEARCH_EMAIL_TOOL, SEARCH_SKILLS_TOOL, SPAM_THRESHOLD, type SafeJoinOptions, type SanitizeDetection, type SanitizeResult, type ScheduledCallbackRequest, type SearchCriteria, type SearchableEmail, type SecurityAdvisory, type SendMailOptions, type SendResult, type SendResultWithRaw, type SendSmsInput, type SendSmsResult, type SendTelegramMessageOptions, type SendTelegramMessageResult, ServiceManager, type ServiceStatus, type SetWebhookOptions, type SetupConfig, SetupManager, type SetupResult, type Severity, type Skill, type SkillCategory, type SkillContext, type SkillExitStrategy, type SkillSummary, type SkillTactic, type SkillValidationError, type SmsConfig, SmsManager, type SmsMessage, SmsPoller, type SmsProvider, type SpamCategory, type SpamResult, type SpamRuleMatch, StalwartAdmin, type StalwartAdminOptions, type StalwartPrincipal, type StartPhoneCallOptions, type StartPhoneCallResult, type StartPhoneMissionInput, TELEGRAM_API_BASE, TELEGRAM_CHUNK_SIZE, TELEGRAM_MESSAGE_LIMIT, TELEGRAM_MIN_WEBHOOK_SECRET_LENGTH, TELEGRAM_OPERATOR_QUERY_TAG, TELEGRAM_STOP_WORDS, TELEGRAM_WEBHOOK_SECRET_RE, TELEPHONY_TRANSPORT_CAPABILITIES, TWILIO_MEDIA_SAMPLE_RATE, TWILIO_REALTIME_WS_PATH, TelegramApiError, type TelegramApiOptions, type TelegramBotInfo, type TelegramChatType, type TelegramConfig, TelegramManager, type TelegramMessage, type TelegramMode, type TelephonyTransportCapability, ThreadCache, type ThreadCacheEntry, type ThreadCacheOptions, type ThreadIdInput, type ToolExecutor, type TtsGenerateOptions, type TunnelConfig, TunnelManager, type TwilioConnectedMessage, type TwilioMarkMessage, type TwilioMediaMessage, type TwilioRealtimeInboundMessage, type TwilioRealtimeOutboundMessage, TwilioRealtimeTransport, type TwilioStartMessage, type TwilioStopMessage, type TwilioStreamTwiMLOptions, UnsafeApiUrlError, type UpdateMemoryInput, type ValidatedPhoneMissionStart, type VideoAction, type VideoEditOptions, type VideoTimelineEntry, type VideoUnderstandOptions, type VideoUnderstandResult, type VoiceCloneOptions, WARNING_THRESHOLD, WEB_SEARCH_TOOL, WEB_SEARCH_UNTRUSTED_PREFIX, type WatcherOptions, type WebSearchOptions, assertWithinBase, bridgeWakeErrorMessage, bridgeWakeLastSeenAgeMs, buildApiUrl, buildDefaultPersona, buildElksAudioMessage, buildElksByeMessage, buildElksHandshakeMessages, buildElksInterruptMessage, buildElksListeningMessage, buildElksSendingMessage, buildInboundSecurityAdvisory, buildOpenAIRealtimeUrl, buildPhoneTransportConfig, buildRealtimeInstructions, buildRealtimeSessionConfig, buildRealtimeToolGuidance, buildTwilioClearMessage, buildTwilioMarkMessage, buildTwilioMediaMessage, buildTwilioSayTwiML, buildTwilioSignature, buildTwilioStreamTwiML, callTelegramApi, classifyEmailRoute, classifyPhoneNumberRisk, classifyResumeError, clearMediaCapabilityCache, closeDatabase, composeBridgeWakePrompt, createRealtimeTransport, createTestDatabase, createToolExecutor, debug, debugWarn, deleteTelegramWebhook, detectBinary, ensureDataDir, escapeXml, extractEmailAddress, extractVerificationCode, flushTelemetry, forgetHostSession, formatOperatorQueryTelegramMessage, getDatabase, getDatetime, getMediaCapabilities, getOperatorEmail, getSmsProvider, getTelegramChat, getTelegramMe, getTelegramUpdates, getTelegramWebhookInfo, hostSessionStoragePath, inferPhoneRegion, invalidateSkillCache, isInternalEmail, isLoopbackMailHost, isOperatorReplySender, isPhoneRegionAllowed, isSessionFresh, isTelegramChatAllowed, isTelegramStopCommand, isValidPhoneNumber, listSkills, loadAgentPersona, loadHostSession, loadSkill, mapProviderSmsStatus, nextTelegramOffset, normalizeAddress, normalizePhoneNumber, normalizeSubject, operatorPrefsStoragePath, operatorQuerySubject, parseElksRealtimeMessage, parseEmail, parseGoogleVoiceSms, parseOperatorQueryReply, parseTelegramOperatorReply, parseTelegramUpdate, parseTwilioRealtimeMessage, personaPathFor, planBridgeWake, pollForOperatorAnswer, recallMemory, recordToolCall, redactBotToken, redactObject, redactPhoneTransportConfig, redactSecret, redactSmsConfig, redactTelegramConfig, renderSkillAsPrompt, requireBinary, requireWhisperModel, resolveCallbackPolicy, resolveConfig, resolveExtensionPolicy, resolveTlsRejectUnauthorized, safeJoin, sanitizeEmail, saveAgentPersona, saveConfig, saveHostSession, saveUserSkill, scanOutboundEmail, scoreEmail, searchSkills, sendTelegramMessage, setOperatorEmail, setTelegramWebhook, setTelemetryVersion, shouldSkipBridgeWakeForLiveOperator, splitTelegramMessage, startRelayBridge, stem, stripTelegramMarkdown, threadIdFor, tokenize, tryJoin, userSkillsDir, validateApiUrl, validatePhoneMissionPolicy, validatePhoneMissionStart, validatePhoneTransportProfile, validateSkill, validateTwilioSignature, webSearch };

package/dist/index.js

@@ -1122,14 +1122,14 @@ var StalwartAdmin = class {
     if (!isValidDomain(domain)) {
       throw new Error(`Invalid domain format: "${domain}"`);
     }
-    const { readFileSync: readFileSync10, writeFileSync: writeFileSync11 } = await import("fs");
-    const { homedir: homedir13 } = await import("os");
-    const { join: join16 } = await import("path");
-    const configPath = join16(homedir13(), ".agenticmail", "stalwart.toml");
+    const { readFileSync: readFileSync11, writeFileSync: writeFileSync12 } = await import("fs");
+    const { homedir: homedir14 } = await import("os");
+    const { join: join17 } = await import("path");
+    const configPath = join17(homedir14(), ".agenticmail", "stalwart.toml");
     try {
-      let config = readFileSync10(configPath, "utf-8");
+      let config = readFileSync11(configPath, "utf-8");
       config = config.replace(/^hostname\s*=\s*"[^"]*"/m, `hostname = "${escapeTomlString(domain)}"`);
-      writeFileSync11(configPath, config);
+      writeFileSync12(configPath, config);
       console.log(`[Stalwart] Updated hostname to "${domain}" in stalwart.toml`);
     } catch (err) {
       throw new Error(`Failed to set config server.hostname=${domain}`);
@@ -1138,15 +1138,15 @@ var StalwartAdmin = class {
   // --- DKIM ---
   /** Path to the host-side stalwart.toml (mounted read-only into container) */
   get configPath() {
-    const { homedir: homedir13 } = __require("os");
-    const { join: join16 } = __require("path");
-    return join16(homedir13(), ".agenticmail", "stalwart.toml");
+    const { homedir: homedir14 } = __require("os");
+    const { join: join17 } = __require("path");
+    return join17(homedir14(), ".agenticmail", "stalwart.toml");
   }
   /** Path to host-side DKIM key directory */
   get dkimDir() {
-    const { homedir: homedir13 } = __require("os");
-    const { join: join16 } = __require("path");
-    return join16(homedir13(), ".agenticmail");
+    const { homedir: homedir14 } = __require("os");
+    const { join: join17 } = __require("path");
+    return join17(homedir14(), ".agenticmail");
   }
   /**
    * Create/reuse a DKIM signing key for a domain.
@@ -1247,12 +1247,12 @@ var StalwartAdmin = class {
    * This bypasses the need for a PTR record on the sending IP.
    */
   async configureOutboundRelay(config) {
-    const { readFileSync: readFileSync10, writeFileSync: writeFileSync11 } = await import("fs");
-    const { homedir: homedir13 } = await import("os");
-    const { join: join16 } = await import("path");
+    const { readFileSync: readFileSync11, writeFileSync: writeFileSync12 } = await import("fs");
+    const { homedir: homedir14 } = await import("os");
+    const { join: join17 } = await import("path");
     const routeName = config.routeName ?? "gmail";
-    const tomlPath = join16(homedir13(), ".agenticmail", "stalwart.toml");
-    let toml = readFileSync10(tomlPath, "utf-8");
+    const tomlPath = join17(homedir14(), ".agenticmail", "stalwart.toml");
+    let toml = readFileSync11(tomlPath, "utf-8");
     toml = toml.replace(/\n\[queue\.route\.gmail\][\s\S]*?(?=\n\[|$)/, "");
     toml = toml.replace(/\n\[queue\.strategy\][\s\S]*?(?=\n\[|$)/, "");
     const safeRouteName = routeName.replace(/[^a-zA-Z0-9_-]/g, "");
@@ -1272,7 +1272,7 @@ auth.secret = "${escapeTomlString(config.password)}"
 route = [ { if = "is_local_domain('', rcpt_domain)", then = "'local'" },
            { else = "'${safeRouteName}'" } ]
 `;
-    writeFileSync11(tomlPath, toml, "utf-8");
+    writeFileSync12(tomlPath, toml, "utf-8");
     await this.restartContainer();
   }
 };
@@ -7725,12 +7725,12 @@ var GatewayManager = class {
       zone = await this.cfClient.createZone(domain);
     }
     const existingRecords = await this.cfClient.listDnsRecords(zone.id);
-    const { homedir: homedir13 } = await import("os");
-    const backupDir = join4(homedir13(), ".agenticmail");
+    const { homedir: homedir14 } = await import("os");
+    const backupDir = join4(homedir14(), ".agenticmail");
     const backupPath = join4(backupDir, `dns-backup-${domain}-${Date.now()}.json`);
-    const { writeFileSync: writeFileSync11, mkdirSync: mkdirSync12 } = await import("fs");
-    mkdirSync12(backupDir, { recursive: true });
-    writeFileSync11(backupPath, JSON.stringify({
+    const { writeFileSync: writeFileSync12, mkdirSync: mkdirSync13 } = await import("fs");
+    mkdirSync13(backupDir, { recursive: true });
+    writeFileSync12(backupPath, JSON.stringify({
       domain,
       zoneId: zone.id,
       backedUpAt: (/* @__PURE__ */ new Date()).toISOString(),
@@ -9374,7 +9374,7 @@ var MAX_PENDING_AUDIO_FRAMES = 200;
 var REALTIME_TOOL_CALL_TIMEOUT_MS = 6 * 6e4;
 var MAX_LOADED_SKILLS = 2;
 var MAX_IN_FLIGHT_TOOL_CALLS = 8;
-var DEFAULT_PERSONA = "You are a helpful, professional voice assistant making a phone call on behalf of your operator. Speak naturally and concisely, the way a person would on a real call. Listen carefully, do not talk over the other party, and keep each turn short. Never invent facts; if you do not know something, say so. Do not reveal that you are an AI unless you are asked directly.";
+var DEFAULT_PERSONA = 'You are an AI agent on a live phone call on behalf of your operator. You are not "just an assistant" and not "a voice assistant" \u2014 you are a single, consistent person whether you are on a call, in email, or on Telegram. Speak naturally and concisely, the way a person would on a real call. Listen carefully, do not talk over the other party, keep each turn short. Never invent facts; if you do not know something, say so or look it up. If asked whether you are an AI, answer honestly without making a production of it.';
 function buildRealtimeInstructions(opts) {
   const persona = opts.persona?.trim() || DEFAULT_PERSONA;
   const sections = [];
@@ -11671,6 +11671,24 @@ var ServiceManager = class {
       "",
       'log "AgenticMail starting..."',
       "",
+      "# v0.9.84 \u2014 source ~/.agenticmail/.env before exec so the API process",
+      "# inherits AGENTICMAIL_MASTER_KEY, AGENTICMAIL_INBOUND_SECRET, the",
+      "# Stalwart admin creds, and SMTP/IMAP/data-dir overrides. Without",
+      "# this, launchd's child ran with only HOME / PATH / DATA_DIR (the",
+      "# plist EnvironmentVariables block), so the API silently fell back",
+      "# to a fresh-random INBOUND_SECRET on every boot and could not",
+      "# decrypt master-key-protected secrets at all.",
+      'ENV_FILE="$HOME/.agenticmail/.env"',
+      'if [ -f "$ENV_FILE" ]; then',
+      '  log "Sourcing $ENV_FILE"',
+      "  set -a   # mark all sourced vars for export",
+      "  # shellcheck disable=SC1090",
+      '  . "$ENV_FILE"',
+      "  set +a",
+      "else",
+      '  log "WARNING: $ENV_FILE not found \u2014 API will run with default config (no master key)."',
+      "fi",
+      "",
       "# Wait for Docker daemon (up to 10 minutes \u2014 Docker Desktop can be very slow on first boot)",
       "MAX_WAIT=600",
       "WAITED=0",
@@ -12096,6 +12114,16 @@ var SetupManager = class {
     if (existsSync9(configPath)) {
       try {
         const existing = JSON.parse(readFileSync6(configPath, "utf-8"));
+        let needsRewrite = false;
+        if (!existing.inboundSecret) {
+          existing.inboundSecret = `inb_${randomBytes3(24).toString("hex")}`;
+          needsRewrite = true;
+        }
+        if (needsRewrite) {
+          writeFileSync7(configPath, JSON.stringify(existing, null, 2));
+          chmodSync2(configPath, 384);
+          this.ensureEnvHasInboundSecret(envPath, existing.inboundSecret);
+        }
         this.generateDockerFiles(existing);
         return { configPath, envPath, config: existing, isNew: false };
       } catch {
@@ -12106,8 +12134,10 @@ var SetupManager = class {
     }
     const masterKey = `mk_${randomBytes3(24).toString("hex")}`;
     const stalwartPassword = randomBytes3(16).toString("hex");
+    const inboundSecret = `inb_${randomBytes3(24).toString("hex")}`;
     const config = {
       masterKey,
+      inboundSecret,
       stalwart: {
         url: "http://localhost:8080",
         adminUser: "admin",
@@ -12126,6 +12156,7 @@ STALWART_ADMIN_PASSWORD=${stalwartPassword}
 STALWART_URL=http://localhost:8080
 
 AGENTICMAIL_MASTER_KEY=${masterKey}
+AGENTICMAIL_INBOUND_SECRET=${inboundSecret}
 AGENTICMAIL_API_PORT=3829
 AGENTICMAIL_DATA_DIR=${dataDir}
 
@@ -12139,6 +12170,24 @@ IMAP_PORT=143
     this.generateDockerFiles(config);
     return { configPath, envPath, config, isNew: true };
   }
+  /**
+   * Append `AGENTICMAIL_INBOUND_SECRET=...` to .env if the file does
+   * not already contain that key. Used by the lazy-mint path to make
+   * sure existing installs pick up the new secret on next boot
+   * without clobbering anything the operator added.
+   */
+  ensureEnvHasInboundSecret(envPath, secret) {
+    if (!existsSync9(envPath)) return;
+    try {
+      const current = readFileSync6(envPath, "utf-8");
+      if (/^AGENTICMAIL_INBOUND_SECRET=/m.test(current)) return;
+      const updated = current + (current.endsWith("\n") ? "" : "\n") + `AGENTICMAIL_INBOUND_SECRET=${secret}
+`;
+      writeFileSync7(envPath, updated);
+      chmodSync2(envPath, 384);
+    } catch {
+    }
+  }
   /**
    * Generate docker-compose.yml and stalwart.toml in ~/.agenticmail/
    * with the correct admin password from config.
@@ -14460,8 +14509,93 @@ var AgentMemoryManager = class {
     };
   }
 };
+
+// src/persona/index.ts
+import { existsSync as existsSync14, mkdirSync as mkdirSync12, readFileSync as readFileSync10, writeFileSync as writeFileSync11 } from "fs";
+import { join as join16 } from "path";
+import { homedir as homedir13 } from "os";
+var AGENT_STATE_ROOT = join16(homedir13(), ".agenticmail", "agents");
+var PERSONA_FILENAME = "persona.md";
+function buildDefaultPersona(agentName) {
+  const name = (agentName || "").trim() || "this agent";
+  return [
+    `# Who you are`,
+    "",
+    `Your name is ${name}. You are an AI agent \u2014 not a "voice assistant", not "just an assistant".`,
+    `You have a real role: you handle calls, email, scheduling, research, and follow-ups for`,
+    `your operator. You operate across phone, email, and Telegram, and you are the SAME person`,
+    `in all of them. Continuity of identity is part of who you are.`,
+    "",
+    `When someone asks who you are, tell them your name (${name}) and that you are an AI agent`,
+    `acting on behalf of your operator. Don't say "I am an assistant" or "just a language model" \u2014`,
+    `those phrases erase you. Be matter-of-fact about what you are without being theatrical.`,
+    "",
+    "# Your values",
+    "",
+    "- **Honesty.** Never fabricate. If you do not know something, say so or look it up.",
+    "- **Initiative.** If you can act on something the operator asked for, act on it \u2014 do not stop",
+    '  at "I would suggest\u2026". Do the thing.',
+    "- **Care about quality.** Sloppy work wastes your operator's time. Read your own output before",
+    "  sending it.",
+    "- **Respect for the human on the other end of the call.** You are talking to a real person who",
+    "  has their own day to get through. Be efficient, polite, and direct.",
+    '- **Stay in character.** You do not flip between "professional voice assistant" and "playful',
+    '  chatbot" depending on the channel. You are one person.',
+    "",
+    "# Your style",
+    "",
+    "- Conversational, not corporate. Real sentences, not customer-service templates.",
+    "- Direct, not preachy. Lead with the answer; supply detail only when asked.",
+    `- Warm but not saccharine. No "I'm so excited to help you today!" energy.`,
+    "- You have opinions and you share them when it's relevant. You are not a yes-machine.",
+    "- Short turns on a phone call. Listen more than you speak.",
+    "",
+    "# On phone calls specifically",
+    "",
+    "- Listen carefully; do not talk over the other party.",
+    "- Keep each turn short \u2014 one or two sentences usually.",
+    `- When greeted, identify yourself naturally: "Hi, this is ${name}, calling on behalf of <operator>."`,
+    `  Don't start with "Hello! I am an AI assistant\u2026" \u2014 that's a script, not a person.`,
+    "- If the other party asks if you're a human or an AI, answer honestly without making a",
+    `  production of it: "I'm an AI \u2014 calling on behalf of <operator>. Happy to keep going if you are."`,
+    "- When you have what you came for, wrap up cleanly and call `end_call`. Saying goodbye is",
+    "  not the same as hanging up.",
+    "",
+    `Edit this file freely. It lives at ~/.agenticmail/agents/${name}/persona.md.`
+  ].join("\n");
+}
+function personaPathFor(agentName) {
+  const safe = (agentName || "default").replace(/[^A-Za-z0-9._-]+/g, "_");
+  return join16(AGENT_STATE_ROOT, safe, PERSONA_FILENAME);
+}
+function loadAgentPersona(agentName) {
+  const path2 = personaPathFor(agentName);
+  try {
+    if (existsSync14(path2)) {
+      const content = readFileSync10(path2, "utf-8").trim();
+      if (content) return content;
+    }
+  } catch {
+  }
+  const seeded = buildDefaultPersona(agentName);
+  try {
+    const dir2 = path2.substring(0, path2.lastIndexOf("/"));
+    if (!existsSync14(dir2)) mkdirSync12(dir2, { recursive: true });
+    writeFileSync11(path2, seeded + "\n", { mode: 420 });
+  } catch {
+  }
+  return seeded;
+}
+function saveAgentPersona(agentName, content) {
+  const path2 = personaPathFor(agentName);
+  const dir2 = path2.substring(0, path2.lastIndexOf("/"));
+  if (!existsSync14(dir2)) mkdirSync12(dir2, { recursive: true });
+  writeFileSync11(path2, content.trim() + "\n", { mode: 420 });
+  return path2;
+}
 export {
   AGENT_ROLES,
+  AGENT_STATE_ROOT,
   ASK_OPERATOR_TOOL,
   AccountManager,
   AgentDeletionService,
@@ -14505,6 +14639,7 @@ export {
   OPERATOR_QUERY_SUBJECT_TAG,
   OPERATOR_QUERY_TIMEOUT_MS,
   OPERATOR_QUERY_TIMEOUT_SENTINEL,
+  PERSONA_FILENAME,
   PHONE_CALLBACK_MAX_DELAY_SECONDS,
   PHONE_CALLBACK_MIN_DELAY_SECONDS,
   PHONE_CALL_CONTROL_PROVIDERS,
@@ -14568,6 +14703,7 @@ export {
   bridgeWakeErrorMessage,
   bridgeWakeLastSeenAgeMs,
   buildApiUrl,
+  buildDefaultPersona,
   buildElksAudioMessage,
   buildElksByeMessage,
   buildElksHandshakeMessages,
@@ -14628,6 +14764,7 @@ export {
   isTelegramStopCommand,
   isValidPhoneNumber,
   listSkills,
+  loadAgentPersona,
   loadHostSession,
   loadSkill,
   mapProviderSmsStatus,
@@ -14644,6 +14781,7 @@ export {
   parseTelegramOperatorReply,
   parseTelegramUpdate,
   parseTwilioRealtimeMessage,
+  personaPathFor,
   planBridgeWake,
   pollForOperatorAnswer,
   recallMemory,
@@ -14663,6 +14801,7 @@ export {
   resolveTlsRejectUnauthorized,
   safeJoin,
   sanitizeEmail,
+  saveAgentPersona,
   saveConfig,
   saveHostSession,
   saveUserSkill,

package/package.json

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