@agenticmail/api 0.9.26 → 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.26",
+  "version": "0.9.28",
   "description": "REST API server for AgenticMail — email and SMS endpoints for AI agents",
   "type": "module",
   "main": "dist/index.js",

package/public/index.html

@@ -63,6 +63,8 @@
       <div class="profile-menu-section">Inboxes</div>
       <div id="profile-menu-list"></div>
       <div class="profile-menu-divider"></div>
+      <div id="profile-menu-operator-email"></div>
+      <div class="profile-menu-divider"></div>
       <div class="profile-menu-footer">
         <a id="signout-link">Sign out</a>
       </div>

package/public/js/api.js

@@ -37,6 +37,25 @@ export async function apiPut(path, body, opts = {}) {
   return await r.json();
 }
 
+export async function apiPatch(path, body, opts = {}) {
+  const r = await fetch(`${API_URL}/api/agenticmail${path}`, {
+    method: 'PATCH',
+    headers: {
+      'Content-Type': 'application/json',
+      Authorization: `Bearer ${opts.agentKey ?? state.masterKey}`,
+    },
+    body: JSON.stringify(body),
+  });
+  if (!r.ok) {
+    // Try to surface the server's error body so the UI can show
+    // "operator email must contain an @" instead of a bare 400.
+    let detail = '';
+    try { const j = await r.json(); detail = j?.error ? `: ${j.error}` : ''; } catch { /* ignore */ }
+    throw new Error(`${r.status} ${path}${detail}`);
+  }
+  return await r.json();
+}
+
 /**
  * Fetch an attachment with auth and trigger a browser download.
  *

package/public/js/profile.js

@@ -16,9 +16,10 @@
 // The selected host persists in localStorage so the operator's view
 // preference survives reloads and across browser tabs.
 import { state } from './state.js';
-import { escapeHtml } from './utils.js';
+import { escapeHtml, toast } from './utils.js';
 import { avatarHtml, isBridgeAgent } from './avatar.js';
 import { icon } from './icons.js';
+import { apiGet, apiPatch } from './api.js';
 
 /**
  * Host registry mirrors the one in avatar.js. Kept duplicated rather
@@ -339,8 +340,131 @@ export function bindHostSwitcher() {
   });
 }
 
+/**
+ * Operator notification email — show + edit in the profile menu.
+ *
+ * The dispatcher emails this address when a sub-agent mails a host
+ * bridge AND no fresh host session is available for a headless
+ * resume. Wired to `GET / PATCH /system/operator-email` (the same
+ * endpoints the `setup_operator_email` MCP tool uses, so changes
+ * from the UI and changes from a host agent stay in sync).
+ *
+ * Two states:
+ *   1. Display: shows the current email or "Not set", with a small
+ *      "Edit" pencil. Clicking the pencil swaps to state 2.
+ *   2. Edit: <input> + Save / Cancel buttons. Save fires PATCH,
+ *      shows a toast, and re-renders state 1.
+ *
+ * Cached value: `operatorEmail` lives on `state.operatorEmail` so a
+ * re-render of the profile menu doesn't refetch every time.
+ */
+
+async function loadOperatorEmail() {
+  try {
+    const r = await apiGet('/system/operator-email');
+    state.operatorEmail = (typeof r?.email === 'string' && r.email) ? r.email : null;
+  } catch (err) {
+    // 404 / 500 on older servers — degrade silently to "not set".
+    state.operatorEmail = null;
+  }
+  renderOperatorEmail();
+}
+
+function renderOperatorEmail() {
+  const slot = document.getElementById('profile-menu-operator-email');
+  if (!slot) return;
+  const value = state.operatorEmail;
+  const editing = slot.dataset.mode === 'edit';
+
+  if (editing) {
+    slot.innerHTML = `
+      <div class="profile-menu-section">Alert email</div>
+      <div class="operator-email-edit">
+        <input
+          type="email"
+          id="operator-email-input"
+          class="operator-email-input"
+          placeholder="you@example.com"
+          value="${escapeHtml(value ?? '')}" />
+        <div class="operator-email-actions">
+          <button class="operator-email-btn operator-email-btn-primary" id="operator-email-save">Save</button>
+          <button class="operator-email-btn" id="operator-email-cancel">Cancel</button>
+          ${value ? `<button class="operator-email-btn operator-email-btn-danger" id="operator-email-clear" title="Clear — no email forward">Clear</button>` : ''}
+        </div>
+        <div class="operator-email-hint">
+          Dispatcher emails this address when sub-agents mail your host bridge and the resume can't run (no fresh session, expired token). Phone push via your normal mail app.
+        </div>
+      </div>
+    `;
+    const input = document.getElementById('operator-email-input');
+    input?.focus();
+    input?.select();
+    document.getElementById('operator-email-save')?.addEventListener('click', () => saveOperatorEmail(input?.value ?? ''));
+    document.getElementById('operator-email-cancel')?.addEventListener('click', () => {
+      slot.dataset.mode = '';
+      renderOperatorEmail();
+    });
+    document.getElementById('operator-email-clear')?.addEventListener('click', () => saveOperatorEmail(''));
+    input?.addEventListener('keydown', (e) => {
+      if (e.key === 'Enter') saveOperatorEmail(input.value);
+      if (e.key === 'Escape') { slot.dataset.mode = ''; renderOperatorEmail(); }
+    });
+    return;
+  }
+
+  slot.innerHTML = `
+    <div class="profile-menu-section">Alert email</div>
+    <div class="operator-email-display" id="operator-email-display">
+      <div class="operator-email-value ${value ? '' : 'is-empty'}">
+        ${value ? escapeHtml(value) : 'Not set — sub-agent escalations stay in the web UI only'}
+      </div>
+      <button class="operator-email-edit-btn" id="operator-email-edit" title="${value ? 'Change' : 'Set up'}">
+        ${icon('compose', { size: 14 })}
+      </button>
+    </div>
+  `;
+  document.getElementById('operator-email-edit')?.addEventListener('click', () => {
+    slot.dataset.mode = 'edit';
+    renderOperatorEmail();
+  });
+}
+
+async function saveOperatorEmail(raw) {
+  const trimmed = String(raw ?? '').trim();
+  try {
+    // Server canonicalises (trims) and validates (must contain @ when
+    // non-empty). Empty string = clear, server stores null. We mirror
+    // the server's canonical value back into state so a refresh
+    // shows exactly what was persisted.
+    const r = await apiPatch('/system/operator-email', { email: trimmed || null });
+    state.operatorEmail = (typeof r?.email === 'string' && r.email) ? r.email : null;
+    toast(state.operatorEmail ? `Alerts now route to ${state.operatorEmail}` : 'Alert email cleared.');
+    const slot = document.getElementById('profile-menu-operator-email');
+    if (slot) slot.dataset.mode = '';
+    renderOperatorEmail();
+  } catch (err) {
+    toast(`Could not save: ${err.message.replace(/^\d+\s+\S+:\s*/, '')}`, true);
+  }
+}
+
+/** Lazy-load on first profile-menu open — keeps the initial page
+ *  load free of an extra round-trip. Subsequent opens use the
+ *  cached value in state.operatorEmail. */
+let operatorEmailHydrated = false;
+export function hydrateOperatorEmail() {
+  if (operatorEmailHydrated) {
+    renderOperatorEmail();
+    return;
+  }
+  operatorEmailHydrated = true;
+  void loadOperatorEmail();
+}
+
 export function toggleProfileMenu(e) {
   if (e) e.stopPropagation();
+  // Lazy-hydrate the operator email block the first time the menu
+  // opens (idempotent for subsequent opens — re-renders from cache).
+  hydrateOperatorEmail();
   document.getElementById('profile-menu').classList.toggle('open');
 }
 export function closeProfileMenu() {

package/public/js/state.js

@@ -48,6 +48,16 @@ export const state = {
    * `state.agents` so no UI work is needed when a new bridge appears.
    */
   activeHost: localStorage.getItem('agenticmail.activeHost') || 'all',
+  /**
+   * Operator's notification email address (or null when not set).
+   * Hydrated lazily on first profile-menu open via
+   * `GET /system/operator-email`. Used by the dispatcher's
+   * bridge-escalation path to forward digests when a sub-agent
+   * mails a bridge and no host session is resumable. See
+   * packages/core/src/operator-prefs.ts for the storage and
+   * profile.js for the in-menu edit affordance.
+   */
+  operatorEmail: null,
 };
 
 export const API_URL = window.location.origin;

package/public/styles.css

@@ -446,6 +446,109 @@ a { color: var(--accent-strong); }
 }
 .profile-menu-footer a:hover { text-decoration: underline; }
 
+/* ─── Operator notification email — display + inline edit ──────────
+ *
+ * Lives between the inbox list and the Sign out footer. Two states:
+ *  - Display: current address (or "Not set" placeholder) + pencil
+ *  - Edit:    <input> + Save / Cancel / Clear buttons + hint copy
+ *
+ * Visual weight is deliberately understated — this is a "set once,
+ * forget" knob, not a primary action. */
+.operator-email-display {
+  padding: 6px 20px 10px;
+  display: flex; align-items: center; gap: 8px;
+  font-size: 13px;
+}
+.operator-email-value {
+  flex: 1;
+  color: var(--ink);
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+.operator-email-value.is-empty {
+  color: var(--muted);
+  font-style: italic;
+  font-size: 12px;
+}
+.operator-email-edit-btn {
+  background: transparent;
+  border: none;
+  cursor: pointer;
+  color: var(--muted);
+  padding: 4px;
+  border-radius: 4px;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+}
+.operator-email-edit-btn:hover {
+  background: var(--bg-hover);
+  color: var(--ink);
+}
+.operator-email-edit {
+  padding: 4px 20px 12px;
+}
+.operator-email-input {
+  width: 100%;
+  padding: 8px 10px;
+  border: 1px solid var(--line);
+  border-radius: 6px;
+  background: var(--bg);
+  color: var(--ink);
+  font-size: 13px;
+  font-family: inherit;
+  box-sizing: border-box;
+}
+.operator-email-input:focus {
+  outline: none;
+  border-color: var(--accent-strong);
+}
+.operator-email-actions {
+  display: flex;
+  gap: 6px;
+  margin-top: 8px;
+}
+.operator-email-btn {
+  padding: 6px 12px;
+  border: 1px solid var(--line);
+  border-radius: 6px;
+  background: var(--bg);
+  color: var(--ink);
+  font-size: 12px;
+  font-weight: 500;
+  cursor: pointer;
+  transition: background 120ms, border-color 120ms;
+}
+.operator-email-btn:hover { background: var(--bg-hover); }
+.operator-email-btn-primary {
+  background: var(--accent-strong);
+  color: white;
+  border-color: var(--accent-strong);
+}
+.operator-email-btn-primary:hover {
+  background: var(--accent-strong);
+  opacity: 0.9;
+}
+.operator-email-btn-danger {
+  margin-left: auto;
+  color: #b91c1c;
+  border-color: transparent;
+}
+.operator-email-btn-danger:hover {
+  background: #fee2e2;
+}
+.operator-email-hint {
+  margin-top: 8px;
+  font-size: 11px;
+  color: var(--muted);
+  line-height: 1.45;
+}
+@media (prefers-color-scheme: dark) {
+  .operator-email-btn-danger { color: #fca5a5; }
+  .operator-email-btn-danger:hover { background: #2a1717; }
+}
+
 /* ─── Avatars ──────────────────────────────────────────────────────── */
 .avatar {
   width: 32px; height: 32px; border-radius: 50%;