@agenticmail/api 0.7.20 → 0.9.0

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

@@ -903,7 +903,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 +1190,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 +1801,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 addr = String(raw).trim().toLowerCase();
+    if (!addr.endsWith("@localhost")) continue;
+    const m = addr.match(/<([^>]+)>/);
+    const bare = m ? m[1].trim() : addr;
+    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(", ") };
@@ -1880,15 +1898,21 @@ async function notifyLocalRecipientsOfNewMail(accountManager2, toField, ccField,
     });
   }
 }
-function saveSentCopy(authUser, password, config, raw) {
-  (async () => {
-    try {
-      const receiver = await getReceiver(authUser, password, config);
-      await receiver.appendMessage(raw, "Sent Items", ["\\Seen"]);
-    } catch (err) {
-      console.warn(`[mail] Failed to save Sent copy for ${authUser}: ${err.message}`);
+var sentFolderCache = /* @__PURE__ */ new Map();
+async function saveSentCopy(authUser, password, config, raw) {
+  try {
+    const receiver = await getReceiver(authUser, password, config);
+    let folder = sentFolderCache.get(authUser);
+    if (!folder) {
+      const folders = await receiver.listFolders();
+      const sentRe = /^sent\b|sent items|sent mail|sent messages|\[gmail\]\/sent/i;
+      folder = folders.find((f) => f.specialUse === "\\Sent")?.path ?? folders.find((f) => sentRe.test(f.name) || sentRe.test(f.path))?.path ?? "Sent Items";
+      sentFolderCache.set(authUser, folder);
     }
-  })();
+    await receiver.appendMessage(raw, folder, ["\\Seen"]);
+  } catch (err) {
+    console.warn(`[mail] Failed to save Sent copy for ${authUser}: ${err.message}`);
+  }
 }
 function createMailRoutes(accountManager2, config, db, gatewayManager) {
   const router = Router6();
@@ -1927,7 +1951,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,
@@ -2010,7 +2035,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,
@@ -2502,6 +2528,95 @@ function createMailRoutes(accountManager2, config, db, gatewayManager) {
       next(err);
     }
   });
+  router.post("/mail/messages/:uid/archive", requireAgent, async (req, res, next) => {
+    try {
+      const agent = req.agent;
+      const uid = parseInt(req.params.uid);
+      if (isNaN(uid) || uid < 1) {
+        res.status(400).json({ error: "Invalid UID" });
+        return;
+      }
+      const sourceFolder = req.body?.folder || "INBOX";
+      const password = getAgentPassword(agent);
+      const receiver = await getReceiver(agent.stalwartPrincipal, password, config);
+      const folders = await receiver.listFolders();
+      const archiveRe = /^archives?\b|^all archive\b/i;
+      let archiveFolder = folders.find((f) => f.specialUse === "\\Archive")?.path ?? folders.find((f) => archiveRe.test(f.name) || archiveRe.test(f.path))?.path;
+      if (!archiveFolder) {
+        try {
+          await receiver.createFolder("Archive");
+        } catch {
+        }
+        archiveFolder = "Archive";
+      }
+      if (archiveFolder === sourceFolder) {
+        res.status(400).json({ error: "Message already in archive" });
+        return;
+      }
+      await receiver.moveMessage(uid, sourceFolder, archiveFolder);
+      res.json({ ok: true, archive: archiveFolder });
+    } catch (err) {
+      next(err);
+    }
+  });
+  router.post("/mail/batch/archive", requireAgent, async (req, res, next) => {
+    try {
+      const agent = req.agent;
+      const { uids: rawUids, folder } = req.body || {};
+      const uids = validateUids(rawUids);
+      if (!uids) {
+        res.status(400).json({ error: "uids must be a non-empty array of positive integers (max 1000)" });
+        return;
+      }
+      const sourceFolder = folder || "INBOX";
+      const password = getAgentPassword(agent);
+      const receiver = await getReceiver(agent.stalwartPrincipal, password, config);
+      const folders = await receiver.listFolders();
+      const archiveRe = /^archives?\b|^all archive\b/i;
+      let archiveFolder = folders.find((f) => f.specialUse === "\\Archive")?.path ?? folders.find((f) => archiveRe.test(f.name) || archiveRe.test(f.path))?.path;
+      if (!archiveFolder) {
+        try {
+          await receiver.createFolder("Archive");
+        } catch {
+        }
+        archiveFolder = "Archive";
+      }
+      if (archiveFolder === sourceFolder) {
+        res.status(400).json({ error: "Messages already in archive" });
+        return;
+      }
+      await receiver.batchMove(uids, sourceFolder, archiveFolder);
+      res.json({ ok: true, archived: uids.length, archive: archiveFolder });
+    } catch (err) {
+      next(err);
+    }
+  });
+  router.post("/mail/batch/trash", requireAgent, async (req, res, next) => {
+    try {
+      const agent = req.agent;
+      const { uids: rawUids, folder } = req.body || {};
+      const uids = validateUids(rawUids);
+      if (!uids) {
+        res.status(400).json({ error: "uids must be a non-empty array of positive integers (max 1000)" });
+        return;
+      }
+      const sourceFolder = folder || "INBOX";
+      const password = getAgentPassword(agent);
+      const receiver = await getReceiver(agent.stalwartPrincipal, password, config);
+      const folders = await receiver.listFolders();
+      const trashRe = /^trash\b|deleted items|deleted messages|\[gmail\]\/trash|\[gmail\]\/bin/i;
+      const trashFolder = folders.find((f) => f.specialUse === "\\Trash")?.path ?? folders.find((f) => trashRe.test(f.name) || trashRe.test(f.path))?.path;
+      if (!trashFolder || trashFolder === sourceFolder) {
+        await receiver.batchDelete(uids, sourceFolder);
+        res.json({ ok: true, deleted: uids.length });
+        return;
+      }
+      await receiver.batchMove(uids, sourceFolder, trashFolder);
+      res.json({ ok: true, trashed: uids.length, trash: trashFolder });
+    } catch (err) {
+      next(err);
+    }
+  });
   router.post("/mail/messages/:uid/spam", requireAgent, async (req, res, next) => {
     try {
       const agent = req.agent;
@@ -5101,6 +5216,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 {
@@ -5201,6 +5401,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.20",
+  "version": "0.9.0",
   "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.0",
     "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.0"
   },
   "devDependencies": {
     "@types/cors": "^2.8.17",

package/public/js/icons.js

@@ -32,6 +32,8 @@ const PATHS = {
 
   // ─── Sidebar folders ────────────────────────────────────────────
   inbox:   'M19 3H5a2 2 0 0 0-2 2v14a2 2 0 0 0 2 2h14a2 2 0 0 0 2-2V5a2 2 0 0 0-2-2zm0 12h-4c0 1.66-1.35 3-3 3s-3-1.34-3-3H5V5h14v10z',
+  // Material-style archive: lidded box with horizontal slot.
+  archive: 'M20.54 5.23l-1.39-1.68A1.45 1.45 0 0 0 18 3H6c-.47 0-.88.21-1.16.55L3.46 5.23A2 2 0 0 0 3 6.5V19a2 2 0 0 0 2 2h14a2 2 0 0 0 2-2V6.5c0-.5-.18-.96-.46-1.27zM12 17.5L6.5 12H10v-2h4v2h3.5L12 17.5zM5.12 5l.82-1h12l.93 1H5.12z',
   sent:    'M2.01 21 23 12 2.01 3 2 10l15 2-15 2z',
   drafts:  'M19 3H4.99c-1.11 0-1.98.9-1.98 2L3 19a2 2 0 0 0 2 2h14c1.1 0 2-.9 2-2v-7l-8 5-8-5V5l8 5 8-5v2h2V5a2 2 0 0 0-2-2z',
   allMail: 'M22 4h-2v9.38l-2.79-2.79L16 12l4 4 4-4-1.21-1.21L22 13.38V4zM4 4a2 2 0 0 0-2 2v12a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V8h-2v10H4V6h12V4H4z',

package/public/js/list-view.js

@@ -38,6 +38,11 @@ const FOLDER_MATCHERS = {
   drafts:  /^drafts?\b|\[gmail\]\/drafts/i,
   spam:    /^junk\b|junk mail|^spam\b|\[gmail\]\/spam/i,
   trash:   /^trash\b|deleted items|deleted messages|\[gmail\]\/trash|\[gmail\]\/bin/i,
+  // Archive is a Gmail/Outlook concept — most servers don't ship
+  // with one by default. We auto-create on demand (see the API's
+  // archive endpoint) so this matcher only needs to recognise
+  // existing folders.
+  archive: /^archives?\b|^all archive\b/i,
   all:     /^all mail\b|\[gmail\]\/all/i,
 };
 
@@ -72,10 +77,11 @@ export async function ensureFolderCache(agent) {
   } catch {
     // Discovery failed — fall back to the most common defaults so
     // at least Inbox + Sent work for vanilla Stalwart.
-    state.folderNames.sent   = 'Sent Items';
-    state.folderNames.drafts = 'Drafts';
-    state.folderNames.spam   = 'Junk Mail';
-    state.folderNames.trash  = 'Trash';
+    state.folderNames.sent    = 'Sent Items';
+    state.folderNames.drafts  = 'Drafts';
+    state.folderNames.spam    = 'Junk Mail';
+    state.folderNames.trash   = 'Trash';
+    state.folderNames.archive = 'Archive';
   }
 }
 
@@ -91,6 +97,14 @@ export async function loadList(agent, folder) {
         <input type="checkbox" id="list-select-all-input" />
       </label>
       <button class="icon-btn list-refresh" title="Refresh" id="list-refresh-btn">${icon('refresh', { size: 18 })}</button>
+      <div class="bulk-actions" id="bulk-actions" hidden>
+        <button class="icon-btn bulk-btn" id="bulk-archive" title="Archive selected">${icon('archive', { size: 18 })}</button>
+        <button class="icon-btn bulk-btn" id="bulk-delete" title="Delete selected">${icon('trash', { size: 18 })}</button>
+        <button class="icon-btn bulk-btn" id="bulk-spam" title="Report as spam">${icon('spam', { size: 18 })}</button>
+        <button class="icon-btn bulk-btn" id="bulk-mark-read" title="Mark as read">${icon('check', { size: 18 })}</button>
+        <button class="icon-btn bulk-btn" id="bulk-mark-unread" title="Mark as unread">${icon('mailUnread', { size: 18 })}</button>
+        <span class="bulk-count" id="bulk-count"></span>
+      </div>
       <div class="list-toolbar-spacer"></div>
       <span class="count-text" id="list-count"></span>
     </div>
@@ -101,7 +115,17 @@ export async function loadList(agent, folder) {
     const checked = e.target.checked;
     document.querySelectorAll('#list-rows .row-check input[type=checkbox]')
       .forEach(cb => { cb.checked = checked; });
+    updateBulkActions();
   });
+  // Wire bulk-action handlers — each gathers the selected UIDs,
+  // calls the matching batch endpoint, and reloads the list. The
+  // toolbar visibility is driven by `updateBulkActions` which is
+  // called every time a checkbox flips.
+  document.getElementById('bulk-archive')?.addEventListener('click', () => runBulkAction(agent, folder, 'archive'));
+  document.getElementById('bulk-delete')?.addEventListener('click',  () => runBulkAction(agent, folder, 'delete'));
+  document.getElementById('bulk-spam')?.addEventListener('click',    () => runBulkAction(agent, folder, 'spam'));
+  document.getElementById('bulk-mark-read')?.addEventListener('click',   () => runBulkAction(agent, folder, 'mark-read'));
+  document.getElementById('bulk-mark-unread')?.addEventListener('click', () => runBulkAction(agent, folder, 'mark-unread'));
 
   // Drafts are a SQL-backed app primitive, not an IMAP mailbox.
   // The autosave path writes to /drafts (sqlite) and the agent
@@ -204,6 +228,20 @@ export function renderList() {
   if (state.selectedFolder === 'starred') {
     filtered = filtered.filter(m => flagsHas(m.flags, '\\Flagged'));
   }
+  // Defensive Sent-folder filter. The API serves the IMAP Sent
+  // mailbox directly, but some Stalwart configurations (or
+  // misconfigured saveSentCopy targets) can land messages whose
+  // sender ISN'T the active agent in Sent. Filter client-side
+  // so the user only ever sees messages they actually sent.
+  // This is a safety net — the server-side fix lives in
+  // saveSentCopy and the dispatcher's send path.
+  if (state.selectedFolder === 'sent' && state.selectedAgent?.email) {
+    const me = state.selectedAgent.email.toLowerCase();
+    filtered = filtered.filter(m => {
+      const fromAddr = (m.from?.[0]?.address ?? '').toLowerCase();
+      return fromAddr === me;
+    });
+  }
 
   const hlTerm = filters?.subject || filters?.from || filters?.text || '';
 
@@ -270,6 +308,12 @@ export function renderList() {
   }).join('');
 
   root.querySelectorAll('.list-row').forEach(el => {
+    // Checkbox change on individual rows — drives the bulk-action
+    // toolbar visibility. Attached separately from the row click
+    // handler so clicking the box doesn't propagate to "open
+    // message".
+    const cb = el.querySelector('.row-check input[type=checkbox]');
+    cb?.addEventListener('change', updateBulkActions);
     el.addEventListener('click', (e) => {
       // Star click — toggle via API and optimistically update the
       // local flags so the icon flips without a reload.
@@ -298,6 +342,112 @@ export function renderList() {
   });
 }
 
+/**
+ * Read every checked row's UID. Empty array when nothing is
+ * selected. Used by the bulk-action handlers and toolbar
+ * visibility logic.
+ */
+function getSelectedUids() {
+  const uids = [];
+  document.querySelectorAll('#list-rows .list-row').forEach(row => {
+    const cb = row.querySelector('.row-check input[type=checkbox]');
+    if (cb?.checked) {
+      const uid = Number(row.dataset.uid);
+      if (Number.isFinite(uid)) uids.push(uid);
+    }
+  });
+  return uids;
+}
+
+/**
+ * Toggle the visibility of the bulk-action toolbar based on
+ * current selection. Also updates the count label so the user
+ * sees "3 selected" etc. Called on every checkbox change +
+ * after each successful bulk action.
+ */
+function updateBulkActions() {
+  const uids = getSelectedUids();
+  const bar = document.getElementById('bulk-actions');
+  const count = document.getElementById('bulk-count');
+  if (!bar || !count) return;
+  if (uids.length === 0) {
+    bar.hidden = true;
+    return;
+  }
+  bar.hidden = false;
+  count.textContent = `${uids.length} selected`;
+}
+
+/**
+ * Execute a bulk action against every currently-selected row.
+ * Maps the action name to the matching batch endpoint, fires
+ * one request, then reloads the list so the rows disappear /
+ * change visibly. Confirm dialogs only on destructive actions
+ * (delete, spam) — archive + mark-read/unread are silent.
+ */
+async function runBulkAction(agent, folder, action) {
+  const uids = getSelectedUids();
+  if (uids.length === 0) return;
+  const imap = state.folderNames?.[folder] ?? 'INBOX';
+  let confirmTitle = '';
+  let confirmBody = '';
+  let confirmLabel = '';
+  let endpoint = '';
+  let body = { uids, folder: imap };
+  let danger = false;
+  switch (action) {
+    case 'archive':
+      endpoint = '/mail/batch/archive';
+      break;
+    case 'delete':
+      // From Trash, batch/trash falls through to permanent
+      // expunge; everywhere else it's a move-to-trash.
+      endpoint = '/mail/batch/trash';
+      danger = true;
+      confirmTitle = folder === 'trash' ? `Delete ${uids.length} message${uids.length === 1 ? '' : 's'} forever?` : `Move ${uids.length} message${uids.length === 1 ? '' : 's'} to Trash?`;
+      confirmBody = folder === 'trash' ? "This can't be undone." : 'You can recover them from Trash.';
+      confirmLabel = folder === 'trash' ? 'Delete forever' : 'Move to Trash';
+      break;
+    case 'spam':
+      // No batch/spam route yet — fall back to batch/move with
+      // the auto-discovered Spam folder.
+      endpoint = '/mail/batch/move';
+      body.toFolder = state.folderNames?.spam ?? 'Junk Mail';
+      danger = true;
+      confirmTitle = `Report ${uids.length} message${uids.length === 1 ? '' : 's'} as spam?`;
+      confirmBody = 'They will be moved to the Junk folder.';
+      confirmLabel = 'Report spam';
+      break;
+    case 'mark-read':
+      endpoint = '/mail/batch/seen';
+      break;
+    case 'mark-unread':
+      endpoint = '/mail/batch/unseen';
+      break;
+    default:
+      return;
+  }
+  if (confirmTitle) {
+    const { confirmModal } = await import('./modal.js');
+    const ok = await confirmModal({ title: confirmTitle, body: confirmBody, confirm: confirmLabel, danger });
+    if (!ok) return;
+  }
+  try {
+    await apiPost(endpoint, body, { agentKey: agent.apiKey });
+    toast(`${uids.length} message${uids.length === 1 ? '' : 's'} ${
+      action === 'archive' ? 'archived' :
+      action === 'delete' ? (folder === 'trash' ? 'deleted' : 'moved to Trash') :
+      action === 'spam' ? 'reported as spam' :
+      action === 'mark-read' ? 'marked as read' :
+      'marked as unread'
+    }.`);
+    // Reload so the rows that moved/changed visibly update.
+    await loadList(agent, folder);
+  } catch (err) {
+    toast(`Bulk ${action} failed: ${err.message}`, true);
+  }
+}
+
 /**
  * Toggle the IMAP \Flagged flag on a message via the API. Updates
  * the in-memory message object on success so renderList reflects

package/public/js/message-view.js

@@ -19,6 +19,7 @@ export async function openMessage(uid) {
       <button class="icon-btn" id="msg-back" title="Back to list">${icon('back')}</button>
       <button class="icon-btn" id="msg-reply" title="Reply">${icon('reply')}</button>
       <button class="icon-btn" id="msg-reply-all" title="Reply all">${icon('replyAll')}</button>
+      <button class="icon-btn" id="msg-archive" title="Archive">${icon('archive')}</button>
       <button class="icon-btn" id="msg-unread" title="Mark unread">${icon('mailUnread')}</button>
       <button class="icon-btn" id="msg-spam" title="Report spam">${icon('spam')}</button>
       <button class="icon-btn" id="msg-delete" title="Delete">${icon('trash')}</button>
@@ -29,6 +30,7 @@ export async function openMessage(uid) {
   document.getElementById('msg-back').addEventListener('click', () => { location.hash = `#/folder/${state.selectedFolder ?? 'inbox'}`; });
   document.getElementById('msg-reply').addEventListener('click', () => openReply(false));
   document.getElementById('msg-reply-all').addEventListener('click', () => openReply(true));
+  document.getElementById('msg-archive').addEventListener('click', () => archiveMessage());
   document.getElementById('msg-unread').addEventListener('click', () => markUnread());
   document.getElementById('msg-spam').addEventListener('click', () => markSpam());
   document.getElementById('msg-delete').addEventListener('click', () => deleteMessage());
@@ -219,6 +221,24 @@ async function markUnread() {
  * route is POST /mail/messages/:uid/spam — it does the move +
  * flags the message so future scans treat it as known spam.
  */
+/**
+ * Archive the open message — move it to the Archive folder.
+ * No confirm dialog; archive is non-destructive (Gmail UX) so
+ * the user can always go to Archive and move things back.
+ */
+async function archiveMessage() {
+  if (!state.currentMessage || !state.selectedAgent) return;
+  try {
+    const imap = state.folderNames?.[state.selectedFolder] ?? 'INBOX';
+    await apiPost(`/mail/messages/${state.selectedUid}/archive`, { folder: imap }, { agentKey: state.selectedAgent.apiKey });
+    toast('Archived.');
+    location.hash = `#/folder/${state.selectedFolder ?? 'inbox'}`;
+    await loadList(state.selectedAgent, state.selectedFolder);
+  } catch (err) {
+    toast(`Archive failed: ${err.message}`, true);
+  }
+}
+
 async function markSpam() {
   if (!state.currentMessage || !state.selectedAgent) return;
   const ok = await confirmModal({

package/public/js/sidebar.js

@@ -19,6 +19,7 @@ export const FOLDERS = [
   { id: 'starred', label: 'Starred',  icon: 'starOutline' },
   { id: 'sent',    label: 'Sent',     icon: 'sent' },
   { id: 'drafts',  label: 'Drafts',   icon: 'drafts' },
+  { id: 'archive', label: 'Archive',  icon: 'archive' },
   { id: 'all',     label: 'All Mail', icon: 'allMail', requiresDiscovery: true },
   { id: 'spam',    label: 'Spam',     icon: 'spam' },
   { id: 'trash',   label: 'Trash',    icon: 'trash' },

package/public/styles.css

@@ -419,6 +419,27 @@ a { color: var(--accent-strong); }
   font-size: 12px; color: var(--muted);
 }
 
+/* Bulk-action toolbar — appears between select-all and refresh
+   when one or more rows are checked. Replaces the visual idle
+   state of the row (toolbar) with action buttons + a "N selected"
+   indicator on the right. */
+.bulk-actions {
+  display: flex; align-items: center; gap: 4px;
+  margin-left: 8px;
+  padding-left: 12px;
+  border-left: 1px solid var(--line);
+}
+.bulk-actions[hidden] { display: none; }
+.bulk-actions .bulk-btn {
+  width: 36px; height: 36px;
+  color: var(--ink-soft);
+}
+.bulk-actions .bulk-btn:hover { background: var(--bg-hover); color: var(--ink); }
+.bulk-count {
+  font-size: 12px; font-weight: 500; color: var(--accent-strong);
+  margin-left: 8px;
+}
+
 /* Gmail-style compact rows.
    Single line per message; subject + preview share one truncated
    cell so longer previews tail off with ellipsis instead of
@@ -576,6 +597,13 @@ mark.search-hl {
   max-width: 840px;
   margin: 0 auto;
   width: 100%;
+  /* Clear visual end-of-message marker. The reply / quoted-thread
+     chrome above made the body's bottom ambiguous; a hairline rule
+     gives the reader a definite stop and separates from the
+     attachments / next message in stack views. */
+  border-bottom: 1px solid var(--line);
+  padding-bottom: 28px;
+  margin-bottom: 8px;
 }
 .message-body h1, .message-body h2, .message-body h3 {
   color: var(--pink); margin: 1.2em 0 .4em;