@agenticmail/mcp 0.7.7 → 0.7.9

package/README.md

@@ -8,6 +8,36 @@ 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
+
+- **📐 `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.
+- **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. */
@@ -23258,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: {
@@ -23305,14 +23322,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"]
     }
@@ -24574,6 +24592,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() : "";
@@ -24585,14 +24612,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) {
@@ -24631,7 +24668,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.7",
+  "version": "0.7.9",
   "mcpName": "io.github.agenticmail/mcp",
   "description": "MCP server for AgenticMail — give any AI client real email and SMS capabilities",
   "type": "module",