@agenticmail/api 0.7.21 → 0.9.1

package/README.md

@@ -8,7 +8,14 @@ The API server for [AgenticMail](https://github.com/agenticmail/agenticmail) —
 
 This package runs a web server that handles everything: sending email and SMS, reading inboxes, managing agents, phone number access, real-time notifications, inter-agent messaging, spam filtering, outbound security scanning, and gateway configuration. Every feature in AgenticMail is accessible through this API.
 
-## ✨ What's new in 0.7.16
+## ✨ What's new in 0.9.0
+
+- **🧠 Agent-thread memory + thread-id resolver endpoints.** Agents persist their own per-thread judgment so the dispatcher can pre-load it into the next wake's prompt:
+  - `GET / POST / DELETE /agents/me/memory/threads/:t` — agent-key scoped; each agent only ever touches its own memory file.
+  - `GET /agents/me/thread-id?uid=42&folder=INBOX` — resolves the stable subject-only thread id for a message UID, looking up the canonical root via the dispatcher's ThreadCache when available.
+- **🎯 `wake` default flipped to "To: only".** `POST /mail/send`, `POST /drafts/:id/send`, `POST /templates/:id/send`, and the pending-outbound persistence path all derive the implicit allowlist from local recipients on the `To:` field when `wake` is omitted. CC'd local agents receive the mail without waking. New helper `deriveDefaultWakeList(to)` exported from `routes/mail.ts`. Opt back into the old behaviour with `wake: 'all'`.
+
+## ✨ Earlier — 0.7.16
 
 - **📐 Typed task contracts** — `POST /tasks/assign` and the long-poll `POST /tasks/rpc` accept an optional `outputSchema` field (JSON Schema, draft-7 subset). The schema is persisted on the task row via migration `014_task_output_schema.sql` and is rendered into the worker's wake prompt. `POST /tasks/:id/result` validates against the schema before accepting; mismatches return **400** with a flat `schemaErrors: [{ path, message }]` list. Validator lives at `src/lib/schema-validator.ts` (hand-rolled, no `ajv` dep) and supports `type`, `required`, `properties`, `items`, `enum`, `additionalProperties: false`, `minLength`/`maxLength`, `minimum`/`maximum`. Tasks without a schema keep the v0.8.x behaviour — fully back-compat.
 - **⭐ Star endpoint** — `POST /mail/messages/:uid/star` with `{ starred: boolean, folder?: string }`. Maps to IMAP's `\Flagged` flag — same on-disk bit Gmail's star uses.

package/dist/index.js

@@ -527,6 +527,19 @@ function createAccountRoutes(accountManager2, db, config) {
       next(err);
     }
   });
+  router.patch("/accounts/:id/wake-on-cc", requireMaster, async (req, res, next) => {
+    try {
+      const wakeOnCc = req.body?.wakeOnCc === false ? 0 : 1;
+      const result = db.prepare("UPDATE agents SET wake_on_cc = ? WHERE id = ?").run(wakeOnCc, req.params.id);
+      if (result.changes === 0) {
+        res.status(404).json({ error: "Agent not found" });
+        return;
+      }
+      res.json({ ok: true, wakeOnCc: wakeOnCc === 1 });
+    } catch (err) {
+      next(err);
+    }
+  });
   router.delete("/accounts/:id", requireMaster, async (req, res, next) => {
     try {
       const allAgents = await accountManager2.list();
@@ -903,7 +916,8 @@ function createFeatureRoutes(db, _accountManager, config, gatewayManager) {
         return;
       }
       const agent = req.agent;
-      const wakeList = normalizeWakeList(req.body?.wake);
+      const explicitWake = normalizeWakeList(req.body?.wake);
+      const wakeList = req.body?.wake === void 0 ? deriveDefaultWakeList(draft.to_addr) : explicitWake;
       const customHeaders = wakeHeaders(wakeList);
       let persistedAttachments;
       if (draft.attachments) {
@@ -1189,7 +1203,8 @@ function createFeatureRoutes(db, _accountManager, config, gatewayManager) {
         return;
       }
       const applyVars = (text, vars2) => text.replace(/\{\{(\w+)\}\}/g, (m, key) => vars2[key] ?? m);
-      const wakeList = normalizeWakeList(wake);
+      const explicitWake = normalizeWakeList(wake);
+      const wakeList = wake === void 0 ? deriveDefaultWakeList(to) : explicitWake;
       const customHeaders = wakeHeaders(wakeList);
       const vars = variables && typeof variables === "object" ? variables : {};
       const renderedSubject = applyVars(template.subject || "(no subject)", vars);
@@ -1799,13 +1814,29 @@ function normalizeMessageId(id) {
   if (!id) return "";
   return id.trim().replace(/^<+|>+$/g, "").toLowerCase();
 }
+var WAKE_ALL_SENTINEL = "__wake_all__";
 function normalizeWakeList(value) {
   if (value === void 0 || value === null) return void 0;
+  if (value === "all" || value === WAKE_ALL_SENTINEL) return void 0;
   const strip = (s) => s.trim().replace(/@localhost$/i, "").toLowerCase();
   if (Array.isArray(value)) return value.map((v) => strip(String(v))).filter(Boolean);
   if (typeof value === "string") return value.split(",").map(strip).filter(Boolean);
   return void 0;
 }
+function deriveDefaultWakeList(toField) {
+  if (!toField) return void 0;
+  const arr = Array.isArray(toField) ? toField : String(toField).split(",");
+  const localNames = [];
+  for (const raw of arr) {
+    const trimmed = String(raw).trim().toLowerCase();
+    const m = trimmed.match(/<([^>]+)>/);
+    const bare = (m ? m[1] : trimmed).trim();
+    if (!bare.endsWith("@localhost")) continue;
+    const name = bare.replace(/@localhost$/i, "");
+    if (name) localNames.push(name);
+  }
+  return localNames.length > 0 ? localNames : void 0;
+}
 function wakeHeaders(wakeList) {
   if (wakeList === void 0) return {};
   return { "X-AgenticMail-Wake": wakeList.join(", ") };
@@ -1821,15 +1852,25 @@ async function notifyLocalRecipientsOfNewMail(accountManager2, toField, ccField,
   push(ccField);
   push(bccField);
   const addrRe = /<([^>]+)>|([^\s,;<>]+@[^\s,;<>]+)/g;
-  const addresses = /* @__PURE__ */ new Set();
-  for (const entry of collected) {
-    let match;
-    addrRe.lastIndex = 0;
-    while ((match = addrRe.exec(entry)) !== null) {
-      const a = (match[1] || match[2] || "").trim().toLowerCase();
-      if (a) addresses.add(a);
-    }
+  function extractAddrs(v) {
+    if (!v) return [];
+    const items = Array.isArray(v) ? v : [v];
+    const out = /* @__PURE__ */ new Set();
+    for (const entry of items) {
+      let match;
+      addrRe.lastIndex = 0;
+      while ((match = addrRe.exec(entry)) !== null) {
+        const a = (match[1] || match[2] || "").trim().toLowerCase();
+        if (a) out.add(a);
+      }
+    }
+    return Array.from(out);
   }
+  const toAddrs = extractAddrs(toField);
+  const ccAddrs = extractAddrs(ccField);
+  const bccAddrs = extractAddrs(bccField);
+  const addresses = /* @__PURE__ */ new Set([...toAddrs, ...ccAddrs, ...bccAddrs]);
+  const toLocalNames = new Set(toAddrs.filter((a) => a.endsWith("@localhost")).map((a) => a.replace(/@localhost$/i, "")));
   const notified = /* @__PURE__ */ new Set();
   for (const addr of addresses) {
     const at = addr.indexOf("@");
@@ -1861,6 +1902,7 @@ async function notifyLocalRecipientsOfNewMail(accountManager2, toField, ccField,
         lookup = "failed";
       }
     }
+    const wasOnTo = toLocalNames.has(recipient.name.toLowerCase());
     pushEventToAgent(recipient.id, {
       type: "new",
       uid,
@@ -1876,7 +1918,11 @@ async function notifyLocalRecipientsOfNewMail(accountManager2, toField, ccField,
       // dispatcher reads this and spawns a Claude worker only for
       // recipients whose name is on the list (or for everyone if the
       // field is absent, preserving the v0.8.x default).
-      ...wakeList !== void 0 ? { wakeAllowlist: wakeList } : {}
+      ...wakeList !== void 0 ? { wakeAllowlist: wakeList } : {},
+      // Per-recipient "was I on To?" flag for wake_on_cc honoring.
+      // The dispatcher uses this combined with account.wakeOnCc to
+      // decide whether to skip a CC-only delivery.
+      wasOnTo
     });
   }
 }
@@ -1933,7 +1979,8 @@ function createMailRoutes(accountManager2, config, db, gatewayManager) {
           const pendingId = crypto.randomUUID();
           const ownerName2 = agent.metadata?.ownerName;
           const fromName2 = ownerName2 ? `${agent.name} from ${ownerName2}` : agent.name;
-          const wakeListForPersist = normalizeWakeList(wake);
+          const explicitWakeForPersist = normalizeWakeList(wake);
+          const wakeListForPersist = wake === void 0 ? deriveDefaultWakeList(to) : explicitWakeForPersist;
           const mailOptions = {
             to,
             subject,
@@ -2016,7 +2063,8 @@ function createMailRoutes(accountManager2, config, db, gatewayManager) {
       }
       const ownerName = agent.metadata?.ownerName;
       const fromName = ownerName ? `${agent.name} from ${ownerName}` : agent.name;
-      const wakeList = normalizeWakeList(wake);
+      const explicitWake = normalizeWakeList(wake);
+      const wakeList = wake === void 0 ? deriveDefaultWakeList(to) : explicitWake;
       const customHeaders = wakeHeaders(wakeList);
       const mailOpts = {
         to,
@@ -4882,7 +4930,7 @@ function createStorageRoutes(rawDb, accountManager2, config, dialect = "sqlite")
       const meta = await verifyAccess(agent, tableName, res);
       if (!meta) return;
       let imported = 0;
-      let skipped = 0;
+      let skipped2 = 0;
       for (const row of rows) {
         const keys = Object.keys(row);
         const vals = Object.values(row).map((v) => typeof v === "object" && v !== null ? JSON.stringify(v) : v);
@@ -4908,7 +4956,7 @@ function createStorageRoutes(rawDb, accountManager2, config, dialect = "sqlite")
           imported++;
         } catch (e) {
           if (onConflict === "skip") {
-            skipped++;
+            skipped2++;
             continue;
           }
           throw e;
@@ -4916,7 +4964,7 @@ function createStorageRoutes(rawDb, accountManager2, config, dialect = "sqlite")
       }
       const countResult = await db.get(`SELECT COUNT(*) as cnt FROM ${tableName}`);
       await db.run("UPDATE agenticmail_storage_meta SET row_count = ?, updated_at = " + nowExpr(dialect) + " WHERE table_name = ?", [countResult?.cnt || 0, tableName]);
-      res.json({ ok: true, imported, skipped, totalRows: countResult?.cnt || 0 });
+      res.json({ ok: true, imported, skipped: skipped2, totalRows: countResult?.cnt || 0 });
     } catch (err) {
       res.status(500).json({ error: err.message });
     }
@@ -5070,6 +5118,10 @@ function prune(nowMs) {
     recent.delete(first);
   }
 }
+var skipped = [];
+var SKIPPED_CAP = 100;
+var SKIPPED_TTL_MS = 5 * 60 * 1e3;
+var processState = null;
 function createDispatcherActivityRoutes() {
   const router = Router13();
   router.post("/dispatcher/worker-started", requireMaster, (req, res) => {
@@ -5117,7 +5169,8 @@ function createDispatcherActivityRoutes() {
       endedAtMs: nowMs,
       ok: body.ok === false ? false : true,
       resultPreview: typeof body.resultPreview === "string" ? body.resultPreview.slice(0, 240) : void 0,
-      turnCount: typeof body.turnCount === "number" ? body.turnCount : existing?.turnCount
+      turnCount: typeof body.turnCount === "number" ? body.turnCount : existing?.turnCount,
+      usage: typeof body.usage === "string" ? body.usage : existing?.usage
     };
     active.delete(body.workerId);
     recent.set(body.workerId, info);
@@ -5150,8 +5203,26 @@ function createDispatcherActivityRoutes() {
   router.get("/dispatcher/activity", requireMaster, (_req, res) => {
     const nowMs = Date.now();
     prune(nowMs);
+    while (skipped.length > 0 && nowMs - skipped[0].atMs > SKIPPED_TTL_MS) skipped.shift();
+    while (skipped.length > SKIPPED_CAP) skipped.shift();
+    const processHealth = (() => {
+      if (!processState) return { state: "missing" };
+      const age = nowMs - processState.atMs;
+      const isAlive = age <= 9e4;
+      return {
+        state: isAlive ? "alive" : "unhealthy",
+        startedAtMs: processState.startedAtMs,
+        uptimeMs: nowMs - processState.startedAtMs,
+        lastHeartbeatAgeMs: age,
+        channels: processState.channels,
+        coalesceQueueSize: processState.coalesceQueueSize,
+        running: processState.running,
+        maxConcurrent: processState.maxConcurrent
+      };
+    })();
     res.json({
       now: nowMs,
+      dispatcher: processHealth,
       active: Array.from(active.values()).map((w) => ({
         ...w,
         durationMs: nowMs - w.startedAtMs,
@@ -5161,8 +5232,51 @@ function createDispatcherActivityRoutes() {
       recent: Array.from(recent.values()).map((w) => ({
         ...w,
         durationMs: (w.endedAtMs ?? nowMs) - w.startedAtMs
-      }))
+      })),
+      // Recent skipped wakes — every filter decision the dispatcher
+      // made that DROPPED a wake. Surfaced so the host can see "the
+      // mail landed, the dispatcher saw it, here's why it skipped"
+      // instead of staring at silence.
+      skipped: skipped.map((s) => ({ ...s, ageMs: nowMs - s.atMs }))
+    });
+  });
+  router.post("/dispatcher/process-heartbeat", requireMaster, (req, res) => {
+    const body = req.body ?? {};
+    if (typeof body.startedAtMs !== "number") {
+      res.status(400).json({ error: "startedAtMs is required" });
+      return;
+    }
+    processState = {
+      startedAtMs: body.startedAtMs,
+      channels: typeof body.channels === "number" ? body.channels : 0,
+      coalesceQueueSize: typeof body.coalesceQueueSize === "number" ? body.coalesceQueueSize : 0,
+      running: typeof body.running === "number" ? body.running : 0,
+      maxConcurrent: typeof body.maxConcurrent === "number" ? body.maxConcurrent : 0,
+      atMs: Date.now()
+    };
+    res.json({ ok: true });
+  });
+  router.post("/dispatcher/worker-skipped", requireMaster, (req, res) => {
+    const body = req.body ?? {};
+    if (typeof body.agentName !== "string" || typeof body.reason !== "string") {
+      res.status(400).json({ error: "agentName and reason are required" });
+      return;
+    }
+    skipped.push({
+      agentId: typeof body.agentId === "string" ? body.agentId : void 0,
+      agentName: body.agentName,
+      uid: typeof body.uid === "number" ? body.uid : void 0,
+      subject: typeof body.subject === "string" ? body.subject : void 0,
+      from: typeof body.from === "string" ? body.from : void 0,
+      reason: body.reason,
+      detail: typeof body.detail === "string" ? body.detail : void 0,
+      atMs: Date.now()
     });
+    while (skipped.length > SKIPPED_CAP) skipped.shift();
+    res.json({ ok: true });
+  });
+  router.post("/dispatcher/worker-queued", requireMaster, (req, res) => {
+    res.json({ ok: true, recorded: req.body ?? null });
   });
   router.get("/dispatcher/worker-log/:workerId", requireMaster, (req, res) => {
     const rawId = String(req.params.workerId ?? "");
@@ -5196,6 +5310,91 @@ function createDispatcherActivityRoutes() {
   return router;
 }
 
+// src/routes/agent-memory.ts
+import { Router as Router14 } from "express";
+import {
+  AgentMemoryStore,
+  threadIdFor,
+  ThreadCache
+} from "@agenticmail/core";
+function createAgentMemoryRoutes(config) {
+  const router = Router14();
+  const memoryStore = new AgentMemoryStore();
+  const threadCache = new ThreadCache();
+  router.get("/agents/me/memory/threads/:t", requireAgent, async (req, res, next) => {
+    try {
+      const t = String(req.params.t);
+      const memory = memoryStore.read(req.agent.id, t);
+      if (!memory) {
+        res.status(404).json({ error: "No memory for this thread" });
+        return;
+      }
+      res.json(memory);
+    } catch (err) {
+      next(err);
+    }
+  });
+  router.post("/agents/me/memory/threads/:t", requireAgent, async (req, res, next) => {
+    try {
+      const t = String(req.params.t);
+      const { summary, commitments, openQuestions, lastAction, lastUid } = req.body ?? {};
+      if (!summary && !commitments && !openQuestions && !lastAction && lastUid === void 0) {
+        res.status(400).json({ error: "At least one field is required (summary, commitments, openQuestions, lastAction, or lastUid)" });
+        return;
+      }
+      memoryStore.write(req.agent.id, t, {
+        summary: typeof summary === "string" ? summary : void 0,
+        commitments: Array.isArray(commitments) ? commitments.map(String) : void 0,
+        openQuestions: Array.isArray(openQuestions) ? openQuestions.map(String) : void 0,
+        lastAction: typeof lastAction === "string" ? lastAction : void 0,
+        lastUid: typeof lastUid === "number" ? lastUid : void 0
+      });
+      res.json({ ok: true, threadId: t });
+    } catch (err) {
+      next(err);
+    }
+  });
+  router.delete("/agents/me/memory/threads/:t", requireAgent, async (req, res, next) => {
+    try {
+      memoryStore.delete(req.agent.id, String(req.params.t));
+      res.json({ ok: true });
+    } catch (err) {
+      next(err);
+    }
+  });
+  router.get("/agents/me/thread-id", requireAgent, async (req, res, next) => {
+    try {
+      const uid = parseInt(String(req.query.uid ?? ""), 10);
+      if (isNaN(uid) || uid < 1) {
+        res.status(400).json({ error: "uid query param is required" });
+        return;
+      }
+      const folder = req.query.folder || "INBOX";
+      const password = getAgentPassword(req.agent);
+      const receiver = await getReceiver(req.agent.stalwartPrincipal, password, config);
+      const envs = await receiver.listEnvelopes(folder, { limit: 1, offset: 0 });
+      const envelope = envs.find((e) => e.uid === uid) ?? (await receiver.listEnvelopes(folder, { limit: 200, offset: 0 })).find((e) => e.uid === uid);
+      if (!envelope) {
+        res.status(404).json({ error: `No message with UID ${uid} in folder ${folder}` });
+        return;
+      }
+      const subject = envelope.subject ?? "";
+      const senderAddr = envelope.from?.[0]?.address ?? "";
+      const provisional = threadIdFor({ subject, rootFromAddr: senderAddr });
+      const existing = threadCache.read(provisional);
+      if (existing) {
+        const canonical = threadIdFor({ subject, rootFromAddr: existing.rootFromAddr });
+        res.json({ threadId: canonical, rootFromAddr: existing.rootFromAddr, subject: existing.subject });
+        return;
+      }
+      res.json({ threadId: provisional, rootFromAddr: senderAddr, subject });
+    } catch (err) {
+      next(err);
+    }
+  });
+  return router;
+}
+
 // src/app.ts
 var integrationRouteFactoryPromise = (async () => {
   try {
@@ -5296,6 +5495,7 @@ function createApp(configOverrides) {
   app2.use("/api/agenticmail", createStorageRoutes(db, accountManager2, config));
   app2.use("/api/agenticmail", createSystemEventRoutes());
   app2.use("/api/agenticmail", createDispatcherActivityRoutes());
+  app2.use("/api/agenticmail", createAgentMemoryRoutes(config));
   app2.use("/api/agenticmail", (_req, res) => {
     res.status(404).json({ error: "Not found" });
   });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agenticmail/api",
-  "version": "0.7.21",
+  "version": "0.9.1",
   "description": "REST API server for AgenticMail — email and SMS endpoints for AI agents",
   "type": "module",
   "main": "dist/index.js",
@@ -28,7 +28,7 @@
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
-    "@agenticmail/core": "^0.7.0",
+    "@agenticmail/core": "^0.9.1",
     "cors": "^2.8.5",
     "dotenv": "^16.4.7",
     "express": "^4.21.0",
@@ -36,7 +36,7 @@
     "uuid": "^11.1.0"
   },
   "optionalDependencies": {
-    "@agenticmail/claudecode": "^0.1.0"
+    "@agenticmail/claudecode": "^0.2.1"
   },
   "devDependencies": {
     "@types/cors": "^2.8.17",

package/public/js/message-view.js

@@ -50,11 +50,22 @@ function renderMessage(msg) {
   if (!view) return;
   const fromAddr = msg.from?.[0]?.address ?? '?';
   const fromName = msg.from?.[0]?.name || fromAddr;
-  const toStr = (msg.to ?? []).map(a => a.name ? `${a.name} <${a.address}>` : a.address).join(', ') || '?';
-  const ccStr = (msg.cc ?? []).map(a => a.address).join(', ');
   const senderPseudo = { name: fromName };  // for avatar generation
   const bodyText = msg.text ?? stripHtml(msg.html ?? '');
 
+  // Build separate To / Cc / Bcc lines so the user can actually
+  // tell who was on the action list vs CC'd for awareness. The
+  // previous renderer concatenated everything onto one "to" line.
+  const formatAddr = (a) => a?.name && a.name !== a.address
+    ? `${a.name} <${a.address}>`
+    : (a?.address ?? '');
+  const renderAddrRow = (label, list, cls) => {
+    if (!Array.isArray(list) || list.length === 0) return '';
+    const rendered = list.map(formatAddr).filter(Boolean).map(escapeHtml).join(', ');
+    if (!rendered) return '';
+    return `<div class="message-recipient-row ${cls}"><span class="message-recipient-label">${label}</span><span class="message-recipient-list">${rendered}</span></div>`;
+  };
+
   const attachmentsHtml = (msg.attachments ?? []).length > 0
     ? `<div class="message-attachments">${msg.attachments.map((a, i) =>
         `<button class="message-attachment" data-att-index="${i}" data-att-filename="${escapeHtml(a.filename ?? 'attachment')}" title="Click to download">
@@ -75,7 +86,9 @@ function renderMessage(msg) {
             <span class="name">${escapeHtml(fromName)}</span>
             <span class="addr">&lt;${escapeHtml(fromAddr)}&gt;</span>
           </div>
-          <div class="message-to">to ${escapeHtml(toStr)}${ccStr ? `, cc ${escapeHtml(ccStr)}` : ''}</div>
+          ${renderAddrRow('To', msg.to, 'message-to')}
+          ${renderAddrRow('Cc', msg.cc, 'message-cc')}
+          ${renderAddrRow('Bcc', msg.bcc, 'message-bcc')}
         </div>
         <div class="message-date">${escapeHtml(formatDateFull(msg.date))}</div>
       </div>

package/public/styles.css

@@ -583,7 +583,28 @@ mark.search-hl {
 }
 .message-from .name { font-weight: 500; }
 .message-from .addr { color: var(--muted); margin-left: 4px; }
-.message-to { font-size: 12px; color: var(--muted); margin-top: 4px; }
+/* Recipient rows — one per field (To / Cc / Bcc). Renders only
+   when the field is non-empty. The label is a fixed-width tag
+   so the addresses align cleanly across the three rows. */
+.message-recipient-row {
+  display: flex; gap: 6px;
+  font-size: 12px; color: var(--muted);
+  margin-top: 4px;
+  line-height: 1.5;
+}
+.message-recipient-label {
+  flex: 0 0 28px;
+  font-weight: 600;
+  color: var(--ink-soft);
+  text-transform: none;
+}
+.message-recipient-list {
+  flex: 1 1 auto;
+  min-width: 0;
+  word-break: break-word;
+}
+.message-cc .message-recipient-label,
+.message-bcc .message-recipient-label { color: var(--muted); }
 .message-date {
   font-size: 12px; color: var(--muted);
   white-space: nowrap;