@agenticmail/core 0.9.37 → 0.9.39

package/dist/{chunk-J6JINNJ3.js → chunk-FYULLCZX.js}

@@ -575,8 +575,8 @@ function validateSkill(s) {
   if (typeof sk.contributed_by !== "string") errs.push({ path: "contributed_by", message: "must be a string" });
   return errs;
 }
-function summarize(s) {
-  return {
+function summarize(s, score) {
+  const out = {
     id: s.id,
     name: s.name,
     category: s.category,
@@ -584,8 +584,12 @@ function summarize(s) {
     description: s.description,
     version: s.version,
     disclaimer_required: !!s.disclaimer,
-    estimated_call_duration_minutes: s.context.estimated_call_duration_minutes
+    estimated_call_duration_minutes: s.context.estimated_call_duration_minutes,
+    when_to_use: s.context.when_to_use,
+    first_principle: s.principles && s.principles.length > 0 ? s.principles[0] : ""
   };
+  if (score !== void 0) out.score = score;
+  return out;
 }
 function listSkills(opts = {}) {
   const all = Array.from(ensureLoaded().byId.values());
@@ -606,17 +610,17 @@ function searchSkills(query, limit = 20) {
     const fallback = [];
     for (const s of byId.values()) {
       if (s.id.toLowerCase().includes(qLow) || s.name.toLowerCase().includes(qLow) || s.tags.some((t) => t.toLowerCase().includes(qLow))) {
-        fallback.push(summarize(s));
+        fallback.push(summarize(s, 0.1));
         if (fallback.length >= limit) break;
       }
     }
     return fallback;
   }
   const out = [];
-  for (const { id } of ranked) {
+  for (const { id, score } of ranked) {
     const skill = byId.get(id);
     if (!skill) continue;
-    out.push(summarize(skill));
+    out.push(summarize(skill, score));
     if (out.length >= limit) break;
   }
   return out;

package/dist/index.cjs

@@ -1280,8 +1280,8 @@ function validateSkill(s) {
   if (typeof sk.contributed_by !== "string") errs.push({ path: "contributed_by", message: "must be a string" });
   return errs;
 }
-function summarize(s) {
-  return {
+function summarize(s, score) {
+  const out = {
     id: s.id,
     name: s.name,
     category: s.category,
@@ -1289,8 +1289,12 @@ function summarize(s) {
     description: s.description,
     version: s.version,
     disclaimer_required: !!s.disclaimer,
-    estimated_call_duration_minutes: s.context.estimated_call_duration_minutes
+    estimated_call_duration_minutes: s.context.estimated_call_duration_minutes,
+    when_to_use: s.context.when_to_use,
+    first_principle: s.principles && s.principles.length > 0 ? s.principles[0] : ""
   };
+  if (score !== void 0) out.score = score;
+  return out;
 }
 function listSkills(opts = {}) {
   const all = Array.from(ensureLoaded().byId.values());
@@ -1311,17 +1315,17 @@ function searchSkills(query, limit = 20) {
     const fallback = [];
     for (const s of byId.values()) {
       if (s.id.toLowerCase().includes(qLow) || s.name.toLowerCase().includes(qLow) || s.tags.some((t) => t.toLowerCase().includes(qLow))) {
-        fallback.push(summarize(s));
+        fallback.push(summarize(s, 0.1));
         if (fallback.length >= limit) break;
       }
     }
     return fallback;
   }
   const out = [];
-  for (const { id } of ranked) {
+  for (const { id, score } of ranked) {
     const skill = byId.get(id);
     if (!skill) continue;
-    out.push(summarize(skill));
+    out.push(summarize(skill, score));
     if (out.length >= limit) break;
   }
   return out;
@@ -1606,6 +1610,7 @@ __export(index_exports, {
   getTelegramMe: () => getTelegramMe,
   getTelegramUpdates: () => getTelegramUpdates,
   getTelegramWebhookInfo: () => getTelegramWebhookInfo,
+  getVoiceProvider: () => getVoiceProvider,
   hostSessionStoragePath: () => hostSessionStoragePath,
   inferPhoneRegion: () => inferPhoneRegion,
   invalidateSkillCache: () => invalidateSkillCache,
@@ -1618,6 +1623,7 @@ __export(index_exports, {
   isTelegramStopCommand: () => isTelegramStopCommand,
   isValidPhoneNumber: () => isValidPhoneNumber,
   listSkills: () => listSkills,
+  listVoiceProviders: () => listVoiceProviders,
   loadAgentPersona: () => loadAgentPersona,
   loadHostSession: () => loadHostSession,
   loadSkill: () => loadSkill,
@@ -1646,6 +1652,7 @@ __export(index_exports, {
   redactSecret: () => redactSecret,
   redactSmsConfig: () => redactSmsConfig,
   redactTelegramConfig: () => redactTelegramConfig,
+  registerVoiceProvider: () => registerVoiceProvider,
   renderSkillAsPrompt: () => renderSkillAsPrompt,
   requireBinary: () => requireBinary,
   requireWhisperModel: () => requireWhisperModel,
@@ -1653,6 +1660,7 @@ __export(index_exports, {
   resolveConfig: () => resolveConfig,
   resolveExtensionPolicy: () => resolveExtensionPolicy,
   resolveTlsRejectUnauthorized: () => resolveTlsRejectUnauthorized,
+  resolveVoiceRuntime: () => resolveVoiceRuntime,
   safeJoin: () => safeJoin,
   sanitizeEmail: () => sanitizeEmail,
   saveAgentPersona: () => saveAgentPersona,
@@ -2584,6 +2592,13 @@ function resolveConfig(overrides) {
     dataDir: env.AGENTICMAIL_DATA_DIR?.replace(/^~(?=\/|$)/, (0, import_node_os.homedir)()) ?? DEFAULT_CONFIG.dataDir
   };
   if (env.OPENAI_API_KEY) config.openaiApiKey = env.OPENAI_API_KEY;
+  if (env.XAI_API_KEY) {
+    config.voiceProviderKeys = config.voiceProviderKeys ?? {};
+    config.voiceProviderKeys.grok = env.XAI_API_KEY;
+  }
+  if (env.AGENTICMAIL_VOICE_RUNTIME && env.AGENTICMAIL_VOICE_RUNTIME.trim()) {
+    config.voiceRuntime = env.AGENTICMAIL_VOICE_RUNTIME.trim();
+  }
   const configPath = (0, import_node_path.join)(config.dataDir, "config.json");
   if ((0, import_node_fs.existsSync)(configPath)) {
     try {
@@ -8678,6 +8693,73 @@ var PhoneManager = class {
     }]);
     return { mission: updated, query: answered, alreadyAnswered: false };
   }
+  /**
+   * v0.9.92 — auto-close stale operator queries.
+   *
+   * An operator query is "stale" when:
+   *   - it's unanswered, AND
+   *   - either (a) the mission is no longer live (status in
+   *     {completed, failed, cancelled}), OR (b) the query is older
+   *     than `maxAgeSeconds`.
+   *
+   * The sweeper marks each stale query as answered with a synthetic
+   * "[auto-closed: ...]" answer + `answeredVia: 'auto-sweeper'`. This
+   * (a) gets the query out of `listOpenOperatorQueries`, (b) clears
+   * the bridge's "you have N open questions" hint to the operator,
+   * and (c) leaves a permanent audit trail of WHY the query was
+   * closed.
+   *
+   * Returns the count of queries closed + a per-mission breakdown
+   * for logging.
+   */
+  sweepStaleOperatorQueries(opts = {}) {
+    const maxAgeMs = (opts.maxAgeSeconds ?? 3600) * 1e3;
+    const nowMs = opts.nowMs ?? Date.now();
+    const TERMINAL = /* @__PURE__ */ new Set(["completed", "failed", "cancelled"]);
+    const rows = this.db.prepare(
+      `SELECT * FROM phone_missions WHERE metadata_json LIKE '%"operatorQueries"%'`
+    ).all();
+    const breakdown = [];
+    let totalClosed = 0;
+    let missionsTouched = 0;
+    for (const row of rows) {
+      const mission = rowToMission(row);
+      const queries = readOperatorQueries(mission);
+      const open = queries.filter((q) => !q.answer);
+      if (open.length === 0) continue;
+      const reason = TERMINAL.has(mission.status) ? "mission-terminal" : null;
+      const closedAt = new Date(nowMs).toISOString();
+      const nextQueries = queries.map((q) => {
+        if (q.answer) return q;
+        const askedAtMs = Date.parse(q.askedAt);
+        const tooOld = Number.isFinite(askedAtMs) && nowMs - askedAtMs >= maxAgeMs;
+        const queryReason = reason ?? (tooOld ? "age" : null);
+        if (!queryReason) return q;
+        return {
+          ...q,
+          answer: queryReason === "mission-terminal" ? `[auto-closed: mission ended (${mission.status}) before this question was answered]` : `[auto-closed: question went unanswered for over ${Math.round(maxAgeMs / 6e4)} minutes]`,
+          answeredAt: closedAt,
+          answeredVia: "auto-sweeper"
+        };
+      });
+      const closedHere = nextQueries.filter(
+        (q, i) => q.answer && !queries[i].answer && q.answeredVia === "auto-sweeper"
+      ).length;
+      if (closedHere === 0) continue;
+      this.updateMissionStatus(mission.id, mission.status, {
+        operatorQueries: nextQueries
+      }, [{
+        at: closedAt,
+        source: "system",
+        text: `Auto-closed ${closedHere} stale operator query(ies): ${reason ?? "aged out"}.`,
+        metadata: { closedCount: closedHere, reason: reason ?? "age" }
+      }]);
+      totalClosed += closedHere;
+      missionsTouched += 1;
+      breakdown.push({ missionId: mission.id, closed: closedHere, reason: reason ?? "age" });
+    }
+    return { closed: totalClosed, missionsTouched, breakdown };
+  }
   // ─── Callback on disconnect (plan §7) ─────────────────
   /**
    * Flag a mission for callback-on-disconnect: the call dropped while
@@ -10690,7 +10772,7 @@ var SEARCH_EMAIL_TOOL = {
 var SEARCH_SKILLS_TOOL = {
   type: "function",
   name: "search_skills",
-  description: "Search your skill library for a playbook that fits the situation you just hit on this call (billing dispute, debt collector tactics, reservation deadlock, etc). Returns ranked summaries \u2014 pick the best match and pass its id to load_skill. Fast.",
+  description: 'Search your skill library for a playbook that fits the situation you just hit on this call (billing dispute, debt collector tactics, reservation deadlock, etc). Returns up to 5 ranked matches, each with: id, name, BM25 score, when_to_use (the specific situation the skill is for), first_principle (the playbook\'s strategic frame), and a `recommendation` field. If `recommendation` says LOAD IT NOW or the top score > 0.3, immediately call load_skill with the top id \u2014 do not deliberate. If scores are weak (< 0.15), re-search with a different phrasing instead of loading a poor match. The model that judges "is this the right skill" is YOU \u2014 but the recommendation field will tell you what the right move usually is.',
   parameters: {
     type: "object",
     properties: {
@@ -12132,6 +12214,94 @@ function withTimeout(promise, ms) {
   return Promise.race([promise, timeout]).finally(() => clearTimeout(timer));
 }
 
+// src/phone/voice-providers/registry.ts
+var PROVIDERS2 = /* @__PURE__ */ new Map();
+function registerVoiceProvider(provider) {
+  if (PROVIDERS2.has(provider.id)) {
+    throw new Error(`Voice provider "${provider.id}" registered twice \u2014 id collision.`);
+  }
+  PROVIDERS2.set(provider.id, provider);
+}
+function listVoiceProviders() {
+  return Array.from(PROVIDERS2.values());
+}
+function getVoiceProvider(id) {
+  return PROVIDERS2.get(id);
+}
+function resolveVoiceRuntime(providerId, config, options = {}) {
+  const id = (providerId || "openai").trim() || "openai";
+  const provider = PROVIDERS2.get(id);
+  if (!provider) {
+    const known = Array.from(PROVIDERS2.keys()).join(", ") || "(none registered)";
+    throw new Error(
+      `Unknown voice runtime "${id}". Known providers: ${known}. Add a new one by dropping a file into packages/core/src/phone/voice-providers/.`
+    );
+  }
+  let apiKey = "";
+  let apiKeySource = "";
+  if (provider.apiKeyConfigField) {
+    const legacy = config[provider.apiKeyConfigField];
+    if (legacy && legacy.trim()) {
+      apiKey = legacy.trim();
+      apiKeySource = `config.${provider.apiKeyConfigField}`;
+    }
+  }
+  if (!apiKey) {
+    const fromMap = config.voiceProviderKeys?.[provider.id];
+    if (fromMap && fromMap.trim()) {
+      apiKey = fromMap.trim();
+      apiKeySource = `config.voiceProviderKeys.${provider.id}`;
+    }
+  }
+  if (!apiKey) {
+    const fromEnv = process.env[provider.apiKeyEnvVar];
+    if (fromEnv && fromEnv.trim()) {
+      apiKey = fromEnv.trim();
+      apiKeySource = `env ${provider.apiKeyEnvVar}`;
+    }
+  }
+  if (!apiKey) {
+    throw new Error(
+      `Voice provider "${provider.id}" (${provider.displayName}) selected, but no API key is configured. Set ${provider.apiKeyEnvVar} in your environment or save it to ~/.agenticmail/config.json under voiceProviderKeys.${provider.id}.`
+    );
+  }
+  const model = options.model && options.model.trim() || provider.defaultModel;
+  const url = `${provider.websocketBaseUrl}?model=${encodeURIComponent(model)}`;
+  return {
+    providerId: provider.id,
+    providerDisplayName: provider.displayName,
+    url,
+    model,
+    apiKey,
+    apiKeySource
+  };
+}
+
+// src/phone/voice-providers/openai.ts
+registerVoiceProvider({
+  id: "openai",
+  displayName: "OpenAI Realtime (gpt-realtime)",
+  websocketBaseUrl: "wss://api.openai.com/v1/realtime",
+  defaultModel: "gpt-realtime",
+  apiKeyEnvVar: "OPENAI_API_KEY",
+  // Legacy: the original config.json schema used a dedicated
+  // `openaiApiKey` field for this key. The resolver checks that field
+  // before the generic voiceProviderKeys map so existing installs
+  // continue to work without migration.
+  apiKeyConfigField: "openaiApiKey",
+  description: "OpenAI Realtime (gpt-realtime). Default voice runtime; supports linear PCM @ 24 kHz (46elks) and G.711 \xB5-law @ 8 kHz (Twilio) without transcoding."
+});
+
+// src/phone/voice-providers/grok.ts
+registerVoiceProvider({
+  id: "grok",
+  displayName: "xAI Grok Voice Agent",
+  websocketBaseUrl: "wss://api.x.ai/v1/realtime",
+  defaultModel: "grok-voice-latest",
+  apiKeyEnvVar: "XAI_API_KEY",
+  description: 'xAI Grok Voice Agent \u2014 OpenAI-Realtime-compatible WebSocket protocol; select via mission policy.voiceRuntime="grok" or env AGENTICMAIL_VOICE_RUNTIME=grok.'
+});
+
 // src/telemetry.ts
 var import_crypto = require("crypto");
 var import_fs = require("fs");
@@ -16446,6 +16616,7 @@ function saveAgentPersona(agentName, content) {
   getTelegramMe,
   getTelegramUpdates,
   getTelegramWebhookInfo,
+  getVoiceProvider,
   hostSessionStoragePath,
   inferPhoneRegion,
   invalidateSkillCache,
@@ -16458,6 +16629,7 @@ function saveAgentPersona(agentName, content) {
   isTelegramStopCommand,
   isValidPhoneNumber,
   listSkills,
+  listVoiceProviders,
   loadAgentPersona,
   loadHostSession,
   loadSkill,
@@ -16486,6 +16658,7 @@ function saveAgentPersona(agentName, content) {
   redactSecret,
   redactSmsConfig,
   redactTelegramConfig,
+  registerVoiceProvider,
   renderSkillAsPrompt,
   requireBinary,
   requireWhisperModel,
@@ -16493,6 +16666,7 @@ function saveAgentPersona(agentName, content) {
   resolveConfig,
   resolveExtensionPolicy,
   resolveTlsRejectUnauthorized,
+  resolveVoiceRuntime,
   safeJoin,
   sanitizeEmail,
   saveAgentPersona,

package/dist/index.d.cts

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

package/dist/index.d.ts

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

package/dist/index.js

@@ -16,7 +16,7 @@ import {
   tokenize,
   userSkillsDir,
   validateSkill
-} from "./chunk-J6JINNJ3.js";
+} from "./chunk-FYULLCZX.js";
 import {
   __require
 } from "./chunk-3RG5ZIWI.js";
@@ -920,6 +920,13 @@ function resolveConfig(overrides) {
     dataDir: env.AGENTICMAIL_DATA_DIR?.replace(/^~(?=\/|$)/, homedir()) ?? DEFAULT_CONFIG.dataDir
   };
   if (env.OPENAI_API_KEY) config.openaiApiKey = env.OPENAI_API_KEY;
+  if (env.XAI_API_KEY) {
+    config.voiceProviderKeys = config.voiceProviderKeys ?? {};
+    config.voiceProviderKeys.grok = env.XAI_API_KEY;
+  }
+  if (env.AGENTICMAIL_VOICE_RUNTIME && env.AGENTICMAIL_VOICE_RUNTIME.trim()) {
+    config.voiceRuntime = env.AGENTICMAIL_VOICE_RUNTIME.trim();
+  }
   const configPath = join(config.dataDir, "config.json");
   if (existsSync(configPath)) {
     try {
@@ -7009,6 +7016,73 @@ var PhoneManager = class {
     }]);
     return { mission: updated, query: answered, alreadyAnswered: false };
   }
+  /**
+   * v0.9.92 — auto-close stale operator queries.
+   *
+   * An operator query is "stale" when:
+   *   - it's unanswered, AND
+   *   - either (a) the mission is no longer live (status in
+   *     {completed, failed, cancelled}), OR (b) the query is older
+   *     than `maxAgeSeconds`.
+   *
+   * The sweeper marks each stale query as answered with a synthetic
+   * "[auto-closed: ...]" answer + `answeredVia: 'auto-sweeper'`. This
+   * (a) gets the query out of `listOpenOperatorQueries`, (b) clears
+   * the bridge's "you have N open questions" hint to the operator,
+   * and (c) leaves a permanent audit trail of WHY the query was
+   * closed.
+   *
+   * Returns the count of queries closed + a per-mission breakdown
+   * for logging.
+   */
+  sweepStaleOperatorQueries(opts = {}) {
+    const maxAgeMs = (opts.maxAgeSeconds ?? 3600) * 1e3;
+    const nowMs = opts.nowMs ?? Date.now();
+    const TERMINAL = /* @__PURE__ */ new Set(["completed", "failed", "cancelled"]);
+    const rows = this.db.prepare(
+      `SELECT * FROM phone_missions WHERE metadata_json LIKE '%"operatorQueries"%'`
+    ).all();
+    const breakdown = [];
+    let totalClosed = 0;
+    let missionsTouched = 0;
+    for (const row of rows) {
+      const mission = rowToMission(row);
+      const queries = readOperatorQueries(mission);
+      const open = queries.filter((q) => !q.answer);
+      if (open.length === 0) continue;
+      const reason = TERMINAL.has(mission.status) ? "mission-terminal" : null;
+      const closedAt = new Date(nowMs).toISOString();
+      const nextQueries = queries.map((q) => {
+        if (q.answer) return q;
+        const askedAtMs = Date.parse(q.askedAt);
+        const tooOld = Number.isFinite(askedAtMs) && nowMs - askedAtMs >= maxAgeMs;
+        const queryReason = reason ?? (tooOld ? "age" : null);
+        if (!queryReason) return q;
+        return {
+          ...q,
+          answer: queryReason === "mission-terminal" ? `[auto-closed: mission ended (${mission.status}) before this question was answered]` : `[auto-closed: question went unanswered for over ${Math.round(maxAgeMs / 6e4)} minutes]`,
+          answeredAt: closedAt,
+          answeredVia: "auto-sweeper"
+        };
+      });
+      const closedHere = nextQueries.filter(
+        (q, i) => q.answer && !queries[i].answer && q.answeredVia === "auto-sweeper"
+      ).length;
+      if (closedHere === 0) continue;
+      this.updateMissionStatus(mission.id, mission.status, {
+        operatorQueries: nextQueries
+      }, [{
+        at: closedAt,
+        source: "system",
+        text: `Auto-closed ${closedHere} stale operator query(ies): ${reason ?? "aged out"}.`,
+        metadata: { closedCount: closedHere, reason: reason ?? "age" }
+      }]);
+      totalClosed += closedHere;
+      missionsTouched += 1;
+      breakdown.push({ missionId: mission.id, closed: closedHere, reason: reason ?? "age" });
+    }
+    return { closed: totalClosed, missionsTouched, breakdown };
+  }
   // ─── Callback on disconnect (plan §7) ─────────────────
   /**
    * Flag a mission for callback-on-disconnect: the call dropped while
@@ -9021,7 +9095,7 @@ var SEARCH_EMAIL_TOOL = {
 var SEARCH_SKILLS_TOOL = {
   type: "function",
   name: "search_skills",
-  description: "Search your skill library for a playbook that fits the situation you just hit on this call (billing dispute, debt collector tactics, reservation deadlock, etc). Returns ranked summaries \u2014 pick the best match and pass its id to load_skill. Fast.",
+  description: 'Search your skill library for a playbook that fits the situation you just hit on this call (billing dispute, debt collector tactics, reservation deadlock, etc). Returns up to 5 ranked matches, each with: id, name, BM25 score, when_to_use (the specific situation the skill is for), first_principle (the playbook\'s strategic frame), and a `recommendation` field. If `recommendation` says LOAD IT NOW or the top score > 0.3, immediately call load_skill with the top id \u2014 do not deliberate. If scores are weak (< 0.15), re-search with a different phrasing instead of loading a poor match. The model that judges "is this the right skill" is YOU \u2014 but the recommendation field will tell you what the right move usually is.',
   parameters: {
     type: "object",
     properties: {
@@ -9676,7 +9750,7 @@ var RealtimeVoiceBridge = class {
     let loadSkill2;
     let renderSkillAsPrompt2;
     try {
-      ({ loadSkill: loadSkill2, renderSkillAsPrompt: renderSkillAsPrompt2 } = await import("./skills-RE3S767B.js"));
+      ({ loadSkill: loadSkill2, renderSkillAsPrompt: renderSkillAsPrompt2 } = await import("./skills-DZVDIMTD.js"));
     } catch (err) {
       return { ok: false, message: `Skill registry unavailable: ${errorText(err)}` };
     }
@@ -10463,6 +10537,94 @@ function withTimeout(promise, ms) {
   return Promise.race([promise, timeout]).finally(() => clearTimeout(timer));
 }
 
+// src/phone/voice-providers/registry.ts
+var PROVIDERS2 = /* @__PURE__ */ new Map();
+function registerVoiceProvider(provider) {
+  if (PROVIDERS2.has(provider.id)) {
+    throw new Error(`Voice provider "${provider.id}" registered twice \u2014 id collision.`);
+  }
+  PROVIDERS2.set(provider.id, provider);
+}
+function listVoiceProviders() {
+  return Array.from(PROVIDERS2.values());
+}
+function getVoiceProvider(id) {
+  return PROVIDERS2.get(id);
+}
+function resolveVoiceRuntime(providerId, config, options = {}) {
+  const id = (providerId || "openai").trim() || "openai";
+  const provider = PROVIDERS2.get(id);
+  if (!provider) {
+    const known = Array.from(PROVIDERS2.keys()).join(", ") || "(none registered)";
+    throw new Error(
+      `Unknown voice runtime "${id}". Known providers: ${known}. Add a new one by dropping a file into packages/core/src/phone/voice-providers/.`
+    );
+  }
+  let apiKey = "";
+  let apiKeySource = "";
+  if (provider.apiKeyConfigField) {
+    const legacy = config[provider.apiKeyConfigField];
+    if (legacy && legacy.trim()) {
+      apiKey = legacy.trim();
+      apiKeySource = `config.${provider.apiKeyConfigField}`;
+    }
+  }
+  if (!apiKey) {
+    const fromMap = config.voiceProviderKeys?.[provider.id];
+    if (fromMap && fromMap.trim()) {
+      apiKey = fromMap.trim();
+      apiKeySource = `config.voiceProviderKeys.${provider.id}`;
+    }
+  }
+  if (!apiKey) {
+    const fromEnv = process.env[provider.apiKeyEnvVar];
+    if (fromEnv && fromEnv.trim()) {
+      apiKey = fromEnv.trim();
+      apiKeySource = `env ${provider.apiKeyEnvVar}`;
+    }
+  }
+  if (!apiKey) {
+    throw new Error(
+      `Voice provider "${provider.id}" (${provider.displayName}) selected, but no API key is configured. Set ${provider.apiKeyEnvVar} in your environment or save it to ~/.agenticmail/config.json under voiceProviderKeys.${provider.id}.`
+    );
+  }
+  const model = options.model && options.model.trim() || provider.defaultModel;
+  const url = `${provider.websocketBaseUrl}?model=${encodeURIComponent(model)}`;
+  return {
+    providerId: provider.id,
+    providerDisplayName: provider.displayName,
+    url,
+    model,
+    apiKey,
+    apiKeySource
+  };
+}
+
+// src/phone/voice-providers/openai.ts
+registerVoiceProvider({
+  id: "openai",
+  displayName: "OpenAI Realtime (gpt-realtime)",
+  websocketBaseUrl: "wss://api.openai.com/v1/realtime",
+  defaultModel: "gpt-realtime",
+  apiKeyEnvVar: "OPENAI_API_KEY",
+  // Legacy: the original config.json schema used a dedicated
+  // `openaiApiKey` field for this key. The resolver checks that field
+  // before the generic voiceProviderKeys map so existing installs
+  // continue to work without migration.
+  apiKeyConfigField: "openaiApiKey",
+  description: "OpenAI Realtime (gpt-realtime). Default voice runtime; supports linear PCM @ 24 kHz (46elks) and G.711 \xB5-law @ 8 kHz (Twilio) without transcoding."
+});
+
+// src/phone/voice-providers/grok.ts
+registerVoiceProvider({
+  id: "grok",
+  displayName: "xAI Grok Voice Agent",
+  websocketBaseUrl: "wss://api.x.ai/v1/realtime",
+  defaultModel: "grok-voice-latest",
+  apiKeyEnvVar: "XAI_API_KEY",
+  description: 'xAI Grok Voice Agent \u2014 OpenAI-Realtime-compatible WebSocket protocol; select via mission policy.voiceRuntime="grok" or env AGENTICMAIL_VOICE_RUNTIME=grok.'
+});
+
 // src/telemetry.ts
 import { randomUUID as randomUUID2 } from "crypto";
 import { readFileSync as readFileSync2, writeFileSync as writeFileSync3, mkdirSync as mkdirSync3, existsSync as existsSync3 } from "fs";
@@ -14792,6 +14954,7 @@ export {
   getTelegramMe,
   getTelegramUpdates,
   getTelegramWebhookInfo,
+  getVoiceProvider,
   hostSessionStoragePath,
   inferPhoneRegion,
   invalidateSkillCache,
@@ -14804,6 +14967,7 @@ export {
   isTelegramStopCommand,
   isValidPhoneNumber,
   listSkills,
+  listVoiceProviders,
   loadAgentPersona,
   loadHostSession,
   loadSkill,
@@ -14832,6 +14996,7 @@ export {
   redactSecret,
   redactSmsConfig,
   redactTelegramConfig,
+  registerVoiceProvider,
   renderSkillAsPrompt,
   requireBinary,
   requireWhisperModel,
@@ -14839,6 +15004,7 @@ export {
   resolveConfig,
   resolveExtensionPolicy,
   resolveTlsRejectUnauthorized,
+  resolveVoiceRuntime,
   safeJoin,
   sanitizeEmail,
   saveAgentPersona,

package/dist/{skills-RE3S767B.js → skills-DZVDIMTD.js}

@@ -8,7 +8,7 @@ import {
   skillFilename,
   userSkillsDir,
   validateSkill
-} from "./chunk-J6JINNJ3.js";
+} from "./chunk-FYULLCZX.js";
 import "./chunk-3RG5ZIWI.js";
 export {
   invalidateSkillCache,

package/package.json

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