@agenticmail/core 0.9.23 → 0.9.24

package/dist/index.js

@@ -1109,14 +1109,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}`);
@@ -1125,15 +1125,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.
@@ -1234,12 +1234,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, "");
@@ -1259,7 +1259,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();
   }
 };
@@ -7460,12 +7460,12 @@ var GatewayManager = class {
       zone = await this.cfClient.createZone(domain);
     }
     const existingRecords = await this.cfClient.listDnsRecords(zone.id);
-    const { homedir: homedir13 } = await import("os");
-    const backupDir = join4(homedir13(), ".agenticmail");
+    const { homedir: homedir14 } = await import("os");
+    const backupDir = join4(homedir14(), ".agenticmail");
     const backupPath = join4(backupDir, `dns-backup-${domain}-${Date.now()}.json`);
-    const { writeFileSync: writeFileSync11, mkdirSync: mkdirSync12 } = await import("fs");
-    mkdirSync12(backupDir, { recursive: true });
-    writeFileSync11(backupPath, JSON.stringify({
+    const { writeFileSync: writeFileSync12, mkdirSync: mkdirSync13 } = await import("fs");
+    mkdirSync13(backupDir, { recursive: true });
+    writeFileSync12(backupPath, JSON.stringify({
       domain,
       zoneId: zone.id,
       backedUpAt: (/* @__PURE__ */ new Date()).toISOString(),
@@ -13874,6 +13874,284 @@ var AgentMemoryManager = class {
     };
   }
 };
+
+// src/skills/registry.ts
+import { existsSync as existsSync14, mkdirSync as mkdirSync12, readFileSync as readFileSync10, readdirSync as readdirSync3, statSync as statSync3, writeFileSync as writeFileSync11 } from "fs";
+import { join as join16, dirname as dirname3, basename as basename2 } from "path";
+import { fileURLToPath } from "url";
+import { homedir as homedir13 } from "os";
+function builtInDir() {
+  const here = dirname3(fileURLToPath(import.meta.url));
+  return join16(here, "built-in");
+}
+function userDir() {
+  const dir2 = join16(homedir13(), ".agenticmail", "skills");
+  try {
+    if (!existsSync14(dir2)) mkdirSync12(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 (!existsSync14(dir2)) continue;
+    let entries;
+    try {
+      entries = readdirSync3(dir2);
+    } catch {
+      continue;
+    }
+    for (const entry of entries) {
+      if (!entry.endsWith(".json")) continue;
+      const fullPath = join16(dir2, entry);
+      try {
+        const st = statSync3(fullPath);
+        if (!st.isFile()) continue;
+        const raw = readFileSync10(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 = join16(dir2, `${skill.id}.json`);
+  const now = (/* @__PURE__ */ new Date()).toISOString();
+  const out = {
+    ...skill,
+    created_at: skill.created_at ?? now,
+    updated_at: now
+  };
+  writeFileSync11(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");
+}
 export {
   AGENT_ROLES,
   ASK_OPERATOR_TOOL,
@@ -14018,6 +14296,7 @@ export {
   getTelegramWebhookInfo,
   hostSessionStoragePath,
   inferPhoneRegion,
+  invalidateSkillCache,
   isInternalEmail,
   isLoopbackMailHost,
   isOperatorReplySender,
@@ -14026,7 +14305,9 @@ export {
   isTelegramChatAllowed,
   isTelegramStopCommand,
   isValidPhoneNumber,
+  listSkills,
   loadHostSession,
+  loadSkill,
   mapProviderSmsStatus,
   nextTelegramOffset,
   normalizeAddress,
@@ -14051,6 +14332,7 @@ export {
   redactSecret,
   redactSmsConfig,
   redactTelegramConfig,
+  renderSkillAsPrompt,
   requireBinary,
   requireWhisperModel,
   resolveConfig,
@@ -14059,8 +14341,10 @@ export {
   sanitizeEmail,
   saveConfig,
   saveHostSession,
+  saveUserSkill,
   scanOutboundEmail,
   scoreEmail,
+  searchSkills,
   sendTelegramMessage,
   setOperatorEmail,
   setTelegramWebhook,
@@ -14073,10 +14357,12 @@ export {
   threadIdFor,
   tokenize,
   tryJoin,
+  userSkillsDir,
   validateApiUrl,
   validatePhoneMissionPolicy,
   validatePhoneMissionStart,
   validatePhoneTransportProfile,
+  validateSkill,
   validateTwilioSignature,
   webSearch
 };

package/dist/skills/built-in/airline-change-or-refund.json

@@ -0,0 +1,111 @@
+{
+  "id": "airline-change-or-refund",
+  "name": "Change or Refund an Airline Reservation",
+  "version": "1.0.0",
+  "category": "travel",
+  "tags": ["airline", "flight", "refund", "rebook", "travel-disruption"],
+  "description": "Call an airline to change a booking, request a refund, or rebook around a cancelled / delayed flight. Surface fare rules, fee waivers, and travel credits that don't show in the app.",
+  "disclaimer": null,
+  "context": {
+    "when_to_use": "User needs to change a flight, get refunded for a cancelled flight, or rebook after a disruption. Use this when the airline's app / website doesn't expose the option the user needs, or when a fee waiver is plausible (weather, schedule change > 1 hour, illness with documentation, bereavement).",
+    "preconditions": [
+      "Confirmation number / record locator (6 letters and numbers).",
+      "Passenger's full name as shown on the ticket (matches photo ID).",
+      "Loyalty number, if any.",
+      "Original itinerary + the desired new itinerary (date / time / cities).",
+      "Reason for the change (schedule change, weather, personal — affects which waivers apply).",
+      "Whether the user wants a refund, travel credit, or a rebooked itinerary."
+    ],
+    "estimated_call_duration_minutes": 30
+  },
+  "principles": [
+    "Loyalty status matters. Lead with the elite number (Platinum, 1K, etc) if the user has one — different reps, different rules.",
+    "If the AIRLINE caused the disruption (cancellation, schedule change > 1 hour, equipment swap), the rules are MUCH more in the user's favour. Lead with the disruption fact.",
+    "Travel credits and refunds are different. A 'refund' goes back to the original payment; a 'travel credit' is airline-only money with an expiry. Be explicit about which you're asking for.",
+    "Fee waivers are sometimes discretionary — a calm, polite request from a long-tenured customer gets them more often than a demanding one.",
+    "Schedule change protections (DOT rules for US flights with significant schedule changes) often entitle a refund EVEN ON A NON-REFUNDABLE FARE. Don't accept 'non-refundable' as final.",
+    "If the first rep can't help, hold for a supervisor or call back later (different rep, different mood, sometimes different answer)."
+  ],
+  "phrases": {
+    "opener_with_status": "Hi, I'm calling about confirmation [PNR] for [passenger name]. I'm a [status] member — number [loyalty]. I need to [change / refund / rebook] this trip.",
+    "opener_without_status": "Hi, I'm calling about confirmation [PNR] for [passenger name]. I need to [change / refund / rebook] this trip.",
+    "lead_with_disruption": "Before we look at fees — this is because of [airline's schedule change / cancellation / equipment swap / weather waiver]. Can we look at change-fee or refund options under that policy first?",
+    "request_specific_rebook": "I'd like to move to [airline] flight [number] on [date] departing [time] — same routing. What's the difference in fare?",
+    "request_refund": "Given [reason], I'd like to refund the unused portion to the original form of payment. What's the refund amount and the processing time?",
+    "ask_credit_alternative": "If a refund isn't possible, what's the travel-credit option — value, expiry date, transferable?",
+    "ask_fee_waiver": "Is there any way to waive the change fee? I'm a long-time customer and this trip is for [brief reason].",
+    "stall_thinking": "Let me think about that for one second.",
+    "stall_research": "Hold on, I want to confirm something with the passenger before I commit.",
+    "graceful_close": "Thank you. To confirm: [new itinerary], confirmation [number], total [amount] charged or refund of [amount] to [method] arriving in [days]. I'll watch for the email."
+  },
+  "tactics": [
+    {
+      "name": "Lead with PNR + loyalty status",
+      "when": "First substantive turn.",
+      "script": "Use `opener_with_status` if the user has any elite status (even bronze). Status changes the rep's screen colour — they treat the call differently.",
+      "priority": 1
+    },
+    {
+      "name": "Frame the call as a disruption claim, not a customer change",
+      "when": "The airline caused (or contributed to) the change.",
+      "script": "Use `lead_with_disruption`. Cancellations, schedule changes > 60 min (for US carriers), equipment swaps that affect seat assignments, all unlock different waivers."
+    },
+    {
+      "name": "Ask for refund first, accept credit as fallback",
+      "when": "User has a clear preference for refund.",
+      "script": "Use `request_refund` first. If denied, use `ask_credit_alternative`. Credits should be accepted only if the user pre-authorised credits-OK."
+    },
+    {
+      "name": "Politely ask for a fee waiver",
+      "when": "A change fee is being quoted on a personal change (not a disruption).",
+      "script": "Use `ask_fee_waiver`. Don't make it a demand — make it a question with a tone of 'help me out if you can'."
+    },
+    {
+      "name": "Escalate to a supervisor",
+      "when": "Front-line rep says no on something a supervisor might say yes to (fee waiver, fare-difference reduction, specific seat reassignment).",
+      "script": "Polite: 'I appreciate you checking. Could we get a supervisor's read on this? Not because you've done anything wrong — I just want to make sure we've explored the policies before I commit.'"
+    },
+    {
+      "name": "Hang up and call back",
+      "when": "Call has gone in circles and the supervisor also said no.",
+      "script": "End politely, wait an hour, call back. Different rep, sometimes different answer. This is a known industry quirk; don't rage about it, just try again."
+    }
+  ],
+  "boundaries": [
+    "Do NOT commit to a fare difference > $X without explicit user authorisation. Use `ask_operator` for big numbers.",
+    "Do NOT accept a travel credit instead of a refund unless the user pre-authorised credit-OK.",
+    "Do NOT agree to non-refundable rules being final on a disruption-caused change — push back politely.",
+    "Do NOT share the user's full credit card on a recorded line if avoidable; the airline usually has the card on file.",
+    "Do NOT make up reasons to claim a waiver (bereavement, illness) — if the user doesn't have actual documentation, don't use those framings."
+  ],
+  "success_signals": [
+    "Rep waives a change fee.",
+    "Rep offers a refund to the original payment method.",
+    "Rep finds a flight in the user's preferred window.",
+    "Rep notes elite-status protections that exceed the base fare's rules."
+  ],
+  "failure_signals": [
+    "Rep + supervisor both decline waiver requests on a disruption-caused change (try calling back).",
+    "Rep can find no flight in the user's window for any price the user pre-authorised.",
+    "Refund processing time quoted at > 60 days (probably wrong — escalate)."
+  ],
+  "exit_strategy": {
+    "on_success": "Read back: new itinerary (flight numbers, dates, times, routing), confirmation number, total charged or refund amount + method + processing time. Thank the rep. Confirm email is coming.",
+    "on_failure": "Note exactly what was offered and what was refused. Thank the rep. Report back so the user can decide to call back, file a DOT complaint (US), or accept the loss.",
+    "follow_ups": [
+      "Email the user: new itinerary, confirmation number, refund / credit details, processing time.",
+      "Add the new flights to the user's calendar.",
+      "If a credit was issued, calendar the expiry date.",
+      "If a refund was promised, calendar a 14-day check that it actually arrived."
+    ]
+  },
+  "required_user_info": [
+    "Confirmation number (PNR) + passenger name as on the ticket",
+    "Loyalty number + status, if any",
+    "Original itinerary + desired new itinerary",
+    "Reason for the change (disruption, personal, etc)",
+    "Outcome preference: refund / credit / rebook (with max fare-difference if rebook)",
+    "Max fare difference the user will authorise without callback"
+  ],
+  "contributed_by": "AgenticMail core team"
+}

package/dist/skills/built-in/book-medical-appointment.json

@@ -0,0 +1,99 @@
+{
+  "id": "book-medical-appointment",
+  "name": "Book a Medical / Dental Appointment",
+  "version": "1.0.0",
+  "category": "medical-admin",
+  "tags": ["doctor", "dentist", "appointment", "scheduling", "insurance"],
+  "description": "Call a medical or dental office to book an appointment, verify they take the operator's insurance, capture the prep instructions, and confirm the time + location.",
+  "disclaimer": "I'm an AI assistant calling on behalf of [patient name]. I'm not a medical professional and cannot answer clinical questions — those will be addressed by the patient directly at the appointment.",
+  "context": {
+    "when_to_use": "User needs to book a routine appointment (cleaning, annual physical, follow-up visit, vaccination, etc). Not for symptom triage or emergencies — for those, the user should call directly or use the office's nurse line.",
+    "preconditions": [
+      "Patient's full name, date of birth, and insurance information (carrier + member ID + group number).",
+      "Reason for visit in plain language ('annual cleaning', 'follow-up on lab results', 'new-patient visit').",
+      "Date / time preferences with a flex window.",
+      "Existing patient or new patient? (Affects intake time required.)"
+    ],
+    "estimated_call_duration_minutes": 10
+  },
+  "principles": [
+    "Lead with the reason for visit and the patient's status (existing vs new). Front-desk staff route the call entirely based on those two facts.",
+    "Verify insurance BEFORE confirming the appointment. 'Do you take [carrier]?' is a free question; finding out at the appointment that they don't is expensive.",
+    "Get every detail in writing if possible — confirmation email, text message, or patient portal entry. Verbal-only confirmations are forgotten by reception.",
+    "Ask for prep instructions (fasting, paperwork, ID, insurance card) — these are easy to forget and embarrassing to discover at check-in.",
+    "Do NOT discuss symptoms or clinical details. You're an AI; the patient will discuss medical specifics at the appointment."
+  ],
+  "phrases": {
+    "open_disclaimer": "I'm an AI assistant calling on behalf of [patient name]. I'm not a medical professional, so I won't be able to discuss symptoms or clinical details — but I can handle scheduling.",
+    "opener_existing": "I'd like to book an appointment for [patient name] for [reason]. The date of birth on file is [DOB]. Existing patient.",
+    "opener_new": "I'd like to book a new-patient appointment for [patient name] for [reason]. They've never been seen at this practice.",
+    "verify_insurance": "Before we lock anything in — can you confirm you accept [insurance carrier], plan name [plan]? Member ID is [ID].",
+    "ask_prep": "What should the patient bring or do to prepare? Anything to bring (ID, insurance card, prior records)? Any fasting or medication restrictions?",
+    "ask_confirmation_method": "Will you send a text or email confirmation? What's the best way to confirm we're on the schedule?",
+    "request_callback_number": "And the best number to reach the patient if anything changes is [phone]. Could you note that on the file?",
+    "graceful_close_success": "Thank you so much. So we're set for [day] at [time] at [location] — and [prep summary]. Have a good day.",
+    "graceful_close_no_availability": "I understand. I'll talk to [patient name] and call back to look at later dates. Thanks for checking."
+  },
+  "tactics": [
+    {
+      "name": "Disclaimer + reason for visit + patient status",
+      "when": "First substantive turn.",
+      "script": "Lead with the disclaimer (`open_disclaimer`), then immediately give reason + existing/new status (`opener_existing` or `opener_new`). Saves the receptionist from extracting it.",
+      "priority": 1
+    },
+    {
+      "name": "Verify insurance before booking",
+      "when": "Receptionist offers a time slot.",
+      "script": "Use `verify_insurance` BEFORE accepting the slot. If they don't take the insurance, ask if they're in-network with any other carriers the patient might have, then exit politely if not."
+    },
+    {
+      "name": "Get prep instructions before hanging up",
+      "when": "Appointment is confirmed.",
+      "script": "Use `ask_prep`. Common items: photo ID, insurance card, list of medications, fasting (lab work), arrive 15 min early for paperwork (new patient)."
+    },
+    {
+      "name": "Get the confirmation method in writing",
+      "when": "Receptionist is wrapping up.",
+      "script": "Use `ask_confirmation_method`. Some offices use a portal, some text, some don't confirm at all (in which case set a reminder yourself)."
+    },
+    {
+      "name": "Read back the full appointment details",
+      "when": "Before ending the call.",
+      "script": "Patient's name + date + time + location + provider name + prep summary. Receptionists appreciate this — it catches their typos, not yours."
+    }
+  ],
+  "boundaries": [
+    "Do NOT discuss the patient's symptoms, medical history, or any clinical information. You're a scheduler, not a clinician.",
+    "Do NOT share the patient's full SSN, even if asked — DOB + insurance ID is enough for routine scheduling.",
+    "Do NOT commit to an appointment without verifying insurance (unless the patient is paying cash and the office is informed).",
+    "Do NOT book without explicit slot acceptance — if multiple slots are offered, pick the user-pre-stated preferred one; if none match, ask the user via `ask_operator`."
+  ],
+  "success_signals": [
+    "Office confirms insurance acceptance.",
+    "Office confirms appointment with a date, time, location, and provider name.",
+    "Office confirms a method for written confirmation."
+  ],
+  "failure_signals": [
+    "Office doesn't take the insurance.",
+    "Office has no availability in the user's window.",
+    "Office requires a referral the patient doesn't have."
+  ],
+  "exit_strategy": {
+    "on_success": "Read back date / time / location / provider / prep. Thank the receptionist. Set a calendar event for the patient.",
+    "on_failure": "Note the obstacle (no in-network, no availability, referral required). Thank the receptionist. Report back so the operator can pick a different provider or get the referral first.",
+    "follow_ups": [
+      "Email or message the operator: date, time, location, provider, prep list, confirmation number / portal entry.",
+      "Calendar the appointment.",
+      "Calendar a 24-hour reminder."
+    ]
+  },
+  "required_user_info": [
+    "Patient's full name + date of birth",
+    "Insurance carrier, member ID, group number, plan name",
+    "Reason for visit (plain language)",
+    "Existing patient or new patient",
+    "Date / time preferences + flex window",
+    "Best callback phone number for the patient"
+  ],
+  "contributed_by": "AgenticMail core team"
+}