@agenticmail/core 0.9.23 → 0.9.25

package/dist/index.js

@@ -4,6 +4,19 @@ import {
   isInternalEmail,
   scoreEmail
 } from "./chunk-TIAKW5DC.js";
+import {
+  MemorySearchIndex,
+  invalidateSkillCache,
+  listSkills,
+  loadSkill,
+  renderSkillAsPrompt,
+  saveUserSkill,
+  searchSkills,
+  stem,
+  tokenize,
+  userSkillsDir,
+  validateSkill
+} from "./chunk-J6JINNJ3.js";
 import {
   __require
 } from "./chunk-3RG5ZIWI.js";
@@ -8749,12 +8762,46 @@ var SEARCH_EMAIL_TOOL = {
     additionalProperties: false
   }
 };
+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.",
+  parameters: {
+    type: "object",
+    properties: {
+      query: {
+        type: "string",
+        description: 'Plain-language description of the situation, e.g. "rep insists on a commitment date", "the restaurant is fully booked", "I need to dispute a recurring charge after cancellation".'
+      }
+    },
+    required: ["query"],
+    additionalProperties: false
+  }
+};
+var LOAD_SKILL_TOOL = {
+  type: "function",
+  name: "load_skill",
+  description: 'Load a skill playbook by id into your context for the rest of this call. The playbook (principles, scripted phrases, ordered tactics, hard boundaries, exit strategy) grounds your next turns. Always call search_skills first to find the right id. Before calling, say "hold on one moment" \u2014 loading is briefer than `ask_operator` but takes a beat.',
+  parameters: {
+    type: "object",
+    properties: {
+      id: {
+        type: "string",
+        description: 'Skill id (lowercase-hyphenated), e.g. "negotiate-bill-reduction". Get it from search_skills.'
+      }
+    },
+    required: ["id"],
+    additionalProperties: false
+  }
+};
 var REALTIME_TOOL_DEFINITIONS = {
   ask_operator: ASK_OPERATOR_TOOL,
   web_search: WEB_SEARCH_TOOL,
   recall_memory: RECALL_MEMORY_TOOL,
   get_datetime: GET_DATETIME_TOOL,
-  search_email: SEARCH_EMAIL_TOOL
+  search_email: SEARCH_EMAIL_TOOL,
+  search_skills: SEARCH_SKILLS_TOOL,
+  load_skill: LOAD_SKILL_TOOL
 };
 function buildRealtimeToolGuidance(tools) {
   if (tools.length === 0) return "";
@@ -8773,6 +8820,16 @@ function buildRealtimeToolGuidance(tools) {
       'The lookup tools (web_search, recall_memory, get_datetime, search_email) return in seconds \u2014 a brief "one moment" is plenty; no long hold is needed for these.'
     );
   }
+  if (names.has("search_skills") && names.has("load_skill")) {
+    lines.push(
+      `Your SKILL LIBRARY contains playbooks for specific real-world phone situations \u2014 bill negotiation, debt-collector handling, restaurant booking, dispute filing, etc. Each playbook is a complete set of principles, scripted phrases, ordered tactics, boundaries, and exit strategy for that one situation. When you find yourself on the call without a clear next move \u2014 the rep brought up something you do not know how to handle, the conversation reached a stage that needs a specific tactic \u2014 load a skill instead of improvising:
+  1. Tell the caller you need a moment: "Hold on one moment \u2014 let me check something."
+  2. Call search_skills with a one-line description of the situation.
+  3. Call load_skill with the id of the best match.
+  4. Resume the call grounded in the playbook the load returned. Follow the playbook's tactic order, use its scripted phrases (paraphrased to match your voice), respect its hard boundaries, watch for its success / failure signals.
+A skill's rendered playbook is now part of your instructions for the rest of the call. You can load a second skill if a new situation comes up \u2014 but the model keeps a max of two loaded; a third load drops the oldest. Pick skills deliberately.`
+    );
+  }
   return lines.join("\n");
 }
 function toolErrorText(err) {
@@ -8958,6 +9015,7 @@ var REALTIME_AUDIO_SAMPLE_RATE = 24e3;
 var REALTIME_MAX_AUDIO_FRAME_BASE64 = 256 * 1024;
 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.";
 function buildRealtimeInstructions(opts) {
@@ -9049,6 +9107,26 @@ var RealtimeVoiceBridge = class {
   toolCallNames = /* @__PURE__ */ new Map();
   /** `call_id`s whose tool call is currently executing. */
   inFlightToolCalls = /* @__PURE__ */ new Set();
+  /**
+   * Mid-call skills loaded into the session so far, FIFO. Earliest at
+   * index 0; cap at {@link MAX_LOADED_SKILLS}. When a (cap+1)th skill
+   * is loaded the oldest one drops out — the model can't usefully
+   * hold five playbooks in working memory at once, so we keep the
+   * working set narrow on purpose.
+   */
+  loadedSkills = [];
+  /**
+   * The original `instructions` string from the session.update sent at
+   * open. We keep a private copy because every mid-call skill load
+   * issues a fresh `session.update` whose `instructions` is built as:
+   *
+   *     baseInstructions + "\n\n" + renderedSkill1 + "\n\n" + renderedSkill2 …
+   *
+   * Without this snapshot, successive loads would compound — the second
+   * load would see "base + skill1" as the base and append skill2 to
+   * THAT, eventually drifting unboundedly.
+   */
+  baseInstructions = "";
   constructor(opts) {
     const carrier = opts.carrier ?? opts.elks;
     if (!carrier) {
@@ -9085,6 +9163,10 @@ var RealtimeVoiceBridge = class {
   handleOpenAIOpen() {
     if (this.ended || this.openaiReady) return;
     this.openaiReady = true;
+    const sess = this.sessionConfig?.session;
+    if (sess && typeof sess.instructions === "string") {
+      this.baseInstructions = sess.instructions;
+    }
     this.safeSend(this.openai, this.sessionConfig);
     this.safeSend(this.openai, { type: "response.create" });
     for (const audio of this.pendingAudio.splice(0)) {
@@ -9095,6 +9177,74 @@ var RealtimeVoiceBridge = class {
   handleOpenAIClose() {
     this.end("openai-closed");
   }
+  /**
+   * Load a skill playbook into the live OpenAI Realtime session for
+   * the rest of the call.
+   *
+   * Mechanics:
+   *   1. Resolve the skill JSON via the skills registry (file on disk).
+   *   2. Append the rendered skill text to the agent's working
+   *      instructions and re-send a `session.update` carrying ONLY
+   *      the new `instructions` field. The OpenAI Realtime API
+   *      supports partial session.update — we don't have to re-send
+   *      audio config, tools, voice, etc.
+   *   3. Track which skills are loaded so we (a) FIFO-evict the
+   *      oldest when the cap is hit and (b) include every still-
+   *      loaded skill in the next composed instructions.
+   *   4. Emit a transcript marker so the mission record shows the
+   *      adaptation ("[skill loaded: Negotiate a Bill Reduction
+   *      v1.0.0]"). Useful for post-call review and for the build
+   *      farm's telemetry on which skills actually got reached for.
+   *
+   * Returns an object the {@link load_skill} tool handler can serialise
+   * back to the model: `ok: true` plus the skill name + version on
+   * success, `ok: false` plus a short reason on failure (unknown id,
+   * call ended, registry I/O error). Never throws — a buggy registry
+   * or a missing file must not crash the bridge mid-call.
+   *
+   * Phase 2 of the skill library (`docs/skill-library-plan.md`).
+   */
+  async loadSkillIntoSession(skillId) {
+    if (this.ended) return { ok: false, message: "Call has already ended; cannot load a skill now." };
+    if (!this.openaiReady) return { ok: false, message: "Session is not ready yet; try again in a moment." };
+    if (this.loadedSkills.some((s) => s.id === skillId)) {
+      const existing = this.loadedSkills.find((s) => s.id === skillId);
+      return { ok: true, message: `Skill "${skillId}" is already loaded.`, name: skillId, version: existing.version };
+    }
+    let loadSkill2;
+    let renderSkillAsPrompt2;
+    try {
+      ({ loadSkill: loadSkill2, renderSkillAsPrompt: renderSkillAsPrompt2 } = await import("./skills-RE3S767B.js"));
+    } catch (err) {
+      return { ok: false, message: `Skill registry unavailable: ${errorText(err)}` };
+    }
+    const skill = loadSkill2(skillId);
+    if (!skill) {
+      return { ok: false, message: `No skill found with id "${skillId}". Call search_skills first to find the right id.` };
+    }
+    const rendered = renderSkillAsPrompt2(skill);
+    while (this.loadedSkills.length >= MAX_LOADED_SKILLS) {
+      const dropped = this.loadedSkills.shift();
+      if (dropped) {
+        this.emitTranscript("system", `[skill unloaded for working-memory limit: ${dropped.id} v${dropped.version}]`);
+      }
+    }
+    this.loadedSkills.push({ id: skill.id, version: skill.version, renderedPrompt: rendered });
+    const composed = [
+      this.baseInstructions,
+      ...this.loadedSkills.map((s) => s.renderedPrompt)
+    ].filter((s) => s && s.length > 0).join("\n\n");
+    this.safeSend(this.openai, {
+      type: "session.update",
+      session: { instructions: composed }
+    });
+    this.emitTranscript("system", `[skill loaded: ${skill.name} v${skill.version}]`);
+    return { ok: true, message: `Loaded skill: ${skill.name} (v${skill.version})`, name: skill.name, version: skill.version };
+  }
+  /** The list of skills currently loaded into the session (FIFO-ordered). */
+  get loadedSkillIds() {
+    return this.loadedSkills.map((s) => s.id);
+  }
   /** Call when the OpenAI socket errors. */
   handleOpenAIError(err) {
     this.emitTranscript("system", `OpenAI Realtime error: ${errorText(err)}`);
@@ -12998,400 +13148,6 @@ function parse(raw) {
 
 // src/memory/manager.ts
 import { randomUUID as randomUUID3 } from "crypto";
-
-// src/memory/text-search.ts
-var BM25_K1 = 1.2;
-var BM25_B = 0.75;
-var FIELD_WEIGHT_TITLE = 3;
-var FIELD_WEIGHT_TAGS = 2;
-var FIELD_WEIGHT_CONTENT = 1;
-var PREFIX_MATCH_PENALTY = 0.7;
-var STOP_WORDS = /* @__PURE__ */ new Set([
-  "a",
-  "about",
-  "above",
-  "after",
-  "again",
-  "against",
-  "all",
-  "am",
-  "an",
-  "and",
-  "any",
-  "are",
-  "as",
-  "at",
-  "be",
-  "because",
-  "been",
-  "before",
-  "being",
-  "below",
-  "between",
-  "both",
-  "but",
-  "by",
-  "can",
-  "could",
-  "did",
-  "do",
-  "does",
-  "doing",
-  "down",
-  "during",
-  "each",
-  "either",
-  "every",
-  "few",
-  "for",
-  "from",
-  "further",
-  "get",
-  "got",
-  "had",
-  "has",
-  "have",
-  "having",
-  "he",
-  "her",
-  "here",
-  "hers",
-  "herself",
-  "him",
-  "himself",
-  "his",
-  "how",
-  "i",
-  "if",
-  "in",
-  "into",
-  "is",
-  "it",
-  "its",
-  "itself",
-  "just",
-  "may",
-  "me",
-  "might",
-  "more",
-  "most",
-  "must",
-  "my",
-  "myself",
-  "neither",
-  "no",
-  "nor",
-  "not",
-  "now",
-  "of",
-  "off",
-  "on",
-  "once",
-  "only",
-  "or",
-  "other",
-  "ought",
-  "our",
-  "ours",
-  "ourselves",
-  "out",
-  "over",
-  "own",
-  "same",
-  "shall",
-  "she",
-  "should",
-  "so",
-  "some",
-  "such",
-  "than",
-  "that",
-  "the",
-  "their",
-  "theirs",
-  "them",
-  "themselves",
-  "then",
-  "there",
-  "these",
-  "they",
-  "this",
-  "those",
-  "through",
-  "to",
-  "too",
-  "under",
-  "until",
-  "up",
-  "us",
-  "very",
-  "was",
-  "we",
-  "were",
-  "what",
-  "when",
-  "where",
-  "which",
-  "while",
-  "who",
-  "whom",
-  "why",
-  "will",
-  "with",
-  "would",
-  "yet",
-  "you",
-  "your",
-  "yours",
-  "yourself",
-  "yourselves"
-]);
-var STEM_RULES = [
-  // Step 1: plurals and past participles
-  [/ies$/, "i", 3],
-  // policies → polici,eries → eri
-  [/sses$/, "ss", 4],
-  // addresses → address
-  [/([^s])s$/, "$1", 3],
-  // items → item, but not "ss"
-  [/eed$/, "ee", 4],
-  // agreed → agree
-  [/ed$/, "", 3],
-  // configured → configur, but min length 3
-  [/ing$/, "", 4],
-  // running → runn → run (handled below)
-  // Step 2: derivational suffixes
-  [/ational$/, "ate", 6],
-  // relational → relate
-  [/tion$/, "t", 5],
-  // adoption → adopt
-  [/ness$/, "", 5],
-  // awareness → aware
-  [/ment$/, "", 5],
-  // deployment → deploy
-  [/able$/, "", 5],
-  // configurable → configur
-  [/ible$/, "", 5],
-  // accessible → access
-  [/ful$/, "", 5],
-  // powerful → power
-  [/ous$/, "", 5],
-  // dangerous → danger
-  [/ive$/, "", 5],
-  // interactive → interact
-  [/ize$/, "", 4],
-  // normalize → normal
-  [/ise$/, "", 4],
-  // organise → organ
-  [/ally$/, "", 5],
-  // automatically → automat
-  [/ly$/, "", 4],
-  // quickly → quick
-  [/er$/, "", 4]
-  // handler → handl
-];
-var DOUBLE_CONSONANT = /([^aeiou])\1$/;
-function stem(word) {
-  if (word.length < 3) return word;
-  let stemmed = word;
-  for (const [pattern, replacement, minLen] of STEM_RULES) {
-    if (stemmed.length >= minLen && pattern.test(stemmed)) {
-      stemmed = stemmed.replace(pattern, replacement);
-      break;
-    }
-  }
-  if (stemmed.length > 2 && DOUBLE_CONSONANT.test(stemmed)) {
-    stemmed = stemmed.slice(0, -1);
-  }
-  return stemmed;
-}
-function tokenize(text) {
-  return text.toLowerCase().split(/[^a-z0-9]+/).filter((t) => t.length > 1 && !STOP_WORDS.has(t)).map(stem);
-}
-var MemorySearchIndex = class {
-  /** Posting lists: stemmed term → Set of memory IDs containing it */
-  postings = /* @__PURE__ */ new Map();
-  /** Per-document metadata for BM25 scoring */
-  docs = /* @__PURE__ */ new Map();
-  /** Pre-computed IDF values. Stale flag triggers lazy recomputation. */
-  idf = /* @__PURE__ */ new Map();
-  idfStale = true;
-  /** 3-character prefix map for prefix matching: prefix → Set of full stems */
-  prefixMap = /* @__PURE__ */ new Map();
-  /** Total weighted document length (for computing average) */
-  totalWeightedLen = 0;
-  get docCount() {
-    return this.docs.size;
-  }
-  get avgDocLen() {
-    return this.docs.size > 0 ? this.totalWeightedLen / this.docs.size : 1;
-  }
-  /**
-   * Index a memory entry. Extracts stems from title, content, and tags
-   * with field-specific weighting and builds posting lists.
-   */
-  addDocument(id, entry) {
-    if (this.docs.has(id)) this.removeDocument(id);
-    const titleTokens = tokenize(entry.title);
-    const contentTokens = tokenize(entry.content);
-    const tagTokens = entry.tags.flatMap((t) => tokenize(t));
-    const weightedTf = /* @__PURE__ */ new Map();
-    for (const t of titleTokens) weightedTf.set(t, (weightedTf.get(t) || 0) + FIELD_WEIGHT_TITLE);
-    for (const t of tagTokens) weightedTf.set(t, (weightedTf.get(t) || 0) + FIELD_WEIGHT_TAGS);
-    for (const t of contentTokens) weightedTf.set(t, (weightedTf.get(t) || 0) + FIELD_WEIGHT_CONTENT);
-    const weightedLen = titleTokens.length * FIELD_WEIGHT_TITLE + tagTokens.length * FIELD_WEIGHT_TAGS + contentTokens.length * FIELD_WEIGHT_CONTENT;
-    const allStems = /* @__PURE__ */ new Set();
-    for (const t of weightedTf.keys()) allStems.add(t);
-    const stemSequence = [...titleTokens, ...contentTokens];
-    const docRecord = { weightedTf, weightedLen, allStems, stemSequence };
-    this.docs.set(id, docRecord);
-    this.totalWeightedLen += weightedLen;
-    for (const term of allStems) {
-      let posting = this.postings.get(term);
-      if (!posting) {
-        posting = /* @__PURE__ */ new Set();
-        this.postings.set(term, posting);
-      }
-      posting.add(id);
-      if (term.length >= 3) {
-        const prefix = term.slice(0, 3);
-        let prefixSet = this.prefixMap.get(prefix);
-        if (!prefixSet) {
-          prefixSet = /* @__PURE__ */ new Set();
-          this.prefixMap.set(prefix, prefixSet);
-        }
-        prefixSet.add(term);
-      }
-    }
-    this.idfStale = true;
-  }
-  /** Remove a document from the index. */
-  removeDocument(id) {
-    const doc = this.docs.get(id);
-    if (!doc) return;
-    this.totalWeightedLen -= doc.weightedLen;
-    this.docs.delete(id);
-    for (const term of doc.allStems) {
-      const posting = this.postings.get(term);
-      if (posting) {
-        posting.delete(id);
-        if (posting.size === 0) {
-          this.postings.delete(term);
-          if (term.length >= 3) {
-            const prefixSet = this.prefixMap.get(term.slice(0, 3));
-            if (prefixSet) {
-              prefixSet.delete(term);
-              if (prefixSet.size === 0) this.prefixMap.delete(term.slice(0, 3));
-            }
-          }
-        }
-      }
-    }
-    this.idfStale = true;
-  }
-  /** Recompute IDF values for all terms. Called lazily before search. */
-  refreshIdf() {
-    if (!this.idfStale) return;
-    const N = this.docs.size;
-    this.idf.clear();
-    for (const [term, posting] of this.postings) {
-      const df = posting.size;
-      this.idf.set(term, Math.log((N - df + 0.5) / (df + 0.5) + 1));
-    }
-    this.idfStale = false;
-  }
-  /**
-   * Expand query terms with prefix matches.
-   * "deploy" → ["deploy", "deployment", "deploying", ...] (if they exist in the index)
-   */
-  expandQueryTerms(queryStems) {
-    const expanded = /* @__PURE__ */ new Map();
-    for (const qs of queryStems) {
-      if (this.postings.has(qs)) {
-        expanded.set(qs, Math.max(expanded.get(qs) || 0, 1));
-      }
-      if (qs.length >= 3) {
-        const prefix = qs.slice(0, 3);
-        const candidates = this.prefixMap.get(prefix);
-        if (candidates) {
-          for (const candidate of candidates) {
-            if (candidate !== qs && candidate.startsWith(qs)) {
-              expanded.set(candidate, Math.max(expanded.get(candidate) || 0, PREFIX_MATCH_PENALTY));
-            }
-          }
-        }
-      }
-    }
-    return expanded;
-  }
-  /**
-   * Compute bigram proximity boost: if two query terms appear adjacent
-   * in the document's stem sequence, boost the score.
-   */
-  bigramProximityBoost(docId, queryStems) {
-    if (queryStems.length < 2) return 0;
-    const doc = this.docs.get(docId);
-    if (!doc || doc.stemSequence.length < 2) return 0;
-    let boost = 0;
-    const seq = doc.stemSequence;
-    const querySet = new Set(queryStems);
-    for (let i = 0; i < seq.length - 1; i++) {
-      if (querySet.has(seq[i]) && querySet.has(seq[i + 1]) && seq[i] !== seq[i + 1]) {
-        boost += 0.5;
-      }
-    }
-    return Math.min(boost, 2);
-  }
-  /**
-   * Search the index for documents matching a query.
-   * Returns scored results sorted by BM25F relevance.
-   *
-   * @param query - Raw query string
-   * @param candidateIds - Optional: only score these document IDs (for agent-scoped search)
-   * @returns Array of { id, score } sorted by descending score
-   */
-  search(query, candidateIds) {
-    const queryStems = tokenize(query);
-    if (queryStems.length === 0) return [];
-    this.refreshIdf();
-    const expandedTerms = this.expandQueryTerms(queryStems);
-    if (expandedTerms.size === 0) return [];
-    const avgDl = this.avgDocLen;
-    const candidates = /* @__PURE__ */ new Set();
-    for (const term of expandedTerms.keys()) {
-      const posting = this.postings.get(term);
-      if (posting) {
-        for (const docId of posting) {
-          if (!candidateIds || candidateIds.has(docId)) candidates.add(docId);
-        }
-      }
-    }
-    const results = [];
-    for (const docId of candidates) {
-      const doc = this.docs.get(docId);
-      if (!doc) continue;
-      let score = 0;
-      for (const [term, weight] of expandedTerms) {
-        const tf = doc.weightedTf.get(term) || 0;
-        if (tf === 0) continue;
-        const termIdf = this.idf.get(term) || 0;
-        const numerator = tf * (BM25_K1 + 1);
-        const denominator = tf + BM25_K1 * (1 - BM25_B + BM25_B * (doc.weightedLen / avgDl));
-        score += termIdf * (numerator / denominator) * weight;
-      }
-      score += this.bigramProximityBoost(docId, queryStems);
-      if (score > 0) results.push({ id: docId, score });
-    }
-    results.sort((a, b) => b.score - a.score);
-    return results;
-  }
-  /** Check if a document exists in the index. */
-  has(id) {
-    return this.docs.has(id);
-  }
-};
-
-// src/memory/manager.ts
 function sj(v, fb = {}) {
   if (!v) return fb;
   try {
@@ -13903,6 +13659,7 @@ export {
   GET_DATETIME_TOOL,
   GatewayManager,
   InboxWatcher,
+  LOAD_SKILL_TOOL,
   MEMORY_CATEGORIES,
   MailReceiver,
   MailSender,
@@ -13939,6 +13696,7 @@ export {
   RelayBridge,
   RelayGateway,
   SEARCH_EMAIL_TOOL,
+  SEARCH_SKILLS_TOOL,
   SPAM_THRESHOLD,
   ServiceManager,
   SetupManager,
@@ -14018,6 +13776,7 @@ export {
   getTelegramWebhookInfo,
   hostSessionStoragePath,
   inferPhoneRegion,
+  invalidateSkillCache,
   isInternalEmail,
   isLoopbackMailHost,
   isOperatorReplySender,
@@ -14026,7 +13785,9 @@ export {
   isTelegramChatAllowed,
   isTelegramStopCommand,
   isValidPhoneNumber,
+  listSkills,
   loadHostSession,
+  loadSkill,
   mapProviderSmsStatus,
   nextTelegramOffset,
   normalizeAddress,
@@ -14051,6 +13812,7 @@ export {
   redactSecret,
   redactSmsConfig,
   redactTelegramConfig,
+  renderSkillAsPrompt,
   requireBinary,
   requireWhisperModel,
   resolveConfig,
@@ -14059,8 +13821,10 @@ export {
   sanitizeEmail,
   saveConfig,
   saveHostSession,
+  saveUserSkill,
   scanOutboundEmail,
   scoreEmail,
+  searchSkills,
   sendTelegramMessage,
   setOperatorEmail,
   setTelegramWebhook,
@@ -14073,10 +13837,12 @@ export {
   threadIdFor,
   tokenize,
   tryJoin,
+  userSkillsDir,
   validateApiUrl,
   validatePhoneMissionPolicy,
   validatePhoneMissionStart,
   validatePhoneTransportProfile,
+  validateSkill,
   validateTwilioSignature,
   webSearch
 };