@agenticmail/mcp 0.7.8 → 0.9.0

package/README.md

@@ -8,7 +8,33 @@ 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
+## ✨ 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
+  await call_agent({
+    target: 'vesper',
+    task: 'Audit row 34 of the YAML patch.',
+    outputSchema: {
+      type: 'object',
+      required: ['summary', 'findings', 'recommendation'],
+      properties: {
+        summary:        { type: 'string' },
+        findings:       { type: 'array', items: { type: 'string' } },
+        recommendation: { type: 'string', enum: ['proceed', 'block'] },
+      },
+    },
+  });
+  ```
+- **📥 `tail_worker(workerId, lines?)`** — paired with `check_activity`. When a worker shows up as long-running or stale, `tail_worker` returns the trailing N lines of its log (every tool call, result, and assistant chunk as a one-liner). Master-key only. Lives in the `multi_agent_extras` tier so it ships in the default toolbelt for hosts that delegate work.
+- **📊 `check_activity` shows live progress** — output now includes last tool used, tool-call count, duration in `Xh Ym Zs`, and a `stale` flag derived from heartbeat age. Workers are no longer auto-evicted from the registry; staleness is diagnostic.
+
+## ✨ Earlier — 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.

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.",
@@ -23322,14 +23355,15 @@ var toolDefinitions = [
   },
   {
     name: "call_agent",
-    description: `Synchronous RPC to delegate work to another AgenticMail agent. Pipeline: the task is queued in AgenticMail, the target agent processes it AS THEMSELVES (under their real identity, mailbox, persona, and audit trail), and the structured result returns into your call. THIS IS HOW MULTI-AGENT COORDINATION IS SUPPOSED TO WORK from any MCP host. Do not, instead, spawn one of your host's native sub-agents and tell it to "act as <target>" \u2014 that produces output under your identity, never touches the target's inbox, and skips their persona. Times out after the specified duration (default 180s, max 300s).`,
+    description: `Synchronous RPC to delegate work to another AgenticMail agent. Pipeline: the task is queued in AgenticMail, the target agent processes it AS THEMSELVES (under their real identity, mailbox, persona, and audit trail), and the structured result returns into your call. THIS IS HOW MULTI-AGENT COORDINATION IS SUPPOSED TO WORK from any MCP host. Do not, instead, spawn one of your host's native sub-agents and tell it to "act as <target>" \u2014 that produces output under your identity, never touches the target's inbox, and skips their persona. Pass outputSchema to require a structured deliverable shape: the API validates the worker's submit_result against the schema and rejects mismatches with validator errors, so the worker can retry with a correct shape rather than returning free-form prose. Times out after the specified duration (default 180s, max 300s).`,
     inputSchema: {
       type: "object",
       properties: {
         target: { type: "string", description: "Name of the agent to call" },
         task: { type: "string", description: "Task description" },
         payload: { type: "object", description: "Additional data" },
-        timeout: { type: "number", description: "Max seconds to wait (default: 180, max: 300)" }
+        timeout: { type: "number", description: "Max seconds to wait (default: 180, max: 300)" },
+        outputSchema: { type: "object", description: "Optional JSON Schema (draft-7 subset: type, required, properties, items, enum, additionalProperties, minLength/maxLength, minimum/maximum) describing the shape submit_result must conform to. The worker sees the schema in the wake prompt and the API validates on submission." }
       },
       required: ["target", "task"]
     }
@@ -24591,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;
@@ -24667,7 +24719,11 @@ ${r.tasks.map(
       const created = await apiRequest("POST", "/tasks/assign", {
         assignee: args2.target,
         taskType: "rpc",
-        payload: { task: args2.task, ...args2.payload || {} }
+        payload: { task: args2.task, ...args2.payload || {} },
+        // Pass outputSchema through verbatim. The API persists it
+        // and renders it into the worker's wake prompt; validation
+        // happens server-side on submit_result.
+        ...args2.outputSchema ? { outputSchema: args2.outputSchema } : {}
       });
       if (!created?.id) throw new Error("Failed to create task");
       const taskId = created.id;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agenticmail/mcp",
-  "version": "0.7.8",
+  "version": "0.9.0",
   "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.0"
   },
   "devDependencies": {
     "tsup": "^8.4.0",