@agenticmail/api 0.9.25 → 0.9.27

package/dist/index.js

@@ -282,6 +282,30 @@ function closeAllSystemEventListeners() {
 }
 function createSystemEventRoutes() {
   const router = Router2();
+  router.get("/system/operator-email", requireMaster, async (_req, res) => {
+    try {
+      const { getOperatorEmail } = await import("@agenticmail/core");
+      res.json({ email: getOperatorEmail() });
+    } catch (err) {
+      res.status(500).json({ error: err.message });
+    }
+  });
+  router.patch("/system/operator-email", requireMaster, async (req, res) => {
+    try {
+      const { setOperatorEmail } = await import("@agenticmail/core");
+      const raw = req.body && typeof req.body === "object" ? req.body.email : null;
+      const email = typeof raw === "string" ? raw : null;
+      const stored = setOperatorEmail(email);
+      res.json({ email: stored });
+    } catch (err) {
+      const msg = err.message;
+      if (msg.includes("must contain an @")) {
+        res.status(400).json({ error: msg });
+        return;
+      }
+      res.status(500).json({ error: msg });
+    }
+  });
   router.get("/system/events", requireMaster, (req, res) => {
     res.setHeader("Content-Type", "text/event-stream");
     res.setHeader("Cache-Control", "no-cache");
@@ -5326,7 +5350,7 @@ var skipped = [];
 var SKIPPED_CAP = 100;
 var SKIPPED_TTL_MS = 5 * 60 * 1e3;
 var processState = null;
-function createDispatcherActivityRoutes() {
+function createDispatcherActivityRoutes(deps = {}) {
   const router = Router13();
   router.post("/dispatcher/worker-started", requireMaster, (req, res) => {
     const body = req.body ?? {};
@@ -5490,7 +5514,7 @@ function createDispatcherActivityRoutes() {
     });
     res.json({ ok: true });
   });
-  router.post("/dispatcher/bridge-escalation", requireMaster, (req, res) => {
+  router.post("/dispatcher/bridge-escalation", requireMaster, async (req, res) => {
     const body = req.body ?? {};
     const event = {
       type: "bridge_escalation",
@@ -5505,7 +5529,43 @@ function createDispatcherActivityRoutes() {
       atMs: Date.now()
     };
     pushSystemEvent(event);
-    res.json({ ok: true, escalated: true });
+    let forwarded = false;
+    try {
+      const { getOperatorEmail } = await import("@agenticmail/core");
+      const operatorEmail = getOperatorEmail();
+      if (operatorEmail && deps.gatewayManager && deps.accountManager && event.agentName) {
+        const bridge = await deps.accountManager.getByName(event.agentName);
+        if (bridge) {
+          const subjectLine = `[AgenticMail Alert] Sub-agent needs your attention \u2014 ${event.subject ?? "(no subject)"}`;
+          const lines = [
+            `A sub-agent mailed your ${event.agentName}@localhost bridge inbox and the dispatcher could not resume a host session to handle it on your behalf.`,
+            "",
+            `Reason: ${event.reason}${event.errorMessage ? ` \u2014 ${event.errorMessage.slice(0, 160)}` : ""}`,
+            "",
+            `From:    ${event.from ?? "unknown"}`,
+            `Subject: ${event.subject ?? "(no subject)"}`,
+            `UID:     ${event.uid ?? "?"}`,
+            "",
+            event.preview ? `Preview:
+${event.preview.slice(0, 800)}` : "",
+            "",
+            `Open ${event.agentName} in the AgenticMail web UI, or run \`claude\` / \`codex\` and the next hook fire will surface this thread.`,
+            "",
+            `\u2014 AgenticMail (this address is set via setup_operator_email; reply does nothing)`
+          ].filter(Boolean).join("\n");
+          await deps.gatewayManager.routeOutbound(bridge.name, {
+            from: bridge.email,
+            to: operatorEmail,
+            subject: subjectLine,
+            text: lines
+          });
+          forwarded = true;
+        }
+      }
+    } catch (err) {
+      console.warn("[bridge-escalation] forward to operator email failed:", err.message);
+    }
+    res.json({ ok: true, escalated: true, forwarded });
   });
   router.post("/dispatcher/worker-skipped", requireMaster, (req, res) => {
     const body = req.body ?? {};
@@ -5765,7 +5825,15 @@ function createApp(configOverrides) {
   app2.use("/api/agenticmail", createSmsRoutes(db, accountManager, config, gatewayManager));
   app2.use("/api/agenticmail", createStorageRoutes(db, accountManager, config));
   app2.use("/api/agenticmail", createSystemEventRoutes());
-  app2.use("/api/agenticmail", createDispatcherActivityRoutes());
+  app2.use("/api/agenticmail", createDispatcherActivityRoutes({
+    // Wire the gateway + account manager so /dispatcher/bridge-escalation
+    // can forward a digest to the operator's notification email when
+    // no host session is available for a headless resume. See
+    // packages/core/src/operator-prefs.ts for the address source and
+    // the setup_operator_email MCP tool for how it gets configured.
+    gatewayManager,
+    accountManager
+  }));
   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.9.25",
+  "version": "0.9.27",
   "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%;