@agenticmail/core 0.9.23 → 0.9.24

package/dist/index.cjs

@@ -851,6 +851,7 @@ __export(index_exports, {
   getTelegramWebhookInfo: () => getTelegramWebhookInfo,
   hostSessionStoragePath: () => hostSessionStoragePath,
   inferPhoneRegion: () => inferPhoneRegion,
+  invalidateSkillCache: () => invalidateSkillCache,
   isInternalEmail: () => isInternalEmail,
   isLoopbackMailHost: () => isLoopbackMailHost,
   isOperatorReplySender: () => isOperatorReplySender,
@@ -859,7 +860,9 @@ __export(index_exports, {
   isTelegramChatAllowed: () => isTelegramChatAllowed,
   isTelegramStopCommand: () => isTelegramStopCommand,
   isValidPhoneNumber: () => isValidPhoneNumber,
+  listSkills: () => listSkills,
   loadHostSession: () => loadHostSession,
+  loadSkill: () => loadSkill,
   mapProviderSmsStatus: () => mapProviderSmsStatus,
   nextTelegramOffset: () => nextTelegramOffset,
   normalizeAddress: () => normalizeAddress,
@@ -884,6 +887,7 @@ __export(index_exports, {
   redactSecret: () => redactSecret,
   redactSmsConfig: () => redactSmsConfig,
   redactTelegramConfig: () => redactTelegramConfig,
+  renderSkillAsPrompt: () => renderSkillAsPrompt,
   requireBinary: () => requireBinary,
   requireWhisperModel: () => requireWhisperModel,
   resolveConfig: () => resolveConfig,
@@ -892,8 +896,10 @@ __export(index_exports, {
   sanitizeEmail: () => sanitizeEmail,
   saveConfig: () => saveConfig,
   saveHostSession: () => saveHostSession,
+  saveUserSkill: () => saveUserSkill,
   scanOutboundEmail: () => scanOutboundEmail,
   scoreEmail: () => scoreEmail,
+  searchSkills: () => searchSkills,
   sendTelegramMessage: () => sendTelegramMessage,
   setOperatorEmail: () => setOperatorEmail,
   setTelegramWebhook: () => setTelegramWebhook,
@@ -906,10 +912,12 @@ __export(index_exports, {
   threadIdFor: () => threadIdFor,
   tokenize: () => tokenize,
   tryJoin: () => tryJoin,
+  userSkillsDir: () => userSkillsDir,
   validateApiUrl: () => validateApiUrl,
   validatePhoneMissionPolicy: () => validatePhoneMissionPolicy,
   validatePhoneMissionStart: () => validatePhoneMissionStart,
   validatePhoneTransportProfile: () => validatePhoneTransportProfile,
+  validateSkill: () => validateSkill,
   validateTwilioSignature: () => validateTwilioSignature,
   webSearch: () => webSearch
 });
@@ -2016,14 +2024,14 @@ var StalwartAdmin = class {
     if (!isValidDomain(domain)) {
       throw new Error(`Invalid domain format: "${domain}"`);
     }
-    const { readFileSync: readFileSync10, writeFileSync: writeFileSync11 } = await import("fs");
-    const { homedir: homedir13 } = await import("os");
-    const { join: join16 } = await import("path");
-    const configPath = join16(homedir13(), ".agenticmail", "stalwart.toml");
+    const { readFileSync: readFileSync11, writeFileSync: writeFileSync12 } = await import("fs");
+    const { homedir: homedir14 } = await import("os");
+    const { join: join17 } = await import("path");
+    const configPath = join17(homedir14(), ".agenticmail", "stalwart.toml");
     try {
-      let config = readFileSync10(configPath, "utf-8");
+      let config = readFileSync11(configPath, "utf-8");
       config = config.replace(/^hostname\s*=\s*"[^"]*"/m, `hostname = "${escapeTomlString(domain)}"`);
-      writeFileSync11(configPath, config);
+      writeFileSync12(configPath, config);
       console.log(`[Stalwart] Updated hostname to "${domain}" in stalwart.toml`);
     } catch (err) {
       throw new Error(`Failed to set config server.hostname=${domain}`);
@@ -2032,15 +2040,15 @@ var StalwartAdmin = class {
   // --- DKIM ---
   /** Path to the host-side stalwart.toml (mounted read-only into container) */
   get configPath() {
-    const { homedir: homedir13 } = require("os");
-    const { join: join16 } = require("path");
-    return join16(homedir13(), ".agenticmail", "stalwart.toml");
+    const { homedir: homedir14 } = require("os");
+    const { join: join17 } = require("path");
+    return join17(homedir14(), ".agenticmail", "stalwart.toml");
   }
   /** Path to host-side DKIM key directory */
   get dkimDir() {
-    const { homedir: homedir13 } = require("os");
-    const { join: join16 } = require("path");
-    return join16(homedir13(), ".agenticmail");
+    const { homedir: homedir14 } = require("os");
+    const { join: join17 } = require("path");
+    return join17(homedir14(), ".agenticmail");
   }
   /**
    * Create/reuse a DKIM signing key for a domain.
@@ -2141,12 +2149,12 @@ var StalwartAdmin = class {
    * This bypasses the need for a PTR record on the sending IP.
    */
   async configureOutboundRelay(config) {
-    const { readFileSync: readFileSync10, writeFileSync: writeFileSync11 } = await import("fs");
-    const { homedir: homedir13 } = await import("os");
-    const { join: join16 } = await import("path");
+    const { readFileSync: readFileSync11, writeFileSync: writeFileSync12 } = await import("fs");
+    const { homedir: homedir14 } = await import("os");
+    const { join: join17 } = await import("path");
     const routeName = config.routeName ?? "gmail";
-    const tomlPath = join16(homedir13(), ".agenticmail", "stalwart.toml");
-    let toml = readFileSync10(tomlPath, "utf-8");
+    const tomlPath = join17(homedir14(), ".agenticmail", "stalwart.toml");
+    let toml = readFileSync11(tomlPath, "utf-8");
     toml = toml.replace(/\n\[queue\.route\.gmail\][\s\S]*?(?=\n\[|$)/, "");
     toml = toml.replace(/\n\[queue\.strategy\][\s\S]*?(?=\n\[|$)/, "");
     const safeRouteName = routeName.replace(/[^a-zA-Z0-9_-]/g, "");
@@ -2166,7 +2174,7 @@ auth.secret = "${escapeTomlString(config.password)}"
 route = [ { if = "is_local_domain('', rcpt_domain)", then = "'local'" },
            { else = "'${safeRouteName}'" } ]
 `;
-    writeFileSync11(tomlPath, toml, "utf-8");
+    writeFileSync12(tomlPath, toml, "utf-8");
     await this.restartContainer();
   }
 };
@@ -8372,12 +8380,12 @@ var GatewayManager = class {
       zone = await this.cfClient.createZone(domain);
     }
     const existingRecords = await this.cfClient.listDnsRecords(zone.id);
-    const { homedir: homedir13 } = await import("os");
-    const backupDir = (0, import_node_path4.join)(homedir13(), ".agenticmail");
+    const { homedir: homedir14 } = await import("os");
+    const backupDir = (0, import_node_path4.join)(homedir14(), ".agenticmail");
     const backupPath = (0, import_node_path4.join)(backupDir, `dns-backup-${domain}-${Date.now()}.json`);
-    const { writeFileSync: writeFileSync11, mkdirSync: mkdirSync12 } = await import("fs");
-    mkdirSync12(backupDir, { recursive: true });
-    writeFileSync11(backupPath, JSON.stringify({
+    const { writeFileSync: writeFileSync12, mkdirSync: mkdirSync13 } = await import("fs");
+    mkdirSync13(backupDir, { recursive: true });
+    writeFileSync12(backupPath, JSON.stringify({
       domain,
       zoneId: zone.id,
       backedUpAt: (/* @__PURE__ */ new Date()).toISOString(),
@@ -14763,6 +14771,285 @@ var AgentMemoryManager = class {
     };
   }
 };
+
+// src/skills/registry.ts
+var import_node_fs14 = require("fs");
+var import_node_path15 = require("path");
+var import_node_url = require("url");
+var import_node_os12 = require("os");
+var import_meta4 = {};
+function builtInDir() {
+  const here = (0, import_node_path15.dirname)((0, import_node_url.fileURLToPath)(import_meta4.url));
+  return (0, import_node_path15.join)(here, "built-in");
+}
+function userDir() {
+  const dir2 = (0, import_node_path15.join)((0, import_node_os12.homedir)(), ".agenticmail", "skills");
+  try {
+    if (!(0, import_node_fs14.existsSync)(dir2)) (0, import_node_fs14.mkdirSync)(dir2, { recursive: true });
+  } catch {
+  }
+  return dir2;
+}
+var cache = { ts: 0, byId: null };
+var CACHE_TTL_MS = 5e3;
+function loadAllSkillsFromDisk() {
+  const all = /* @__PURE__ */ new Map();
+  const dirs = [builtInDir(), userDir()];
+  for (const dir2 of dirs) {
+    if (!(0, import_node_fs14.existsSync)(dir2)) continue;
+    let entries;
+    try {
+      entries = (0, import_node_fs14.readdirSync)(dir2);
+    } catch {
+      continue;
+    }
+    for (const entry of entries) {
+      if (!entry.endsWith(".json")) continue;
+      const fullPath = (0, import_node_path15.join)(dir2, entry);
+      try {
+        const st = (0, import_node_fs14.statSync)(fullPath);
+        if (!st.isFile()) continue;
+        const raw = (0, import_node_fs14.readFileSync)(fullPath, "utf-8");
+        const parsed = JSON.parse(raw);
+        const errors = validateSkill(parsed);
+        if (errors.length > 0) {
+          console.warn(`[skills] ${entry} invalid, skipping: ${errors.map((e) => `${e.path}: ${e.message}`).join("; ")}`);
+          continue;
+        }
+        all.set(parsed.id, parsed);
+      } catch (err) {
+        console.warn(`[skills] could not load ${fullPath}: ${err.message}`);
+      }
+    }
+  }
+  return all;
+}
+function ensureLoaded() {
+  const now = Date.now();
+  if (cache.byId && now - cache.ts < CACHE_TTL_MS) return cache.byId;
+  const fresh = loadAllSkillsFromDisk();
+  cache.byId = fresh;
+  cache.ts = now;
+  return fresh;
+}
+function invalidateSkillCache() {
+  cache.byId = null;
+  cache.ts = 0;
+}
+function validateSkill(s) {
+  const errs = [];
+  if (!s || typeof s !== "object" || Array.isArray(s)) {
+    return [{ path: "$", message: "skill must be a JSON object" }];
+  }
+  const sk = s;
+  const requireString = (key, minLen = 1) => {
+    const v = sk[key];
+    if (typeof v !== "string" || v.length < minLen) {
+      errs.push({ path: key, message: `must be a non-empty string` });
+    }
+  };
+  const requireArray = (key, minLen = 1) => {
+    const v = sk[key];
+    if (!Array.isArray(v) || v.length < minLen) {
+      errs.push({ path: key, message: `must be a non-empty array` });
+    }
+  };
+  requireString("id");
+  if (typeof sk.id === "string" && !/^[a-z0-9]+(-[a-z0-9]+)*$/.test(sk.id)) {
+    errs.push({ path: "id", message: "must be lowercase-hyphenated slug (a-z, 0-9, -)" });
+  }
+  requireString("name");
+  requireString("version");
+  requireString("description");
+  requireString("category");
+  const validCategories = [
+    "negotiation",
+    "customer-service",
+    "reservations",
+    "medical-admin",
+    "legal-admin",
+    "finance-admin",
+    "real-estate",
+    "travel",
+    "subscription",
+    "home-services",
+    "social",
+    "civic",
+    "employment",
+    "debt-collection",
+    "other"
+  ];
+  if (typeof sk.category === "string" && !validCategories.includes(sk.category)) {
+    errs.push({ path: "category", message: `unknown category "${sk.category}"; must be one of: ${validCategories.join(", ")}` });
+  }
+  if (!Array.isArray(sk.tags)) errs.push({ path: "tags", message: "must be an array of strings" });
+  if (sk.disclaimer !== null && typeof sk.disclaimer !== "string") {
+    errs.push({ path: "disclaimer", message: "must be a string or null" });
+  }
+  if (!sk.context || typeof sk.context !== "object") {
+    errs.push({ path: "context", message: "must be an object" });
+  } else {
+    const ctx = sk.context;
+    if (typeof ctx.when_to_use !== "string") errs.push({ path: "context.when_to_use", message: "must be a string" });
+    if (!Array.isArray(ctx.preconditions)) errs.push({ path: "context.preconditions", message: "must be an array" });
+    if (typeof ctx.estimated_call_duration_minutes !== "number") errs.push({ path: "context.estimated_call_duration_minutes", message: "must be a number" });
+  }
+  requireArray("principles", 2);
+  if (!sk.phrases || typeof sk.phrases !== "object") errs.push({ path: "phrases", message: "must be an object of {key: phrase}" });
+  if (!Array.isArray(sk.tactics) || sk.tactics.length === 0) {
+    errs.push({ path: "tactics", message: "must be a non-empty array" });
+  } else {
+    sk.tactics.forEach((t, i) => {
+      if (!t || typeof t !== "object") {
+        errs.push({ path: `tactics[${i}]`, message: "must be an object" });
+        return;
+      }
+      const tactic = t;
+      if (typeof tactic.name !== "string") errs.push({ path: `tactics[${i}].name`, message: "must be a string" });
+      if (typeof tactic.when !== "string") errs.push({ path: `tactics[${i}].when`, message: "must be a string" });
+      if (typeof tactic.script !== "string" || tactic.script.length < 5) {
+        errs.push({ path: `tactics[${i}].script`, message: "must be a non-empty string (>= 5 chars)" });
+      }
+    });
+  }
+  requireArray("boundaries", 1);
+  if (!Array.isArray(sk.success_signals)) errs.push({ path: "success_signals", message: "must be an array" });
+  if (!Array.isArray(sk.failure_signals)) errs.push({ path: "failure_signals", message: "must be an array" });
+  if (!sk.exit_strategy || typeof sk.exit_strategy !== "object") {
+    errs.push({ path: "exit_strategy", message: "must be an object" });
+  } else {
+    const xs = sk.exit_strategy;
+    if (typeof xs.on_success !== "string") errs.push({ path: "exit_strategy.on_success", message: "must be a string" });
+    if (typeof xs.on_failure !== "string") errs.push({ path: "exit_strategy.on_failure", message: "must be a string" });
+  }
+  if (!Array.isArray(sk.required_user_info)) errs.push({ path: "required_user_info", message: "must be an array" });
+  if (typeof sk.contributed_by !== "string") errs.push({ path: "contributed_by", message: "must be a string" });
+  return errs;
+}
+function summarize(s) {
+  return {
+    id: s.id,
+    name: s.name,
+    category: s.category,
+    tags: s.tags,
+    description: s.description,
+    version: s.version,
+    disclaimer_required: !!s.disclaimer,
+    estimated_call_duration_minutes: s.context.estimated_call_duration_minutes
+  };
+}
+function listSkills(opts = {}) {
+  const all = Array.from(ensureLoaded().values());
+  const filtered = all.filter((s) => {
+    if (opts.category && s.category !== opts.category) return false;
+    if (opts.tag && !s.tags.includes(opts.tag.toLowerCase())) return false;
+    return true;
+  });
+  return filtered.sort((a, b) => a.name.localeCompare(b.name)).map(summarize);
+}
+function searchSkills(query, limit = 20) {
+  const q = query.toLowerCase().trim();
+  if (!q) return listSkills();
+  const all = Array.from(ensureLoaded().values());
+  const scored = [];
+  for (const s of all) {
+    let score = 0;
+    if (s.id.toLowerCase().includes(q)) score += 10;
+    if (s.name.toLowerCase().includes(q)) score += 8;
+    if (s.tags.some((t) => t.toLowerCase().includes(q))) score += 5;
+    if (s.category.toLowerCase().includes(q)) score += 4;
+    if (s.description.toLowerCase().includes(q)) score += 3;
+    if (s.principles.some((p) => p.toLowerCase().includes(q))) score += 2;
+    if (Object.values(s.phrases).some((p) => p.toLowerCase().includes(q))) score += 2;
+    if (s.tactics.some((t) => t.script.toLowerCase().includes(q) || t.name.toLowerCase().includes(q))) score += 2;
+    if (score > 0) scored.push({ skill: s, score });
+  }
+  scored.sort((a, b) => b.score - a.score || a.skill.name.localeCompare(b.skill.name));
+  return scored.slice(0, limit).map((x) => summarize(x.skill));
+}
+function loadSkill(id) {
+  return ensureLoaded().get(id) ?? null;
+}
+function saveUserSkill(skill) {
+  const errors = validateSkill(skill);
+  if (errors.length > 0) {
+    throw new Error(`skill validation failed: ${errors.map((e) => `${e.path}: ${e.message}`).join("; ")}`);
+  }
+  const dir2 = userDir();
+  const path2 = (0, import_node_path15.join)(dir2, `${skill.id}.json`);
+  const now = (/* @__PURE__ */ new Date()).toISOString();
+  const out = {
+    ...skill,
+    created_at: skill.created_at ?? now,
+    updated_at: now
+  };
+  (0, import_node_fs14.writeFileSync)(path2, JSON.stringify(out, null, 2), "utf-8");
+  invalidateSkillCache();
+  return { path: path2 };
+}
+function userSkillsDir() {
+  return userDir();
+}
+
+// src/skills/index.ts
+function renderSkillAsPrompt(skill) {
+  const lines = [];
+  lines.push(`=== SKILL LOADED: ${skill.name} (v${skill.version}) ===`);
+  lines.push(`Category: ${skill.category}    Tags: ${skill.tags.join(", ")}`);
+  lines.push("");
+  lines.push(skill.description);
+  lines.push("");
+  if (skill.disclaimer) {
+    lines.push("REQUIRED DISCLAIMER (recite at start of the substantive turn):");
+    lines.push(`  "${skill.disclaimer}"`);
+    lines.push("");
+  }
+  lines.push("WHEN TO USE THIS:");
+  lines.push(`  ${skill.context.when_to_use}`);
+  if (skill.context.preconditions.length > 0) {
+    lines.push("Preconditions:");
+    for (const p of skill.context.preconditions) lines.push(`  - ${p}`);
+  }
+  lines.push("");
+  lines.push("PRINCIPLES:");
+  for (const p of skill.principles) lines.push(`  - ${p}`);
+  lines.push("");
+  if (Object.keys(skill.phrases).length > 0) {
+    lines.push("PHRASES (paraphrase to match your voice; keep the structural move):");
+    for (const [k, v] of Object.entries(skill.phrases)) lines.push(`  [${k}] "${v}"`);
+    lines.push("");
+  }
+  if (skill.tactics.length > 0) {
+    lines.push("TACTICS (try in order; fall back to next on failure):");
+    skill.tactics.forEach((t, i) => {
+      lines.push(`  ${i + 1}. ${t.name}`);
+      lines.push(`     When: ${t.when}`);
+      lines.push(`     Script: "${t.script}"`);
+    });
+    lines.push("");
+  }
+  if (skill.boundaries.length > 0) {
+    lines.push("HARD BOUNDARIES \u2014 do not cross:");
+    for (const b of skill.boundaries) lines.push(`  - ${b}`);
+    lines.push("");
+  }
+  lines.push("SUCCESS SIGNALS:");
+  for (const s of skill.success_signals) lines.push(`  - ${s}`);
+  lines.push("");
+  lines.push("FAILURE SIGNALS \u2014 when these appear, escalate or exit:");
+  for (const s of skill.failure_signals) lines.push(`  - ${s}`);
+  lines.push("");
+  lines.push("EXIT:");
+  lines.push(`  On success: ${skill.exit_strategy.on_success}`);
+  lines.push(`  On failure: ${skill.exit_strategy.on_failure}`);
+  if (skill.exit_strategy.follow_ups && skill.exit_strategy.follow_ups.length > 0) {
+    lines.push("  Follow-ups (after the call):");
+    for (const f of skill.exit_strategy.follow_ups) lines.push(`    - ${f}`);
+  }
+  lines.push("");
+  lines.push("=== END SKILL ===");
+  return lines.join("\n");
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   AGENT_ROLES,
@@ -14908,6 +15195,7 @@ var AgentMemoryManager = class {
   getTelegramWebhookInfo,
   hostSessionStoragePath,
   inferPhoneRegion,
+  invalidateSkillCache,
   isInternalEmail,
   isLoopbackMailHost,
   isOperatorReplySender,
@@ -14916,7 +15204,9 @@ var AgentMemoryManager = class {
   isTelegramChatAllowed,
   isTelegramStopCommand,
   isValidPhoneNumber,
+  listSkills,
   loadHostSession,
+  loadSkill,
   mapProviderSmsStatus,
   nextTelegramOffset,
   normalizeAddress,
@@ -14941,6 +15231,7 @@ var AgentMemoryManager = class {
   redactSecret,
   redactSmsConfig,
   redactTelegramConfig,
+  renderSkillAsPrompt,
   requireBinary,
   requireWhisperModel,
   resolveConfig,
@@ -14949,8 +15240,10 @@ var AgentMemoryManager = class {
   sanitizeEmail,
   saveConfig,
   saveHostSession,
+  saveUserSkill,
   scanOutboundEmail,
   scoreEmail,
+  searchSkills,
   sendTelegramMessage,
   setOperatorEmail,
   setTelegramWebhook,
@@ -14963,10 +15256,12 @@ var AgentMemoryManager = class {
   threadIdFor,
   tokenize,
   tryJoin,
+  userSkillsDir,
   validateApiUrl,
   validatePhoneMissionPolicy,
   validatePhoneMissionStart,
   validatePhoneTransportProfile,
+  validateSkill,
   validateTwilioSignature,
   webSearch
 });