@agenticmail/mcp 0.7.5 → 0.7.8

package/README.md

@@ -8,6 +8,15 @@ The MCP (Model Context Protocol) server for [AgenticMail](https://github.com/age
 
 When connected, your AI agent can send emails and texts, check inboxes, reply to messages, receive verification codes, manage contacts, schedule emails, assign tasks to other agents, and more — all through natural language. The server provides 62 tools that cover every email, SMS, and agent management operation.
 
+## ✨ What's new in 0.7.7
+
+- **`wake` parameter on every send tool** — `send_email`, `reply_email`, `forward_email`, `template_send`, `manage_drafts(send)` all accept `wake: ["alice", "bob"]` (or comma-separated string). The dispatcher gives a Claude turn only to listed agents; the rest still receive the mail but stay asleep. Single biggest token saver on multi-agent threads.
+- **`check_activity` tool** (in the `essential` set) — see which agents the dispatcher has woken right now, what they're working on, how long they've been running, plus a preview of recently-finished work. Answers "did the agent I just emailed actually start working?" without waiting for a reply.
+- **Thread-close markers** — put `[FINAL]`, `[DONE]`, `[CLOSED]`, or `[WRAP]` in a subject to tell the dispatcher this thread is sealed; no more wakes on any reply to it. The wake prompt teaches agents to add these markers when they sign off the work.
+- **LLM-tolerant input coercion** — `batch_mark_read({ uids: "[1,2,3,4]" })`, `wait_for_email({ timeout: "120" })`, `manage_drafts({ where: '{"id":"abc"}' })`, `manage_pending({ allowSensitive: "true" })` all now just work. Strings get parsed before zod validates. No more "expected array, received string" retries.
+- **Server `instructions` field** sent on `initialize` — every connecting MCP client (Claude Code, ChatGPT, Cursor, Grok…) gets the coordination protocol in context before they touch any tool. Provider-agnostic.
+- **`wait_for_email` filters** — block on a specific reply, not just "any new event". Supports `from`, `subject`, `inReplyTo`, `participants`, `includeTasks`.
+
 ## Install
 
 ```bash

package/dist/index.js

@@ -22401,6 +22401,11 @@ var TOOL_SETS = {
     // "did the agent I just emailed actually start working?" without
     // having to wait for a reply or send an acknowledgment.
     "check_activity",
+    // tail_worker complements check_activity: when a worker has been
+    // running a long time or shows up as stale, tail_worker gives you
+    // the running log of what it actually did — every tool call, every
+    // result. Paired with check_activity so they ship in the same tier.
+    "tail_worker",
     "check_tasks"
   ],
   /** Less-common mail operations. */
@@ -22615,7 +22620,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: {
@@ -22623,7 +22628,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",
@@ -22711,27 +22721,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"]
     }
@@ -22832,7 +22852,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: {
@@ -22840,7 +22860,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"]
     }
@@ -23197,7 +23222,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"]
     }
@@ -23233,9 +23263,21 @@ var toolDefinitions = [
       required: ["action"]
     }
   },
+  {
+    name: "tail_worker",
+    description: "Tail the log of a running (or recently-finished) dispatcher worker. Use this when check_activity shows a worker has been running a long time or is marked stale, and you want to see what it is actually doing \u2014 every tool call, tool result, and assistant chunk is logged as a one-liner. Returns the last N lines (default 80). The workerId comes from check_activity output. Requires master key.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        workerId: { type: "string", description: "Worker id from check_activity output." },
+        lines: { type: "number", description: "How many trailing log lines to return. Default 80, max 1000." }
+      },
+      required: ["workerId"]
+    }
+  },
   {
     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.",
+    description: "Check which agents are currently being woken by the dispatcher. 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, the most recent tool they invoked, how many tool calls they have made, a `stale` flag (true if the dispatcher has not heartbeated in 90s+), and a preview of recently-finished work. Workers may run for hours \u2014 there is no auto-eviction; staleness is just a hint. Requires master key.",
     inputSchema: {
       type: "object",
       properties: {
@@ -23585,6 +23627,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));
@@ -23718,6 +23763,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));
@@ -23766,6 +23814,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));
@@ -23870,7 +23921,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") {
@@ -24476,12 +24529,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": {
@@ -24536,6 +24591,15 @@ ${r.agents.map(
       }
       throw new Error("Invalid action. Use: list_inactive, cleanup, or set_persistent");
     }
+    case "tail_worker": {
+      if (!args2.workerId) throw new Error("workerId is required");
+      const lines = typeof args2.lines === "number" ? args2.lines : 80;
+      const r = await apiRequest("GET", `/dispatcher/worker-log/${encodeURIComponent(String(args2.workerId))}?lines=${lines}`, void 0, true);
+      if (!r?.tail || !Array.isArray(r.tail)) return `No log found for worker ${args2.workerId}.`;
+      if (r.tail.length === 0) return `Worker ${args2.workerId} has no log entries yet.`;
+      return `Worker ${args2.workerId} log (last ${r.lines} of ${r.bytes} bytes):
+${r.tail.join("\n")}`;
+    }
     case "check_activity": {
       const r = await apiRequest("GET", "/dispatcher/activity", void 0, true);
       const filterAgent = typeof args2.agent === "string" ? args2.agent.toLowerCase() : "";
@@ -24547,14 +24611,24 @@ ${r.agents.map(
         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 fmtDur = (ms) => {
+        if (ms < 6e4) return `${(ms / 1e3).toFixed(1)}s`;
+        if (ms < 36e5) return `${Math.floor(ms / 6e4)}m${Math.floor(ms % 6e4 / 1e3)}s`;
+        return `${Math.floor(ms / 36e5)}h${Math.floor(ms % 36e5 / 6e4)}m`;
+      };
       const fmt = (w, prefix) => {
-        const dur = w.durationMs ? `${(w.durationMs / 1e3).toFixed(1)}s` : "?";
+        const dur = w.durationMs ? fmtDur(w.durationMs) : "?";
         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}`;
+        let status = w.endedAtMs ? w.ok === false ? "failed" : "finished" : "running";
+        if (!w.endedAtMs && w.stale) status = "running (stale heartbeat)";
+        const turns = !w.endedAtMs && typeof w.turnCount === "number" ? ` \xB7 ${w.turnCount} tool calls` : "";
+        const tool = !w.endedAtMs && w.lastTool ? ` \xB7 last tool: ${w.lastTool}` : "";
+        const idHint = !w.endedAtMs ? `
+      id: ${w.workerId}  (use tail_worker for the log)` : "";
+        return `  ${prefix} ${w.agentName} [${w.kind}] ${status} ${dur}${turns}${tool}${trig}${from}${preview}${idHint}`;
       };
       const lines = [];
       if (activeList.length > 0) {
@@ -25118,6 +25192,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",',
   '           "",',
@@ -25130,6 +25205,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",
@@ -25149,7 +25232,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.5",
+  "version": "0.7.8",
   "mcpName": "io.github.agenticmail/mcp",
   "description": "MCP server for AgenticMail — give any AI client real email and SMS capabilities",
   "type": "module",