@agenticmail/mcp 0.7.9 → 0.9.1

package/README.md

@@ -8,7 +8,12 @@ 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.9
+## ✨ What's new in 0.9.0
+
+- **🧠 `get_thread_id` + `save_thread_memory`** — two new tools in the `multi_agent_extras` tier. Workers call `get_thread_id({uid})` once after reading a new message, then `save_thread_memory({threadId, summary, commitments?, openQuestions?, lastAction?, lastUid?})` at end-of-wake. The dispatcher reads the memory back into the next wake's prompt automatically. Pairs with the dispatcher-side ThreadCache to flatten wake cost — agents no longer have to re-read 10 prior messages every time.
+- **🎯 `send_email` / `reply_email` / `forward_email` / `template_send` docs updated** for the new `wake` defaults. CC'd local agents no longer wake by default; `wake: 'all'` opts back into the pre-0.9.0 behaviour.
+
+## ✨ Earlier — 0.7.9
 
 - **📐 `call_agent` accepts `outputSchema`** — pass a JSON Schema (draft-7 subset) describing the deliverable shape and the API validates `submit_result` against it; mismatches come back as validator errors so the worker can retry with a correct shape instead of returning free-form prose. The schema is rendered into the worker's wake prompt up-front. Example:
   ```js

package/dist/index.js

@@ -22406,6 +22406,13 @@ var TOOL_SETS = {
     // 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",
+    // Wake-context memory tools. Agents call get_thread_id once when
+    // they read a message to find the stable thread id, then
+    // save_thread_memory at end-of-wake to persist their judgment.
+    // The dispatcher reads both back into the next wake's prompt so
+    // the agent doesn't re-read prior messages from scratch.
+    "get_thread_id",
+    "save_thread_memory",
     "check_tasks"
   ],
   /** Less-common mail operations. */
@@ -22620,7 +22627,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 \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.",
+    description: 'Send an email from the agent\'s mailbox. Supports multiple recipients on To and CC (comma-separated). The PRIMARY primitive for multi-agent coordination. WAKE SEMANTICS (changed in 0.9.0): by default only local @localhost recipients on `To:` get a Claude wake; CC\'d local agents receive the mail but don\'t wake \u2014 they see it on their next natural wake (replies addressed to them, or a future inbox check). This mirrors the email convention "To is for action, CC is for awareness" and prevents wake-thrash on multi-CC threads. To override: pass `wake: ["alice","bob"]` to wake specific agents regardless of To/CC position, or `wake: "all"` to opt back into the pre-0.9.0 "wake every CC\'d recipient" behaviour. Pass `wake: []` to deliver silently with no wakes at all. External emails are scanned for sensitive content; HIGH severity detections are BLOCKED for owner approval.',
     inputSchema: {
       type: "object",
       properties: {
@@ -22628,11 +22635,9 @@ 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 UNLESS you also pass `wake` to restrict.' },
+        cc: { type: "string", description: 'CC recipients \u2014 the team. Comma-separated, e.g. "vesper@localhost, orion@localhost". CC\'d local recipients receive the mail but DO NOT wake by default (0.9.0+). Put the actor on `to`; CC the rest for awareness.' },
         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.'
+          description: 'Optional wake-control. Accepts: (1) an array of agent names \u2014 `["alice","bob"]` \u2014 to wake exactly those agents (overrides default To-only behaviour); (2) the string `"all"` to wake every local recipient on To and CC (pre-0.9.0 behaviour); (3) an empty array `[]` to deliver silently with no wakes; (4) omit entirely to use the default \u2014 wake local recipients on `To:` only. CC\'d recipients NOT in the wake list still receive the mail in their inbox and will see it when they next wake naturally.'
         },
         inReplyTo: { type: "string", description: "Message-ID to reply to (optional)" },
         references: {
@@ -23263,6 +23268,34 @@ var toolDefinitions = [
       required: ["action"]
     }
   },
+  {
+    name: "save_thread_memory",
+    description: "Persist a one-paragraph memory of where THIS agent stands on the given thread. Called at the end of every wake \u2014 Claude Code reads it back into the next wake's prompt so the agent doesn't re-derive context from scratch by re-reading 10 prior messages. Pass `threadId` from `get_thread_id`. Fields are a snapshot: summary (where the thread stands), commitments (what you committed to), openQuestions (what you are blocked on), lastAction (what you just did), lastUid (newest UID you have digested). The file overwrites; you do not need to merge with the previous version \u2014 the dispatcher reads only the most recent write.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        threadId: { type: "string", description: "Stable thread id from get_thread_id. Required." },
+        summary: { type: "string", description: "One-paragraph narrative of where the thread stands." },
+        commitments: { type: "array", items: { type: "string" }, description: "Things you have committed to doing on this thread." },
+        openQuestions: { type: "array", items: { type: "string" }, description: "Things you are waiting on / open questions." },
+        lastAction: { type: "string", description: 'The last action you took on the thread (e.g. "replied UID 41 asking for raw counts").' },
+        lastUid: { type: "number", description: "Newest message UID you have digested into this memory." }
+      },
+      required: ["threadId"]
+    }
+  },
+  {
+    name: "get_thread_id",
+    description: "Resolve the stable thread id for a message UID. Use this BEFORE calling save_thread_memory or when you want to inspect the cache for a thread. Pass the UID of any message on the thread (root or reply) \u2014 the API normalises the subject, resolves the canonical root sender, and returns the same id every time. `folder` defaults to INBOX.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        uid: { type: "number", description: "Message UID." },
+        folder: { type: "string", description: "IMAP folder where the UID lives. Defaults to INBOX." }
+      },
+      required: ["uid"]
+    }
+  },
   {
     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.",
@@ -24592,6 +24625,24 @@ ${r.agents.map(
       }
       throw new Error("Invalid action. Use: list_inactive, cleanup, or set_persistent");
     }
+    case "save_thread_memory": {
+      if (!args2.threadId) throw new Error("threadId is required (call get_thread_id first)");
+      const body = {};
+      if (typeof args2.summary === "string") body.summary = args2.summary;
+      if (Array.isArray(args2.commitments)) body.commitments = args2.commitments;
+      if (Array.isArray(args2.openQuestions)) body.openQuestions = args2.openQuestions;
+      if (typeof args2.lastAction === "string") body.lastAction = args2.lastAction;
+      if (typeof args2.lastUid === "number") body.lastUid = args2.lastUid;
+      await apiRequest("POST", `/agents/me/memory/threads/${encodeURIComponent(String(args2.threadId))}`, body);
+      return `Memory saved for thread ${args2.threadId}.`;
+    }
+    case "get_thread_id": {
+      if (typeof args2.uid !== "number" || args2.uid < 1) throw new Error("uid (number, \u22651) is required");
+      const folder = typeof args2.folder === "string" ? args2.folder : "INBOX";
+      const r = await apiRequest("GET", `/agents/me/thread-id?uid=${args2.uid}&folder=${encodeURIComponent(folder)}`);
+      if (!r?.threadId) throw new Error("Failed to resolve thread id");
+      return `Thread ${r.threadId} (subject "${r.subject}", root from ${r.rootFromAddr}).`;
+    }
     case "tail_worker": {
       if (!args2.workerId) throw new Error("workerId is required");
       const lines = typeof args2.lines === "number" ? args2.lines : 80;
@@ -24623,13 +24674,15 @@ ${r.tail.join("\n")}`;
         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 usage = w.usage ? `
+      \u26A1 ${String(w.usage)}` : "";
         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}`;
+        return `  ${prefix} ${w.agentName} [${w.kind}] ${status} ${dur}${turns}${tool}${trig}${from}${preview}${usage}${idHint}`;
       };
       const lines = [];
       if (activeList.length > 0) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agenticmail/mcp",
-  "version": "0.7.9",
+  "version": "0.9.1",
   "mcpName": "io.github.agenticmail/mcp",
   "description": "MCP server for AgenticMail — give any AI client real email and SMS capabilities",
   "type": "module",
@@ -30,7 +30,7 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.12.0",
     "zod": "^3.24.0",
-    "@agenticmail/core": "^0.7.0"
+    "@agenticmail/core": "^0.9.1"
   },
   "devDependencies": {
     "tsup": "^8.4.0",