apple-mail-mcp 2.14.0 → 2.15.0

package/README.md

@@ -1444,12 +1444,23 @@ Three more honesty rules:
   than list positions — and `expected` stays comparable with the mailbox instead
   of double-counting a duplicate into a false `over`.
 
-`imap:` ids are not reconciled by `countDelta`. An IMAP UID names exactly one
-message in exactly one mailbox, so the mis-targeting class this exists for cannot
-occur there; a batch of only `imap:` ids returns no `countDelta` rather than a
-fabricated one.
-
-They carry their own post-condition check instead. `delete-message` and
+**`imap:` ids are reconciled too, as of 2.15.0.** `batch-delete-messages` and
+`batch-move-messages` return the same `countDelta` structure on the IMAP path, so
+one shape covers both backends and a mixed batch reports an entry per source
+mailbox from whichever backend handled it. The entries are **concatenated, never
+summed** — Mail's own count can lag (#155) while the server's `STATUS` cannot, and
+averaging the two would hide which reading you were looking at.
+
+Only the operations that actually remove messages from their source reconcile.
+`batch-mark-as-read` and the flag tools change no count, so emitting
+`expected: N, observed: 0` for them would manufacture an alarm; they report no
+`countDelta` at all.
+
+Note the mis-targeting class `countDelta` was originally built for cannot occur
+on the IMAP path — a UID names exactly one message in exactly one mailbox — so
+there the value is effect confirmation rather than target confirmation.
+
+Single-message tools carry a post-condition check instead. `delete-message` and
 `move-message` on an `imap:` id return a **`verification`** object in
 `structuredContent`:
 

package/build/index.js

@@ -78828,6 +78828,14 @@ function auditSnapshotChunk() {
   if (!Number.isFinite(n) || n < 1) return DEFAULT_SNAPSHOT_CHUNK;
   return Math.floor(n);
 }
+function classifyCountStatus(readable, expected, observed) {
+  if (!readable) return { status: "unknown", unknownReason: "count-unreadable" };
+  if (expected === null) return { status: "unknown", unknownReason: "no-expectation" };
+  if (observed === expected) return { status: "match" };
+  if ((observed ?? 0) > expected) return { status: "over" };
+  if (observed === 0) return { status: "unknown", unknownReason: "count-did-not-move" };
+  return { status: "unknown", unknownReason: "count-partial" };
+}
 function writeAuditRecord(record2) {
   const path = auditLogPath();
   if (!path) return;
@@ -79470,16 +79478,61 @@ ${indent}end try${this.sanitizeFragment("_uacct", indent)}${this.sanitizeFragmen
         set _sMiss to ""
         set _sPairs to {}
         set _sChunk to ${chunk}
+        -- The mailbox's MEASURED length, emitted only when it disagrees with the
+        -- count (#187). -1 = "not measured", which is the normal case: the probe
+        -- only runs a binary search when the count's last position is unreadable.
+        -- Initialised here, not in the else-branch, or the skipped/unavailable
+        -- paths would reference an unbound variable when emitting.
+        set _sTrue to -1
         if ${countVar} < 0 then
           set _sStatus to "unavailable"
         else if ${countVar} > ${max} then
           set _sStatus to "skipped"
           set _sPayload to "mailbox holds " & (${countVar} as string) & " messages, above ${AUDIT_SNAPSHOT_MAX_ENV}=${max}"
         else
+          -- #187: the count can read HIGH, and an out-of-range range RAISES as
+          -- a whole rather than clamping. On a mailbox smaller than one chunk
+          -- there is only ONE slice, so a high count made it fail entirely:
+          -- _sPairs stayed empty, the status collapsed to "unavailable", and
+          -- the record carried no holes and no warning. The collateral
+          -- instrument switched itself off in exactly the stale direction #155
+          -- evidences, silently.
+          --
+          -- So establish a bound that actually EXISTS before slicing. If the
+          -- last position the count claims is readable, the count is not high
+          -- and this costs one probe. Otherwise binary-search the true end,
+          -- which is O(log n) probes and also MEASURES how stale the count is.
+          set _sBound to ${countVar}
+          if _sBound > 0 then
+            set _sEndOk to false
+            try
+              get id of message _sBound of ${mbVar}
+              set _sEndOk to true
+            end try
+            if not _sEndOk then
+              set _sLoB to 0
+              set _sHiB to _sBound
+              repeat while (_sHiB - _sLoB) > 1
+                set _sMid to (_sLoB + _sHiB) div 2
+                set _sMidOk to false
+                try
+                  get id of message _sMid of ${mbVar}
+                  set _sMidOk to true
+                end try
+                if _sMidOk then
+                  set _sLoB to _sMid
+                else
+                  set _sHiB to _sMid
+                end if
+              end repeat
+              set _sBound to _sLoB
+              set _sTrue to _sLoB
+            end if
+          end if
           set _sLo to 1
-          repeat while _sLo <= ${countVar}
+          repeat while _sLo <= _sBound
             set _sHi to _sLo + _sChunk - 1
-            if _sHi > ${countVar} then set _sHi to ${countVar}
+            if _sHi > _sBound then set _sHi to _sBound
             set _sGot to false
             repeat with _sTry from 1 to ${SNAPSHOT_SLICE_ATTEMPTS}
               set _sIds to {}
@@ -79537,7 +79590,7 @@ ${indent}end try${this.sanitizeFragment("_uacct", indent)}${this.sanitizeFragmen
           -- PARTIAL under the existing rules and withholds the halves a
           -- truncation would poison.
           try
-            set _sOverId to ((id of message (${countVar} + 1) of ${mbVar}) as string)
+            set _sOverId to ((id of message (_sBound + 1) of ${mbVar}) as string)
             -- A specifier that CLAMPS rather than raising hands back the LAST
             -- message instead of failing. That is not evidence of a truncation,
             -- so only an id this enumeration did not already record counts.
@@ -79547,7 +79600,7 @@ ${indent}end try${this.sanitizeFragment("_uacct", indent)}${this.sanitizeFragmen
             end repeat
             if not _sSeen then
               if _sMiss is not "" then set _sMiss to _sMiss & ","
-              set _sMiss to _sMiss & ((${countVar} + 1) as string) & "-end"
+              set _sMiss to _sMiss & ((_sBound + 1) as string) & "-end"
             end if
           end try
           if _sMiss is not "" then
@@ -79562,7 +79615,7 @@ ${indent}end try${this.sanitizeFragment("_uacct", indent)}${this.sanitizeFragmen
           set _sPayload to _sPairs as string
           set AppleScript's text item delimiters to _sTid
         end if
-        set _out to _out & "${SNAP_TAG}${FIELD_SEP}" & ${acctExpr} & "${FIELD_SEP}" & ${mbExpr} & "${FIELD_SEP}${phase}${FIELD_SEP}" & _sStatus & "${FIELD_SEP}" & _sPayload & "${FIELD_SEP}" & _sMiss & "${RECORD_SEP}"`;
+        set _out to _out & "${SNAP_TAG}${FIELD_SEP}" & ${acctExpr} & "${FIELD_SEP}" & ${mbExpr} & "${FIELD_SEP}${phase}${FIELD_SEP}" & _sStatus & "${FIELD_SEP}" & _sPayload & "${FIELD_SEP}" & _sMiss & "${FIELD_SEP}" & (_sTrue as string) & "${RECORD_SEP}"`;
   }
   /**
    * AppleScript capturing the message the op is ABOUT to touch into `_pre`,
@@ -79623,13 +79676,15 @@ ${indent}end try${this.sanitizeFragment("_uacct", indent)}${this.sanitizeFragmen
         continue;
       }
       if (f[0] === SNAP_TAG) {
+        const measured = f[7] !== void 0 && f[7] !== "" ? Number(f[7]) : -1;
         snaps.push({
           account: f[1] ?? "",
           mailbox: f[2] ?? "",
           phase: f[3] === "after" ? "after" : "before",
           status: f[4] ?? "",
           payload: f[5] ?? "",
-          miss: f[6] ?? ""
+          miss: f[6] ?? "",
+          ...Number.isFinite(measured) && measured >= 0 ? { measuredLength: measured } : {}
         });
         continue;
       }
@@ -79724,25 +79779,7 @@ ${indent}end try${this.sanitizeFragment("_uacct", indent)}${this.sanitizeFragmen
       const readable = m.before >= 0 && m.after >= 0;
       const observed = readable ? m.before - m.after : null;
       const note = noteFor(m.account, m.mailbox);
-      let status;
-      let unknownReason;
-      if (!readable) {
-        status = "unknown";
-        unknownReason = "count-unreadable";
-      } else if (m.expected === null) {
-        status = "unknown";
-        unknownReason = "no-expectation";
-      } else if (observed === m.expected) {
-        status = "match";
-      } else if ((observed ?? 0) > m.expected) {
-        status = "over";
-      } else if (observed === 0) {
-        status = "unknown";
-        unknownReason = "count-did-not-move";
-      } else {
-        status = "unknown";
-        unknownReason = "count-partial";
-      }
+      const { status, unknownReason } = classifyCountStatus(readable, m.expected, observed);
       return {
         account: m.account,
         mailbox: m.mailbox,
@@ -79813,6 +79850,7 @@ ${indent}end try${this.sanitizeFragment("_uacct", indent)}${this.sanitizeFragmen
       const unrequested = disappeared.filter(
         (e) => !requestedNumericIds.has(canonicalNumericId(e.id))
       );
+      const countStale = [b, a].filter((s) => s.measuredLength !== void 0).map((s) => ({ phase: s.phase, measuredLength: s.measuredLength }));
       const holes = [b, a].filter((s) => s.miss !== "").map((s) => ({ phase: s.phase, ranges: s.miss }));
       if (holes.length === 0) {
         collateral.push({
@@ -79821,7 +79859,8 @@ ${indent}end try${this.sanitizeFragment("_uacct", indent)}${this.sanitizeFragmen
           snapshot: "ok",
           disappeared,
           unrequested,
-          appeared
+          appeared,
+          ...countStale.length ? { countStale } : {}
         });
         continue;
       }
@@ -79833,6 +79872,7 @@ ${indent}end try${this.sanitizeFragment("_uacct", indent)}${this.sanitizeFragmen
         account: g.account,
         mailbox: g.mailbox,
         snapshot: "partial",
+        ...countStale.length ? { countStale } : {},
         skipReason: `Mail would not read ${holes.map((h) => `${h.ranges} (${h.phase})`).join(", ")} of this mailbox, so the snapshot has a hole in it. ` + (derivable.length > 0 ? `Still derivable and reported: ${derivable.join(" and ")}. ` : `Neither half of the diff is derivable from it. `) + `Anything the unread range could refute is omitted rather than guessed \u2014 an absent field here means "not computable", not "empty".`,
         unobserved: holes,
         ...a.miss === "" ? { disappeared, unrequested } : {},
@@ -84425,7 +84465,15 @@ async function imapFetchAttachment(id, attachmentName, deps = {}) {
     }
   });
 }
-async function imapBatch(ids, deps, op) {
+async function mailboxCount(client, path) {
+  try {
+    const st = await client.status(path, { messages: true });
+    return typeof st.messages === "number" ? st.messages : null;
+  } catch {
+    return null;
+  }
+}
+async function imapBatch(ids, deps, op, opts = {}) {
   const groups = /* @__PURE__ */ new Map();
   const errors = [];
   let failed = 0;
@@ -84442,15 +84490,39 @@ async function imapBatch(ids, deps, op) {
     groups.set(key, g);
   }
   let success = 0;
+  const countDelta = [];
   for (const g of groups.values()) {
     try {
       await useClient(depsForAccount(g.account, deps), async (client) => {
+        const before = opts.reconcile ? await mailboxCount(client, g.path) : null;
         const lock = await client.getMailboxLock(g.path);
         try {
           await op(client, g.uids, g.path);
         } finally {
           lock.release();
         }
+        if (!opts.reconcile) return;
+        const after = await mailboxCount(client, g.path);
+        const readable = before !== null && after !== null;
+        const observed = readable ? before - after : null;
+        const { status, unknownReason } = classifyCountStatus(readable, g.uids.length, observed);
+        countDelta.push({
+          account: g.account,
+          mailbox: g.path,
+          before,
+          after,
+          expected: g.uids.length,
+          observed,
+          status,
+          ...unknownReason ? { unknownReason } : {},
+          ...unknownReason === "count-unreadable" ? { note: "The server did not answer STATUS for this mailbox" } : {},
+          ...unknownReason === "count-did-not-move" ? {
+            note: `The mailbox count did not move. On a label store (Gmail) a message can stay visible in an all-mail view after being moved out of a label, so this is not by itself evidence the operation failed \u2014 check the destination.`
+          } : {},
+          ...unknownReason === "count-partial" ? {
+            note: `Fewer messages left than were operated on. \`observed\` is a LOWER BOUND on what left, not a count of what left \u2014 a concurrent delivery to this mailbox masks departures one-for-one.`
+          } : {}
+        });
       });
       success += g.uids.length;
     } catch (e) {
@@ -84458,7 +84530,7 @@ async function imapBatch(ids, deps, op) {
       errors.push(`${g.path}: ${errText(e)}`);
     }
   }
-  return { success, failed, errors };
+  return { success, failed, errors, ...countDelta.length ? { countDelta } : {} };
 }
 var imapBatchMarkRead = (ids, deps = {}) => imapBatch(ids, deps, async (c, uids) => {
   assertMutated(
@@ -84493,17 +84565,27 @@ var imapBatchUnflag = (ids, deps = {}) => imapBatch(ids, deps, async (c, uids) =
     `IMAP unflag of ${uids.length} message(s)`
   );
 });
-var imapBatchDelete = (ids, deps = {}) => imapBatch(ids, deps, async (c, uids, path) => {
-  await trashUids(c, uids, path);
-});
+var imapBatchDelete = (ids, deps = {}) => imapBatch(
+  ids,
+  deps,
+  async (c, uids, path) => {
+    await trashUids(c, uids, path);
+  },
+  { reconcile: true }
+);
 function imapBatchMove(ids, destMailbox, deps = {}) {
-  return imapBatch(ids, deps, async (c, uids) => {
-    const dest = await findMailboxPathOrThrow(c, destMailbox) ?? resolveMailboxPath(destMailbox, "list");
-    assertMutated(
-      await c.messageMove(uids, dest, { uid: true }),
-      `IMAP move of ${uids.length} message(s) to "${dest}"`
-    );
-  });
+  return imapBatch(
+    ids,
+    deps,
+    async (c, uids) => {
+      const dest = await findMailboxPathOrThrow(c, destMailbox) ?? resolveMailboxPath(destMailbox, "list");
+      assertMutated(
+        await c.messageMove(uids, dest, { uid: true }),
+        `IMAP move of ${uids.length} message(s) to "${dest}"`
+      );
+    },
+    { reconcile: true }
+  );
 }
 function senderName(from) {
   const a = from?.[0];
@@ -84702,13 +84784,15 @@ async function hybridBatchCounts(ids, appleFn, imapFn) {
     fail += res.length - s;
     errors.push(...res.filter((r) => !r.success && r.error).map((r) => r.error));
   }
+  let countDelta;
   if (imapIds.length > 0) {
     const r = await imapFn(imapIds);
     success += r.success;
     fail += r.failed;
     errors.push(...r.errors);
+    if (r.countDelta?.length) countDelta = r.countDelta;
   }
-  return { success, fail, errors };
+  return { success, fail, errors, ...countDelta ? { countDelta } : {} };
 }
 function distinctErrors(errors) {
   return [...new Set(errors.filter(Boolean))];
@@ -84747,6 +84831,10 @@ ${warnings.join("\n")}` : "";
 function toManagerScope(args) {
   return { account: args.sourceAccount, mailbox: args.sourceMailbox };
 }
+function mergeCountDeltas(apple, imap) {
+  const all = [...apple ?? [], ...imap ?? []];
+  return all.length ? { countDelta: all } : {};
+}
 async function runBatchDelete(deps, args) {
   const { ids, sourceMailbox, sourceAccount } = args;
   let forensics = { warnings: [] };
@@ -84770,7 +84858,10 @@ async function runBatchDelete(deps, args) {
       allFailed: (n) => `Failed to delete all ${n} message(s)`,
       partial: (ok, failed) => `Deleted ${ok} message(s), ${failed} failed`
     },
-    forensics.countDelta ? { countDelta: forensics.countDelta } : {},
+    // #181: merge both backends' reconciliation. An AppleScript-only batch is
+    // unchanged; an IMAP-only one now reports a delta where it previously
+    // reported nothing; a mixed batch reports both, per source mailbox.
+    mergeCountDeltas(forensics.countDelta, counts.countDelta),
     forensics.warnings
   );
 }
@@ -84804,7 +84895,10 @@ async function runBatchMove(deps, args) {
       allFailed: (n) => `Failed to move all ${n} message(s)`,
       partial: (ok, failed) => `Moved ${ok} message(s) to "${mailbox}", ${failed} failed`
     },
-    { mailbox, ...forensics.countDelta ? { countDelta: forensics.countDelta } : {} },
+    {
+      mailbox,
+      ...mergeCountDeltas(forensics.countDelta, counts.countDelta)
+    },
     forensics.warnings
   );
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "apple-mail-mcp",
-  "version": "2.14.0",
+  "version": "2.15.0",
   "description": "MCP server for Apple Mail - read, search, send, and manage emails via Claude and other AI assistants",
   "type": "module",
   "main": "build/index.js",