hypermail-mcp 0.7.12 → 0.7.13

package/README.md

@@ -3,6 +3,12 @@
 A **Model Context Protocol** server that lets an agent operate any of the user's
 inboxes through a single, unified tool surface.
 
+> **v0.7.13** — Hardened `get_new_emails` against duplicate delivery when
+> multiple MCP processes share the same encrypted account store. Store writes
+> now reload and merge under a cross-process lock, checkpoints are monotonic,
+> and new-email batches are atomically claimed before being returned. `trash_email`
+> also now uses provider-native trash operations for Gmail and IMAP trash aliases.
+>
 > **v0.7.12** — Hardened Outlook reply/forward draft formatting when
 > Microsoft Graph labels generated thread history as HTML but returns
 > plain/unstructured text. Such histories are now defensively normalized with

package/dist/cli.js

@@ -13956,16 +13956,21 @@ async function tryKeytarSet(key) {
 
 // src/store/account-store.ts
 var FILE_NAME = "accounts.json.enc";
+var LOCK_STALE_MS = 3e4;
+var LOCK_TIMEOUT_MS = 1e4;
+var LOCK_RETRY_MS = 25;
 var AccountStore = class _AccountStore {
   constructor(filePath, key, data) {
     this.filePath = filePath;
     this.key = key;
     this.data = data;
+    this.lockPath = `${filePath}.lock`;
   }
   filePath;
   key;
   data;
   writeLocks = /* @__PURE__ */ new Map();
+  lockPath;
   static async open(opts = {}) {
     const dataDir = resolveDataDir(opts.dataDir);
     await fs2.mkdir(dataDir, { recursive: true, mode: 448 });
@@ -13993,62 +13998,93 @@ var AccountStore = class _AccountStore {
     return rec ? { ...rec } : void 0;
   }
   async upsertAccount(rec) {
-    return this.runSerial(rec.email, async () => {
+    return this.runSerial(rec.email, async () => this.updateLocked((data) => {
       const norm = rec.email.trim().toLowerCase();
+      const idx = data.accounts.findIndex((a) => a.email.toLowerCase() === norm);
+      const current = idx >= 0 ? data.accounts[idx] : void 0;
       const next = { ...rec, email: norm };
-      const idx = this.data.accounts.findIndex((a) => a.email.toLowerCase() === norm);
-      if (idx >= 0) this.data.accounts[idx] = next;
-      else this.data.accounts.push(next);
-      await this.flush();
-      return { ...next };
-    });
+      const mergedCheckpoint = mergeNewEmailCheckpoints(
+        current?.newEmailCheckpoint,
+        rec.newEmailCheckpoint
+      );
+      if (mergedCheckpoint) next.newEmailCheckpoint = mergedCheckpoint;
+      else delete next.newEmailCheckpoint;
+      if (idx >= 0) data.accounts[idx] = next;
+      else data.accounts.push(next);
+      return { result: { ...next }, changed: true };
+    }));
   }
   async updateTokens(email, tokens) {
-    return this.runSerial(email, async () => {
+    return this.runSerial(email, async () => this.updateLocked((data) => {
       const norm = email.trim().toLowerCase();
-      const idx = this.data.accounts.findIndex((a) => a.email.toLowerCase() === norm);
-      if (idx < 0) return void 0;
-      const current = this.data.accounts[idx];
+      const idx = data.accounts.findIndex((a) => a.email.toLowerCase() === norm);
+      if (idx < 0) return { result: void 0, changed: false };
+      const current = data.accounts[idx];
       const next = { ...current, tokens };
-      this.data.accounts[idx] = next;
-      await this.flush();
-      return { ...next };
-    });
+      data.accounts[idx] = next;
+      return { result: { ...next }, changed: true };
+    }));
   }
   async updateNewEmailCheckpoint(email, checkpoint) {
-    return this.runSerial(email, async () => {
+    return this.runSerial(email, async () => this.updateLocked((data) => {
       const norm = email.trim().toLowerCase();
-      const idx = this.data.accounts.findIndex((a) => a.email.toLowerCase() === norm);
-      if (idx < 0) return void 0;
-      const current = this.data.accounts[idx];
-      const currentCheckpoint = current.newEmailCheckpoint;
-      const mergedCheckpoint = currentCheckpoint?.receivedAt === checkpoint.receivedAt ? {
-        receivedAt: checkpoint.receivedAt,
-        deliveredIdsAtReceivedAt: [
-          .../* @__PURE__ */ new Set([
-            ...currentCheckpoint.deliveredIdsAtReceivedAt ?? [],
-            ...checkpoint.deliveredIdsAtReceivedAt ?? []
-          ])
-        ]
-      } : checkpoint;
+      const idx = data.accounts.findIndex((a) => a.email.toLowerCase() === norm);
+      if (idx < 0) return { result: void 0, changed: false };
+      const current = data.accounts[idx];
+      const mergedCheckpoint = mergeNewEmailCheckpoints(
+        current.newEmailCheckpoint,
+        checkpoint
+      );
+      if (!mergedCheckpoint) return { result: { ...current }, changed: false };
       const next = {
         ...current,
         newEmailCheckpoint: mergedCheckpoint
       };
-      this.data.accounts[idx] = next;
-      await this.flush();
-      return { ...next };
-    });
+      data.accounts[idx] = next;
+      return { result: { ...next }, changed: true };
+    }));
+  }
+  async claimNewEmails(email, candidates) {
+    return this.runSerial(email, async () => this.updateLocked((data) => {
+      const norm = email.trim().toLowerCase();
+      const idx = data.accounts.findIndex((a) => a.email.toLowerCase() === norm);
+      if (idx < 0 || candidates.length === 0) return { result: [], changed: false };
+      const account = data.accounts[idx];
+      let checkpoint = normalizeCheckpoint(account.newEmailCheckpoint);
+      const claimed = [];
+      const ordered = [...candidates].sort((a, b) => {
+        const byTime = compareTimestamp(normalizeTimestamp(a.receivedAt) ?? a.receivedAt, normalizeTimestamp(b.receivedAt) ?? b.receivedAt);
+        if (byTime !== 0) return byTime;
+        return a.summaryId.localeCompare(b.summaryId);
+      });
+      for (const candidate of ordered) {
+        const receivedAt = normalizeTimestamp(candidate.receivedAt);
+        if (!receivedAt) continue;
+        const ids = uniqueIds([candidate.summaryId, ...candidate.ids]);
+        if (ids.length === 0) continue;
+        if (isAlreadyDelivered(checkpoint, receivedAt, ids)) continue;
+        claimed.push(candidate.summaryId);
+        checkpoint = mergeNewEmailCheckpoints(checkpoint, {
+          receivedAt,
+          deliveredIdsAtReceivedAt: ids
+        });
+      }
+      if (claimed.length === 0 || !checkpoint) return { result: claimed, changed: false };
+      const next = {
+        ...account,
+        newEmailCheckpoint: checkpoint
+      };
+      data.accounts[idx] = next;
+      return { result: claimed, changed: true };
+    }));
   }
   async removeAccount(email) {
-    return this.runSerial(email, async () => {
+    return this.runSerial(email, async () => this.updateLocked((data) => {
       const norm = email.trim().toLowerCase();
-      const before = this.data.accounts.length;
-      this.data.accounts = this.data.accounts.filter((a) => a.email.toLowerCase() !== norm);
-      if (this.data.accounts.length === before) return false;
-      await this.flush();
-      return true;
-    });
+      const before = data.accounts.length;
+      data.accounts = data.accounts.filter((a) => a.email.toLowerCase() !== norm);
+      return { result: data.accounts.length !== before, changed: data.accounts.length !== before };
+    }));
   }
   async runSerial(email, task) {
     const norm = email.trim().toLowerCase();
@@ -14067,11 +14103,120 @@ var AccountStore = class _AccountStore {
       }
     }
   }
+  async updateLocked(task) {
+    return this.withFileLock(async () => {
+      this.data = await this.readLatest();
+      const { result, changed } = await task(this.data);
+      if (changed) await this.flush();
+      return result;
+    });
+  }
+  async readLatest() {
+    try {
+      const buf = await fs2.readFile(this.filePath);
+      return decrypt(buf, this.key);
+    } catch (err) {
+      if (err.code === "ENOENT") {
+        return { version: 1, accounts: [] };
+      }
+      throw err;
+    }
+  }
   async flush() {
     const buf = encrypt(this.data, this.key);
     await writeAtomic(this.filePath, buf);
   }
+  async withFileLock(task) {
+    await this.acquireFileLock();
+    try {
+      return await task();
+    } finally {
+      await fs2.rm(this.lockPath, { recursive: true, force: true });
+    }
+  }
+  async acquireFileLock() {
+    const startedAt = Date.now();
+    while (true) {
+      try {
+        await fs2.mkdir(this.lockPath, { mode: 448 });
+        await fs2.writeFile(
+          path2.join(this.lockPath, "owner"),
+          `${process.pid}
+${(/* @__PURE__ */ new Date()).toISOString()}
+`,
+          { mode: 384 }
+        );
+        return;
+      } catch (err) {
+        if (err.code !== "EEXIST") throw err;
+        await this.removeStaleLock();
+        if (Date.now() - startedAt > LOCK_TIMEOUT_MS) {
+          throw new Error(`timed out waiting for account store lock: ${this.lockPath}`);
+        }
+        await delay(LOCK_RETRY_MS);
+      }
+    }
+  }
+  async removeStaleLock() {
+    try {
+      const stat = await fs2.stat(this.lockPath);
+      if (Date.now() - stat.mtimeMs > LOCK_STALE_MS) {
+        await fs2.rm(this.lockPath, { recursive: true, force: true });
+      }
+    } catch (err) {
+      if (err.code !== "ENOENT") throw err;
+    }
+  }
 };
+function normalizeCheckpoint(checkpoint) {
+  const receivedAt = normalizeTimestamp(checkpoint?.receivedAt);
+  if (!receivedAt) return void 0;
+  return {
+    receivedAt,
+    deliveredIdsAtReceivedAt: uniqueIds(checkpoint?.deliveredIdsAtReceivedAt ?? [])
+  };
+}
+function mergeNewEmailCheckpoints(current, incoming) {
+  const normalizedCurrent = normalizeCheckpoint(current);
+  const normalizedIncoming = normalizeCheckpoint(incoming);
+  if (!normalizedIncoming) return normalizedCurrent;
+  if (!normalizedCurrent) return normalizedIncoming;
+  const comparison = compareTimestamp(normalizedIncoming.receivedAt, normalizedCurrent.receivedAt);
+  if (comparison > 0) return normalizedIncoming;
+  if (comparison < 0) return normalizedCurrent;
+  return {
+    receivedAt: normalizedCurrent.receivedAt,
+    deliveredIdsAtReceivedAt: uniqueIds([
+      ...normalizedCurrent.deliveredIdsAtReceivedAt ?? [],
+      ...normalizedIncoming.deliveredIdsAtReceivedAt ?? []
+    ])
+  };
+}
+function isAlreadyDelivered(checkpoint, receivedAt, ids) {
+  if (!checkpoint) return false;
+  const comparison = compareTimestamp(receivedAt, checkpoint.receivedAt);
+  if (comparison < 0) return true;
+  if (comparison > 0) return false;
+  const delivered = new Set(checkpoint.deliveredIdsAtReceivedAt ?? []);
+  return ids.some((id) => delivered.has(id));
+}
+function normalizeTimestamp(value) {
+  if (!value) return void 0;
+  const ms = Date.parse(value);
+  if (!Number.isFinite(ms)) return void 0;
+  return new Date(ms).toISOString();
+}
+function compareTimestamp(a, b) {
+  if (a < b) return -1;
+  if (a > b) return 1;
+  return 0;
+}
+function uniqueIds(ids) {
+  return [...new Set(ids.filter((id) => id.length > 0))];
+}
+async function delay(ms) {
+  await new Promise((resolve) => setTimeout(resolve, ms));
+}
 
 // src/providers/outlook/index.ts
 import { randomUUID as randomUUID2 } from "crypto";
@@ -14744,6 +14889,9 @@ var OutlookProvider = class {
   async moveEmail(account, id, destinationId) {
     return moveEmail(this.clients.get(account), account, id, destinationId);
   }
+  async trashEmail(account, id) {
+    return moveEmail(this.clients.get(account), account, id, "deleteditems");
+  }
   async sendDraft(account, id) {
     return sendDraft(this.clients.get(account), account, id);
   }
@@ -14910,6 +15058,21 @@ var WELL_KNOWN_TO_IMAP = {
 function resolveFolder(wellKnownOrPath) {
   return WELL_KNOWN_TO_IMAP[wellKnownOrPath.toLowerCase()] ?? wellKnownOrPath;
 }
+function isTrashFolderAlias(wellKnownOrPath) {
+  const lower = wellKnownOrPath.toLowerCase();
+  return lower === "deleteditems" || lower === "trash";
+}
+function resolveTrashMailbox(mailboxes) {
+  for (const mailbox of mailboxes) {
+    const specialUse = mailbox.specialUse?.toLowerCase();
+    if (specialUse === "\\trash") return mailbox.path;
+    const flags = mailbox.flags ? Array.from(mailbox.flags) : [];
+    if (flags.some((flag) => flag.toLowerCase() === "\\trash")) {
+      return mailbox.path;
+    }
+  }
+  return "Trash";
+}
 function clampLimit2(v, dflt, max) {
   if (!v || v <= 0) return dflt;
   return Math.min(v, max);
@@ -15380,6 +15543,9 @@ async function updateDraft2(clients, account, id, update) {
   });
 }
 async function moveEmail2(clients, account, id, destinationId) {
+  if (isTrashFolderAlias(destinationId)) {
+    return trashEmail(clients, account, id);
+  }
   const client = clients.get(account);
   const { folder, uid } = decodeId(id);
   const dest = resolveFolder(destinationId);
@@ -15387,6 +15553,17 @@ async function moveEmail2(clients, account, id, destinationId) {
     await imap.messageMove(uid, dest, { uid: true });
   });
 }
+async function trashEmail(clients, account, id) {
+  const client = clients.get(account);
+  const { folder, uid } = decodeId(id);
+  const imap = await client.getImap();
+  const dest = resolveTrashMailbox(
+    await imap.list()
+  );
+  return client.withMailbox(folder, async (lockedImap) => {
+    await lockedImap.messageMove(uid, dest, { uid: true });
+  });
+}
 async function sendDraft2(clients, account, id) {
   const client = clients.get(account);
   const { folder, uid } = decodeId(id);
@@ -15599,6 +15776,9 @@ var ImapProvider = class {
   async moveEmail(account, id, destinationId) {
     return moveEmail2(this.clients, account, id, destinationId);
   }
+  async trashEmail(account, id) {
+    return trashEmail(this.clients, account, id);
+  }
   async sendDraft(account, id) {
     return sendDraft2(this.clients, account, id);
   }
@@ -16355,7 +16535,14 @@ async function updateDraft3(clients, account, id, update) {
   });
   return { id: updated.data.message?.id ?? updated.data.id ?? id };
 }
+function isTrashDestination(destinationId) {
+  const lower = destinationId.toLowerCase();
+  return lower === "deleteditems" || lower === "trash";
+}
 async function moveEmail3(clients, account, id, destinationId) {
+  if (isTrashDestination(destinationId)) {
+    return trashEmail2(clients, account, id);
+  }
   const { gmail } = clients.get(account);
   const { addLabelIds, removeLabelIds } = resolveLabelsForMove(destinationId);
   await gmail.users.messages.modify({
@@ -16364,6 +16551,13 @@ async function moveEmail3(clients, account, id, destinationId) {
     requestBody: { addLabelIds, removeLabelIds }
   });
 }
+async function trashEmail2(clients, account, id) {
+  const { gmail } = clients.get(account);
+  await gmail.users.messages.trash({
+    userId: "me",
+    id
+  });
+}
 async function sendDraft3(clients, account, id) {
   const { gmail } = clients.get(account);
   const res = await gmail.users.drafts.send({
@@ -16685,6 +16879,9 @@ var GmailProvider = class {
   async moveEmail(account, id, destinationId) {
     return moveEmail3(this.clients, account, id, destinationId);
   }
+  async trashEmail(account, id) {
+    return trashEmail2(this.clients, account, id);
+  }
   async sendDraft(account, id) {
     return sendDraft3(this.clients, account, id);
   }
@@ -17257,7 +17454,7 @@ function registerNewEmailTool(server, ctx) {
   );
 }
 async function collectCandidatesForAccount(store, provider, account) {
-  const checkpoint = normalizeCheckpoint(account.newEmailCheckpoint);
+  const checkpoint = normalizeCheckpoint2(account.newEmailCheckpoint);
   if (!checkpoint) {
     await initializeCheckpoint(store, provider, account);
     return { account, candidates: [] };
@@ -17275,7 +17472,7 @@ async function collectCandidatesForAccount(store, provider, account) {
     let sawOlderThanCheckpoint = false;
     for (const item of items) {
       const timestamp = effectiveReceivedAt(item.receivedAt);
-      const comparison = compareTimestamp(timestamp, checkpoint.receivedAt);
+      const comparison = compareTimestamp2(timestamp, checkpoint.receivedAt);
       if (comparison > 0) {
         candidates.push({ account, summary: item, timestamp });
       } else if (comparison === 0) {
@@ -17306,13 +17503,22 @@ async function initializeCheckpoint(store, provider, account) {
 }
 async function hydrateAndAdvance(store, provider, account, selected) {
   if (selected.length === 0) return [];
-  const emails = [];
+  const hydrated = [];
   for (const candidate of selected) {
     const full = await provider.readEmail(account, candidate.summary.id);
-    emails.push(formatNewEmail(account.email, full, candidate.summary));
+    hydrated.push({
+      candidate,
+      email: formatNewEmail(account.email, full, candidate.summary),
+      fullId: full.id
+    });
   }
-  await advanceCheckpoint(store, account, selected);
-  return emails;
+  const claims = hydrated.map(({ candidate, fullId }) => ({
+    summaryId: candidate.summary.id,
+    receivedAt: candidate.timestamp,
+    ids: [candidate.summary.id, fullId]
+  }));
+  const claimed = new Set(await store.claimNewEmails(account.email, claims));
+  return hydrated.filter(({ candidate }) => claimed.has(candidate.summary.id)).map(({ email }) => email);
 }
 function formatNewEmail(account, msg, summary) {
   const body = selectBody(msg, "markdown");
@@ -17337,19 +17543,8 @@ function formatNewEmail(account, msg, summary) {
     bodyOriginalLength: body.length
   };
 }
-async function advanceCheckpoint(store, account, selected) {
-  const ordered = oldestCandidatesFirst(selected);
-  const newest = ordered[ordered.length - 1];
-  if (!newest) return;
-  const newestTimestamp = newest.timestamp;
-  const idsAtNewest = ordered.filter((candidate) => candidate.timestamp === newestTimestamp).map((candidate) => candidate.summary.id);
-  await store.updateNewEmailCheckpoint(account.email, {
-    receivedAt: newestTimestamp,
-    deliveredIdsAtReceivedAt: idsAtNewest
-  });
-}
-function normalizeCheckpoint(checkpoint) {
-  const receivedAt = normalizeTimestamp(checkpoint?.receivedAt);
+function normalizeCheckpoint2(checkpoint) {
+  const receivedAt = normalizeTimestamp2(checkpoint?.receivedAt);
   if (!receivedAt) return null;
   return {
     receivedAt,
@@ -17357,9 +17552,9 @@ function normalizeCheckpoint(checkpoint) {
   };
 }
 function effectiveReceivedAt(receivedAt) {
-  return normalizeTimestamp(receivedAt) ?? MISSING_RECEIVED_AT;
+  return normalizeTimestamp2(receivedAt) ?? MISSING_RECEIVED_AT;
 }
-function normalizeTimestamp(value) {
+function normalizeTimestamp2(value) {
   if (!value) return null;
   const ms = Date.parse(value);
   if (!Number.isFinite(ms)) return null;
@@ -17367,20 +17562,20 @@ function normalizeTimestamp(value) {
 }
 function oldestCandidatesFirst(items) {
   return [...items].sort((a, b) => {
-    const byTimestamp = compareTimestamp(a.timestamp, b.timestamp);
+    const byTimestamp = compareTimestamp2(a.timestamp, b.timestamp);
     if (byTimestamp !== 0) return byTimestamp;
     return a.summary.id.localeCompare(b.summary.id);
   });
 }
 function compareNewEmailOutputOldestFirst(a, b) {
-  const byTimestamp = compareTimestamp(
+  const byTimestamp = compareTimestamp2(
     effectiveReceivedAt(a.receivedAt),
     effectiveReceivedAt(b.receivedAt)
   );
   if (byTimestamp !== 0) return byTimestamp;
   return a.id.localeCompare(b.id);
 }
-function compareTimestamp(a, b) {
+function compareTimestamp2(a, b) {
   if (a < b) return -1;
   if (a > b) return 1;
   return 0;
@@ -17713,6 +17908,12 @@ function registerOrganizeTools(server, ctx) {
     const data = { marked: true, id: args.id, isRead };
     return ok(data, data);
   }
+  async function trashMessage(args) {
+    const { provider, account } = registry.resolveByEmail(args.account);
+    await provider.trashEmail(account, args.id);
+    const data = { trashed: true, id: args.id };
+    return ok(data, data);
+  }
   const archiveMoveSchema = z7.object({
     account: z7.string().email(),
     id: z7.string().min(1).describe("Message ID to move")
@@ -17752,7 +17953,7 @@ function registerOrganizeTools(server, ctx) {
       },
       async (args) => {
         try {
-          return await moveToWellKnown(args, "deleteditems", "trashed");
+          return await trashMessage(args);
         } catch (err) {
           return fail(errMsg(err));
         }
@@ -18189,7 +18390,7 @@ function registerTools(server, opts) {
 // package.json
 var package_default = {
   name: "hypermail-mcp",
-  version: "0.7.12",
+  version: "0.7.13",
   description: "Unified email MCP server \u2014 operate any inbox (Outlook now, IMAP/Gmail later) by passing an email address.",
   type: "module",
   bin: {