@agenticmail/api 0.9.6 → 0.9.8

package/dist/index.js

@@ -38,7 +38,7 @@ function safeEqual(a, b) {
   const hb = createHash("sha256").update(b).digest();
   return timingSafeEqual(ha, hb);
 }
-function createAuthMiddleware(masterKey, accountManager2, db) {
+function createAuthMiddleware(masterKey, accountManager, db) {
   return async (req, res, next) => {
     const authHeader = req.headers.authorization;
     if (!authHeader?.startsWith("Bearer ")) {
@@ -56,7 +56,7 @@ function createAuthMiddleware(masterKey, accountManager2, db) {
       return;
     }
     try {
-      const agent = await accountManager2.getByApiKey(token);
+      const agent = await accountManager.getByApiKey(token);
       if (agent) {
         req.agent = agent;
         if (db) {
@@ -327,9 +327,9 @@ function sanitizeAgent(agent) {
   }
   return agent;
 }
-function createAccountRoutes(accountManager2, db, config) {
+function createAccountRoutes(accountManager, db, config) {
   const router = Router3();
-  const deletionService = new AgentDeletionService(db, accountManager2, config);
+  const deletionService = new AgentDeletionService(db, accountManager, config);
   router.post("/accounts", requireMaster, async (req, res, next) => {
     if (!req.body || typeof req.body !== "object") {
       res.status(400).json({ error: "Request body must be JSON" });
@@ -360,7 +360,7 @@ function createAccountRoutes(accountManager2, db, config) {
       const cleanMeta = metadata ? Object.fromEntries(
         Object.entries(metadata).filter(([k]) => !k.startsWith("_"))
       ) : void 0;
-      const agent = await accountManager2.create({ name: accountName, domain, password: password || void 0, metadata: cleanMeta, role });
+      const agent = await accountManager.create({ name: accountName, domain, password: password || void 0, metadata: cleanMeta, role });
       try {
         db.prepare("UPDATE agents SET last_activity_at = datetime('now') WHERE id = ?").run(agent.id);
       } catch {
@@ -392,7 +392,7 @@ function createAccountRoutes(accountManager2, db, config) {
   });
   router.get("/accounts", requireMaster, async (_req, res, next) => {
     try {
-      const agents = await accountManager2.list();
+      const agents = await accountManager.list();
       res.json({ agents: agents.map(sanitizeAgent) });
     } catch (err) {
       next(err);
@@ -400,7 +400,7 @@ function createAccountRoutes(accountManager2, db, config) {
   });
   router.get("/accounts/directory", requireAuth, async (_req, res, next) => {
     try {
-      const agents = await accountManager2.list();
+      const agents = await accountManager.list();
       const directory = agents.map((a) => ({ name: a.name, email: a.email, role: a.role }));
       res.json({ agents: directory });
     } catch (err) {
@@ -409,7 +409,7 @@ function createAccountRoutes(accountManager2, db, config) {
   });
   router.get("/accounts/directory/:name", requireAuth, async (req, res, next) => {
     try {
-      const agent = await accountManager2.getByName(req.params.name);
+      const agent = await accountManager.getByName(req.params.name);
       if (!agent) {
         res.status(404).json({ error: "Agent not found" });
         return;
@@ -474,7 +474,7 @@ function createAccountRoutes(accountManager2, db, config) {
       const deleted = [];
       for (const row of rows) {
         try {
-          await accountManager2.delete(row.id);
+          await accountManager.delete(row.id);
           deleted.push(row.name);
         } catch {
         }
@@ -486,7 +486,7 @@ function createAccountRoutes(accountManager2, db, config) {
   });
   router.get("/accounts/:id", requireMaster, async (req, res, next) => {
     try {
-      const agent = await accountManager2.getById(req.params.id);
+      const agent = await accountManager.getById(req.params.id);
       if (!agent) {
         res.status(404).json({ error: "Agent not found" });
         return;
@@ -504,7 +504,7 @@ function createAccountRoutes(accountManager2, db, config) {
         res.status(400).json({ error: "metadata must be an object" });
         return;
       }
-      const updated = await accountManager2.updateMetadata(agent.id, metadata);
+      const updated = await accountManager.updateMetadata(agent.id, metadata);
       if (!updated) {
         res.status(404).json({ error: "Agent not found" });
         return;
@@ -542,7 +542,7 @@ function createAccountRoutes(accountManager2, db, config) {
   });
   router.delete("/accounts/:id", requireMaster, async (req, res, next) => {
     try {
-      const allAgents = await accountManager2.list();
+      const allAgents = await accountManager.list();
       if (allAgents.length <= 1) {
         res.status(400).json({ error: "Cannot delete the last agent. At least one agent must remain." });
         return;
@@ -560,7 +560,7 @@ function createAccountRoutes(accountManager2, db, config) {
         }
         res.json(summary);
       } else {
-        const deleted = await accountManager2.delete(req.params.id);
+        const deleted = await accountManager.delete(req.params.id);
         if (!deleted) {
           res.status(404).json({ error: "Agent not found" });
           return;
@@ -728,7 +728,7 @@ function parseScheduleTime(input) {
   const fallback = new Date(trimmed);
   return isNaN(fallback.getTime()) ? null : fallback;
 }
-function createFeatureRoutes(db, _accountManager, config, gatewayManager) {
+function createFeatureRoutes(db, accountManager, config, gatewayManager) {
   const router = Router4();
   router.get("/contacts", requireAgent, async (req, res, next) => {
     try {
@@ -1318,7 +1318,7 @@ function evaluateRules(db, agentId, email) {
   }
   return null;
 }
-function startScheduledSender(db, accountManager2, config, gatewayManager) {
+function startScheduledSender(db, accountManager, config, gatewayManager) {
   return setInterval(async () => {
     try {
       const now = (/* @__PURE__ */ new Date()).toISOString();
@@ -1327,7 +1327,7 @@ function startScheduledSender(db, accountManager2, config, gatewayManager) {
       ).all(now);
       for (const row of pending) {
         try {
-          const agent = await accountManager2.getById(row.agent_id);
+          const agent = await accountManager.getById(row.agent_id);
           if (!agent) {
             db.prepare("UPDATE scheduled_emails SET status = 'failed', error = ? WHERE id = ?").run("Agent not found", row.id);
             continue;
@@ -1426,7 +1426,7 @@ async function closeAllWatchers() {
   }
   activeWatchers.clear();
 }
-function createEventRoutes(accountManager2, config, db) {
+function createEventRoutes(accountManager, config, db) {
   const router = Router5();
   router.get("/events", requireAgent, async (req, res, next) => {
     try {
@@ -1569,6 +1569,15 @@ function createEventRoutes(accountManager2, config, db) {
         safeWrite(`data: ${JSON.stringify(event)}
 
 `);
+        try {
+          pushSystemEvent({
+            type: "new_mail",
+            agentId: agent.id,
+            agentName: agent.name,
+            event
+          });
+        } catch {
+        }
       });
       watcher.on("expunge", (event) => {
         safeWrite(`data: ${JSON.stringify(event)}
@@ -1629,6 +1638,38 @@ var receiverPending = /* @__PURE__ */ new Map();
 var CACHE_TTL_MS = 10 * 60 * 1e3;
 var MAX_CACHE_SIZE = 100;
 var draining = false;
+var parsedMessageCache = /* @__PURE__ */ new Map();
+var PARSED_MESSAGE_TTL_MS = 6e4;
+var PARSED_MESSAGE_MAX = 200;
+function parsedMessageCacheKey(agentId, folder, uid) {
+  return `${agentId}::${folder}::${uid}`;
+}
+function getParsedMessageFromCache(agentId, folder, uid) {
+  const key = parsedMessageCacheKey(agentId, folder, uid);
+  const entry = parsedMessageCache.get(key);
+  if (!entry) return null;
+  if (Date.now() - entry.cachedAt > PARSED_MESSAGE_TTL_MS) {
+    parsedMessageCache.delete(key);
+    return null;
+  }
+  parsedMessageCache.delete(key);
+  parsedMessageCache.set(key, entry);
+  return entry.data;
+}
+function setParsedMessageInCache(agentId, folder, uid, data) {
+  if (parsedMessageCache.size >= PARSED_MESSAGE_MAX) {
+    const oldest = parsedMessageCache.keys().next().value;
+    if (oldest) parsedMessageCache.delete(oldest);
+  }
+  parsedMessageCache.set(parsedMessageCacheKey(agentId, folder, uid), { data, cachedAt: Date.now() });
+}
+function invalidateParsedMessage(agentId, uid) {
+  const prefix = `${agentId}::`;
+  const suffix = `::${uid}`;
+  for (const key of parsedMessageCache.keys()) {
+    if (key.startsWith(prefix) && key.endsWith(suffix)) parsedMessageCache.delete(key);
+  }
+}
 function getAgentPassword(agent) {
   return agent.metadata?._password || agent.name;
 }
@@ -1763,7 +1804,7 @@ async function findUidByMessageId(receiver, messageId, maxAttempts = 8) {
     const lock = await client.getMailboxLock("INBOX");
     try {
       const results = await client.search(
-        { header: ["Message-ID", messageId] },
+        { header: { "Message-ID": messageId } },
         { uid: true }
       );
       if (Array.isArray(results) && results.length > 0) {
@@ -1841,7 +1882,7 @@ function wakeHeaders(wakeList) {
   if (wakeList === void 0) return {};
   return { "X-AgenticMail-Wake": wakeList.join(", ") };
 }
-async function notifyLocalRecipientsOfNewMail(accountManager2, toField, ccField, bccField, fromAgent, subject, messageId, config, wakeList) {
+async function notifyLocalRecipientsOfNewMail(accountManager, toField, ccField, bccField, fromAgent, subject, messageId, config, wakeList) {
   const collected = [];
   const push = (v) => {
     if (!v) return;
@@ -1881,7 +1922,7 @@ async function notifyLocalRecipientsOfNewMail(accountManager2, toField, ccField,
     if (addr === fromAgent.email.toLowerCase()) continue;
     let recipient = null;
     try {
-      recipient = await accountManager2.getByName(localPart);
+      recipient = await accountManager.getByName(localPart);
     } catch {
     }
     if (!recipient || notified.has(recipient.id)) continue;
@@ -1942,7 +1983,7 @@ async function saveSentCopy(authUser, password, config, raw) {
     console.warn(`[mail] Failed to save Sent copy for ${authUser}: ${err.message}`);
   }
 }
-function createMailRoutes(accountManager2, config, db, gatewayManager) {
+function createMailRoutes(accountManager, config, db, gatewayManager) {
   const router = Router6();
   router.post("/mail/send", requireAgent, async (req, res, next) => {
     try {
@@ -2096,7 +2137,7 @@ function createMailRoutes(accountManager2, config, db, gatewayManager) {
       const result = await sender.send(mailOpts);
       saveSentCopy(agent.stalwartPrincipal, password, config, result.raw);
       notifyLocalRecipientsOfNewMail(
-        accountManager2,
+        accountManager,
         to,
         cc,
         bcc,
@@ -2137,33 +2178,52 @@ function createMailRoutes(accountManager2, config, db, gatewayManager) {
         return;
       }
       const folder = req.query.folder || "INBOX";
+      const cached = getParsedMessageFromCache(agent.id, folder, uid);
+      if (cached) {
+        res.json(cached);
+        return;
+      }
       const password = getAgentPassword(agent);
       const receiver = await getReceiver(agent.stalwartPrincipal, password, config);
       const raw = await receiver.fetchMessage(uid, folder);
       const parsed = await parseEmail2(raw);
+      const attachments = Array.isArray(parsed.attachments) ? parsed.attachments.map((a, index) => ({
+        index,
+        filename: a.filename,
+        contentType: a.contentType,
+        size: typeof a.size === "number" ? a.size : a.content?.length ?? 0,
+        contentDisposition: a.contentDisposition,
+        cid: a.cid,
+        related: a.related
+      })) : [];
+      let payload;
       if (isInternalEmail2(parsed)) {
-        res.json({
+        payload = {
           ...parsed,
+          attachments,
           security: { internal: true, spamScore: 0, isSpam: false, isWarning: false }
-        });
-        return;
+        };
+      } else {
+        const sanitized = sanitizeEmail(parsed);
+        const spamScore = scoreEmail2(parsed);
+        payload = {
+          ...parsed,
+          attachments,
+          text: sanitized.text,
+          html: sanitized.html,
+          security: {
+            spamScore: spamScore.score,
+            isSpam: spamScore.isSpam,
+            isWarning: spamScore.isWarning,
+            topCategory: spamScore.topCategory,
+            matches: spamScore.matches.map((m) => m.ruleId),
+            sanitized: sanitized.wasModified,
+            sanitizeDetections: sanitized.detections
+          }
+        };
       }
-      const sanitized = sanitizeEmail(parsed);
-      const spamScore = scoreEmail2(parsed);
-      res.json({
-        ...parsed,
-        text: sanitized.text,
-        html: sanitized.html,
-        security: {
-          spamScore: spamScore.score,
-          isSpam: spamScore.isSpam,
-          isWarning: spamScore.isWarning,
-          topCategory: spamScore.topCategory,
-          matches: spamScore.matches.map((m) => m.ruleId),
-          sanitized: sanitized.wasModified,
-          sanitizeDetections: sanitized.detections
-        }
-      });
+      setParsedMessageInCache(agent.id, folder, uid, payload);
+      res.json(payload);
     } catch (err) {
       next(err);
     }
@@ -2294,6 +2354,7 @@ function createMailRoutes(accountManager2, config, db, gatewayManager) {
       const password = getAgentPassword(agent);
       const receiver = await getReceiver(agent.stalwartPrincipal, password, config);
       await receiver.markSeen(uid);
+      invalidateParsedMessage(agent.id, uid);
       res.json({ ok: true });
     } catch (err) {
       next(err);
@@ -2340,6 +2401,7 @@ function createMailRoutes(accountManager2, config, db, gatewayManager) {
       const password = getAgentPassword(agent);
       const receiver = await getReceiver(agent.stalwartPrincipal, password, config);
       await receiver.markUnseen(uid);
+      invalidateParsedMessage(agent.id, uid);
       res.json({ ok: true });
     } catch (err) {
       next(err);
@@ -2358,6 +2420,7 @@ function createMailRoutes(accountManager2, config, db, gatewayManager) {
       const password = getAgentPassword(agent);
       const receiver = await getReceiver(agent.stalwartPrincipal, password, config);
       await receiver.setStarred(uid, starred, folder);
+      invalidateParsedMessage(agent.id, uid);
       res.json({ ok: true, starred });
     } catch (err) {
       next(err);
@@ -2379,6 +2442,7 @@ function createMailRoutes(accountManager2, config, db, gatewayManager) {
       const password = getAgentPassword(agent);
       const receiver = await getReceiver(agent.stalwartPrincipal, password, config);
       await receiver.moveMessage(uid, fromFolder || "INBOX", toFolder);
+      invalidateParsedMessage(agent.id, uid);
       res.json({ ok: true });
     } catch (err) {
       next(err);
@@ -2842,7 +2906,7 @@ function createMailRoutes(accountManager2, config, db, gatewayManager) {
         res.status(400).json({ error: `Email already ${row.status}` });
         return;
       }
-      const agent = await accountManager2.getById(row.agent_id);
+      const agent = await accountManager.getById(row.agent_id);
       if (!agent) {
         res.status(404).json({ error: "Agent account no longer exists" });
         return;
@@ -2879,7 +2943,7 @@ function createMailRoutes(accountManager2, config, db, gatewayManager) {
         const result = await sender.send(mailOpts);
         saveSentCopy(agent.stalwartPrincipal, password, config, result.raw);
         notifyLocalRecipientsOfNewMail(
-          accountManager2,
+          accountManager,
           mailOpts.to,
           mailOpts.cc,
           mailOpts.bcc,
@@ -2936,7 +3000,7 @@ var INBOUND_SECRET = process.env.AGENTICMAIL_INBOUND_SECRET || (() => {
   return generated;
 })();
 var DEBUG = () => !!process.env.AGENTICMAIL_DEBUG;
-function createInboundRoutes(accountManager2, config, gatewayManager) {
+function createInboundRoutes(accountManager, config, gatewayManager) {
   const router = Router7();
   router.post("/mail/inbound", async (req, res, next) => {
     try {
@@ -2952,7 +3016,7 @@ function createInboundRoutes(accountManager2, config, gatewayManager) {
       }
       const recipientEmail = typeof to === "string" ? to : to[0];
       const localPart = recipientEmail.split("@")[0];
-      const agent = await accountManager2.getByName(localPart);
+      const agent = await accountManager.getByName(localPart);
       if (!agent) {
         console.warn(`[Inbound] No agent found for "${localPart}" (${recipientEmail})`);
         res.status(404).json({ error: `No agent found for ${recipientEmail}` });
@@ -3544,7 +3608,7 @@ function deepEqual(a, b) {
 
 // src/routes/tasks.ts
 var rpcResolvers = /* @__PURE__ */ new Map();
-function createTaskRoutes(db, accountManager2, config) {
+function createTaskRoutes(db, accountManager, config) {
   const router = Router10();
   router.post("/tasks/assign", requireAuth, async (req, res, next) => {
     try {
@@ -3553,7 +3617,7 @@ function createTaskRoutes(db, accountManager2, config) {
         res.status(400).json({ error: "assignee (agent name) is required" });
         return;
       }
-      const target = await accountManager2.getByName(assignee);
+      const target = await accountManager.getByName(assignee);
       if (!target) {
         res.status(404).json({ error: `Agent "${assignee}" not found` });
         return;
@@ -3631,7 +3695,7 @@ Please check your pending tasks.`
       let assigneeId = req.agent.id;
       const assigneeName = req.query.assignee;
       if (assigneeName) {
-        const target = await accountManager2.getByName(assigneeName);
+        const target = await accountManager.getByName(assigneeName);
         if (target) assigneeId = target.id;
       }
       const rows = db.prepare(
@@ -3778,7 +3842,7 @@ Please check your pending tasks.`
         res.status(400).json({ error: "target (agent name) and task are required" });
         return;
       }
-      const targetAgent = await accountManager2.getByName(target);
+      const targetAgent = await accountManager.getByName(target);
       if (!targetAgent) {
         res.status(404).json({ error: `Agent "${target}" not found` });
         return;
@@ -3919,7 +3983,7 @@ import {
   normalizePhoneNumber,
   isValidPhoneNumber
 } from "@agenticmail/core";
-function createSmsRoutes(db, accountManager2, config, gatewayManager) {
+function createSmsRoutes(db, accountManager, config, gatewayManager) {
   const router = Router11();
   const smsManager = new SmsManager(db);
   function getAgent(req, res) {
@@ -4307,7 +4371,7 @@ function adaptBetterSqlite(raw) {
     }
   };
 }
-function createStorageRoutes(rawDb, accountManager2, config, dialect = "sqlite") {
+function createStorageRoutes(rawDb, accountManager, config, dialect = "sqlite") {
   const db = adaptBetterSqlite(rawDb);
   const router = Router12();
   function getAgent(req, res) {
@@ -5485,12 +5549,12 @@ function createApp(configOverrides) {
     adminUser: config.stalwart.adminUser,
     adminPassword: config.stalwart.adminPassword
   });
-  const accountManager2 = new AccountManager(db, stalwart);
+  const accountManager = new AccountManager(db, stalwart);
   const domainManager = new DomainManager(db, stalwart);
   const gatewayManager = new GatewayManager2({
     db,
     stalwart,
-    accountManager: accountManager2,
+    accountManager,
     localSmtp: {
       host: config.smtp.host,
       port: config.smtp.port,
@@ -5510,7 +5574,7 @@ function createApp(configOverrides) {
   app2.use(
     rateLimit({
       windowMs: 60 * 1e3,
-      max: 1e4,
+      limit: 1e4,
       standardHeaders: true,
       legacyHeaders: false,
       message: { error: "Too many requests, please try again later" }
@@ -5526,25 +5590,45 @@ function createApp(configOverrides) {
     return null;
   })();
   if (staticDir) {
-    app2.use("/", express.static(staticDir, { index: "index.html", extensions: ["html"] }));
+    app2.use("/", express.static(staticDir, {
+      index: "index.html",
+      extensions: ["html"],
+      // Browser caching for static assets. Without these every page
+      // refresh re-downloads every .js / .css / branding image, which
+      // ate ~30 round-trips per refresh and made the page feel slow.
+      //
+      // We DON'T cache index.html — it stays fresh so a deploy is
+      // visible on the next refresh. Everything else gets a short
+      // max-age + must-revalidate so the browser will keep using its
+      // cached copy across refreshes while still picking up new builds
+      // (the dist contents are deterministic — same code → same etag
+      // → 304 Not Modified on revalidate).
+      setHeaders: (res, filePath) => {
+        if (filePath.endsWith("index.html") || filePath.endsWith(".html")) {
+          res.setHeader("Cache-Control", "no-cache, must-revalidate");
+        } else {
+          res.setHeader("Cache-Control", "public, max-age=300, must-revalidate");
+        }
+      }
+    }));
     app2.get("/ui", (_req, res) => res.sendFile(join3(staticDir, "index.html")));
   }
   app2.use("/api/agenticmail", createHealthRoutes(stalwart));
-  app2.use("/api/agenticmail", createInboundRoutes(accountManager2, config, gatewayManager));
+  app2.use("/api/agenticmail", createInboundRoutes(accountManager, config, gatewayManager));
   const integrationFactory = readResolvedFactory(integrationRouteFactoryPromise);
   if (integrationFactory) {
     app2.use("/api/agenticmail", integrationFactory());
   }
-  app2.use("/api/agenticmail", createAuthMiddleware(config.masterKey, accountManager2, db));
-  app2.use("/api/agenticmail", createAccountRoutes(accountManager2, db, config));
-  app2.use("/api/agenticmail", createMailRoutes(accountManager2, config, db, gatewayManager));
-  app2.use("/api/agenticmail", createEventRoutes(accountManager2, config, db));
+  app2.use("/api/agenticmail", createAuthMiddleware(config.masterKey, accountManager, db));
+  app2.use("/api/agenticmail", createAccountRoutes(accountManager, db, config));
+  app2.use("/api/agenticmail", createMailRoutes(accountManager, config, db, gatewayManager));
+  app2.use("/api/agenticmail", createEventRoutes(accountManager, config, db));
   app2.use("/api/agenticmail", createDomainRoutes(domainManager));
   app2.use("/api/agenticmail", createGatewayRoutes(gatewayManager));
-  app2.use("/api/agenticmail", createFeatureRoutes(db, accountManager2, config, gatewayManager));
-  app2.use("/api/agenticmail", createTaskRoutes(db, accountManager2, config));
-  app2.use("/api/agenticmail", createSmsRoutes(db, accountManager2, config, gatewayManager));
-  app2.use("/api/agenticmail", createStorageRoutes(db, accountManager2, config));
+  app2.use("/api/agenticmail", createFeatureRoutes(db, accountManager, config, gatewayManager));
+  app2.use("/api/agenticmail", createTaskRoutes(db, accountManager, config));
+  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", createAgentMemoryRoutes(config));
@@ -5552,7 +5636,7 @@ function createApp(configOverrides) {
     res.status(404).json({ error: "Not found" });
   });
   app2.use(errorHandler);
-  const context2 = { config, db, stalwart, accountManager: accountManager2, domainManager, gatewayManager };
+  const context2 = { config, db, stalwart, accountManager, domainManager, gatewayManager };
   return { app: app2, context: context2 };
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agenticmail/api",
-  "version": "0.9.6",
+  "version": "0.9.8",
   "description": "REST API server for AgenticMail — email and SMS endpoints for AI agents",
   "type": "module",
   "main": "dist/index.js",
@@ -40,7 +40,7 @@
   },
   "devDependencies": {
     "@types/cors": "^2.8.17",
-    "@types/express": "^5.0.0",
+    "@types/express": "^4.17.0",
     "@types/uuid": "^10.0.0",
     "tsup": "^8.4.0",
     "tsx": "^4.19.0",

package/public/js/activity-badges.js

@@ -11,7 +11,7 @@
 // arrive at the heartbeat cadence (30 s) so the badge text
 // reflects what the agent is doing right now.
 
-import { state, API_URL } from './state.js';
+import { onSystemEvent } from './system-stream.js';
 
 const BADGE_CONTAINER_ID = 'activity-badges';
 
@@ -21,7 +21,9 @@ const BADGE_CONTAINER_ID = 'activity-badges';
  * the badge container on every event.
  */
 const workers = new Map();
-let sseController = null;
+let unsubWorkerStarted = null;
+let unsubWorkerHeartbeat = null;
+let unsubWorkerFinished = null;
 
 /**
  * Map an SDK tool name (or the truncated head we capture in
@@ -91,36 +93,16 @@ function handleEvent(event) {
 }
 
 /**
- * Subscribe to /system/events with the master key. The web UI
- * already holds the master key in state.masterKey (set on
- * sign-in). Re-subscribes idempotently — safe to call after
- * agent-list refresh.
+ * Subscribe to worker_* events on the shared /system/events stream.
+ * Idempotent — safe to call after agent-list refresh.
  */
 export function subscribeToActivity() {
-  if (sseController) { try { sseController.abort(); } catch {} }
-  sseController = new AbortController();
-  fetch(`${API_URL}/api/agenticmail/system/events`, {
-    headers: { Authorization: `Bearer ${state.masterKey}`, Accept: 'text/event-stream' },
-    signal: sseController.signal,
-  }).then(async res => {
-    if (!res.ok || !res.body) return;
-    const reader = res.body.getReader();
-    const dec = new TextDecoder();
-    let buf = '';
-    while (!sseController.signal.aborted) {
-      const { done, value } = await reader.read();
-      if (done) break;
-      buf += dec.decode(value, { stream: true });
-      let i;
-      while ((i = buf.indexOf('\n\n')) !== -1) {
-        const frame = buf.slice(0, i); buf = buf.slice(i + 2);
-        for (const line of frame.split('\n')) {
-          if (!line.startsWith('data: ')) continue;
-          try { handleEvent(JSON.parse(line.slice(6))); } catch {}
-        }
-      }
-    }
-  }).catch(() => { /* dropped — user can refresh to reconnect */ });
+  if (unsubWorkerStarted) { try { unsubWorkerStarted(); } catch {} }
+  if (unsubWorkerHeartbeat) { try { unsubWorkerHeartbeat(); } catch {} }
+  if (unsubWorkerFinished) { try { unsubWorkerFinished(); } catch {} }
+  unsubWorkerStarted   = onSystemEvent('worker_started',   handleEvent);
+  unsubWorkerHeartbeat = onSystemEvent('worker_heartbeat', handleEvent);
+  unsubWorkerFinished  = onSystemEvent('worker_finished',  handleEvent);
 }
 
 // Tiny HTML escapers (kept local to avoid an import cycle).

package/public/js/app.js

@@ -14,6 +14,7 @@ import { loadList, renderList, clearSearch, ensureFolderCache } from './list-vie
 import { openMessage } from './message-view.js';
 import { populateComposeFrom, openCompose, openDraft, closeCompose, discardCompose, sendCompose } from './compose.js';
 import { subscribeToAllAgents, maybeRequestNotificationPermission } from './sse.js';
+import { connectSystemStream } from './system-stream.js';
 import { subscribeToActivity } from './activity-badges.js';
 import { icon } from './icons.js';
 import { isSoundEnabled, setSoundEnabled, playNotificationSound } from './sound.js';
@@ -111,12 +112,14 @@ async function bootstrap() {
     if (initial) await selectAgent(initial);
     renderProfile();
     populateComposeFrom();
-    subscribeToAllAgents();
-    // Real-time worker activity badges. Master-key-scoped SSE on
-    // /system/events; the dispatcher's worker_started /
-    // worker_heartbeat / worker_finished events drive the badge
-    // rendering. Idempotent — safe to call after bootstrap reruns.
-    subscribeToActivity();
+    // ONE shared SSE connection on /system/events for the whole UI.
+    // Used to be N+1 (one per agent for new mail + one for activity
+    // badges), which saturated the browser's 6-connections-per-origin
+    // cap with 5 agents and blocked page navigation. Now everything
+    // multiplexes through this single stream — see system-stream.js.
+    connectSystemStream();
+    subscribeToAllAgents();   // new_mail handlers
+    subscribeToActivity();    // worker_* handlers
     maybeRequestNotificationPermission();
     // If the URL points at a message (not a folder), open it now —
     // the folder list selectAgent already loaded stays in the
@@ -176,10 +179,20 @@ function onFolderSelect(folder) {
 // Folder switches go through here too so the URL is the source of truth
 // for "what's on screen". If you bookmark or copy-paste a URL like
 // http://127.0.0.1:3829/#/folder/sent, opening it lands you on Sent.
+// Track which view shape is currently on screen so the router knows
+// whether navigating back to #/folder/<x> for the SAME folder should
+// re-render the list. Without this, hitting Back from #/m/54 to
+// #/folder/inbox would early-return because state.selectedFolder is
+// still 'inbox' (it never changed when the message opened) — leaving
+// the message-detail view stuck on screen even though the URL bar
+// flipped back to the folder.
+let currentView = 'folder';   // 'folder' | 'message' | 'draft'
+
 function route() {
   const hash = location.hash || '#/inbox';
   const msgMatch = hash.match(/^#\/m\/(\d+)$/);
   if (msgMatch) {
+    currentView = 'message';
     openMessage(Number(msgMatch[1]));
     return;
   }
@@ -188,23 +201,27 @@ function route() {
   // row click handler emits #/d/<uuid> for draft rows.
   const draftMatch = hash.match(/^#\/d\/([a-zA-Z0-9-]+)$/);
   if (draftMatch) {
+    currentView = 'draft';
     openDraft(draftMatch[1]);
     return;
   }
   const folderMatch = hash.match(/^#\/folder\/([a-z]+)$/);
   const folder = folderMatch ? folderMatch[1] : 'inbox';
-  // Only do work if the folder actually changed. Re-firing loadList
-  // for the SAME folder on every hashchange (e.g. closing a message
-  // detail back to the list) makes the UI feel sluggish — the list
-  // is already rendered, and a second digest fetch just churns
-  // through 50 messages on the IMAP server for no visible change.
-  if (state.selectedFolder === folder) return;
+  // Skip the reload ONLY when we're already showing this folder's
+  // list view. Coming back from a message / draft → folder must
+  // always re-render the list, even if state.selectedFolder hasn't
+  // changed since the message was opened.
+  if (currentView === 'folder' && state.selectedFolder === folder) return;
+  const folderChanged = state.selectedFolder !== folder;
   state.selectedFolder = folder;
-  // Reset pagination on every folder switch — a fresh folder
-  // starts at page 1. Preserved across silent SSE refreshes so
-  // a new arrival doesn't yank the user back from page 3.
-  state.pagination = { offset: 0, limit: 50, total: 0 };
-  renderSidebar(onFolderSelect);
+  currentView = 'folder';
+  if (folderChanged) {
+    // Fresh folder → page 1. Preserved across silent SSE refreshes so
+    // a new arrival doesn't yank the user back from page 3. We also
+    // re-render the sidebar so the active-folder highlight updates.
+    state.pagination = { offset: 0, limit: 50, total: 0 };
+    renderSidebar(onFolderSelect);
+  }
   if (state.selectedAgent) loadList(state.selectedAgent, folder);
 }
 window.addEventListener('hashchange', route);

package/public/js/sse.js

@@ -1,47 +1,35 @@
-// Real-time mail delivery via Server-Sent Events. Every agent gets
-// its own subscription; the dispatcher pushes a `new` event per
-// arrived message. We fan that out to:
-//   1. List view — silent in-place refresh (no flicker, no scroll
-//      jump, no bulk-selection wipe) if it's the active inbox
-//   2. Profile dropdown — bump the per-agent unread counter
-//   3. Browser notification — system ping when the tab is in the background
-//   4. Soft chime (toggleable) when sound is enabled
-import { state, API_URL } from './state.js';
+// New-mail notifications for the web UI.
+//
+// Listens for `new_mail` events on the shared /system/events stream
+// (one connection for the whole UI; see system-stream.js for why).
+// Fans the event out to:
+//   1. List view — silent in-place refresh (no flicker / scroll jump)
+//      if it's the active inbox.
+//   2. Profile dropdown — bump the per-agent unread counter.
+//   3. Browser notification when tab isn't focused.
+//   4. Soft chime (toggleable) when sound is enabled.
+
+import { state } from './state.js';
 import { toast } from './utils.js';
 import { renderProfile } from './profile.js';
 import { silentRefresh } from './list-view.js';
 import { playNotificationSound } from './sound.js';
+import { onSystemEvent } from './system-stream.js';
+
+let unsubscribe = null;
 
+/**
+ * Wire the new-mail listener onto the shared system stream.
+ * Idempotent — safe to call after agent-list refreshes.
+ */
 export function subscribeToAllAgents() {
-  // Tear down previous controllers (called on agent-list refresh).
-  for (const c of state.sseControllers) { try { c.abort(); } catch {} }
-  state.sseControllers = [];
-  for (const agent of state.agents) {
-    const ctrl = new AbortController();
-    state.sseControllers.push(ctrl);
-    fetch(`${API_URL}/api/agenticmail/events`, {
-      headers: { Authorization: `Bearer ${agent.apiKey}`, Accept: 'text/event-stream' },
-      signal: ctrl.signal,
-    }).then(async res => {
-      if (!res.ok || !res.body) return;
-      const reader = res.body.getReader();
-      const dec = new TextDecoder();
-      let buf = '';
-      while (!ctrl.signal.aborted) {
-        const { done, value } = await reader.read();
-        if (done) break;
-        buf += dec.decode(value, { stream: true });
-        let i;
-        while ((i = buf.indexOf('\n\n')) !== -1) {
-          const frame = buf.slice(0, i); buf = buf.slice(i + 2);
-          for (const line of frame.split('\n')) {
-            if (!line.startsWith('data: ')) continue;
-            try { handleSseEvent(agent, JSON.parse(line.slice(6))); } catch {}
-          }
-        }
-      }
-    }).catch(() => {});
-  }
+  if (unsubscribe) { try { unsubscribe(); } catch {} }
+  unsubscribe = onSystemEvent('new_mail', payload => {
+    // payload shape: { type: 'new_mail', agentId, agentName, event }
+    const agent = state.agents.find(a => a.id === payload.agentId);
+    if (!agent) return;  // unknown agent (account_deleted race)
+    handleSseEvent(agent, payload.event);
+  });
 }
 
 async function handleSseEvent(agent, event) {
@@ -52,23 +40,12 @@ async function handleSseEvent(agent, event) {
 
   const isOpen = state.selectedAgent?.id === agent.id;
   if (isOpen) {
-    // Silent in-place refresh — re-fetches the list digest and
-    // re-renders ONLY the rows div. Toolbar (select-all, refresh,
-    // bulk-actions) is untouched; existing row checkboxes survive;
-    // scroll position is preserved by the browser since we replace
-    // only the inner content. No "Loading…" flicker.
     await silentRefresh(agent, state.selectedFolder);
-    state.unread[agent.id] = 0;   // user is looking — clear badge
+    state.unread[agent.id] = 0;
     renderProfile();
   }
 
-  // Soft chime — respects the user's sound toggle. Plays for every
-  // arrival regardless of whether the tab is focused, because that
-  // is the whole point of the chime (a foregrounded tab still
-  // benefits from the audible ping when the user's attention is
-  // elsewhere on screen).
   playNotificationSound();
-
   fireBrowserNotification(agent, event, isOpen);
 
   if (!isOpen) {
@@ -103,8 +80,6 @@ function fireBrowserNotification(agent, event, isOpen) {
     });
     n.onclick = () => {
       window.focus();
-      // Switching agent here requires the router; let the user click
-      // through manually so we don't tightly couple sse → router.
       if (event.uid) location.hash = `#/m/${event.uid}`;
       n.close();
     };

package/public/js/state.js

@@ -10,7 +10,6 @@ export const state = {
   currentMessage: null,
   composeReplyContext: null,
   searchQuery: '',
-  sseControllers: [],
   unread: {},                  // { [agentId]: count }
   /**
    * Mapping from sidebar folder id ('sent', 'drafts', 'spam', etc.)

package/public/js/system-stream.js

@@ -0,0 +1,109 @@
+// Single shared SSE connection to /system/events.
+//
+// # Why this exists
+//
+// Browsers cap HTTP connections at 6 per origin. The old web UI opened
+// ONE per-agent /events SSE plus ONE /system/events SSE — so with 5
+// agents, that's 6 long-lived connections, exhausting the cap. Every
+// other request (page refresh, message fetch, attachment download)
+// had to wait for an SSE slot to free up, which never happened
+// because they're persistent.
+//
+// Fix: every per-agent new-mail event is now also pushed to
+// /system/events by the API. The UI subscribes ONCE here, and modules
+// register handlers via `onSystemEvent(type, handler)`. Net effect:
+// 6 SSE connections → 1, freeing 5 slots for actual HTTP traffic.
+//
+// # API
+//
+//   import { connectSystemStream, onSystemEvent } from './system-stream.js';
+//   connectSystemStream();                        // wire it up once after sign-in
+//   onSystemEvent('new_mail', (e) => { ... });    // subscribe to event type
+//   onSystemEvent('worker_started', (e) => {});   // ANY type the server emits
+//
+// Multiple subscribers per type are supported. Each handler runs in
+// try/catch so one buggy handler can't kill the others.
+
+import { state, API_URL } from './state.js';
+
+let controller = null;
+let connected = false;
+const handlers = new Map();          // type → Set<handler>
+
+export function onSystemEvent(type, handler) {
+  if (!handlers.has(type)) handlers.set(type, new Set());
+  handlers.get(type).add(handler);
+  return () => handlers.get(type)?.delete(handler);
+}
+
+function dispatch(event) {
+  if (!event || typeof event !== 'object') return;
+  const set = handlers.get(event.type);
+  if (!set) return;
+  for (const h of set) {
+    try { h(event); } catch (err) { console.error('[system-stream] handler error', err); }
+  }
+}
+
+export function connectSystemStream() {
+  if (controller) { try { controller.abort(); } catch {} }
+  controller = new AbortController();
+  connected = false;
+  const sig = controller.signal;
+
+  // Auto-reconnect with exponential backoff. Capped at 30s — keeping
+  // a UI live during a long server outage shouldn't slam the API
+  // every two seconds.
+  let backoff = 1000;
+  const loop = async () => {
+    while (!sig.aborted) {
+      try {
+        const res = await fetch(`${API_URL}/api/agenticmail/system/events`, {
+          headers: { Authorization: `Bearer ${state.masterKey}`, Accept: 'text/event-stream' },
+          signal: sig,
+        });
+        if (!res.ok || !res.body) {
+          // Hard 4xx (auth) → stop trying; user has to refresh / sign in again.
+          if (res.status === 401 || res.status === 403) return;
+          throw new Error(`/system/events HTTP ${res.status}`);
+        }
+        connected = true;
+        backoff = 1000;  // healthy connection — reset
+        const reader = res.body.getReader();
+        const dec = new TextDecoder();
+        let buf = '';
+        while (!sig.aborted) {
+          const { done, value } = await reader.read();
+          if (done) break;
+          buf += dec.decode(value, { stream: true });
+          let i;
+          while ((i = buf.indexOf('\n\n')) !== -1) {
+            const frame = buf.slice(0, i); buf = buf.slice(i + 2);
+            for (const line of frame.split('\n')) {
+              if (!line.startsWith('data: ')) continue;
+              try { dispatch(JSON.parse(line.slice(6))); } catch {}
+            }
+          }
+        }
+      } catch (err) {
+        if (sig.aborted) return;
+        // Stream dropped — wait + reconnect.
+      }
+      connected = false;
+      if (sig.aborted) return;
+      await new Promise(r => setTimeout(r, backoff));
+      backoff = Math.min(backoff * 2, 30_000);
+    }
+  };
+  loop();
+}
+
+export function isSystemStreamConnected() {
+  return connected;
+}
+
+export function disconnectSystemStream() {
+  if (controller) { try { controller.abort(); } catch {} }
+  controller = null;
+  connected = false;
+}