@agenticmail/api 0.9.27 → 0.9.28

package/README.md

@@ -408,6 +408,17 @@ JSON parse errors (malformed request bodies) return a clear 400 error rather tha
 
 ---
 
+## External inbox exposure — what `/gateway/relay` actually opens up
+
+> **The `POST /gateway/relay` endpoint (the one `agenticmail setup-email` calls) makes every sub-agent publicly reachable from the internet via plus-addressing.** This is by design — agents that can only email each other aren't very useful for talking to real people — but the implications surprise some operators:
+
+- **Plus-addresses are publicly guessable.** Once relay is connected, anyone can hit `your-relay+secretary@gmail.com`, `your-relay+kepler@gmail.com`, etc. and the corresponding agent's AgenticMail inbox receives the message. The `+sub` part is not a secret.
+- **External mail wakes the dispatcher identically to internal `@localhost` mail.** The API publishes the same SSE `new-mail` event regardless of source; the host integration (`@agenticmail/claudecode`, `@agenticmail/codex`) spawns a worker turn either way.
+- **The host bridges take a different path.** Mail to `your-relay+claudecode@gmail.com` / `your-relay+codex@gmail.com` routes to `handleBridgeMail` in the dispatcher, which uses the host SDK's `resume` option to wake the operator's last session headlessly. If that fails it falls through to the bridge-escalation email configured via `setup_operator_email`.
+- **Spam = worker turns.** Throttles in order of escalation: the `wake-budget` guard in `dispatcher.handleEvent` (automatic, default cap per minute per agent), the built-in relay-level spam filter (runs before publishing the SSE event), and `metadata.host`-based fencing for agents that should stay internal-only.
+
+---
+
 ## License
 
 [MIT](./LICENSE) - Ope Olatunji ([@ope-olatunji](https://github.com/ope-olatunji))

package/dist/index.js

@@ -1956,18 +1956,45 @@ function normalizeWakeList(value) {
   return void 0;
 }
 function deriveDefaultWakeList(toField) {
-  if (!toField) return void 0;
-  const arr = Array.isArray(toField) ? toField : String(toField).split(",");
-  const localNames = [];
+  const localNames = extractLocalNames(toField);
+  return localNames.length > 0 ? localNames : void 0;
+}
+function extractLocalNames(field) {
+  if (!field) return [];
+  const arr = Array.isArray(field) ? field : String(field).split(",");
+  const out = [];
   for (const raw of arr) {
     const trimmed = String(raw).slice(0, 500).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);
+    if (name) out.push(name);
   }
-  return localNames.length > 0 ? localNames : void 0;
+  return out;
+}
+function deriveWakeFromBody(body, candidateNames) {
+  if (!body || candidateNames.length === 0) return [];
+  const sample = body.length > 2e4 ? body.slice(0, 2e4) : body;
+  const found = /* @__PURE__ */ new Set();
+  for (const raw of candidateNames) {
+    const name = String(raw).trim().toLowerCase();
+    if (!name) continue;
+    const esc = name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    const patterns = [
+      // Greeting / handoff anchors:
+      //   "Marlow —"  "Marlow:"  "Marlow,"
+      new RegExp(`(?:^|[\\n.])\\s*${esc}\\s*[\u2014\u2013\\-:,]`, "i"),
+      // Mention syntax:
+      //   "@marlow"
+      new RegExp(`@${esc}\\b`, "i"),
+      // Conversational handoff phrases:
+      //   "over to marlow"  "handing off to marlow"  "next up: marlow"
+      new RegExp(`\\b(?:hi|hey|hello|over to|hand(?:ing)? off to|dispatch(?:ing)? to|assigning to|next up:?|next slice:?)\\s+${esc}\\b`, "i")
+    ];
+    if (patterns.some((p) => p.test(sample))) found.add(name);
+  }
+  return Array.from(found);
 }
 function wakeHeaders(wakeList) {
   if (wakeList === void 0) return {};
@@ -2113,7 +2140,13 @@ function createMailRoutes(accountManager, config, db, gatewayManager) {
           const ownerName2 = agent.metadata?.ownerName;
           const fromName2 = ownerName2 ? `${agent.name} from ${ownerName2}` : agent.name;
           const explicitWakeForPersist = normalizeWakeList(wake);
-          const wakeListForPersist = wake === void 0 ? deriveDefaultWakeList(to) : explicitWakeForPersist;
+          let wakeListForPersist;
+          if (wake !== void 0) {
+            wakeListForPersist = explicitWakeForPersist;
+          } else {
+            const bodyDerived = deriveWakeFromBody(typeof text === "string" ? text : "", extractLocalNames(cc));
+            wakeListForPersist = bodyDerived.length > 0 ? bodyDerived : deriveDefaultWakeList(to);
+          }
           const mailOptions = {
             to,
             subject,
@@ -2197,7 +2230,13 @@ function createMailRoutes(accountManager, config, db, gatewayManager) {
       const ownerName = agent.metadata?.ownerName;
       const fromName = ownerName ? `${agent.name} from ${ownerName}` : agent.name;
       const explicitWake = normalizeWakeList(wake);
-      const wakeList = wake === void 0 ? deriveDefaultWakeList(to) : explicitWake;
+      let wakeList;
+      if (wake !== void 0) {
+        wakeList = explicitWake;
+      } else {
+        const bodyDerived = deriveWakeFromBody(typeof text === "string" ? text : "", extractLocalNames(cc));
+        wakeList = bodyDerived.length > 0 ? bodyDerived : deriveDefaultWakeList(to);
+      }
       const customHeaders = wakeHeaders(wakeList);
       const mailOpts = {
         to,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agenticmail/api",
-  "version": "0.9.27",
+  "version": "0.9.28",
   "description": "REST API server for AgenticMail — email and SMS endpoints for AI agents",
   "type": "module",
   "main": "dist/index.js",