apple-mail-mcp 2.19.17 → 2.19.18

package/README.md

@@ -280,19 +280,27 @@ human reader; the same information is also returned as structured fields on
 `search-messages` and `list-messages`, so a caller can tell _"nothing matched"_
 apart from _"I did not look everywhere"_ without parsing the text:
 
-| Field                   | Type     | Meaning                                                                                                                                                                            |
-| ----------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `partial`               | boolean  | Coverage was incomplete — **the result is not a confirmed "no such mail"**. True whenever any field below is non-empty.                                                            |
-| `skippedLargeMailboxes` | string[] | Mailboxes never scanned because their message count exceeded `APPLE_MAIL_MAX_SEARCH_MAILBOX`, formatted `"Account / Mailbox (count)"` — e.g. `"iCloud / Archive (90694)"`.         |
-| `notSearchedMailboxes`  | string[] | Mailboxes that _were_ reached but timed out or errored mid-scan, formatted `"Account / Mailbox"`. Also carries the IMAP path's `failedMailboxes`.                                  |
-| `timedOutAccounts`      | string[] | Accounts whose whole-account AppleScript was killed by the per-account time budget — nothing from that account was searched.                                                       |
-| `failedMailboxes`       | string[] | IMAP-backend mailboxes that errored. These are merged into `notSearchedMailboxes` as well; read that field unless you need to attribute the failure to the IMAP path specifically. |
+| Field                   | Type     | Meaning                                                                                                                                                                                                                                                                                                               |
+| ----------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `partial`               | boolean  | Coverage was incomplete — **the result is not a confirmed "no such mail"**. True whenever any field below is non-empty.                                                                                                                                                                                               |
+| `skippedLargeMailboxes` | string[] | Mailboxes never scanned because their message count exceeded `APPLE_MAIL_MAX_SEARCH_MAILBOX`, formatted `"Account / Mailbox (count)"` — e.g. `"iCloud / Archive (90694)"`.                                                                                                                                            |
+| `notSearchedMailboxes`  | string[] | Mailboxes that _were_ reached but timed out or errored mid-scan, formatted `"Account / Mailbox"`. Also carries the IMAP path's `failedMailboxes`.                                                                                                                                                                     |
+| `timedOutAccounts`      | string[] | Accounts whose whole-account AppleScript was killed by the per-account time budget — nothing from that account was searched.                                                                                                                                                                                          |
+| `failedMailboxes`       | string[] | IMAP-backend mailboxes that errored. These are merged into `notSearchedMailboxes` as well; read that field unless you need to attribute the failure to the IMAP path specifically.                                                                                                                                    |
+| `failedMailboxReasons`  | object   | The IMAP server's own error text for each entry in `failedMailboxes`, keyed the same way.                                                                                                                                                                                                                             |
+| `omittedMessages`       | object[] | IMAP messages that belong on the page but whose `FETCH` response could not be read even with a reduced item set — `{ id, mailbox, uid, reason }`. The page is short by exactly these; the `id` still works with `get-message` / `get-message-headers`. ([#256](https://github.com/sweetrb/apple-mail-mcp/issues/256)) |
 
 Treat a non-empty `skippedLargeMailboxes` as actionable rather than
 informational: re-run scoped to the named mailbox with a `dateFrom`/`dateTo`
 window, or configure the [IMAP backend](#imap-backend--opt-in), which searches
-those mailboxes server-side. All five fields are optional and are omitted when
-coverage was complete.
+those mailboxes server-side. The list fields are optional and are omitted (or
+empty) when coverage was complete.
+
+A row the IMAP backend could only read with a reduced item set (its full
+`BODYSTRUCTURE`, or its whole `FETCH` response, was unparseable — e.g. a message
+forwarded as an attachment many levels deep) is still returned, with a
+`metadataIncomplete` note saying what was missing; its `hasAttachments` is then
+inferred from the top-level `Content-Type`.
 
 ---
 

package/build/cli.js

@@ -58092,6 +58092,7 @@ __export(imapClient_exports, {
   mailFlagColorIndex: () => mailFlagColorIndex,
   matchMailbox: () => matchMailbox,
   normalizeMessageId: () => normalizeMessageId,
+  omittedNote: () => omittedNote,
   resolveImapConfig: () => resolveImapConfig,
   resolveImapConfigs: () => resolveImapConfigs,
   resolveMailboxPath: () => resolveMailboxPath,
@@ -58402,7 +58403,12 @@ function structuredRow(m, account, path) {
     // a caller from "no attachments", so every IMAP-sourced message claimed to
     // have none. Falls back to false only when the fetch carried no
     // BODYSTRUCTURE at all.
-    hasAttachments: bodyStructureHasAttachments(m.bodyStructure),
+    // A row read without BODYSTRUCTURE (#256 follow-up) judges by its top-level
+    // Content-Type instead, and says so in `metadataIncomplete`.
+    hasAttachments: m.bodyStructure ? bodyStructureHasAttachments(m.bodyStructure) : m.degraded ? contentTypeSuggestsAttachments(m) : false,
+    ...m.degraded ? {
+      metadataIncomplete: m.degraded === "bodystructure" ? "BODYSTRUCTURE unreadable; hasAttachments inferred from Content-Type" : "FETCH response unreadable; row rebuilt from raw headers, hasAttachments inferred from Content-Type"
+    } : {},
     // Message-ID (when the envelope carries it) is the strongest cross-/intra-
     // backend dedup key for the multi-account merge (imapMultiAccount.ts). The
     // AppleScript path does not expose it, so cross-backend dedup falls back to
@@ -58410,6 +58416,13 @@ function structuredRow(m, account, path) {
     ...env.messageId ? { messageId: env.messageId } : {}
   };
 }
+function omittedNote(omitted, merged) {
+  if (omitted.length === 0) return "";
+  const list = omitted.map((o) => `UID ${o.uid} in "${o.mailbox}" (${o.id})`).join(", ");
+  return `
+
+Partial result. ${omitted.length} message(s) ${merged ? "that may belong" : "that belong"} on this page could not be read and are not listed: ${list}. Reason: ${[...new Set(omitted.map((o) => o.reason))].join("; ")}. get-message or get-message-headers with those ids may still read them.`;
+}
 function describeMailboxFailure(error) {
   const raw = errText(error);
   const oneLine = raw.split("\n")[0].trim();
@@ -58451,30 +58464,106 @@ async function searchUids(client, path, criteria, size) {
     `IMAP SEARCH on "${path}"${sized} failed: ` + (cause ? errText(cause) : "the server rejected it or the connection dropped before it answered (on a mailbox this size, usually a server-side timeout)")
   );
 }
+function mergeFetched(into, msg) {
+  const prev = into.get(msg.uid);
+  if (!prev) {
+    into.set(msg.uid, msg);
+    return;
+  }
+  const merged = { ...prev };
+  for (const [key, value] of Object.entries(msg)) {
+    if (value !== void 0 && value !== null)
+      merged[key] = value;
+  }
+  into.set(msg.uid, merged);
+}
+async function fetchInto(client, uids, query, into) {
+  const wanted = new Set(uids);
+  for await (const msg of client.fetch(uids.join(","), query, { uid: true })) {
+    if (typeof msg?.uid === "number" && wanted.has(msg.uid)) mergeFetched(into, msg);
+  }
+}
+function fetchedHeaders(m) {
+  return m.headers ? parseHeaderBlock(decodeHeaderBytes(asBuffer(m.headers))) : void 0;
+}
+function envelopeFromHeaders(m) {
+  const h = fetchedHeaders(m);
+  if (!h || h.headers.length === 0) return void 0;
+  const env = {};
+  if (h.subject) env.subject = h.subject;
+  if (h.from) {
+    const angle = h.from.match(/^\s*"?([^"<]*?)"?\s*<([^>]+)>/);
+    env.from = angle ? [{ ...angle[1].trim() ? { name: angle[1].trim() } : {}, address: angle[2].trim() }] : [{ address: h.from.trim() }];
+  }
+  if (h.messageId) env.messageId = `<${h.messageId}>`;
+  if (h.inReplyTo) env.inReplyTo = `<${h.inReplyTo}>`;
+  if (h.dateHeader) env.date = h.dateHeader;
+  return env;
+}
+function contentTypeSuggestsAttachments(m) {
+  const type = fetchedHeaders(m)?.headers.find((h) => h.name.toLowerCase() === "content-type");
+  return /^\s*multipart\/mixed\b/i.test(type?.value ?? "");
+}
 async function fetchRows(client, uids) {
-  if (uids.length === 0) return [];
+  if (uids.length === 0) return { messages: [], omitted: [] };
   const byUid = /* @__PURE__ */ new Map();
-  for await (const msg of client.fetch(
-    uids.join(","),
-    // BODYSTRUCTURE rides along so `hasAttachments` is computed rather
-    // than assumed. Measured on 50 real messages: ~390ms -> ~465ms for
-    // the fetch (~17%), same single round trip, no extra request.
-    //
-    // INTERNALDATE rides along for the same reason, and is why `dateReceived`
-    // can finally mean what it says: imapflow's `envelope.date` is built from
-    // the header block, so it IS the `Date:` header, not arrival time.
-    //
-    // The `Date:` header itself (BODY.PEEK[HEADER.FIELDS (DATE)]) rides in the
-    // SAME FETCH command, so a date the server's ENVELOPE parser rejected can
-    // still be recovered (#234). Measured on 50 real messages, 6 alternating
-    // runs: median ~334ms without vs ~315ms with — inside the noise — for ~44
-    // bytes per message. Too cheap to hide behind an opt-in.
-    { envelope: true, flags: true, bodyStructure: true, internalDate: true, headers: ["date"] },
-    { uid: true }
-  )) {
-    byUid.set(msg.uid, msg);
-  }
-  return uids.map((uid) => byUid.get(uid)).filter((message) => message !== void 0);
+  const causes = [];
+  const noteCause = () => {
+    const err = client.takeLastCommandError?.();
+    if (err !== void 0) {
+      const text = describeMailboxFailure(err);
+      if (!causes.includes(text)) causes.push(text);
+    }
+  };
+  const missing = () => uids.filter((uid) => !byUid.get(uid)?.envelope);
+  client.takeLastCommandError?.();
+  await fetchInto(client, uids, ROW_QUERY, byUid);
+  noteCause();
+  let gap = missing();
+  if (gap.length > 0) {
+    await fetchInto(client, gap, ROW_QUERY, byUid);
+    noteCause();
+    gap = missing();
+  }
+  if (gap.length > 0) {
+    const reduced = /* @__PURE__ */ new Map();
+    await fetchInto(client, gap, ROW_QUERY_NO_STRUCTURE, reduced);
+    noteCause();
+    for (const msg of reduced.values()) {
+      if (!msg.envelope) continue;
+      mergeFetched(byUid, { ...msg, degraded: "bodystructure" });
+    }
+    gap = missing();
+  }
+  if (gap.length > 0) {
+    for (const uid of gap) {
+      const bare = /* @__PURE__ */ new Map();
+      await fetchInto(client, [uid], ROW_QUERY_HEADERS_ONLY, bare);
+      noteCause();
+      const msg = bare.get(uid);
+      const envelope = msg ? envelopeFromHeaders(msg) : void 0;
+      if (msg && envelope) {
+        mergeFetched(byUid, { ...msg, envelope, degraded: "envelope" });
+      }
+    }
+    gap = missing();
+  }
+  const omitted = new Set(gap);
+  return {
+    messages: uids.filter((uid) => !omitted.has(uid)).map((uid) => byUid.get(uid)).filter((message) => message !== void 0),
+    omitted: gap,
+    ...causes.length > 0 ? { cause: causes.join("; ") } : {}
+  };
+}
+function pageRows(fetch) {
+  return {
+    messages: fetch.messages,
+    omitted: fetch.omitted,
+    ...fetch.omitted.length > 0 ? { omittedReason: omissionReason(fetch) } : {}
+  };
+}
+function omissionReason(fetch) {
+  return "the server's FETCH response for this message could not be read, even without BODYSTRUCTURE or ENVELOPE" + (fetch.cause ? ` (${fetch.cause})` : "");
 }
 async function walkWindows(exists, page, firstWindow, readWindow) {
   const wanted = page.skip + page.take;
@@ -58514,7 +58603,7 @@ async function listLargeMailbox(client, exists, page) {
     }
   );
   return {
-    messages: await fetchRows(client, walk.uids),
+    ...pageRows(await fetchRows(client, walk.uids)),
     total: Math.max(0, exists - deletedSeen),
     totalExact: true
   };
@@ -58530,7 +58619,7 @@ async function searchLargeMailbox(client, path, criteria, exists, page) {
     return found;
   });
   return {
-    messages: await fetchRows(client, walk.uids),
+    ...pageRows(await fetchRows(client, walk.uids)),
     total: walk.matched,
     totalExact: walk.exhausted
   };
@@ -58539,7 +58628,7 @@ async function fetchMailboxMatches(client, path, criteria, page) {
   const lock = await client.getMailboxLock(path);
   try {
     const exists = await statusMessageCount(client, path);
-    if (exists === 0) return { messages: [], total: 0, totalExact: true };
+    if (exists === 0) return { messages: [], omitted: [], total: 0, totalExact: true };
     if (exists !== void 0 && exists > LARGE_MAILBOX_MESSAGES) {
       try {
         return isUnfiltered(criteria) ? await listLargeMailbox(client, exists, page) : await searchLargeMailbox(client, path, criteria, exists, page);
@@ -58552,7 +58641,7 @@ async function fetchMailboxMatches(client, path, criteria, page) {
     }
     const uids = await searchUids(client, path, criteria, exists);
     if (uids.length === 0 || page.take === 0) {
-      return { messages: [], total: uids.length, totalExact: true };
+      return { messages: [], omitted: [], total: uids.length, totalExact: true };
     }
     const messages = exists ?? (await client.status(path, { messages: true })).messages ?? void 0;
     if (typeof messages === "number" && uids.length > messages) {
@@ -58561,7 +58650,7 @@ async function fetchMailboxMatches(client, path, criteria, page) {
       );
     }
     const newest = uids.slice().reverse().slice(page.skip, page.skip + page.take);
-    return { messages: await fetchRows(client, newest), total: uids.length, totalExact: true };
+    return { ...pageRows(await fetchRows(client, newest)), total: uids.length, totalExact: true };
   } finally {
     lock.release();
   }
@@ -58594,6 +58683,7 @@ async function run(args, listMode, deps) {
       const fetched = [];
       const failedMailboxes = [];
       const failedMailboxReasons = {};
+      const omittedMessages = [];
       let totalMatched = 0;
       let totalExact = true;
       for (const path of paths) {
@@ -58602,6 +58692,14 @@ async function run(args, listMode, deps) {
           totalMatched += result.total;
           totalExact &&= result.totalExact;
           fetched.push(...result.messages.map((message) => ({ message, path })));
+          for (const uid of result.omitted) {
+            omittedMessages.push({
+              id: encodeImapId(cfg.accountLabel, path, uid),
+              mailbox: path,
+              uid,
+              reason: result.omittedReason ?? "the server's FETCH response could not be read"
+            });
+          }
         } catch (error) {
           failedMailboxes.push(path);
           failedMailboxReasons[path] = describeMailboxFailure(error);
@@ -58630,10 +58728,10 @@ async function run(args, listMode, deps) {
       const messages = ordered.map(
         ({ message, path }) => structuredRow(message, cfg.accountLabel, path)
       );
-      const partial = failedMailboxes.length > 0;
-      const failureNote = partial ? `
+      const partial = failedMailboxes.length > 0 || omittedMessages.length > 0;
+      const failureNote = (failedMailboxes.length > 0 ? `
 
-Partial result. Could not search mailbox(es): ${failedMailboxes.map((path) => `"${path}" (${failedMailboxReasons[path]})`).join(", ")}.` : "";
+Partial result. Could not search mailbox(es): ${failedMailboxes.map((path) => `"${path}" (${failedMailboxReasons[path]})`).join(", ")}.` : "") + omittedNote(omittedMessages, unscopedSearch);
       const verb = listMode ? "listed" : "matched";
       const totalText = totalExact ? `${totalMatched} total` : `at least ${totalMatched} total`;
       const scope = unscopedSearch ? allMailboxCount === 1 ? `mailbox "${paths[0]}"` : `${allMailboxCount} selectable mailboxes` : `mailbox "${paths[0]}"`;
@@ -58644,7 +58742,8 @@ Partial result. Could not search mailbox(es): ${failedMailboxes.map((path) => `"
           count: 0,
           partial,
           failedMailboxes,
-          failedMailboxReasons
+          failedMailboxReasons,
+          omittedMessages
         };
       }
       const text = `Found ${rows.length} message(s) via IMAP (server-side, account ${cfg.accountLabel}, ${scope}; ${totalText} ${verb}):
@@ -58657,7 +58756,8 @@ Note: these IMAP IDs (imap:\u2026) work with get-message and the message mutatio
         count: messages.length,
         partial,
         failedMailboxes,
-        failedMailboxReasons
+        failedMailboxReasons,
+        omittedMessages
       };
     },
     true
@@ -59617,31 +59717,21 @@ async function imapThread(id, deps = {}, limit = 50) {
         }
         if (uidSet.size <= 1) return null;
         const uids = [...uidSet].slice(0, limit);
-        const msgs = [];
-        for await (const msg of client.fetch(
-          uids.join(","),
-          // Same reason as the list/search fetch: get-thread emits structured
-          // rows too, so it needs BODYSTRUCTURE or its hasAttachments would
-          // silently disagree with the same message seen via search.
-          // INTERNALDATE and the Date: header ride along for the same reason as
-          // the list/search fetch: the per-message date is recovered and
-          // sanity-checked exactly as a row's dateSent is (#234).
-          {
-            envelope: true,
-            flags: true,
-            bodyStructure: true,
-            internalDate: true,
-            headers: ["date"]
-          },
-          { uid: true }
-        )) {
-          msgs.push(msg);
-        }
+        const rows = await fetchRows(client, uids);
+        const msgs = rows.messages.slice();
+        const omittedMessages = rows.omitted.map((uid) => ({
+          id: encodeImapId(ref.account, ref.path, uid),
+          mailbox: ref.path,
+          uid,
+          reason: omissionReason(rows)
+        }));
         msgs.sort((a, b) => dateMs(a) - dateMs(b));
         const subject = seed.envelope?.subject || "(no subject)";
         const structured = {
           subject,
           count: msgs.length,
+          partial: omittedMessages.length > 0,
+          omittedMessages,
           messages: msgs.map((m) => ({
             id: encodeImapId(ref.account, ref.path, m.uid),
             subject: m.envelope?.subject || "(no subject)",
@@ -59656,7 +59746,7 @@ async function imapThread(id, deps = {}, limit = 50) {
           }))
         };
         const text = `Thread "${subject}" \u2014 ${msgs.length} message(s) via IMAP (References-linked, oldest first):
-` + msgs.map((m) => formatRow(m, ref.account, ref.path)).join("\n");
+` + msgs.map((m) => formatRow(m, ref.account, ref.path)).join("\n") + omittedNote(omittedMessages, false);
         return { count: msgs.length, text, structured };
       } finally {
         lock.release();
@@ -59665,7 +59755,7 @@ async function imapThread(id, deps = {}, limit = 50) {
     true
   );
 }
-var import_imapflow, IMAP_ENV, defaultConnect, SPECIAL_USE_ALIASES, NOT_DELETED, LARGE_MAILBOX_MESSAGES, FIRST_SEARCH_WINDOW, MAX_WINDOW, poolConnect, pools, connecting, MAX_COMPOSE_SOURCE_BYTES, MAX_RFC822_INLINE_BYTES, MAX_RFC822_FILE_BYTES, HEADER_WINDOW_BYTES, MAIL_FLAG_BITS, imapMarkRead, imapMarkUnread, FALLBACK_TRASH_PATH, imapBatchMarkRead, imapBatchMarkUnread, imapBatchFlag, imapBatchUnflag, imapBatchDelete;
+var import_imapflow, IMAP_ENV, defaultConnect, SPECIAL_USE_ALIASES, NOT_DELETED, LARGE_MAILBOX_MESSAGES, FIRST_SEARCH_WINDOW, MAX_WINDOW, ROW_QUERY, ROW_QUERY_NO_STRUCTURE, ROW_QUERY_HEADERS_ONLY, poolConnect, pools, connecting, MAX_COMPOSE_SOURCE_BYTES, MAX_RFC822_INLINE_BYTES, MAX_RFC822_FILE_BYTES, HEADER_WINDOW_BYTES, MAIL_FLAG_BITS, imapMarkRead, imapMarkUnread, FALLBACK_TRASH_PATH, imapBatchMarkRead, imapBatchMarkUnread, imapBatchFlag, imapBatchUnflag, imapBatchDelete;
 var init_imapClient = __esm({
   "src/services/imapClient.ts"() {
     "use strict";
@@ -59739,6 +59829,24 @@ var init_imapClient = __esm({
     LARGE_MAILBOX_MESSAGES = 1e4;
     FIRST_SEARCH_WINDOW = 5e3;
     MAX_WINDOW = 5e4;
+    ROW_QUERY = {
+      envelope: true,
+      flags: true,
+      bodyStructure: true,
+      internalDate: true,
+      headers: ["date"]
+    };
+    ROW_QUERY_NO_STRUCTURE = {
+      envelope: true,
+      flags: true,
+      internalDate: true,
+      headers: ["date", "content-type"]
+    };
+    ROW_QUERY_HEADERS_ONLY = {
+      flags: true,
+      internalDate: true,
+      headers: ["date", "from", "subject", "message-id", "in-reply-to", "content-type"]
+    };
     poolConnect = defaultConnect;
     pools = /* @__PURE__ */ new Map();
     connecting = /* @__PURE__ */ new Map();

package/build/index.js

@@ -65421,6 +65421,7 @@ __export(imapClient_exports, {
   mailFlagColorIndex: () => mailFlagColorIndex,
   matchMailbox: () => matchMailbox,
   normalizeMessageId: () => normalizeMessageId,
+  omittedNote: () => omittedNote,
   resolveImapConfig: () => resolveImapConfig,
   resolveImapConfigs: () => resolveImapConfigs,
   resolveMailboxPath: () => resolveMailboxPath,
@@ -65731,7 +65732,12 @@ function structuredRow(m, account, path) {
     // a caller from "no attachments", so every IMAP-sourced message claimed to
     // have none. Falls back to false only when the fetch carried no
     // BODYSTRUCTURE at all.
-    hasAttachments: bodyStructureHasAttachments(m.bodyStructure),
+    // A row read without BODYSTRUCTURE (#256 follow-up) judges by its top-level
+    // Content-Type instead, and says so in `metadataIncomplete`.
+    hasAttachments: m.bodyStructure ? bodyStructureHasAttachments(m.bodyStructure) : m.degraded ? contentTypeSuggestsAttachments(m) : false,
+    ...m.degraded ? {
+      metadataIncomplete: m.degraded === "bodystructure" ? "BODYSTRUCTURE unreadable; hasAttachments inferred from Content-Type" : "FETCH response unreadable; row rebuilt from raw headers, hasAttachments inferred from Content-Type"
+    } : {},
     // Message-ID (when the envelope carries it) is the strongest cross-/intra-
     // backend dedup key for the multi-account merge (imapMultiAccount.ts). The
     // AppleScript path does not expose it, so cross-backend dedup falls back to
@@ -65739,6 +65745,13 @@ function structuredRow(m, account, path) {
     ...env.messageId ? { messageId: env.messageId } : {}
   };
 }
+function omittedNote(omitted, merged) {
+  if (omitted.length === 0) return "";
+  const list = omitted.map((o) => `UID ${o.uid} in "${o.mailbox}" (${o.id})`).join(", ");
+  return `
+
+Partial result. ${omitted.length} message(s) ${merged ? "that may belong" : "that belong"} on this page could not be read and are not listed: ${list}. Reason: ${[...new Set(omitted.map((o) => o.reason))].join("; ")}. get-message or get-message-headers with those ids may still read them.`;
+}
 function describeMailboxFailure(error2) {
   const raw = errText(error2);
   const oneLine = raw.split("\n")[0].trim();
@@ -65780,30 +65793,106 @@ async function searchUids(client, path, criteria, size) {
     `IMAP SEARCH on "${path}"${sized} failed: ` + (cause ? errText(cause) : "the server rejected it or the connection dropped before it answered (on a mailbox this size, usually a server-side timeout)")
   );
 }
+function mergeFetched(into, msg) {
+  const prev = into.get(msg.uid);
+  if (!prev) {
+    into.set(msg.uid, msg);
+    return;
+  }
+  const merged = { ...prev };
+  for (const [key, value] of Object.entries(msg)) {
+    if (value !== void 0 && value !== null)
+      merged[key] = value;
+  }
+  into.set(msg.uid, merged);
+}
+async function fetchInto(client, uids, query, into) {
+  const wanted = new Set(uids);
+  for await (const msg of client.fetch(uids.join(","), query, { uid: true })) {
+    if (typeof msg?.uid === "number" && wanted.has(msg.uid)) mergeFetched(into, msg);
+  }
+}
+function fetchedHeaders(m) {
+  return m.headers ? parseHeaderBlock(decodeHeaderBytes(asBuffer(m.headers))) : void 0;
+}
+function envelopeFromHeaders(m) {
+  const h = fetchedHeaders(m);
+  if (!h || h.headers.length === 0) return void 0;
+  const env = {};
+  if (h.subject) env.subject = h.subject;
+  if (h.from) {
+    const angle = h.from.match(/^\s*"?([^"<]*?)"?\s*<([^>]+)>/);
+    env.from = angle ? [{ ...angle[1].trim() ? { name: angle[1].trim() } : {}, address: angle[2].trim() }] : [{ address: h.from.trim() }];
+  }
+  if (h.messageId) env.messageId = `<${h.messageId}>`;
+  if (h.inReplyTo) env.inReplyTo = `<${h.inReplyTo}>`;
+  if (h.dateHeader) env.date = h.dateHeader;
+  return env;
+}
+function contentTypeSuggestsAttachments(m) {
+  const type = fetchedHeaders(m)?.headers.find((h) => h.name.toLowerCase() === "content-type");
+  return /^\s*multipart\/mixed\b/i.test(type?.value ?? "");
+}
 async function fetchRows(client, uids) {
-  if (uids.length === 0) return [];
+  if (uids.length === 0) return { messages: [], omitted: [] };
   const byUid = /* @__PURE__ */ new Map();
-  for await (const msg of client.fetch(
-    uids.join(","),
-    // BODYSTRUCTURE rides along so `hasAttachments` is computed rather
-    // than assumed. Measured on 50 real messages: ~390ms -> ~465ms for
-    // the fetch (~17%), same single round trip, no extra request.
-    //
-    // INTERNALDATE rides along for the same reason, and is why `dateReceived`
-    // can finally mean what it says: imapflow's `envelope.date` is built from
-    // the header block, so it IS the `Date:` header, not arrival time.
-    //
-    // The `Date:` header itself (BODY.PEEK[HEADER.FIELDS (DATE)]) rides in the
-    // SAME FETCH command, so a date the server's ENVELOPE parser rejected can
-    // still be recovered (#234). Measured on 50 real messages, 6 alternating
-    // runs: median ~334ms without vs ~315ms with — inside the noise — for ~44
-    // bytes per message. Too cheap to hide behind an opt-in.
-    { envelope: true, flags: true, bodyStructure: true, internalDate: true, headers: ["date"] },
-    { uid: true }
-  )) {
-    byUid.set(msg.uid, msg);
-  }
-  return uids.map((uid) => byUid.get(uid)).filter((message) => message !== void 0);
+  const causes = [];
+  const noteCause = () => {
+    const err = client.takeLastCommandError?.();
+    if (err !== void 0) {
+      const text = describeMailboxFailure(err);
+      if (!causes.includes(text)) causes.push(text);
+    }
+  };
+  const missing = () => uids.filter((uid) => !byUid.get(uid)?.envelope);
+  client.takeLastCommandError?.();
+  await fetchInto(client, uids, ROW_QUERY, byUid);
+  noteCause();
+  let gap = missing();
+  if (gap.length > 0) {
+    await fetchInto(client, gap, ROW_QUERY, byUid);
+    noteCause();
+    gap = missing();
+  }
+  if (gap.length > 0) {
+    const reduced = /* @__PURE__ */ new Map();
+    await fetchInto(client, gap, ROW_QUERY_NO_STRUCTURE, reduced);
+    noteCause();
+    for (const msg of reduced.values()) {
+      if (!msg.envelope) continue;
+      mergeFetched(byUid, { ...msg, degraded: "bodystructure" });
+    }
+    gap = missing();
+  }
+  if (gap.length > 0) {
+    for (const uid of gap) {
+      const bare = /* @__PURE__ */ new Map();
+      await fetchInto(client, [uid], ROW_QUERY_HEADERS_ONLY, bare);
+      noteCause();
+      const msg = bare.get(uid);
+      const envelope = msg ? envelopeFromHeaders(msg) : void 0;
+      if (msg && envelope) {
+        mergeFetched(byUid, { ...msg, envelope, degraded: "envelope" });
+      }
+    }
+    gap = missing();
+  }
+  const omitted = new Set(gap);
+  return {
+    messages: uids.filter((uid) => !omitted.has(uid)).map((uid) => byUid.get(uid)).filter((message) => message !== void 0),
+    omitted: gap,
+    ...causes.length > 0 ? { cause: causes.join("; ") } : {}
+  };
+}
+function pageRows(fetch) {
+  return {
+    messages: fetch.messages,
+    omitted: fetch.omitted,
+    ...fetch.omitted.length > 0 ? { omittedReason: omissionReason(fetch) } : {}
+  };
+}
+function omissionReason(fetch) {
+  return "the server's FETCH response for this message could not be read, even without BODYSTRUCTURE or ENVELOPE" + (fetch.cause ? ` (${fetch.cause})` : "");
 }
 async function walkWindows(exists, page, firstWindow, readWindow) {
   const wanted = page.skip + page.take;
@@ -65843,7 +65932,7 @@ async function listLargeMailbox(client, exists, page) {
     }
   );
   return {
-    messages: await fetchRows(client, walk.uids),
+    ...pageRows(await fetchRows(client, walk.uids)),
     total: Math.max(0, exists - deletedSeen),
     totalExact: true
   };
@@ -65859,7 +65948,7 @@ async function searchLargeMailbox(client, path, criteria, exists, page) {
     return found;
   });
   return {
-    messages: await fetchRows(client, walk.uids),
+    ...pageRows(await fetchRows(client, walk.uids)),
     total: walk.matched,
     totalExact: walk.exhausted
   };
@@ -65868,7 +65957,7 @@ async function fetchMailboxMatches(client, path, criteria, page) {
   const lock = await client.getMailboxLock(path);
   try {
     const exists = await statusMessageCount(client, path);
-    if (exists === 0) return { messages: [], total: 0, totalExact: true };
+    if (exists === 0) return { messages: [], omitted: [], total: 0, totalExact: true };
     if (exists !== void 0 && exists > LARGE_MAILBOX_MESSAGES) {
       try {
         return isUnfiltered(criteria) ? await listLargeMailbox(client, exists, page) : await searchLargeMailbox(client, path, criteria, exists, page);
@@ -65881,7 +65970,7 @@ async function fetchMailboxMatches(client, path, criteria, page) {
     }
     const uids = await searchUids(client, path, criteria, exists);
     if (uids.length === 0 || page.take === 0) {
-      return { messages: [], total: uids.length, totalExact: true };
+      return { messages: [], omitted: [], total: uids.length, totalExact: true };
     }
     const messages = exists ?? (await client.status(path, { messages: true })).messages ?? void 0;
     if (typeof messages === "number" && uids.length > messages) {
@@ -65890,7 +65979,7 @@ async function fetchMailboxMatches(client, path, criteria, page) {
       );
     }
     const newest = uids.slice().reverse().slice(page.skip, page.skip + page.take);
-    return { messages: await fetchRows(client, newest), total: uids.length, totalExact: true };
+    return { ...pageRows(await fetchRows(client, newest)), total: uids.length, totalExact: true };
   } finally {
     lock.release();
   }
@@ -65923,6 +66012,7 @@ async function run(args, listMode, deps) {
       const fetched = [];
       const failedMailboxes = [];
       const failedMailboxReasons = {};
+      const omittedMessages = [];
       let totalMatched = 0;
       let totalExact = true;
       for (const path of paths) {
@@ -65931,6 +66021,14 @@ async function run(args, listMode, deps) {
           totalMatched += result.total;
           totalExact &&= result.totalExact;
           fetched.push(...result.messages.map((message) => ({ message, path })));
+          for (const uid of result.omitted) {
+            omittedMessages.push({
+              id: encodeImapId(cfg.accountLabel, path, uid),
+              mailbox: path,
+              uid,
+              reason: result.omittedReason ?? "the server's FETCH response could not be read"
+            });
+          }
         } catch (error2) {
           failedMailboxes.push(path);
           failedMailboxReasons[path] = describeMailboxFailure(error2);
@@ -65959,10 +66057,10 @@ async function run(args, listMode, deps) {
       const messages = ordered.map(
         ({ message, path }) => structuredRow(message, cfg.accountLabel, path)
       );
-      const partial2 = failedMailboxes.length > 0;
-      const failureNote = partial2 ? `
+      const partial2 = failedMailboxes.length > 0 || omittedMessages.length > 0;
+      const failureNote = (failedMailboxes.length > 0 ? `
 
-Partial result. Could not search mailbox(es): ${failedMailboxes.map((path) => `"${path}" (${failedMailboxReasons[path]})`).join(", ")}.` : "";
+Partial result. Could not search mailbox(es): ${failedMailboxes.map((path) => `"${path}" (${failedMailboxReasons[path]})`).join(", ")}.` : "") + omittedNote(omittedMessages, unscopedSearch);
       const verb = listMode ? "listed" : "matched";
       const totalText = totalExact ? `${totalMatched} total` : `at least ${totalMatched} total`;
       const scope = unscopedSearch ? allMailboxCount === 1 ? `mailbox "${paths[0]}"` : `${allMailboxCount} selectable mailboxes` : `mailbox "${paths[0]}"`;
@@ -65973,7 +66071,8 @@ Partial result. Could not search mailbox(es): ${failedMailboxes.map((path) => `"
           count: 0,
           partial: partial2,
           failedMailboxes,
-          failedMailboxReasons
+          failedMailboxReasons,
+          omittedMessages
         };
       }
       const text = `Found ${rows.length} message(s) via IMAP (server-side, account ${cfg.accountLabel}, ${scope}; ${totalText} ${verb}):
@@ -65986,7 +66085,8 @@ Note: these IMAP IDs (imap:\u2026) work with get-message and the message mutatio
         count: messages.length,
         partial: partial2,
         failedMailboxes,
-        failedMailboxReasons
+        failedMailboxReasons,
+        omittedMessages
       };
     },
     true
@@ -66946,31 +67046,21 @@ async function imapThread(id, deps = {}, limit = 50) {
         }
         if (uidSet.size <= 1) return null;
         const uids = [...uidSet].slice(0, limit);
-        const msgs = [];
-        for await (const msg of client.fetch(
-          uids.join(","),
-          // Same reason as the list/search fetch: get-thread emits structured
-          // rows too, so it needs BODYSTRUCTURE or its hasAttachments would
-          // silently disagree with the same message seen via search.
-          // INTERNALDATE and the Date: header ride along for the same reason as
-          // the list/search fetch: the per-message date is recovered and
-          // sanity-checked exactly as a row's dateSent is (#234).
-          {
-            envelope: true,
-            flags: true,
-            bodyStructure: true,
-            internalDate: true,
-            headers: ["date"]
-          },
-          { uid: true }
-        )) {
-          msgs.push(msg);
-        }
+        const rows = await fetchRows(client, uids);
+        const msgs = rows.messages.slice();
+        const omittedMessages = rows.omitted.map((uid) => ({
+          id: encodeImapId(ref.account, ref.path, uid),
+          mailbox: ref.path,
+          uid,
+          reason: omissionReason(rows)
+        }));
         msgs.sort((a, b) => dateMs(a) - dateMs(b));
         const subject = seed.envelope?.subject || "(no subject)";
         const structured = {
           subject,
           count: msgs.length,
+          partial: omittedMessages.length > 0,
+          omittedMessages,
           messages: msgs.map((m) => ({
             id: encodeImapId(ref.account, ref.path, m.uid),
             subject: m.envelope?.subject || "(no subject)",
@@ -66985,7 +67075,7 @@ async function imapThread(id, deps = {}, limit = 50) {
           }))
         };
         const text = `Thread "${subject}" \u2014 ${msgs.length} message(s) via IMAP (References-linked, oldest first):
-` + msgs.map((m) => formatRow(m, ref.account, ref.path)).join("\n");
+` + msgs.map((m) => formatRow(m, ref.account, ref.path)).join("\n") + omittedNote(omittedMessages, false);
         return { count: msgs.length, text, structured };
       } finally {
         lock.release();
@@ -66994,7 +67084,7 @@ async function imapThread(id, deps = {}, limit = 50) {
     true
   );
 }
-var import_imapflow, IMAP_ENV, defaultConnect, SPECIAL_USE_ALIASES, NOT_DELETED, LARGE_MAILBOX_MESSAGES, FIRST_SEARCH_WINDOW, MAX_WINDOW, poolConnect, pools, connecting, MAX_COMPOSE_SOURCE_BYTES, MAX_RFC822_INLINE_BYTES, MAX_RFC822_FILE_BYTES, HEADER_WINDOW_BYTES, MAIL_FLAG_BITS, imapMarkRead, imapMarkUnread, FALLBACK_TRASH_PATH, imapBatchMarkRead, imapBatchMarkUnread, imapBatchFlag, imapBatchUnflag, imapBatchDelete;
+var import_imapflow, IMAP_ENV, defaultConnect, SPECIAL_USE_ALIASES, NOT_DELETED, LARGE_MAILBOX_MESSAGES, FIRST_SEARCH_WINDOW, MAX_WINDOW, ROW_QUERY, ROW_QUERY_NO_STRUCTURE, ROW_QUERY_HEADERS_ONLY, poolConnect, pools, connecting, MAX_COMPOSE_SOURCE_BYTES, MAX_RFC822_INLINE_BYTES, MAX_RFC822_FILE_BYTES, HEADER_WINDOW_BYTES, MAIL_FLAG_BITS, imapMarkRead, imapMarkUnread, FALLBACK_TRASH_PATH, imapBatchMarkRead, imapBatchMarkUnread, imapBatchFlag, imapBatchUnflag, imapBatchDelete;
 var init_imapClient = __esm({
   "src/services/imapClient.ts"() {
     "use strict";
@@ -67068,6 +67158,24 @@ var init_imapClient = __esm({
     LARGE_MAILBOX_MESSAGES = 1e4;
     FIRST_SEARCH_WINDOW = 5e3;
     MAX_WINDOW = 5e4;
+    ROW_QUERY = {
+      envelope: true,
+      flags: true,
+      bodyStructure: true,
+      internalDate: true,
+      headers: ["date"]
+    };
+    ROW_QUERY_NO_STRUCTURE = {
+      envelope: true,
+      flags: true,
+      internalDate: true,
+      headers: ["date", "content-type"]
+    };
+    ROW_QUERY_HEADERS_ONLY = {
+      flags: true,
+      internalDate: true,
+      headers: ["date", "from", "subject", "message-id", "in-reply-to", "content-type"]
+    };
     poolConnect = defaultConnect;
     pools = /* @__PURE__ */ new Map();
     connecting = /* @__PURE__ */ new Map();
@@ -87569,6 +87677,7 @@ async function fanOutImapMessages(args, kind, deps = {}, configs = resolveImapCo
   const accountsFailed = [];
   const failedMailboxes = [];
   const failedMailboxReasons = {};
+  const omittedMessages = [];
   for (const config2 of configs) {
     const perAccountArgs = { ...args, account: void 0 };
     try {
@@ -87581,12 +87690,25 @@ async function fanOutImapMessages(args, kind, deps = {}, configs = resolveImapCo
       for (const [mailbox, reason] of Object.entries(res.failedMailboxReasons)) {
         failedMailboxReasons[`${config2.accountLabel} / ${mailbox}`] = reason;
       }
+      omittedMessages.push(
+        ...(res.omittedMessages ?? []).map((o) => ({
+          ...o,
+          mailbox: `${config2.accountLabel} / ${o.mailbox}`
+        }))
+      );
     } catch (e) {
       accountsFailed.push(config2.accountLabel);
       console.error(`IMAP fan-out failed for account "${config2.accountLabel}": ${String(e)}`);
     }
   }
-  return { rows, accountsQueried, accountsFailed, failedMailboxes, failedMailboxReasons };
+  return {
+    rows,
+    accountsQueried,
+    accountsFailed,
+    failedMailboxes,
+    failedMailboxReasons,
+    omittedMessages
+  };
 }
 function configMatchesAccount(config2, account) {
   const name = account.name.trim().toLowerCase();
@@ -88189,7 +88311,10 @@ var LIST_OUTPUT_SCHEMA = {
   failedMailboxes: external_exports.array(external_exports.string()).optional(),
   // Underlying error text per entry in `failedMailboxes`, same keys (#246
   // follow-up) — declared so a client can rely on it rather than parse text.
-  failedMailboxReasons: external_exports.record(external_exports.string(), external_exports.string()).optional()
+  failedMailboxReasons: external_exports.record(external_exports.string(), external_exports.string()).optional(),
+  // Messages that belong on the page but could not be read, each with its
+  // imap: id and why (#256 follow-up). Non-empty implies `partial: true`.
+  omittedMessages: external_exports.array(external_exports.object({ id: external_exports.string(), mailbox: external_exports.string(), uid: external_exports.number(), reason: external_exports.string() })).optional()
 };
 var BATCH_COUNT_OUTPUT_SCHEMA = {
   ok: external_exports.boolean().optional(),
@@ -88268,7 +88393,7 @@ function mergedMessageResponse(fan, apple, limit, verb) {
   const merged = mergeMessages(fan.rows, apple.rows, limit);
   const diagnostics = {
     ...apple.diagnostics,
-    partial: apple.diagnostics.partial || fan.accountsFailed.length > 0 || fan.failedMailboxes.length > 0,
+    partial: apple.diagnostics.partial || fan.accountsFailed.length > 0 || fan.failedMailboxes.length > 0 || fan.omittedMessages.length > 0,
     timedOutAccounts: [...apple.diagnostics.timedOutAccounts, ...fan.accountsFailed],
     notSearchedMailboxes: [...apple.diagnostics.notSearchedMailboxes, ...fan.failedMailboxes]
   };
@@ -88280,9 +88405,10 @@ function mergedMessageResponse(fan, apple, limit, verb) {
     notSearchedMailboxes: diagnostics.notSearchedMailboxes,
     timedOutAccounts: diagnostics.timedOutAccounts,
     failedMailboxes: fan.failedMailboxes,
-    failedMailboxReasons: fan.failedMailboxReasons
+    failedMailboxReasons: fan.failedMailboxReasons,
+    omittedMessages: fan.omittedMessages
   };
-  const coverageBlock = partialCoverageBlock(diagnostics);
+  const coverageBlock = partialCoverageBlock(diagnostics) + omittedNote(fan.omittedMessages, true);
   if (merged.length === 0) {
     const base = diagnostics.partial ? `No messages found in the portions that were ${verb === "matched" ? "searched" : "listed"}.` : "No messages found";
     return successResponse(`${base}${coverageBlock}`, structured);
@@ -88383,7 +88509,8 @@ registerTool(
             count: r.count,
             partial: r.partial,
             failedMailboxes: r.failedMailboxes,
-            failedMailboxReasons: r.failedMailboxReasons
+            failedMailboxReasons: r.failedMailboxReasons,
+            omittedMessages: r.omittedMessages
           });
         }
         const fan = await fanOutImapMessages(imapArgs, "search");
@@ -88737,7 +88864,9 @@ registerTool(
       messages: external_exports.array(MESSAGE_ROW_SCHEMA).optional(),
       count: external_exports.number().optional(),
       partial: external_exports.boolean().optional(),
-      failedMailboxes: external_exports.array(external_exports.string()).optional()
+      failedMailboxes: external_exports.array(external_exports.string()).optional(),
+      failedMailboxReasons: LIST_OUTPUT_SCHEMA.failedMailboxReasons,
+      omittedMessages: LIST_OUTPUT_SCHEMA.omittedMessages
     }
   },
   withErrorHandling(async ({ id, account, mailbox, limit = 50 }) => {
@@ -88767,7 +88896,8 @@ ${r.text}`, {
           count: r.count,
           partial: r.partial,
           failedMailboxes: r.failedMailboxes,
-          failedMailboxReasons: r.failedMailboxReasons
+          failedMailboxReasons: r.failedMailboxReasons,
+          omittedMessages: r.omittedMessages
         });
       }
       const fan = await fanOutImapMessages({ subject: base, mailbox, limit }, "search");
@@ -88792,20 +88922,21 @@ ${r.text}`, {
       const orderedRows = mergedNewestFirst.slice().reverse().sort(
         (a, b) => (a.dateReceived ? new Date(a.dateReceived).getTime() : 0) - (b.dateReceived ? new Date(b.dateReceived).getTime() : 0)
       );
-      const partial2 = apple.diagnostics.partial || fan.accountsFailed.length > 0 || fan.failedMailboxes.length > 0;
+      const partial2 = apple.diagnostics.partial || fan.accountsFailed.length > 0 || fan.failedMailboxes.length > 0 || fan.omittedMessages.length > 0;
       const coverage = partialCoverageBlock({
         ...apple.diagnostics,
         partial: partial2,
         timedOutAccounts: [...apple.diagnostics.timedOutAccounts, ...fan.accountsFailed],
         notSearchedMailboxes: [...apple.diagnostics.notSearchedMailboxes, ...fan.failedMailboxes]
-      });
+      }) + omittedNote(fan.omittedMessages, true);
       const structured2 = {
         subject: base,
         messages: orderedRows,
         count: orderedRows.length,
         partial: partial2,
         failedMailboxes: fan.failedMailboxes,
-        failedMailboxReasons: fan.failedMailboxReasons
+        failedMailboxReasons: fan.failedMailboxReasons,
+        omittedMessages: fan.omittedMessages
       };
       if (orderedRows.length === 0) {
         return successResponse(`No messages found in thread "${base}".${coverage}`, structured2);
@@ -88870,7 +89001,8 @@ registerTool(
           count: r.count,
           partial: r.partial,
           failedMailboxes: r.failedMailboxes,
-          failedMailboxReasons: r.failedMailboxReasons
+          failedMailboxReasons: r.failedMailboxReasons,
+          omittedMessages: r.omittedMessages
         });
       }
       const fan = await fanOutImapMessages({ mailbox, limit, offset, from, unreadOnly }, "list");

package/package.json

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