@mgcrea/mcp-apple-mail 1.36.2 → 1.37.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -165,7 +165,15 @@ wrong:
165
165
  164,156-byte PDF advertises 224,634.
166
166
 
167
167
  `list_attachments` therefore reports `sizeBytes` from the file on disk and a `retrievable` flag
168
- saying whether `save_attachment` will actually succeed, rather than guessing from the message.
168
+ saying whether the bytes are on disk, rather than guessing from the message.
169
+
170
+ An attachment with `retrievable: false` has not been downloaded by Mail, which on a Gmail account
171
+ caching messages without their attachments is most older mail. `save_attachment` then asks Mail to
172
+ save it, and Mail's `save` fetches it from the server first; the result says `from: "mail"`. Mail
173
+ also keeps what it fetched, so the attachment reads `retrievable: true` afterwards. Mail has to be
174
+ running and online, a large file can take a while (Mail allows itself two minutes), and Mail writes into a
175
+ staging folder inside `APPLE_MAIL_ATTACHMENT_DIR` that is removed after the copy, never into the
176
+ destination itself.
169
177
 
170
178
  ## Security
171
179
 
@@ -182,8 +190,10 @@ Once implemented, sending will default to leaving a **draft** open for review; a
182
190
  requires both `ALLOW_WRITES` and an explicit `confirm: true`.
183
191
 
184
192
  **No secrets.** The server holds no credential of any kind — its access is the macOS permission you
185
- granted the host app. There is nothing here to leak, and nothing is sent anywhere: no network calls
186
- are made at all.
193
+ granted the host app. There is nothing here to leak, and nothing is sent anywhere: the server makes
194
+ no network calls at all. What reaches a network is Mail itself, doing what it was asked: sending,
195
+ checking for new mail, and also `save_attachment` asking it to download an attachment from your own
196
+ mail server.
187
197
 
188
198
  **Attachments.** `save_attachment` can only write inside `APPLE_MAIL_ATTACHMENT_DIR`, and the
189
199
  filename is reduced to its basename first — a sender who names their attachment
package/dist/cli.js CHANGED
@@ -1,5 +1,5 @@
1
1
  #!/usr/bin/env node
2
- import { a as loadConfig, b as MAIL_SURFACE, j as BUILD_INFO, r as createServer } from "./server-ynr059Dx.js";
2
+ import { a as loadConfig, b as MAIL_SURFACE, j as BUILD_INFO, r as createServer } from "./server-D5S4dzq6.js";
3
3
  import { runStdioServer } from "@mgcrea/mcp-apple-core";
4
4
  //#region src/cli.ts
5
5
  const LOG_PREFIX = "apple-mail-mcp";
package/dist/index.d.ts CHANGED
@@ -1,4 +1,4 @@
1
- import { AppBusyError as MailBusyError, AppNotRunningError as MailNotRunningError, AppleAutomationError, AppleAutomationError as AppleMailError, ArrivalRow, ArrivalSource, BuildInfo, Era, FileIdentity, IndexUnavailableError, InterferenceWatch, JxaEnvelope, ListenLedger, Logger, OsascriptRunner, OsascriptTimeoutError, PlatformError, PreconditionError, ProtocolError, SchemaDriftError, TccDeniedError, Watch, WatchRegistry, WritesDisabledError, assertStaticScript, createOsascriptRunner, inspectFile, mapOsaError, normalizeFilter, withBusyRetry } from "@mgcrea/mcp-apple-core";
1
+ import { AppBusyError as MailBusyError, AppNotRunningError as MailNotRunningError, AppleAutomationError, AppleAutomationError as AppleMailError, ArrivalRow, ArrivalSource, BuildInfo, Era, FileIdentity, IndexUnavailableError, InterferenceWatch, JxaEnvelope, ListenLedger, Logger, OsascriptRunner, OsascriptTimeoutError, PlatformError, PreconditionError, PreconditionError as PreconditionError$1, ProtocolError, SchemaDriftError, TccDeniedError, Watch, WatchRegistry, WritesDisabledError, assertStaticScript, createOsascriptRunner, inspectFile, mapOsaError, normalizeFilter, withBusyRetry } from "@mgcrea/mcp-apple-core";
2
2
  import { z } from "zod";
3
3
  import { McpServer } from "@modelcontextprotocol/server";
4
4
  import { DatabaseSync } from "node:sqlite";
@@ -395,7 +395,10 @@ type ParsedMessage = {
395
395
  headers: Record<string, string | null>;
396
396
  body: string;
397
397
  bodyFrom: "text/plain" | "text/html" | "none";
398
- /** `retrievable` says whether save_attachment can actually fetch the bytes. */
398
+ /**
399
+ * `retrievable` says whether the bytes are on disk. When they are not,
400
+ * save_attachment has Mail download them, which needs Mail running and online.
401
+ */
399
402
  attachments: (Attachment & {
400
403
  retrievable: boolean;
401
404
  })[];
@@ -1009,13 +1012,17 @@ declare class AppleMailClient {
1009
1012
  * The destination is resolved and then checked to be inside
1010
1013
  * `APPLE_MAIL_ATTACHMENT_DIR`, so a filename of `../../.ssh/authorized_keys`
1011
1014
  * lands nowhere. Existing files are never overwritten.
1015
+ *
1016
+ * When the bytes are not on disk, which on a Gmail account caching messages
1017
+ * without their attachments is most older mail, Mail is asked to download
1018
+ * the attachment (see `#fetchFromMail`).
1012
1019
  */
1013
1020
  saveAttachment(ref: string, filename: string, opts?: {
1014
1021
  overwrite?: boolean;
1015
1022
  }): Promise<{
1016
1023
  path: string;
1017
1024
  bytes: number;
1018
- from: "inline" | "sidecar";
1025
+ from: "inline" | "sidecar" | "mail";
1019
1026
  }>;
1020
1027
  /** Set flags across refs, one Apple Event per distinct mailbox. */
1021
1028
  setFlags(refs: string[], flags: {
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.ts","names":[],"sources":["../src/build-info.ts","../src/client/errors.ts","../src/client/locate.ts","../src/config.ts","../src/client/ax.ts","../src/client/mime.ts","../src/client/emlx.ts","../src/client/schema.ts","../src/client/envelope.ts","../src/client/mailbox-map.ts","../src/client/mail.ts","../src/client/ref.ts","../src/client/watch.ts","../src/tools/watch.ts","../src/server.ts","../src/tools/index.ts"],"mappings":"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"}
1
+ {"version":3,"file":"index.d.ts","names":[],"sources":["../src/build-info.ts","../src/client/errors.ts","../src/client/locate.ts","../src/config.ts","../src/client/ax.ts","../src/client/mime.ts","../src/client/emlx.ts","../src/client/schema.ts","../src/client/envelope.ts","../src/client/mailbox-map.ts","../src/client/mail.ts","../src/client/ref.ts","../src/client/watch.ts","../src/tools/watch.ts","../src/server.ts","../src/tools/index.ts"],"mappings":"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"}
package/dist/index.js CHANGED
@@ -1,2 +1,2 @@
1
- import { A as WritesDisabledError, C as MessageNotFoundError, D as ProtocolError, E as PreconditionError, O as SchemaDriftError, S as MailNotRunningError, T as PlatformError, _ as locateEnvelopeIndex, a as loadConfig, c as decodeRef, d as assertStaticScript, f as createOsascriptRunner, g as inspectFile, h as MailboxMap, i as registerTools, j as BUILD_INFO, k as TccDeniedError, l as encodeRef, m as withBusyRetry, n as SERVER_VERSION, o as AppleMailClient, p as mapOsaError, r as createServer, s as REF_VERSION, t as SERVER_NAME, u as groupRefsByMailbox, v as AppleMailError, w as OsascriptTimeoutError, x as MailBusyError, y as IndexUnavailableError } from "./server-ynr059Dx.js";
1
+ import { A as WritesDisabledError, C as MessageNotFoundError, D as ProtocolError, E as PreconditionError, O as SchemaDriftError, S as MailNotRunningError, T as PlatformError, _ as locateEnvelopeIndex, a as loadConfig, c as decodeRef, d as assertStaticScript, f as createOsascriptRunner, g as inspectFile, h as MailboxMap, i as registerTools, j as BUILD_INFO, k as TccDeniedError, l as encodeRef, m as withBusyRetry, n as SERVER_VERSION, o as AppleMailClient, p as mapOsaError, r as createServer, s as REF_VERSION, t as SERVER_NAME, u as groupRefsByMailbox, v as AppleMailError, w as OsascriptTimeoutError, x as MailBusyError, y as IndexUnavailableError } from "./server-D5S4dzq6.js";
2
2
  export { AppleMailClient, AppleMailError, BUILD_INFO, IndexUnavailableError, MailBusyError, MailNotRunningError, MailboxMap, MessageNotFoundError, OsascriptTimeoutError, PlatformError, PreconditionError, ProtocolError, REF_VERSION, SERVER_NAME, SERVER_VERSION, SchemaDriftError, TccDeniedError, WritesDisabledError, assertStaticScript, createOsascriptRunner, createServer, decodeRef, encodeRef, groupRefsByMailbox, inspectFile, loadConfig, locateEnvelopeIndex, mapOsaError, registerTools, withBusyRetry };
@@ -1,7 +1,7 @@
1
- import { AppBusyError as MailBusyError, AppNotRunningError as MailNotRunningError, AppleAutomationError, AppleAutomationError as AppleMailError, BaseConfigSchema, IndexUnavailableError, OsascriptTimeoutError, PlatformError, PreconditionError, ProtocolError, SchemaDriftError, TccDeniedError, WritesDisabledError, assertStaticScript, buildBaseDiagnostics, confirmArg, createOsascriptRunner, createWatches, describeAggregation, detectEpoch, escapeLike, fileIdentity, fileTrigger, fingerprintSchema, groupByArg, inspectFile, interferenceNote, isoMs, limitArg, mapOsaError, normalizeFilter, occurrenceTimestamp, openAxChannel, openReadOnly, parseBool, parseBound, parseConfig, parseIntOpt, parseList, parseSenderArgs, project, promptArg, readPackageIdentity, registerEvents, registerSurfaceResources, registerWorkflowPrompt, requiredPromptArg, resolveLimit, sameFile, selectArg, tableMap, trimmed, watchInterference, withBusyRetry, withLazyTools, wrap, writeConfinedFile } from "@mgcrea/mcp-apple-core";
2
- import { closeSync, existsSync, openSync, readFileSync, readSync, readdirSync, statSync } from "node:fs";
1
+ import { AppBusyError as MailBusyError, AppNotRunningError as MailNotRunningError, AppleAutomationError, AppleAutomationError as AppleMailError, BaseConfigSchema, IndexUnavailableError, OsascriptTimeoutError, PlatformError, PreconditionError, PreconditionError as PreconditionError$1, ProtocolError, SchemaDriftError, TccDeniedError, WritesDisabledError, assertStaticScript, buildBaseDiagnostics, confirmArg, createOsascriptRunner, createWatches, describeAggregation, detectEpoch, escapeLike, fileIdentity, fileTrigger, fingerprintSchema, groupByArg, inspectFile, interferenceNote, isoMs, limitArg, mapOsaError, normalizeFilter, occurrenceTimestamp, openAxChannel, openReadOnly, parseBool, parseBound, parseConfig, parseIntOpt, parseList, parseSenderArgs, project, promptArg, readPackageIdentity, registerEvents, registerSurfaceResources, registerWorkflowPrompt, requiredPromptArg, resolveLimit, sameFile, selectArg, tableMap, trimmed, watchInterference, withBusyRetry, withLazyTools, wrap, writeConfinedFile } from "@mgcrea/mcp-apple-core";
2
+ import { closeSync, existsSync, lstatSync, mkdirSync, mkdtempSync, openSync, readFileSync, readSync, readdirSync, rmSync, statSync } from "node:fs";
3
3
  import { homedir, tmpdir } from "node:os";
4
- import { basename, dirname, isAbsolute, join, resolve } from "node:path";
4
+ import { basename, dirname, extname, isAbsolute, join, resolve } from "node:path";
5
5
  import { mkdtemp, rm, writeFile } from "node:fs/promises";
6
6
  import { z } from "zod";
7
7
  import { McpServer } from "@modelcontextprotocol/server";
@@ -14,8 +14,8 @@ const pkg = readPackageIdentity(new URL("../package.json", import.meta.url), {
14
14
  const BUILD_INFO = {
15
15
  name: pkg.name,
16
16
  version: pkg.version,
17
- gitCommit: "64f8fc3",
18
- gitCommitDate: "2026-11-03T23:19:14+01:00"
17
+ gitCommit: "9f3ce2c",
18
+ gitCommitDate: "2026-11-06T12:19:38+01:00"
19
19
  };
20
20
  //#endregion
21
21
  //#region src/client/errors.ts
@@ -39,6 +39,15 @@ var MessageNotFoundError = class extends AppleAutomationError {
39
39
  super(`No message for ref "${ref}". It was probably moved or deleted since the search ran. Re-run the search to get a current ref.`);
40
40
  }
41
41
  };
42
+ /**
43
+ * An attachment whose bytes are in neither the message file nor the sidecar
44
+ * tree: Mail has not downloaded it. Its own class so that save_attachment can
45
+ * tell this case, which Mail can repair by fetching it, from the refusals
46
+ * (no such name, a path outside the confinement) that it must pass on.
47
+ */
48
+ var AttachmentNotStoredError = class extends PreconditionError {
49
+ name = "AttachmentNotStoredError";
50
+ };
42
51
  //#endregion
43
52
  //#region src/client/locate.ts
44
53
  const INDEX_SUFFIX = join("MailData", "Envelope Index");
@@ -1032,7 +1041,7 @@ const splitEmlx = (buf) => {
1032
1041
  };
1033
1042
  const readEmlx = (path, opts) => {
1034
1043
  const stat = statSync(path);
1035
- if (stat.size > MAX_FILE_BYTES) throw new PreconditionError(`Message file is ${stat.size} bytes, above the ${MAX_FILE_BYTES}-byte ceiling. Use apple_mail_list_attachments to see what is in it.`, {
1044
+ if (stat.size > MAX_FILE_BYTES) throw new PreconditionError$1(`Message file is ${stat.size} bytes, above the ${MAX_FILE_BYTES}-byte ceiling. Use apple_mail_list_attachments to see what is in it.`, {
1036
1045
  path,
1037
1046
  sizeBytes: stat.size
1038
1047
  });
@@ -1142,7 +1151,7 @@ const extractAttachment = (emlxPath, filename, rowid) => {
1142
1151
  walkParts(root, (p) => {
1143
1152
  if (!match && p.filename === filename) match = p;
1144
1153
  });
1145
- if (!match) throw new PreconditionError(`No attachment named "${filename}" in this message. Use apple_mail_list_attachments to see what is there.`);
1154
+ if (!match) throw new PreconditionError$1(`No attachment named "${filename}" in this message. Use apple_mail_list_attachments to see what is there.`);
1146
1155
  const inline = partBytes(match);
1147
1156
  if (hasContent(inline)) return {
1148
1157
  bytes: inline,
@@ -1153,7 +1162,7 @@ const extractAttachment = (emlxPath, filename, rowid) => {
1153
1162
  bytes: readFileSync(hit),
1154
1163
  from: "sidecar"
1155
1164
  };
1156
- throw new PreconditionError(`The attachment "${filename}" is not stored locally. Either it was never downloaded, or this account caches headers only — apple_mail_diagnostics reports the caching policy per account. Opening the message in Mail fetches it.`, {
1165
+ throw new AttachmentNotStoredError(`The attachment "${filename}" is not stored locally. Either it was never downloaded, or this account caches headers only — apple_mail_diagnostics reports the caching policy per account.`, {
1157
1166
  emlxPath,
1158
1167
  rowid
1159
1168
  });
@@ -3345,6 +3354,79 @@ const OPEN_COMPOSER = script(`
3345
3354
 
3346
3355
  return ok({ subject: subject });
3347
3356
  `, { allowLaunch: true });
3357
+ /**
3358
+ * Have Mail download one attachment and save it to `p.dest`.
3359
+ *
3360
+ * Mail's `save` on a `mail attachment` that is not downloaded fetches it from
3361
+ * the server first, and the fetch also lands in Mail's own store: measured
3362
+ * 2026-11-06 on a Gmail account caching messages without attachments, a message
3363
+ * whose attachments were not on disk listed them `retrievable: true`, with real
3364
+ * sizes, after Mail had saved them this way. There is no separate download verb
3365
+ * in Mail's dictionary; `downloaded` is read-only.
3366
+ *
3367
+ * `p.dest` is a path in a fresh staging folder the caller made and owns. Mail's
3368
+ * `save` overwrites and follows symlinks, so it must never be pointed at the
3369
+ * user's destination; the caller moves the bytes there through the confinement.
3370
+ *
3371
+ * A name that matches nothing, or matches twice, comes back as data rather than
3372
+ * an error so the caller can say what Mail listed.
3373
+ */
3374
+ const FETCH_ATTACHMENT = script(`
3375
+ var acct = findAccount(M, p.accountUuid);
3376
+ if (!acct) return err("ACCOUNT_NOT_FOUND", "No account with id " + p.accountUuid);
3377
+ var mb = resolveMailbox(acct, p.mailbox);
3378
+ if (!mb) return err("MAILBOX_NOT_FOUND", "No mailbox " + p.mailbox + " in that account");
3379
+
3380
+ var m;
3381
+ try {
3382
+ m = mb.messages.byId(p.id);
3383
+ m.id();
3384
+ } catch (e) {
3385
+ return err("MESSAGE_NOT_FOUND", "No message " + p.id + " in " + p.mailbox);
3386
+ }
3387
+
3388
+ var wanted = String(p.filename).normalize("NFC");
3389
+ // Not prop(): a failed read here is not a message without attachments, and
3390
+ // answering "none" would tell the caller the name does not exist.
3391
+ var atts;
3392
+ try {
3393
+ atts = m.mailAttachments();
3394
+ } catch (e) {
3395
+ return ok({
3396
+ saved: false,
3397
+ reason: "save-failed",
3398
+ downloaded: null,
3399
+ error: "Mail could not list the message's attachments: " +
3400
+ String(e && e.message ? e.message : e)
3401
+ });
3402
+ }
3403
+ var names = [];
3404
+ var hits = [];
3405
+ for (var i = 0; i < atts.length; i++) {
3406
+ var a = atts[i];
3407
+ var name = prop(function () { return a.name(); }, null);
3408
+ if (name === null) continue;
3409
+ names.push(String(name));
3410
+ if (String(name).normalize("NFC") === wanted) hits.push(a);
3411
+ }
3412
+ if (hits.length === 0) return ok({ saved: false, reason: "none", names: names });
3413
+ if (hits.length > 1) return ok({ saved: false, reason: "ambiguous", count: hits.length });
3414
+
3415
+ var hit = hits[0];
3416
+ var downloaded = prop(function () { return hit.downloaded(); }, null);
3417
+ var fileSize = prop(function () { return hit.fileSize(); }, null);
3418
+ try {
3419
+ M.save(hit, { in: Path(p.dest) });
3420
+ } catch (e) {
3421
+ return ok({
3422
+ saved: false,
3423
+ reason: "save-failed",
3424
+ downloaded: downloaded,
3425
+ error: String(e && e.message ? e.message : e)
3426
+ });
3427
+ }
3428
+ return ok({ saved: true, downloaded: downloaded, fileSize: fileSize });
3429
+ `);
3348
3430
  //#endregion
3349
3431
  //#region src/client/compose.ts
3350
3432
  /**
@@ -4319,7 +4401,7 @@ var MailboxMap = class {
4319
4401
  accounts = await this.accounts(true);
4320
4402
  found = find(accounts);
4321
4403
  }
4322
- if (!found) throw new PreconditionError(`No account "${needle}". Known accounts: ${accounts.map((a) => a.name).join(", ") || "(none visible)"}.` + (this.#allowlist.length ? " An allowlist is active (APPLE_MAIL_ACCOUNTS)." : ""));
4404
+ if (!found) throw new PreconditionError$1(`No account "${needle}". Known accounts: ${accounts.map((a) => a.name).join(", ") || "(none visible)"}.` + (this.#allowlist.length ? " An allowlist is active (APPLE_MAIL_ACCOUNTS)." : ""));
4323
4405
  return found;
4324
4406
  }
4325
4407
  /**
@@ -4339,7 +4421,7 @@ var MailboxMap = class {
4339
4421
  const hit = account.mailboxes.find((m) => m.toLowerCase() === c.toLowerCase());
4340
4422
  if (hit) return hit;
4341
4423
  }
4342
- throw new PreconditionError(`No mailbox "${wanted}" in account "${account.name}". Available: ${account.mailboxes.join(", ")}.`);
4424
+ throw new PreconditionError$1(`No mailbox "${wanted}" in account "${account.name}". Available: ${account.mailboxes.join(", ")}.`);
4343
4425
  }
4344
4426
  /**
4345
4427
  * Map an Envelope Index `mailboxes.url` onto a scriptable account + mailbox.
@@ -5078,12 +5160,12 @@ const UUID_RE = /^[0-9A-Fa-f-]{8,64}$/;
5078
5160
  const encodeRef = (ref) => `m1:${ref.accountUuid}/${encodeURIComponent(ref.mailbox)}#${ref.id}`;
5079
5161
  const decodeRef = (raw) => {
5080
5162
  const m = /^([a-z0-9]+):([^/]+)\/(.*)#(\d+)$/.exec(raw);
5081
- if (!m) throw new PreconditionError(`Malformed message ref "${raw}". Refs come from the search and list tools — construct them from those results rather than by hand.`, { expected: `m1:<accountUuid>/<mailbox>#<id>` });
5163
+ if (!m) throw new PreconditionError$1(`Malformed message ref "${raw}". Refs come from the search and list tools — construct them from those results rather than by hand.`, { expected: `m1:<accountUuid>/<mailbox>#<id>` });
5082
5164
  const [, version, accountUuid, mailboxRaw, idRaw] = m;
5083
- if (version !== "m1") throw new PreconditionError(`Unsupported message ref version "${version}". This server issues "m1" refs; re-run the search to get current ones.`);
5084
- if (!accountUuid || !UUID_RE.test(accountUuid)) throw new PreconditionError(`Message ref "${raw}" does not carry a valid account id.`);
5165
+ if (version !== "m1") throw new PreconditionError$1(`Unsupported message ref version "${version}". This server issues "m1" refs; re-run the search to get current ones.`);
5166
+ if (!accountUuid || !UUID_RE.test(accountUuid)) throw new PreconditionError$1(`Message ref "${raw}" does not carry a valid account id.`);
5085
5167
  const id = Number(idRaw);
5086
- if (!Number.isSafeInteger(id) || id <= 0) throw new PreconditionError(`Message ref "${raw}" does not carry a valid message id.`);
5168
+ if (!Number.isSafeInteger(id) || id <= 0) throw new PreconditionError$1(`Message ref "${raw}" does not carry a valid message id.`);
5087
5169
  return {
5088
5170
  accountUuid,
5089
5171
  mailbox: decodeURIComponent(mailboxRaw ?? ""),
@@ -5217,6 +5299,22 @@ const reviseDraftInPlace = async (lane, facts, opts) => {
5217
5299
  };
5218
5300
  //#endregion
5219
5301
  //#region src/client/mail.ts
5302
+ /**
5303
+ * How long the process may take to have Mail download one attachment. A large
5304
+ * Gmail PDF can outlast the ordinary 30 s budget. Mail's own reply deadline is
5305
+ * the default Apple Event timeout, 120 s from when `save` is sent; the margin
5306
+ * lets the script's catch around `save` answer first, with Mail's reason,
5307
+ * rather than the process being killed with none.
5308
+ */
5309
+ const FETCH_TIMEOUT_MS = 135e3;
5310
+ const isFetchAnswer = (value) => {
5311
+ if (typeof value !== "object" || value === null || !("saved" in value)) return false;
5312
+ const a = value;
5313
+ if (a.saved === true) return true;
5314
+ if (a.reason === "none") return Array.isArray(a.names);
5315
+ if (a.reason === "ambiguous") return typeof a.count === "number";
5316
+ return a.reason === "save-failed" && typeof a.error === "string";
5317
+ };
5220
5318
  /** The FDA sentence, kept verbatim for the case where FDA really is the problem. */
5221
5319
  /**
5222
5320
  * A display name, quoted when it holds a comma, and only then.
@@ -5625,7 +5723,7 @@ var AppleMailClient = class {
5625
5723
  if (rowids.length === 0) {
5626
5724
  const known = [...lookup.values()].filter((e) => !account || e.accountUuid === account.id).map((e) => e.mailbox);
5627
5725
  const unique = [...new Set(known)].toSorted();
5628
- throw new PreconditionError(`No mailbox matching ${JSON.stringify(opts.mailbox ?? "")}${account ? ` in account ${JSON.stringify(account.name)}` : ""} is present in Mail's search index.` + (unique.length ? ` Indexed there: ${unique.slice(0, 20).join(", ")}.` : " That account has no indexed mailboxes at all."));
5726
+ throw new PreconditionError$1(`No mailbox matching ${JSON.stringify(opts.mailbox ?? "")}${account ? ` in account ${JSON.stringify(account.name)}` : ""} is present in Mail's search index.` + (unique.length ? ` Indexed there: ${unique.slice(0, 20).join(", ")}.` : " That account has no indexed mailboxes at all."));
5629
5727
  }
5630
5728
  return rowids;
5631
5729
  }
@@ -6052,27 +6150,112 @@ var AppleMailClient = class {
6052
6150
  * The destination is resolved and then checked to be inside
6053
6151
  * `APPLE_MAIL_ATTACHMENT_DIR`, so a filename of `../../.ssh/authorized_keys`
6054
6152
  * lands nowhere. Existing files are never overwritten.
6153
+ *
6154
+ * When the bytes are not on disk, which on a Gmail account caching messages
6155
+ * without their attachments is most older mail, Mail is asked to download
6156
+ * the attachment (see `#fetchFromMail`).
6055
6157
  */
6056
6158
  async saveAttachment(ref, filename, opts = {}) {
6057
6159
  const decoded = decodeRef(ref);
6058
6160
  const located = await this.#lookupMessageFile(decoded);
6059
- if (!located.found) throw new PreconditionError(`The message file was not found, so its attachments are not reachable. ${located.explain}`, { probed: located.lookup?.probed.slice(0, 3) ?? [] });
6161
+ if (!located.found) throw new PreconditionError$1(`The message file was not found, so its attachments are not reachable. ${located.explain}`, { probed: located.lookup?.probed.slice(0, 3) ?? [] });
6060
6162
  let from = "inline";
6163
+ try {
6164
+ return {
6165
+ ...writeConfinedFile({
6166
+ root: this.config.attachmentDir,
6167
+ name: filename,
6168
+ bytes: () => {
6169
+ const extracted = extractAttachment(located.path, filename, decoded.id);
6170
+ from = extracted.from;
6171
+ return extracted.bytes;
6172
+ },
6173
+ overwrite: opts.overwrite ?? false,
6174
+ settingName: "APPLE_MAIL_ATTACHMENT_DIR"
6175
+ }),
6176
+ from
6177
+ };
6178
+ } catch (error) {
6179
+ if (!(error instanceof AttachmentNotStoredError)) throw error;
6180
+ }
6181
+ const dest = resolve(this.config.attachmentDir, basename(filename));
6182
+ if (!opts.overwrite && existsSync(dest)) throw new PreconditionError$1(`${dest} already exists; refusing to overwrite it.`);
6183
+ const bytes = await this.#fetchFromMail(decoded, filename);
6061
6184
  return {
6062
6185
  ...writeConfinedFile({
6063
6186
  root: this.config.attachmentDir,
6064
6187
  name: filename,
6065
- bytes: () => {
6066
- const extracted = extractAttachment(located.path, filename, decoded.id);
6067
- from = extracted.from;
6068
- return extracted.bytes;
6069
- },
6188
+ bytes,
6070
6189
  overwrite: opts.overwrite ?? false,
6071
6190
  settingName: "APPLE_MAIL_ATTACHMENT_DIR"
6072
6191
  }),
6073
- from
6192
+ from: "mail"
6074
6193
  };
6075
6194
  }
6195
+ /**
6196
+ * Have Mail download an attachment it has not fetched, and return its bytes.
6197
+ *
6198
+ * Mail's `save` fetches the attachment from the server, and keeps it in its
6199
+ * own store as well, so the next save finds the sidecar on disk.
6200
+ *
6201
+ * Mail writes into a staging folder of ours inside the attachment directory,
6202
+ * never the destination itself: its `save` overwrites and follows symlinks,
6203
+ * which is exactly what `writeConfinedFile` refuses. The staging file gets a
6204
+ * fixed name, keeping only a sanitised extension, so no part of a caller's
6205
+ * filename becomes a path Mail writes to. The folder goes whatever happens.
6206
+ *
6207
+ * Not retried on a busy answer: -1712 is also what a timed-out Apple Event
6208
+ * returns, and retrying a slow download would only double the wait.
6209
+ */
6210
+ async #fetchFromMail(ref, filename) {
6211
+ mkdirSync(this.config.attachmentDir, { recursive: true });
6212
+ const staging = mkdtempSync(join(this.config.attachmentDir, ".cupertino-download-"));
6213
+ try {
6214
+ const ext = extname(basename(filename)).replace(/[^A-Za-z0-9.]/g, "");
6215
+ const target = join(staging, `attachment${ext}`);
6216
+ const notStored = `The attachment "${filename}" is not stored locally, and`;
6217
+ let answer;
6218
+ try {
6219
+ answer = await this.runner.run(FETCH_ATTACHMENT, {
6220
+ accountUuid: ref.accountUuid,
6221
+ mailbox: ref.mailbox,
6222
+ id: ref.id,
6223
+ filename,
6224
+ dest: target
6225
+ }, { timeoutMs: Math.max(FETCH_TIMEOUT_MS, this.config.osascriptTimeoutMs) });
6226
+ } catch (error) {
6227
+ if (error instanceof MailNotRunningError) throw new PreconditionError$1(`${notStored} Mail is not running to download it. Open Mail and try again.`);
6228
+ if (error instanceof OsascriptTimeoutError) throw new PreconditionError$1(`${notStored} Mail did not finish downloading it in time. It may still be downloading: try again in a minute, or open the message in Mail.`);
6229
+ if (error instanceof ProtocolError) throw new ProtocolError(`${notStored} Mail could not download it: ${error.message}`, { ...error.details });
6230
+ throw error;
6231
+ }
6232
+ if (!isFetchAnswer(answer)) throw new ProtocolError(`${notStored} Mail's answer to the download was not one save_attachment can read: ${String(JSON.stringify(answer ?? null)).slice(0, 200)}.`);
6233
+ if (!answer.saved) {
6234
+ if (answer.reason === "ambiguous") throw new PreconditionError$1(`${notStored} this message has ${answer.count} attachments named "${filename}", so there is no telling which one to have Mail download. Save it from Mail.`);
6235
+ if (answer.reason === "none") {
6236
+ const listed = answer.names.length > 0 ? answer.names.join(", ") : "none";
6237
+ throw new PreconditionError$1(`${notStored} Mail lists no attachment by that name on this message, so it cannot download it. Mail lists: ${listed}.`);
6238
+ }
6239
+ throw new PreconditionError$1(`${notStored} Mail could not download "${filename}": ${answer.error}. Check that Mail is online and the account is enabled.`);
6240
+ }
6241
+ const entries = readdirSync(staging);
6242
+ const candidate = existsSync(target) ? target : entries.length === 1 ? join(staging, entries[0]) : null;
6243
+ const written = candidate && lstatSync(candidate).isFile() ? candidate : null;
6244
+ if (!written) throw new PreconditionError$1(`${notStored} Mail reported saving "${filename}" but wrote no file. Opening the message in Mail downloads it.`);
6245
+ const bytes = readFileSync(written);
6246
+ if (bytes.length === 0) throw new PreconditionError$1(`${notStored} Mail saved "${filename}" as an empty file, so it did not download it. Check that Mail is online and the account is enabled.`);
6247
+ return bytes;
6248
+ } finally {
6249
+ try {
6250
+ rmSync(staging, {
6251
+ recursive: true,
6252
+ force: true
6253
+ });
6254
+ } catch {
6255
+ this.#logger?.warn?.(`could not remove the download staging folder ${staging}`);
6256
+ }
6257
+ }
6258
+ }
6076
6259
  /** Set flags across refs, one Apple Event per distinct mailbox. */
6077
6260
  async setFlags(refs, flags) {
6078
6261
  const groups = groupRefsByMailbox(refs.map((r) => decodeRef(r)));
@@ -6192,8 +6375,8 @@ var AppleMailClient = class {
6192
6375
  */
6193
6376
  async createMailbox(name, account) {
6194
6377
  const trimmed = name.trim();
6195
- if (!trimmed) throw new PreconditionError("A mailbox name cannot be empty or only whitespace.");
6196
- if (trimmed.split("/").some((segment) => segment.trim() === "")) throw new PreconditionError(`"${name}" has an empty path segment. "/" separates levels, so a name may not start or end with it, e.g. "Projects/Cupertino".`);
6378
+ if (!trimmed) throw new PreconditionError$1("A mailbox name cannot be empty or only whitespace.");
6379
+ if (trimmed.split("/").some((segment) => segment.trim() === "")) throw new PreconditionError$1(`"${name}" has an empty path segment. "/" separates levels, so a name may not start or end with it, e.g. "Projects/Cupertino".`);
6197
6380
  const resolved = account ? await this.mailboxes.resolveAccount(account) : null;
6198
6381
  const result = await withBusyRetry(() => this.runner.run(CREATE_MAILBOX, {
6199
6382
  name: trimmed,
@@ -6235,13 +6418,13 @@ var AppleMailClient = class {
6235
6418
  * which is the one outcome nothing downstream could distinguish from success.
6236
6419
  */
6237
6420
  async updateDraft(target, opts) {
6238
- if (target.ref !== void 0 && target.composer !== void 0) throw new PreconditionError("Pass either ref or composer, not both: a ref finds the draft's window by its content, and a composer handle already names the window.");
6239
- if (opts.body !== void 0 && opts.edits !== void 0) throw new PreconditionError("Pass either body or edits, not both: a body replaces the whole text and edits change only what they match.");
6240
- if (opts.body === void 0 && !opts.edits?.length && !opts.attachments?.length) throw new PreconditionError("Nothing to change: pass a body, edits, attachments, or a combination. A new subject alone needs a body.");
6241
- if (opts.body !== void 0 && !opts.body.trim()) throw new PreconditionError("A replacement body cannot be empty. Blanking a draft and reporting success is indistinguishable from having written it, so it is refused here rather than done. Delete the draft with apple_mail_delete_messages if that is what you meant.");
6421
+ if (target.ref !== void 0 && target.composer !== void 0) throw new PreconditionError$1("Pass either ref or composer, not both: a ref finds the draft's window by its content, and a composer handle already names the window.");
6422
+ if (opts.body !== void 0 && opts.edits !== void 0) throw new PreconditionError$1("Pass either body or edits, not both: a body replaces the whole text and edits change only what they match.");
6423
+ if (opts.body === void 0 && !opts.edits?.length && !opts.attachments?.length) throw new PreconditionError$1("Nothing to change: pass a body, edits, attachments, or a combination. A new subject alone needs a body.");
6424
+ if (opts.body !== void 0 && !opts.body.trim()) throw new PreconditionError$1("A replacement body cannot be empty. Blanking a draft and reporting success is indistinguishable from having written it, so it is refused here rather than done. Delete the draft with apple_mail_delete_messages if that is what you meant.");
6242
6425
  const attachments = this.#resolveAttachments(opts.attachments, false);
6243
6426
  if (target.ref === void 0) {
6244
- if (opts.subject !== void 0) throw new PreconditionError("A new subject can only be set by rebuilding a saved draft, which needs its ref. Editing a composer by handle, or the one open, leaves the subject as it is.");
6427
+ if (opts.subject !== void 0) throw new PreconditionError$1("A new subject can only be set by rebuilding a saved draft, which needs its ref. Editing a composer by handle, or the one open, leaves the subject as it is.");
6245
6428
  if (!this.#ax) return nativeOnlyRefusal(target.composer !== void 0 ? "Editing a composer by handle" : "Editing the open composer");
6246
6429
  return released(this.#ax, await this.#editComposerDirectly(this.#ax, target.composer, opts, attachments));
6247
6430
  }
@@ -6530,12 +6713,12 @@ var AppleMailClient = class {
6530
6713
  */
6531
6714
  #resolveAttachments(paths, sendNow) {
6532
6715
  if (!paths?.length) return [];
6533
- if (sendNow && !this.config.allowFileSend) throw new PreconditionError("Sending a local file immediately is off. Leave out sendNow to open a draft with the attachments for the user to review and send, or set APPLE_MAIL_ALLOW_FILE_SEND=1 to allow attaching and sending in one call.");
6716
+ if (sendNow && !this.config.allowFileSend) throw new PreconditionError$1("Sending a local file immediately is off. Leave out sendNow to open a draft with the attachments for the user to review and send, or set APPLE_MAIL_ALLOW_FILE_SEND=1 to allow attaching and sending in one call.");
6534
6717
  return paths.map((path) => {
6535
- if (!isAbsolute(path)) throw new PreconditionError(`"${path}" is not an absolute path. This server has no meaningful working directory, so a relative path cannot be resolved to the file you mean.`);
6718
+ if (!isAbsolute(path)) throw new PreconditionError$1(`"${path}" is not an absolute path. This server has no meaningful working directory, so a relative path cannot be resolved to the file you mean.`);
6536
6719
  const source = resolve(path);
6537
- if (!existsSync(source)) throw new PreconditionError(`There is no file at ${source}.`);
6538
- if (!statSync(source).isFile()) throw new PreconditionError(`${source} is not a regular file; Mail can only attach files.`);
6720
+ if (!existsSync(source)) throw new PreconditionError$1(`There is no file at ${source}.`);
6721
+ if (!statSync(source).isFile()) throw new PreconditionError$1(`${source} is not a regular file; Mail can only attach files.`);
6539
6722
  return source;
6540
6723
  });
6541
6724
  }
@@ -7435,7 +7618,7 @@ const registerMessageTools = (server, client, allowWrites) => {
7435
7618
  truncated: parsed.truncated,
7436
7619
  body: parsed.body,
7437
7620
  attachments: parsed.attachments,
7438
- ...missing.length > 0 ? { note: `Not downloaded by Mail yet: ${missing.join(", ")}. Its bytes are not on disk, so apple_mail_save_attachment cannot retrieve it. Open the message in Mail to download it first.` } : {}
7621
+ ...missing.length > 0 ? { note: `Not downloaded by Mail yet: ${missing.join(", ")}. Its bytes are not on disk; apple_mail_save_attachment asks Mail to download it, which takes a few seconds per file and needs Mail running and online.` } : {}
7439
7622
  };
7440
7623
  }));
7441
7624
  server.registerTool("apple_mail_list_open_drafts", {
@@ -7477,7 +7660,7 @@ const registerMessageTools = (server, client, allowWrites) => {
7477
7660
  }));
7478
7661
  if (!allowWrites) return;
7479
7662
  server.registerTool("apple_mail_save_attachment", {
7480
- description: "Save one attachment to disk. It can only write into APPLE_MAIL_ATTACHMENT_DIR (default ~/Downloads) and will not overwrite an existing file unless you ask it to. Write-gated because it puts a file on the user's disk, even though it changes nothing in Mail.",
7663
+ description: "Save one attachment to disk. It can only write into APPLE_MAIL_ATTACHMENT_DIR (default ~/Downloads) and will not overwrite an existing file unless you ask it to. An attachment Mail has not downloaded (retrievable: false) is fetched by Mail from the server first, which needs Mail running and online and can take a few seconds; `from` says \"mail\" then. Write-gated because it puts a file on the user's disk.",
7481
7664
  inputSchema: z.object({
7482
7665
  ref: messageRefArg,
7483
7666
  filename: z.string().min(1).describe("Exact filename from apple_mail_list_attachments."),
@@ -8034,10 +8217,10 @@ var MailWatchService = class {
8034
8217
  }
8035
8218
  async #setUp() {
8036
8219
  const shared = await this.#client.index();
8037
- if (!shared) throw new PreconditionError(`The Envelope Index cannot be read, so there is nothing to ${this.#noun === "watch" ? "watch" : "read events from"}: ${this.#client.indexError ?? "reason unknown"}`);
8038
- if (shared.mode === "immutable") throw new PreconditionError(immutableReason(this.#noun));
8220
+ if (!shared) throw new PreconditionError$1(`The Envelope Index cannot be read, so there is nothing to ${this.#noun === "watch" ? "watch" : "read events from"}: ${this.#client.indexError ?? "reason unknown"}`);
8221
+ if (shared.mode === "immutable") throw new PreconditionError$1(immutableReason(this.#noun));
8039
8222
  const located = await this.#client.locate();
8040
- if (!located.envelopeIndexPath) throw new PreconditionError(located.reason ?? "The Envelope Index was not located.");
8223
+ if (!located.envelopeIndexPath) throw new PreconditionError$1(located.reason ?? "The Envelope Index was not located.");
8041
8224
  this.#open(located.envelopeIndexPath);
8042
8225
  try {
8043
8226
  await this.#refresh();
@@ -8055,7 +8238,7 @@ var MailWatchService = class {
8055
8238
  const index = new EnvelopeIndex(openIndex(path, this.#client.config.indexMode, this.#logger));
8056
8239
  if (index.mode === "immutable") {
8057
8240
  index.close();
8058
- throw new PreconditionError(immutableReason(this.#noun));
8241
+ throw new PreconditionError$1(immutableReason(this.#noun));
8059
8242
  }
8060
8243
  const old = this.#index;
8061
8244
  this.#index = index;
@@ -8218,10 +8401,10 @@ var MailWatchService = class {
8218
8401
  return [];
8219
8402
  }
8220
8403
  if (!(running ?? await this.#isMailRunning())) throw this.#mailboxesNeedMail();
8221
- for (const name of mailboxes) if (isUnwatchedMailbox(`imap://x/${name}`)) throw new PreconditionError(`"${name}" is never ${noun === "watch" ? "watched" : "followed"}: Sent, Drafts, Junk and Trash are excluded, so a ${noun} on it could never fire.`);
8404
+ for (const name of mailboxes) if (isUnwatchedMailbox(`imap://x/${name}`)) throw new PreconditionError$1(`"${name}" is never ${noun === "watch" ? "watched" : "followed"}: Sent, Drafts, Junk and Trash are excluded, so a ${noun} on it could never fire.`);
8222
8405
  await this.ensure();
8223
8406
  const rowids = await this.#client.mailboxRowidsFor(mailboxes);
8224
- if (rowids.length > MAX_WATCHED_MAILBOXES) throw new PreconditionError(`Those names cover ${rowids.length} mailboxes across the accounts, more than a ${noun} can follow (${MAX_WATCHED_MAILBOXES}). Name fewer mailboxes.`);
8407
+ if (rowids.length > MAX_WATCHED_MAILBOXES) throw new PreconditionError$1(`Those names cover ${rowids.length} mailboxes across the accounts, more than a ${noun} can follow (${MAX_WATCHED_MAILBOXES}). Name fewer mailboxes.`);
8225
8408
  return rowids.map(String);
8226
8409
  }
8227
8410
  /**
@@ -8233,7 +8416,7 @@ var MailWatchService = class {
8233
8416
  if (mailboxes.length > 0 && !await this.#isMailRunning()) throw this.#mailboxesNeedMail();
8234
8417
  }
8235
8418
  #mailboxesNeedMail() {
8236
- return new PreconditionError(`Mailbox names cannot be resolved until Mail is running: Mail is what says which mailboxes an account has. Open Mail and try again, or ${this.#noun === "watch" ? "watch" : "subscribe"} without \`mailboxes\`.`);
8419
+ return new PreconditionError$1(`Mailbox names cannot be resolved until Mail is running: Mail is what says which mailboxes an account has. Open Mail and try again, or ${this.#noun === "watch" ? "watch" : "subscribe"} without \`mailboxes\`.`);
8237
8420
  }
8238
8421
  /** Resolve `mailboxes` to scope keys and register the watch. */
8239
8422
  async add(filter, mailboxes) {
@@ -8411,6 +8594,6 @@ const createServer = (opts) => {
8411
8594
  };
8412
8595
  };
8413
8596
  //#endregion
8414
- export { WritesDisabledError as A, MessageNotFoundError as C, ProtocolError as D, PreconditionError as E, SchemaDriftError as O, MailNotRunningError as S, PlatformError as T, locateEnvelopeIndex as _, loadConfig as a, MAIL_SURFACE as b, decodeRef as c, assertStaticScript as d, createOsascriptRunner as f, inspectFile as g, MailboxMap as h, registerTools as i, BUILD_INFO as j, TccDeniedError as k, encodeRef as l, withBusyRetry as m, SERVER_VERSION as n, AppleMailClient as o, mapOsaError as p, createServer as r, REF_VERSION as s, SERVER_NAME as t, groupRefsByMailbox as u, AppleMailError as v, OsascriptTimeoutError as w, MailBusyError as x, IndexUnavailableError as y };
8597
+ export { WritesDisabledError as A, MessageNotFoundError as C, ProtocolError as D, PreconditionError$1 as E, SchemaDriftError as O, MailNotRunningError as S, PlatformError as T, locateEnvelopeIndex as _, loadConfig as a, MAIL_SURFACE as b, decodeRef as c, assertStaticScript as d, createOsascriptRunner as f, inspectFile as g, MailboxMap as h, registerTools as i, BUILD_INFO as j, TccDeniedError as k, encodeRef as l, withBusyRetry as m, SERVER_VERSION as n, AppleMailClient as o, mapOsaError as p, createServer as r, REF_VERSION as s, SERVER_NAME as t, groupRefsByMailbox as u, AppleMailError as v, OsascriptTimeoutError as w, MailBusyError as x, IndexUnavailableError as y };
8415
8598
 
8416
- //# sourceMappingURL=server-ynr059Dx.js.map
8599
+ //# sourceMappingURL=server-D5S4dzq6.js.map