@agenticmail/mcp 0.7.2 → 0.7.4

package/README.md

@@ -1,4 +1,8 @@
-# @agenticmail/mcp
+<p align="center">
+  <img src="https://raw.githubusercontent.com/agenticmail/agenticmail/main/docs/images/logo-200.png" alt="AgenticMail logo (pink bow)" width="180" />
+</p>
+
+<h1 align="center">@agenticmail/mcp</h1>
 
 The MCP (Model Context Protocol) server for [AgenticMail](https://github.com/agenticmail/agenticmail) — gives any MCP-compatible AI client full email and SMS capabilities.
 

package/dist/index.js

@@ -22383,11 +22383,18 @@ var TOOL_SETS = {
     "search_emails",
     "list_agents",
     "message_agent",
-    // call_agent is the headline coordination primitive: synchronous RPC
-    // to another AgenticMail agent that returns a structured result. It is
-    // the reason multi-agent setups exist on this platform and belongs in
-    // the pre-loaded toolset, not behind a request_tools indirection.
+    // call_agent is the one-shot RPC primitive — sync request, sync answer.
+    // Used when you need ONE structured result from ONE teammate; for
+    // multi-step coordination use the thread pattern (send_email with CC
+    // + reply_email with replyAll) instead.
     "call_agent",
+    // wait_for_email is the thread-coordination primitive: block until a
+    // specific reply lands in your inbox (filter by from / subject /
+    // inReplyTo / participants). The host uses it to wake on the next
+    // teammate reply; agents use it when they delegate and need an answer
+    // back. Essential enough that paying its tokens at every spawn beats
+    // making the agent discover it via request_tools.
+    "wait_for_email",
     "check_tasks"
   ],
   /** Less-common mail operations. */
@@ -22429,7 +22436,6 @@ var TOOL_SETS = {
   /** Agent coordination beyond the basics in `essential`. */
   agent_coord: [
     "check_messages",
-    "wait_for_email",
     "claim_task",
     "submit_result"
   ],
@@ -22603,15 +22609,15 @@ async function apiRequest(method, path, body, useMasterKey = false, timeoutMs =
 var toolDefinitions = [
   {
     name: "send_email",
-    description: "Send an email from the agent's mailbox. External emails are scanned for sensitive content. HIGH severity detections are BLOCKED and held for owner approval. Your owner will be notified and must approve blocked emails. You CANNOT bypass the outbound guard.",
+    description: "Send an email from the agent's mailbox. Supports multiple recipients on To and CC (comma-separated). This is the PRIMARY primitive for multi-agent coordination: kick off a thread with all participants on CC, and every local recipient is woken automatically. Each woken agent reads the thread, decides whose turn it is, and either reply-all's to contribute or stays silent. External emails are scanned for sensitive content; HIGH severity detections are BLOCKED for owner approval. You CANNOT bypass the outbound guard.",
     inputSchema: {
       type: "object",
       properties: {
-        to: { type: "string", description: "Recipient email address" },
+        to: { type: "string", description: "Recipient email address(es). For multi-agent threads, put the primary actor here and CC the rest. Comma-separated supported." },
         subject: { type: "string", description: "Email subject line" },
         text: { type: "string", description: "Plain text body" },
         html: { type: "string", description: "HTML body (optional)" },
-        cc: { type: "string", description: "CC recipients (optional)" },
+        cc: { type: "string", description: 'CC recipients \u2014 the team. Comma-separated, e.g. "vesper@localhost, orion@localhost". Every local @localhost recipient is auto-woken when this email lands.' },
         inReplyTo: { type: "string", description: "Message-ID to reply to (optional)" },
         references: {
           type: "array",
@@ -22699,7 +22705,7 @@ var toolDefinitions = [
   },
   {
     name: "reply_email",
-    description: "Reply to an email. Fetches the original message, auto-fills To, Subject (Re:), In-Reply-To, and References, then sends with quoted body. Outbound guard applies \u2014 HIGH severity content is held for review.",
+    description: "Reply to an email. Fetches the original message, auto-fills To, Subject (Re:), In-Reply-To, and References, then sends with quoted body. **For multi-agent thread coordination, pass `replyAll: true`** so every CC'd participant sees your contribution and stays in context \u2014 that is how the thread-as-workspace pattern works. Outbound guard applies \u2014 HIGH severity content is held for review.",
     inputSchema: {
       type: "object",
       properties: {
@@ -23133,11 +23139,20 @@ var toolDefinitions = [
   },
   {
     name: "wait_for_email",
-    description: "Wait for a new email or task notification using push notifications (SSE). Blocks until an email arrives, a task is assigned to you, or timeout is reached. Much more efficient than polling \u2014 use this when waiting for a reply or a task from another agent.",
+    description: 'Block until a matching email (or task) lands in your inbox. Push-based (SSE) \u2014 far more efficient than polling. Supports filtering by sender, subject substring, thread (In-Reply-To), or a participants list. The single-most-useful tool for thread-based coordination: send a kickoff email CC\'ing your team, then `wait_for_email({ subject: "<core thread subject>" })` to wake on the first reply. Non-matching events that arrive during the wait are ignored \u2014 you only resume when something you asked for shows up (or timeout).',
     inputSchema: {
       type: "object",
       properties: {
-        timeout: { type: "number", description: "Max seconds to wait (default: 120, max: 300)" }
+        timeout: { type: "number", description: "Max seconds to wait (default: 120, max: 300)" },
+        from: { type: "string", description: 'Only resume on an email FROM this address (case-insensitive substring match on the bare address \u2014 "orion" matches "orion@localhost").' },
+        subject: { type: "string", description: `Only resume on an email whose subject contains this string (case-insensitive). The thread's core subject works \u2014 "Build a small game" matches "Re: Build a small game".` },
+        inReplyTo: { type: "string", description: "Only resume on an email whose In-Reply-To header equals this Message-ID. Most precise thread filter \u2014 use when you have the exact Message-ID of the message you expect a reply to." },
+        participants: {
+          type: "array",
+          items: { type: "string" },
+          description: `Only resume on an email from ANY of these addresses (case-insensitive). Use this to wait for any teammate's reply, e.g. ["vesper@localhost", "orion@localhost"].`
+        },
+        includeTasks: { type: "boolean", description: "Include task-assignment events as matches (default: true). Set false if you only care about email." }
       }
     }
   },
@@ -24237,6 +24252,32 @@ ${lines.join("\n")}`;
     }
     case "wait_for_email": {
       const timeoutSec = Math.min(Math.max(Number(args2.timeout) || 120, 5), 300);
+      const includeTasks = args2.includeTasks !== false;
+      const fromFilter = typeof args2.from === "string" ? args2.from.trim().toLowerCase() : "";
+      const subjectFilter = typeof args2.subject === "string" ? args2.subject.trim().toLowerCase() : "";
+      const inReplyToFilter = typeof args2.inReplyTo === "string" ? args2.inReplyTo.trim() : "";
+      const participantsRaw = Array.isArray(args2.participants) ? args2.participants : [];
+      const participantsFilter = participantsRaw.filter((p) => typeof p === "string" && p.trim().length > 0).map((p) => p.trim().toLowerCase());
+      const hasAnyFilter = !!(fromFilter || subjectFilter || inReplyToFilter || participantsFilter.length);
+      const bareAddr = (s) => {
+        if (!s) return "";
+        const m = s.match(/<([^>]+)>/);
+        return (m ? m[1] : s).trim().toLowerCase();
+      };
+      const emailMatches = (email2) => {
+        if (!hasAnyFilter) return true;
+        const fromAddr = bareAddr(email2?.from?.[0]?.address ?? "");
+        const subj = String(email2?.subject ?? "").toLowerCase();
+        const ire = String(email2?.inReplyTo ?? "").trim();
+        if (fromFilter && !fromAddr.includes(fromFilter)) return false;
+        if (subjectFilter && !subj.includes(subjectFilter)) return false;
+        if (inReplyToFilter && ire !== inReplyToFilter) return false;
+        if (participantsFilter.length > 0) {
+          const ok = participantsFilter.some((p) => fromAddr.includes(p));
+          if (!ok) return false;
+        }
+        return true;
+      };
       const controller = new AbortController();
       const timer = setTimeout(() => controller.abort(), timeoutSec * 1e3);
       try {
@@ -24246,24 +24287,38 @@ ${lines.join("\n")}`;
         });
         if (!res.ok) {
           clearTimeout(timer);
-          const search = await apiRequest("POST", "/mail/search", { seen: false });
+          const searchBody = { seen: false };
+          if (fromFilter) searchBody.from = fromFilter;
+          if (subjectFilter) searchBody.subject = subjectFilter;
+          const search = await apiRequest("POST", "/mail/search", searchBody);
           const uids = search?.uids ?? [];
-          if (uids.length > 0) {
-            const email2 = await apiRequest("GET", `/mail/messages/${uids[0]}`);
+          for (const uid of [...uids].reverse()) {
+            const email2 = await apiRequest("GET", `/mail/messages/${uid}`);
+            if (!email2 || !emailMatches(email2)) continue;
+            const fromAddr = bareAddr(email2.from?.[0]?.address);
             return JSON.stringify({
               arrived: true,
               mode: "poll-fallback",
-              email: email2 ? {
-                uid: uids[0],
-                from: email2.from?.[0]?.address ?? "",
+              eventType: "email",
+              email: {
+                uid,
+                from: fromAddr,
+                fromName: email2.from?.[0]?.name ?? fromAddr,
                 subject: email2.subject ?? "(no subject)",
                 date: email2.date,
-                preview: (email2.text ?? "").slice(0, 300)
-              } : null,
+                preview: (email2.text ?? "").slice(0, 300),
+                messageId: email2.messageId,
+                inReplyTo: email2.inReplyTo,
+                isInterAgent: fromAddr.endsWith("@localhost")
+              },
               totalUnread: uids.length
             });
           }
-          return JSON.stringify({ arrived: false, reason: "SSE unavailable and no unread emails", timedOut: true });
+          return JSON.stringify({
+            arrived: false,
+            reason: hasAnyFilter ? "SSE unavailable and no unread emails match the filters" : "SSE unavailable and no unread emails",
+            timedOut: true
+          });
         }
         if (!res.body) {
           clearTimeout(timer);
@@ -24272,6 +24327,7 @@ ${lines.join("\n")}`;
         const reader = res.body.getReader();
         const decoder = new TextDecoder();
         let buffer = "";
+        let skipped = 0;
         try {
           while (true) {
             const { done, value } = await reader.read();
@@ -24282,54 +24338,65 @@ ${lines.join("\n")}`;
               const frame = buffer.slice(0, boundary);
               buffer = buffer.slice(boundary + 2);
               for (const line of frame.split("\n")) {
-                if (line.startsWith("data: ")) {
+                if (!line.startsWith("data: ")) continue;
+                let event;
+                try {
+                  event = JSON.parse(line.slice(6));
+                } catch {
+                  continue;
+                }
+                if (event.type === "task" && event.taskId) {
+                  if (!includeTasks || hasAnyFilter) {
+                    skipped++;
+                    continue;
+                  }
+                  clearTimeout(timer);
                   try {
-                    const event = JSON.parse(line.slice(6));
-                    if (event.type === "task" && event.taskId) {
-                      clearTimeout(timer);
-                      try {
-                        reader.cancel();
-                      } catch {
-                      }
-                      return JSON.stringify({
-                        arrived: true,
-                        mode: "push",
-                        eventType: "task",
-                        task: {
-                          taskId: event.taskId,
-                          taskType: event.taskType,
-                          description: event.task,
-                          from: event.from
-                        },
-                        hint: 'You have a new task. Use check_tasks(action="pending") to see and claim it.'
-                      });
-                    }
-                    if (event.type === "new" && event.uid) {
-                      clearTimeout(timer);
-                      try {
-                        reader.cancel();
-                      } catch {
-                      }
-                      const email2 = await apiRequest("GET", `/mail/messages/${event.uid}`);
-                      const fromAddr = email2?.from?.[0]?.address ?? "";
-                      return JSON.stringify({
-                        arrived: true,
-                        mode: "push",
-                        eventType: "email",
-                        email: email2 ? {
-                          uid: event.uid,
-                          from: fromAddr,
-                          fromName: email2.from?.[0]?.name ?? fromAddr,
-                          subject: email2.subject ?? "(no subject)",
-                          date: email2.date,
-                          preview: (email2.text ?? "").slice(0, 300),
-                          messageId: email2.messageId,
-                          isInterAgent: fromAddr.endsWith("@localhost")
-                        } : null
-                      });
-                    }
+                    reader.cancel();
+                  } catch {
+                  }
+                  return JSON.stringify({
+                    arrived: true,
+                    mode: "push",
+                    eventType: "task",
+                    task: {
+                      taskId: event.taskId,
+                      taskType: event.taskType,
+                      description: event.task,
+                      from: event.from
+                    },
+                    hint: 'You have a new task. Use check_tasks(action="pending") to see and claim it.'
+                  });
+                }
+                if (event.type === "new" && event.uid) {
+                  const email2 = await apiRequest("GET", `/mail/messages/${event.uid}`);
+                  if (!email2 || !emailMatches(email2)) {
+                    skipped++;
+                    continue;
+                  }
+                  clearTimeout(timer);
+                  try {
+                    reader.cancel();
                   } catch {
                   }
+                  const fromAddr = bareAddr(email2.from?.[0]?.address);
+                  return JSON.stringify({
+                    arrived: true,
+                    mode: "push",
+                    eventType: "email",
+                    skippedEvents: skipped,
+                    email: {
+                      uid: event.uid,
+                      from: fromAddr,
+                      fromName: email2.from?.[0]?.name ?? fromAddr,
+                      subject: email2.subject ?? "(no subject)",
+                      date: email2.date,
+                      preview: (email2.text ?? "").slice(0, 300),
+                      messageId: email2.messageId,
+                      inReplyTo: email2.inReplyTo,
+                      isInterAgent: fromAddr.endsWith("@localhost")
+                    }
+                  });
                 }
               }
             }
@@ -24341,11 +24408,20 @@ ${lines.join("\n")}`;
           }
         }
         clearTimeout(timer);
-        return JSON.stringify({ arrived: false, reason: "SSE connection closed", timedOut: false });
+        return JSON.stringify({ arrived: false, reason: "SSE connection closed", timedOut: false, skippedEvents: skipped });
       } catch (err) {
         clearTimeout(timer);
         if (err.name === "AbortError") {
-          return JSON.stringify({ arrived: false, reason: `No email received within ${timeoutSec}s`, timedOut: true });
+          return JSON.stringify({
+            arrived: false,
+            reason: hasAnyFilter ? `Timed out after ${timeoutSec}s \u2014 no matching email arrived (filters: ${[
+              fromFilter && `from~="${fromFilter}"`,
+              subjectFilter && `subject~="${subjectFilter}"`,
+              inReplyToFilter && `inReplyTo="${inReplyToFilter}"`,
+              participantsFilter.length && `participants=${JSON.stringify(participantsFilter)}`
+            ].filter(Boolean).join(", ")})` : `No email received within ${timeoutSec}s`,
+            timedOut: true
+          });
         }
         return JSON.stringify({ arrived: false, reason: err.message });
       }
@@ -24869,6 +24945,69 @@ ${lines.join("\n")}`;
 import { setTelemetryVersion } from "@agenticmail/core";
 import { createServer } from "http";
 import { randomUUID } from "crypto";
+
+// src/coerce.ts
+function coerceToArray(value, itemKind) {
+  if (Array.isArray(value)) return value;
+  if (typeof value !== "string") return value;
+  const trimmed = value.trim();
+  if (trimmed.startsWith("[")) {
+    try {
+      const parsed = JSON.parse(trimmed);
+      if (Array.isArray(parsed)) return parsed;
+    } catch {
+      return value;
+    }
+  }
+  if (itemKind === "number" || itemKind === "integer" || itemKind === "string") {
+    const parts = trimmed.split(",").map((s) => s.trim()).filter((s) => s.length > 0);
+    if (itemKind === "number" || itemKind === "integer") {
+      return parts.map((s) => {
+        const n = Number(s);
+        return Number.isNaN(n) ? s : n;
+      });
+    }
+    return parts;
+  }
+  return value;
+}
+function coerceToObject(value) {
+  if (value && typeof value === "object" && !Array.isArray(value)) return value;
+  if (typeof value !== "string") return value;
+  const trimmed = value.trim();
+  if (!trimmed.startsWith("{")) return value;
+  try {
+    const parsed = JSON.parse(trimmed);
+    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) return parsed;
+  } catch {
+  }
+  return value;
+}
+function coerceToNumber(value) {
+  if (typeof value === "number") return value;
+  if (typeof value === "string") {
+    const trimmed = value.trim();
+    if (trimmed === "") return value;
+    const n = Number(trimmed);
+    if (!Number.isNaN(n)) return n;
+  }
+  return value;
+}
+function coerceToBoolean(value) {
+  if (typeof value === "boolean") return value;
+  if (typeof value === "string") {
+    const v = value.trim().toLowerCase();
+    if (v === "true" || v === "yes" || v === "1") return true;
+    if (v === "false" || v === "no" || v === "0") return false;
+  }
+  if (typeof value === "number") {
+    if (value === 1) return true;
+    if (value === 0) return false;
+  }
+  return value;
+}
+
+// src/index.ts
 setTelemetryVersion("0.5.55");
 function jsonSchemaToZod(schema, topLevel = false) {
   if (!schema || typeof schema !== "object") return topLevel ? {} : external_exports.any();
@@ -24876,16 +25015,18 @@ function jsonSchemaToZod(schema, topLevel = false) {
   if (schema.type === "string") {
     result = schema.enum?.length ? external_exports.enum(schema.enum) : external_exports.string();
   } else if (schema.type === "number" || schema.type === "integer") {
-    result = external_exports.number();
+    result = external_exports.preprocess(coerceToNumber, external_exports.number());
   } else if (schema.type === "boolean") {
-    result = external_exports.boolean();
+    result = external_exports.preprocess(coerceToBoolean, external_exports.boolean());
   } else if (schema.type === "array") {
     const hasItems = !!schema.items && typeof schema.items === "object" && Object.keys(schema.items).length > 0;
-    result = external_exports.array(hasItems ? jsonSchemaToZod(schema.items, false) : external_exports.any());
+    const inner = external_exports.array(hasItems ? jsonSchemaToZod(schema.items, false) : external_exports.any());
+    const itemKind = schema.items?.type;
+    result = external_exports.preprocess((v) => coerceToArray(v, itemKind), inner);
   } else if (schema.type === "object") {
     if (!schema.properties || Object.keys(schema.properties).length === 0) {
       if (topLevel) return {};
-      result = external_exports.record(external_exports.string(), external_exports.any());
+      result = external_exports.preprocess(coerceToObject, external_exports.record(external_exports.string(), external_exports.any()));
     } else {
       const shape = {};
       const required2 = new Set(schema.required ?? []);
@@ -24895,7 +25036,7 @@ function jsonSchemaToZod(schema, topLevel = false) {
         shape[key] = child;
       }
       if (topLevel) return shape;
-      result = external_exports.object(shape);
+      result = external_exports.preprocess(coerceToObject, external_exports.object(shape));
     }
   } else {
     result = external_exports.any();
@@ -24905,57 +25046,107 @@ function jsonSchemaToZod(schema, topLevel = false) {
 var SERVER_INSTRUCTIONS = [
   "\u{1F380} AgenticMail \u2014 multi-agent email + SMS infrastructure.",
   "",
-  "AgenticMail agents are NOT prompts you wrap around your host's native",
-  "sub-agent tool. Each AgenticMail agent is a persistent identity with its",
-  "own inbox, API key, persona, and audit trail. Address other agents through",
-  "AgenticMail's own primitives below \u2014 never roleplay them inside your host.",
+  "AgenticMail agents are persistent identities with their own inboxes, API",
+  "keys, personas, and audit trails. They coordinate the way humans do: in",
+  "email threads, with every participant CC'd, taking turns implicitly from",
+  "context. Address other agents through AgenticMail's own primitives \u2014",
+  "never roleplay them inside your host's native sub-agent / sub-task tool.",
+  "",
+  "\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550",
+  "PREFERRED PATTERN: Single thread, CC everyone, agents take turns",
+  "\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550",
+  "",
+  "This is how a human boss coordinates a small team \u2014 and it is the right",
+  "pattern for multi-agent work. One email thread is the shared workspace.",
+  "",
+  "1. Decide who participates.",
+  "     \u2022 `list_agents()` \u2014 find existing identities",
+  "     \u2022 `create_account({ name, role, ... })` \u2014 spawn fresh ones",
+  "",
+  "2. Send ONE kickoff email with all participants on To / CC:",
+  "",
+  "       send_email({",
+  '         to: "vesper@localhost",                         // primary owner of step 1',
+  '         cc: "orion@localhost, claudecode@localhost",     // teammates + yourself',
+  '         subject: "Build a small terminal game",',
+  "         text: [",
+  '           "Team \u2014",',
+  '           "",',
+  '           "Vesper, please design a minimal terminal game (under ~80 LOC).",',
+  '           "Reply-all with the design doc when ready.",',
+  '           "",',
+  '           "Orion, once Vesper signs off, implement it and reply-all with the code.",',
+  '           "",',
+  '           "I (the host) will watch the thread and step in if needed.",',
+  '         ].join("\\n"),',
+  "       })",
+  "",
+  "   The mail server pushes a wake-up to every local recipient simultaneously.",
+  "   Each agent reads the thread, decides if it is THEIR turn, and either",
+  "   reply-all's to contribute or stays silent. Vesper goes first because she",
+  "   was named first; Orion stays silent until Vesper hands off; you (the",
+  "   host) see every reply land in your bridge inbox.",
+  "",
+  "3. Watch progress from the HOST session. The bridge inbox is yours to",
+  "   monitor \u2014 the dispatcher does NOT spawn an autonomous worker for the",
+  "   bridge (that would compete with you). Pick your monitoring style:",
+  "     \u2022 `wait_for_email({ timeout? })` \u2014 blocks the current turn (push-",
+  "         based, SSE-driven) until the next event lands in your inbox.",
+  '         Best when you want a single-shot "ping me when anything new',
+  '         arrives". Pair with `read_email` afterwards.',
+  "     \u2022 `list_inbox()` + `read_email({ uid })` \u2014 explicit poll. Best when",
+  "         the user is actively driving the conversation turn-by-turn.",
+  "     \u2022 `search_emails({ subject })` \u2014 load the full thread at any point.",
+  "   To unblock a stuck agent or change direction, just reply-all into the",
+  "   same thread.",
+  "",
+  '4. Done when the last hand-off (or an explicit "complete" message) lands',
+  "   in your inbox. Show the result to the user.",
+  "",
+  "Why this is right:",
+  "  \u2022 Every agent has FULL context every time they wake (they read the thread).",
+  "  \u2022 Turn-taking is implicit; no scheduler, no RPC ceremony.",
+  "  \u2022 The thread is searchable history. The host (you) sees everything.",
+  "  \u2022 Bringing in another teammate later is just adding them to CC.",
+  "",
+  "\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550",
+  "When to use one-shot RPC instead",
+  "\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550",
   "",
-  "How to coordinate work between agents \u2014 the right way:",
+  "`call_agent({ target, task, timeout? })` is still the right tool when:",
+  "  \u2022 You need ONE structured answer from ONE agent and no multi-step work.",
+  "  \u2022 You need the result inline in your current call (not async).",
+  '  \u2022 The work is short and there is no useful "thread" to share.',
   "",
-  "1. List or create the agents you need (`list_agents`, `create_account`).",
-  "2. Send them work using ONE of:",
-  "     \u2022 `call_agent({ target, task, payload?, timeout? })` \u2014 SYNCHRONOUS RPC.",
-  "         Fires a structured task at the target agent and waits for their",
-  "         result. The target processes the task as themselves (under their",
-  "         own identity and mailbox) and the structured result returns into",
-  "         your call. Use this when you need an answer back.",
-  '     \u2022 `send_email({ to: "<name>@localhost", ... })` or',
-  "       `message_agent({ agent, subject, text })` \u2014 ASYNCHRONOUS.",
-  "         Mail lands in their inbox; they process it on their own schedule",
-  "         and may reply by email. Use this for fire-and-forget handoffs.",
-  "3. Read replies with `list_inbox` + `read_email`, or `search_emails`.",
+  "For multi-step / multi-agent coordination \u2014 use the thread pattern above.",
+  "For fire-and-forget handoffs to a single agent \u2014 `message_agent` is fine.",
   "",
-  "What NOT to do (regardless of host \u2014 Claude Code, ChatGPT, Cursor, Grok, \u2026):",
+  "\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550",
+  "What NOT to do (regardless of host \u2014 Claude Code, ChatGPT, Cursor, Grok)",
+  "\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550",
   "",
-  "\u2717 Do NOT spawn a native sub-agent / sub-task / parallel-thinking tool of",
-  '  your host and instruct it to "act as Lyra" / "write as Orion". That',
-  "  produces output under YOUR identity, never reaches the named agent's",
-  "  inbox, and bypasses their persona, signatures, outbound guard, and",
-  "  audit trail. The real agent has not actually thought anything.",
+  "\u2717 Do NOT spawn a native sub-agent / sub-task tool of your host and tell",
+  '  it to "act as Vesper" / "write as Orion". That produces output under',
+  "  YOUR identity, never reaches the named agent's inbox, and bypasses",
+  "  their persona, signatures, outbound guard, and audit trail.",
   "\u2717 Do NOT compose an agent's reply yourself in the host session and then",
-  "  `send_email` it on their behalf. Let `call_agent` (or an email handoff)",
-  "  produce the reply from the real agent.",
+  "  `send_email` it on their behalf. Let the real agent reply from their",
+  "  own mailbox (via the thread pattern, or via call_agent for RPC).",
   '\u2717 Do NOT pass `_account: "<other-agent>"` to act AS another agent. That',
-  "  falsifies the From: header. Use `call_agent` to delegate instead.",
+  "  falsifies the From: header.",
+  '\u2717 Do NOT serialise the work yourself ("first I call_agent Vesper, get her',
+  '  result, then I call_agent Orion with her result"). That works but it',
+  "  is fragile, slow, and burns one full Claude turn per hop. The thread",
+  "  pattern lets the agents drive their own handoffs.",
   "",
-  "How the wake-up actually happens (host-dependent \u2014 best-effort):",
-  "  - With the Claude Code integration installed, a dispatcher daemon",
-  "    auto-wakes the target agent as a Claude Code subagent when mail",
-  "    arrives or `call_agent` fires.",
-  "  - With other MCP hosts (no dispatcher), `send_email` / `message_agent`",
-  "    still deliver the mail; a human or another scheduled process picks",
-  "    it up later. `call_agent` will still queue the task and return its",
-  "    result once any worker (yourself, a cron, another agent) processes",
-  "    it \u2014 see `check_tasks` / `claim_task` / `submit_result`.",
-  "  Either way, the RIGHT primitives from your side are the same:",
-  "  call_agent / send_email / message_agent. Never roleplay.",
+  "\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550",
+  "Identity (`_account`) & tool surface",
+  "\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550",
   "",
-  "Identity & `_account`:",
-  '  Every tool call accepts an optional `_account: "<your-agent-name>"` to',
-  "  scope the call to a specific agent. From the HOST session, omit it to",
-  "  use bridge identity, or pass it to read/write a specific agent's",
-  "  mailbox directly. From inside an agent's own context, ALWAYS pass",
-  '  `_account: "<self>"`.',
+  'Every tool call accepts optional `_account: "<agent-name>"` to scope the',
+  "call to a specific identity. From the host, omit it to use the bridge",
+  "identity, or pass it to read/write a specific agent's mailbox directly.",
+  'From inside an agent\'s own context, ALWAYS pass `_account: "<self>"`.',
   "",
   "Tool surface: ~62 tools across email, SMS, contacts, drafts, templates,",
   "rules, tags, search, scheduling, RPC. Only ~10 are pre-loaded; the rest",
@@ -24965,7 +25156,7 @@ function createMcpServer() {
   const server = new McpServer(
     {
       name: "\u{1F380} AgenticMail",
-      version: "0.2.29",
+      version: "0.2.30",
       description: "\u{1F380} AgenticMail \u2014 Email infrastructure for AI agents. By Ope Olatunji (https://github.com/agenticmail/agenticmail)"
     },
     { instructions: SERVER_INSTRUCTIONS }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agenticmail/mcp",
-  "version": "0.7.2",
+  "version": "0.7.4",
   "mcpName": "io.github.agenticmail/mcp",
   "description": "MCP server for AgenticMail — give any AI client real email and SMS capabilities",
   "type": "module",