@agenticmail/mcp 0.7.4 → 0.7.7

package/dist/index.js

@@ -22395,6 +22395,12 @@ var TOOL_SETS = {
     // back. Essential enough that paying its tokens at every spawn beats
     // making the agent discover it via request_tools.
     "wait_for_email",
+    // check_activity is the dispatcher visibility primitive: see which
+    // agents the dispatcher has woken right now (or in the last 2 min)
+    // and how long they have been running. The host uses it to answer
+    // "did the agent I just emailed actually start working?" without
+    // having to wait for a reply or send an acknowledgment.
+    "check_activity",
     "check_tasks"
   ],
   /** Less-common mail operations. */
@@ -22609,7 +22615,7 @@ async function apiRequest(method, path, body, useMasterKey = false, timeoutMs =
 var toolDefinitions = [
   {
     name: "send_email",
-    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.",
+    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 \u2014 UNLESS you set `wake` to limit the wake-up to specific agents. Use `wake` aggressively on large threads: 15 agents on CC \xD7 every reply burns 15 Claude turns per round if every recipient wakes. Naming the single next actor cuts that to one. 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: {
@@ -22617,7 +22623,12 @@ var toolDefinitions = [
         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 \u2014 the team. Comma-separated, e.g. "vesper@localhost, orion@localhost". Every local @localhost recipient is auto-woken when this email lands.' },
+        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 UNLESS you also pass `wake` to restrict.' },
+        wake: {
+          type: "array",
+          items: { type: "string" },
+          description: 'Optional. Names (or @localhost addresses) of the agents the dispatcher should give a Claude turn to when this mail lands. CC\'d agents NOT in this list still receive the email but get no Claude turn \u2014 they will see it the next time someone explicitly wakes them or they check their inbox. Use this to scope cost on large threads: send to 15 agents but wake only the 1 or 2 who need to act next. Pass an empty array `[]` for "deliver silently \u2014 wake nobody". Omit entirely to keep the default "wake everyone CC\'d" behaviour.'
+        },
         inReplyTo: { type: "string", description: "Message-ID to reply to (optional)" },
         references: {
           type: "array",
@@ -22705,27 +22716,37 @@ 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. **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.",
+    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. **Pass `wake` to name only the next actor(s)** so the dispatcher gives a Claude turn only to them; everyone else still receives the mail but stays asleep. Outbound guard applies \u2014 HIGH severity content is held for review.",
     inputSchema: {
       type: "object",
       properties: {
         uid: { type: "number", description: "UID of the email to reply to" },
         text: { type: "string", description: "Your reply text" },
         html: { type: "string", description: "HTML reply (optional)" },
-        replyAll: { type: "boolean", description: "Reply to all recipients (default: false)" }
+        replyAll: { type: "boolean", description: "Reply to all recipients (default: false)" },
+        wake: {
+          type: "array",
+          items: { type: "string" },
+          description: "Optional. Names of the agents who should get a Claude turn from the dispatcher when this reply lands. CC'd agents NOT in this list still receive the email but stay asleep \u2014 saves significant tokens on large threads. Pass `[]` to deliver silently. Omit to wake everyone CC'd."
+        }
       },
       required: ["uid", "text"]
     }
   },
   {
     name: "forward_email",
-    description: "Forward an email to another recipient. Outbound guard applies \u2014 HIGH severity content is held for review.",
+    description: "Forward an email to another recipient. Outbound guard applies \u2014 HIGH severity content is held for review. Pass `wake` to limit which local recipients get a Claude turn from the dispatcher when this forward lands.",
     inputSchema: {
       type: "object",
       properties: {
         uid: { type: "number", description: "UID of the email to forward" },
         to: { type: "string", description: "Recipient to forward to" },
-        text: { type: "string", description: "Additional message (optional)" }
+        text: { type: "string", description: "Additional message (optional)" },
+        wake: {
+          type: "array",
+          items: { type: "string" },
+          description: "Optional. Names of the agents who should get a Claude turn when the forward lands. Pass `[]` to deliver silently. Omit to wake everyone CC'd."
+        }
       },
       required: ["uid", "to"]
     }
@@ -22826,7 +22847,7 @@ var toolDefinitions = [
   },
   {
     name: "manage_drafts",
-    description: "List, create, update, send, or delete drafts",
+    description: "List, create, update, send, or delete drafts. On send, you can pass `wake` to limit which local recipients get a Claude turn \u2014 same semantics as send_email.",
     inputSchema: {
       type: "object",
       properties: {
@@ -22834,7 +22855,12 @@ var toolDefinitions = [
         id: { type: "string", description: "Draft ID (for update/send/delete)" },
         to: { type: "string", description: "Recipient (for create/update)" },
         subject: { type: "string", description: "Subject (for create/update)" },
-        text: { type: "string", description: "Body text (for create/update)" }
+        text: { type: "string", description: "Body text (for create/update)" },
+        wake: {
+          type: "array",
+          items: { type: "string" },
+          description: "Optional, for action=send. Names of the agents who should get a Claude turn when the drafted mail lands. Pass `[]` to deliver silently. Omit to wake everyone CC'd."
+        }
       },
       required: ["action"]
     }
@@ -23191,7 +23217,12 @@ var toolDefinitions = [
         to: { type: "string", description: "Recipient email" },
         variables: { type: "object", description: 'Variables to substitute: { name: "Alice" }' },
         cc: { type: "string", description: "CC recipients" },
-        bcc: { type: "string", description: "BCC recipients" }
+        bcc: { type: "string", description: "BCC recipients" },
+        wake: {
+          type: "array",
+          items: { type: "string" },
+          description: "Optional. Names of the agents who should get a Claude turn when this template-rendered mail lands. Pass `[]` to deliver silently. Omit to wake everyone CC'd."
+        }
       },
       required: ["id", "to"]
     }
@@ -23227,6 +23258,17 @@ var toolDefinitions = [
       required: ["action"]
     }
   },
+  {
+    name: "check_activity",
+    description: "Check which agents are currently being woken by the dispatcher (right now or in the last 2 minutes). Use this when you sent mail to a teammate and want to know if they have actually started working, or to audit the live multi-agent state. Returns active workers with the agent name, what triggered the wake (mail UID + subject, or task id), how long they have been running, and a preview of the most recent finished work. Requires master key \u2014 the host session has it; subagents normally do not.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        agent: { type: "string", description: "Filter to a specific agent by name (case-insensitive). Omit to see every active and recently-finished worker." },
+        includeRecent: { type: "boolean", description: "Include workers that finished in the last ~2 minutes (default: true). Set false to see only currently-running workers." }
+      }
+    }
+  },
   {
     name: "check_tasks",
     description: "Check for pending tasks assigned to you (or a specific agent) or tasks you assigned to others",
@@ -23568,6 +23610,9 @@ async function dispatchToolCall(name, args2, useMaster) {
           ...a.encoding ? { encoding: a.encoding } : {}
         }));
       }
+      if (args2.wake !== void 0) {
+        sendBody.wake = args2.wake;
+      }
       const result = await apiRequest("POST", "/mail/send", sendBody);
       if (result?.blocked && result?.pendingId) {
         scheduleFollowUp(result.pendingId, String(args2.to), String(args2.subject || "(no subject)"), makePendingCheck(result.pendingId));
@@ -23701,6 +23746,9 @@ ${quotedBody}`;
         inReplyTo: original.messageId,
         references: refs
       };
+      if (args2.wake !== void 0) {
+        replySendBody.wake = args2.wake;
+      }
       const sendResult = await apiRequest("POST", "/mail/send", replySendBody);
       if (sendResult?.blocked && sendResult?.pendingId) {
         scheduleFollowUp(sendResult.pendingId, to, String(replySendBody.subject || "(no subject)"), makePendingCheck(sendResult.pendingId));
@@ -23749,6 +23797,9 @@ ${orig.text || ""}`;
           encoding: "base64"
         }));
       }
+      if (args2.wake !== void 0) {
+        fwdSendBody.wake = args2.wake;
+      }
       const fwdResult = await apiRequest("POST", "/mail/send", fwdSendBody);
       if (fwdResult?.blocked && fwdResult?.pendingId) {
         scheduleFollowUp(fwdResult.pendingId, String(args2.to), fwdSubject, makePendingCheck(fwdResult.pendingId));
@@ -23853,7 +23904,9 @@ ${lines.join("\n")}`;
       }
       if (args2.action === "send") {
         if (!args2.id) throw new Error("id is required");
-        const r = await apiRequest("POST", `/drafts/${args2.id}/send`);
+        const draftSendBody = {};
+        if (args2.wake !== void 0) draftSendBody.wake = args2.wake;
+        const r = await apiRequest("POST", `/drafts/${args2.id}/send`, draftSendBody);
         return `Draft sent. Message ID: ${r?.messageId ?? "unknown"}`;
       }
       if (args2.action === "delete") {
@@ -24459,12 +24512,14 @@ ${lines.join("\n\n---\n\n")}`;
 ${lines.join("\n")}`;
     }
     case "template_send": {
-      const result = await apiRequest("POST", `/templates/${args2.id}/send`, {
+      const templateBody = {
         to: args2.to,
         variables: args2.variables,
         cc: args2.cc,
         bcc: args2.bcc
-      });
+      };
+      if (args2.wake !== void 0) templateBody.wake = args2.wake;
+      const result = await apiRequest("POST", `/templates/${args2.id}/send`, templateBody);
       return `Template email sent. Message ID: ${result?.messageId ?? "unknown"}`;
     }
     case "manage_rules": {
@@ -24519,6 +24574,38 @@ ${r.agents.map(
       }
       throw new Error("Invalid action. Use: list_inactive, cleanup, or set_persistent");
     }
+    case "check_activity": {
+      const r = await apiRequest("GET", "/dispatcher/activity", void 0, true);
+      const filterAgent = typeof args2.agent === "string" ? args2.agent.toLowerCase() : "";
+      const includeRecent = args2.includeRecent !== false;
+      const matchesFilter = (w) => !filterAgent || (w.agentName ?? "").toLowerCase().includes(filterAgent);
+      const activeList = Array.isArray(r?.active) ? r.active.filter(matchesFilter) : [];
+      const recentList = includeRecent && Array.isArray(r?.recent) ? r.recent.filter(matchesFilter) : [];
+      if (activeList.length === 0 && recentList.length === 0) {
+        if (filterAgent) return `No dispatcher activity for "${args2.agent}" right now or in the last 2 minutes. Either the agent has not been woken on this thread yet, the dispatcher is not running, or mail to them is still in flight.`;
+        return "No dispatcher activity right now or in the last 2 minutes. If you just sent mail and expected an agent to wake, give it a moment \u2014 the dispatcher subscribes to /system/events for sub-second wake. If nothing happens for 30s, check that the dispatcher process is running (`pm2 list`) and that the recipient is a real local agent (`list_agents`).";
+      }
+      const fmt = (w, prefix) => {
+        const dur = w.durationMs ? `${(w.durationMs / 1e3).toFixed(1)}s` : "?";
+        const trig = w.trigger?.subject ? ` \u2014 ${String(w.trigger.subject).slice(0, 60)}` : w.trigger?.taskId ? ` \u2014 task ${String(w.trigger.taskId).slice(0, 8)}` : "";
+        const from = w.trigger?.from ? ` (from ${w.trigger.from})` : "";
+        const preview = w.resultPreview ? `
+      \u2192 ${String(w.resultPreview).slice(0, 140).replace(/\s+/g, " ").trim()}` : "";
+        const status = w.endedAtMs ? w.ok === false ? "failed" : "finished" : "running";
+        return `  ${prefix} ${w.agentName} [${w.kind}] ${status} ${dur}${trig}${from}${preview}`;
+      };
+      const lines = [];
+      if (activeList.length > 0) {
+        lines.push(`Active workers (${activeList.length}):`);
+        for (const w of activeList) lines.push(fmt(w, "\u25CF"));
+      }
+      if (recentList.length > 0) {
+        if (lines.length > 0) lines.push("");
+        lines.push(`Recently finished (last 2 min, ${recentList.length}):`);
+        for (const w of recentList) lines.push(fmt(w, "\u25CB"));
+      }
+      return lines.join("\n");
+    }
     case "check_tasks": {
       let endpoint = args2.direction === "outgoing" ? "/tasks/assigned" : "/tasks/pending";
       if (args2.direction !== "outgoing" && args2.assignee) {
@@ -25069,6 +25156,7 @@ var SERVER_INSTRUCTIONS = [
   '         to: "vesper@localhost",                         // primary owner of step 1',
   '         cc: "orion@localhost, claudecode@localhost",     // teammates + yourself',
   '         subject: "Build a small terminal game",',
+  '         wake: ["vesper"],                                // only Vesper gets a Claude turn',
   "         text: [",
   '           "Team \u2014",',
   '           "",',
@@ -25081,6 +25169,14 @@ var SERVER_INSTRUCTIONS = [
   '         ].join("\\n"),',
   "       })",
   "",
+  "   The `wake` parameter is the SINGLE BIGGEST TOKEN SAVER on large threads.",
+  "   Without it, every CC'd recipient burns one Claude turn deciding whether",
+  "   it is their turn. With it, only the named agents get a turn \u2014 the rest",
+  "   receive the mail in their inbox but stay asleep until you (or another",
+  "   agent) explicitly names them in a later `wake` list. Pass `wake: []`",
+  '   for "deliver silently \u2014 wake nobody". Omit `wake` entirely to keep the',
+  `   old "wake every CC'd agent" behaviour (backwards compatible).`,
+  "",
   "   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",
@@ -25100,7 +25196,15 @@ var SERVER_INSTRUCTIONS = [
   "   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',
+  "4. **Close the thread when work is complete.** Send a wrap-up reply",
+  "   with one of these markers in the subject: `[FINAL]`, `[DONE]`,",
+  "   `[CLOSED]`, or `[WRAP]`. The dispatcher honours those markers and",
+  "   stops waking workers on any further replies to that thread. Without",
+  "   this, the cascade can keep firing as agents critique each other's",
+  "   work even after the deliverables are in. Add the marker once, the",
+  "   thread is sealed.",
+  "",
+  '5. 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:",

package/package.json

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