@mgcrea/mcp-apple-mail 1.35.0 → 1.36.1

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
@@ -222,6 +222,7 @@ and a tripwire that refuses to run any script containing a `${`.
222
222
  | `APPLE_MAIL_ALLOW_FILE_SEND` | off | Let a compose tool attach local files and send in the same call. |
223
223
  | `APPLE_MAIL_ALLOW_WATCHES` | off | Register `watch` and `unwatch`: a resource agents read and hosts can subscribe to. |
224
224
  | `APPLE_MAIL_ALLOW_EVENTS` | off | Serve the experimental `mail.received` event (draft MCP Events extension, 2026-07-28 only). |
225
+ | `APPLE_MAIL_HAND_BACK_AFTER_DRAFT` | off | Bring back the app you were in after a draft. Off leaves Mail in front with the draft. |
225
226
  | `APPLE_MAIL_MAILBOX_CACHE_TTL_MS` | `60000` | How long the account/mailbox map is cached. |
226
227
 
227
228
  ## Notes
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-BANNirMx.js";
2
+ import { a as loadConfig, b as MAIL_SURFACE, j as BUILD_INFO, r as createServer } from "./server-BcVfuC1E.js";
3
3
  import { runStdioServer } from "@mgcrea/mcp-apple-core";
4
4
  //#region src/cli.ts
5
5
  const LOG_PREFIX = "apple-mail-mcp";
@@ -12,7 +12,8 @@ runStdioServer({
12
12
  const { server } = createServer({
13
13
  config,
14
14
  logger,
15
- era: ctx.era
15
+ era: ctx.era,
16
+ listens: ctx.listens
16
17
  });
17
18
  return {
18
19
  server,
package/dist/cli.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"cli.js","names":[],"sources":["../src/cli.ts"],"sourcesContent":["#!/usr/bin/env node\nimport { runStdioServer } from \"@mgcrea/mcp-apple-core\";\n\nimport { BUILD_INFO } from \"./build-info.js\";\nimport { MAIL_SURFACE } from \"./client/errors.js\";\nimport { loadConfig } from \"./config.js\";\nimport { createServer } from \"./server.js\";\n\nconst LOG_PREFIX = \"apple-mail-mcp\";\n\nrunStdioServer({\n build: BUILD_INFO,\n surface: MAIL_SURFACE,\n logPrefix: LOG_PREFIX,\n start: async (logger, ctx) => {\n const config = loadConfig();\n const { server } = createServer({ config, logger, era: ctx.era });\n return {\n server,\n banner:\n `writes=${config.allowWrites ? \"ENABLED\" : \"disabled\"}, ` +\n `watches=${config.allowWatches ? \"ENABLED\" : \"disabled\"}, ` +\n `accounts=${config.accounts.length ? config.accounts.join(\"/\") : \"all\"}, ` +\n `index=${config.indexMode}`,\n };\n },\n}).catch((err: unknown) => {\n console.error(`[${LOG_PREFIX}] fatal:`, err);\n process.exit(1);\n});\n"],"mappings":";;;;AAQA,MAAM,aAAa;AAEnB,eAAe;CACb,OAAO;CACP,SAAS;CACT,WAAW;CACX,OAAO,OAAO,QAAQ,QAAQ;EAC5B,MAAM,SAAS,WAAW;EAC1B,MAAM,EAAE,WAAW,aAAa;GAAE;GAAQ;GAAQ,KAAK,IAAI;EAAI,CAAC;EAChE,OAAO;GACL;GACA,QACE,UAAU,OAAO,cAAc,YAAY,WAAW,YAC3C,OAAO,eAAe,YAAY,WAAW,aAC5C,OAAO,SAAS,SAAS,OAAO,SAAS,KAAK,GAAG,IAAI,MAAM,UAC9D,OAAO;EACpB;CACF;AACF,CAAC,CAAC,CAAC,OAAO,QAAiB;CACzB,QAAQ,MAAM,IAAI,WAAW,WAAW,GAAG;CAC3C,QAAQ,KAAK,CAAC;AAChB,CAAC"}
1
+ {"version":3,"file":"cli.js","names":[],"sources":["../src/cli.ts"],"sourcesContent":["#!/usr/bin/env node\nimport { runStdioServer } from \"@mgcrea/mcp-apple-core\";\n\nimport { BUILD_INFO } from \"./build-info.js\";\nimport { MAIL_SURFACE } from \"./client/errors.js\";\nimport { loadConfig } from \"./config.js\";\nimport { createServer } from \"./server.js\";\n\nconst LOG_PREFIX = \"apple-mail-mcp\";\n\nrunStdioServer({\n build: BUILD_INFO,\n surface: MAIL_SURFACE,\n logPrefix: LOG_PREFIX,\n start: async (logger, ctx) => {\n const config = loadConfig();\n const { server } = createServer({ config, logger, era: ctx.era, listens: ctx.listens });\n return {\n server,\n banner:\n `writes=${config.allowWrites ? \"ENABLED\" : \"disabled\"}, ` +\n `watches=${config.allowWatches ? \"ENABLED\" : \"disabled\"}, ` +\n `accounts=${config.accounts.length ? config.accounts.join(\"/\") : \"all\"}, ` +\n `index=${config.indexMode}`,\n };\n },\n}).catch((err: unknown) => {\n console.error(`[${LOG_PREFIX}] fatal:`, err);\n process.exit(1);\n});\n"],"mappings":";;;;AAQA,MAAM,aAAa;AAEnB,eAAe;CACb,OAAO;CACP,SAAS;CACT,WAAW;CACX,OAAO,OAAO,QAAQ,QAAQ;EAC5B,MAAM,SAAS,WAAW;EAC1B,MAAM,EAAE,WAAW,aAAa;GAAE;GAAQ;GAAQ,KAAK,IAAI;GAAK,SAAS,IAAI;EAAQ,CAAC;EACtF,OAAO;GACL;GACA,QACE,UAAU,OAAO,cAAc,YAAY,WAAW,YAC3C,OAAO,eAAe,YAAY,WAAW,aAC5C,OAAO,SAAS,SAAS,OAAO,SAAS,KAAK,GAAG,IAAI,MAAM,UAC9D,OAAO;EACpB;CACF;AACF,CAAC,CAAC,CAAC,OAAO,QAAiB;CACzB,QAAQ,MAAM,IAAI,WAAW,WAAW,GAAG;CAC3C,QAAQ,KAAK,CAAC;AAChB,CAAC"}
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, 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, 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";
@@ -95,6 +95,7 @@ declare const ConfigSchema: z.ZodObject<{
95
95
  allowFileSend: z.ZodDefault<z.ZodBoolean>;
96
96
  allowWatches: z.ZodDefault<z.ZodBoolean>;
97
97
  allowEvents: z.ZodDefault<z.ZodBoolean>;
98
+ handBackAfterDraft: z.ZodDefault<z.ZodBoolean>;
98
99
  mailboxCacheTtlMs: z.ZodDefault<z.ZodNumber>;
99
100
  }, z.core.$strict>;
100
101
  type Config = z.infer<typeof ConfigSchema>;
@@ -165,6 +166,14 @@ type NativeComposer = {
165
166
  quoted: boolean | null;
166
167
  /** Named files in the own text. Empty for a background tab, which is not read. */
167
168
  files: string[];
169
+ /**
170
+ * On a desktop that is not the one shown (another Space, or Mail full
171
+ * screen): read where it is, and brought forward by `windowId` to be
172
+ * edited. Absent otherwise, and from an app that predates it.
173
+ */
174
+ onAnotherDesktop?: true;
175
+ /** The window server's number for its window; present with `onAnotherDesktop`. */
176
+ windowId?: number | null;
168
177
  };
169
178
  type EditComposerArgs = {
170
179
  composer: string;
@@ -191,22 +200,45 @@ type ReachReport = {
191
200
  reason: "accessibility" | null;
192
201
  windows: string[] | null;
193
202
  };
203
+ type MailAxLaneOptions = {
204
+ handBack?: boolean;
205
+ desktopTimeoutMs?: number;
206
+ };
194
207
  declare class MailAxLane {
195
208
  #private;
196
209
  private constructor();
197
210
  /** Null when this server is not hosted by Cupertino — see the note above. */
198
- static open(env?: NodeJS.ProcessEnv): MailAxLane | null;
211
+ static open(env?: NodeJS.ProcessEnv, opts?: MailAxLaneOptions): MailAxLane | null;
199
212
  close(): void;
200
213
  /** Start watching for someone using the Mac during a sequence. */
201
214
  watch(): InterferenceWatch;
202
- /** Every open composer, with its handle and own text. */
215
+ /**
216
+ * Every open composer, with its handle and own text. Those on another
217
+ * desktop (a Space, or Mail full screen) are listed too, read where they
218
+ * are, with `onAnotherDesktop`: the app finds them by the window server's
219
+ * count, which Accessibility's own list does not reach.
220
+ */
203
221
  composers(quoteChars?: number): Promise<NativeComposer[]>;
204
222
  /**
205
223
  * Edit a composer in one verified native step. The verb's JSON comes back
206
224
  * verbatim: a refusal is an answer, not an error. A failure of the call itself
207
225
  * (bad arguments, Accessibility not trusted) throws, as every `#call` does.
226
+ *
227
+ * A composer on another desktop is refused by the app before anything is
228
+ * touched, with its `windowId`. It is then brought forward here, which
229
+ * switches to its desktop, and asked about again until it is on the one
230
+ * shown or `desktopTimeoutMs` runs out: so every path that edits a
231
+ * composer (compose, revise, rebuild) reaches one wherever it is.
208
232
  */
209
233
  editComposer(args: EditComposerArgs): Promise<Record<string, unknown>>;
234
+ /**
235
+ * End the driving session a draft opened, now rather than on the app's idle
236
+ * release 45 seconds later, which brought back the app the person had been
237
+ * in while they were reading the draft. Whether it does that is the setting.
238
+ * Best effort: the draft is saved whatever this answers, and the app does
239
+ * not end a session that also drove another application.
240
+ */
241
+ release(): Promise<void>;
210
242
  /**
211
243
  * Can this process read Mail's windows, right now?
212
244
  *
@@ -1263,6 +1295,8 @@ type CreateServerOptions = {
1263
1295
  osascript?: OsascriptRunner;
1264
1296
  /** Which protocol era this instance serves. Only watches care. Default `legacy`. */
1265
1297
  era?: Era;
1298
+ /** The connection's open listens, so a watch update nobody listens for is logged. */
1299
+ listens?: ListenLedger;
1266
1300
  /** Injected by tests so a watch never runs `pgrep`. */
1267
1301
  isMailRunning?: () => Promise<boolean>;
1268
1302
  };
@@ -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":";;;;;cAkBa,YAAY;;;;cCWZ,6BAA6B;WACtB;EAElB,YAAY;;;;;;;;;;;;;;;;;;;;KCTF;;EAEV;;EAEA;EACA;;EAEA;EACA;EACA;EACA;EACA;;EAEA;EACA;EACA;;KAKU;;EAEV;;EAEA;;EAEA;;EAEA;;cAiBW,sBAAmB,OAAU,kBAAqB;;;;;;;;;;;;;;;cC3CzD,cAAY,EAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAkFP,EAAA,KAAA;KAEC,SAAS,EAAE,aAAa;;;;;cAMvB,aAAU,MAAS,OAAO,eAA2B;;;KCjCtD;EAAgB;EAAgB;EAAc;;;KAG9C;;;;;;;;;EASV;;;;;;;;;;;EAWA;;EAEA;;;;;;;;EAQA;;EAEA;;EAEA;;EAEA;EACA;EACA;;EAEA;;EAEA;EACA;;;;;;EAMA;;EAEA;;EAEA;;KAGU;EACV;EACA;;;;;;;EAOA;EACA;EACA;IAAU;IAAc;;EACxB;EACA;EACA;;KAGU;EACV;;EAEA;EACA;;cAGW;;UAGJ;;SAKA,KAAK,MAAK,OAAO,aAA2B;EAKnD;;EAKA,SAAS;;EASH,UAAU,sBAAsB,QAAQ;;;;;;EAaxC,aAAa,MAAM,mBAAmB,QAAQ;;;;;;;;;;;;;;;;;;EAqB9C,SAAS,QAAQ;;;;;;;;;;;;;;;SA2BhB,aAAa;;kBAUJ;;;;;;;;;;;;;;;;;EAkBV,aAAa,iBAAiB,oBAAoB,QAAQ;;EA4B1D,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAkDZ,OACJ,kBACA,KAAK,aACL,cAAc,mBACb;;;;;;;;;;;;;EAiCG,aAAa,iBAAiB,oBAAoB;;;;KCpX9C;EACV;EACA;EACA;;;;;;;;;EASA;;EAEA;;;;;;;;;;;;;;;;;;;;;KCGU;EACV,SAAS;EACT;EACA;;EAEA,cAAc;IAAe;;EAC7B;EACA;EACA;EACA;;;;KC3BU;EACV;EACA,QAAQ;EACR;IACE;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;;;EAGF;EACA;EACA;;;;KChBU;EACV;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;;KAGU;EACV;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;;;;;;;;;cAUW;KAED,qBAAqB;KAErB;;EAEV;;EAEA;EACA;EACA;EACA;EACA;;KAGU;EACV,QAAQ;;EAER;;EAEA;;;KAIU;EACV;;EAEA;EACA;;EAEA;;EAEA;EACA;EACA;EACA;EACA;;KAOU;EACV,IAAI;;EAEJ;EACA,MAAM;;cA+BK;;WAEF,MAAM;WACN;EAET,YAAY,QAAQ;EAMpB;;EASA;IAAe;IAAe;IAAa;IAAsB;;EA2IjE,OAAO,SAAS,gBAAgB;;;;;;;;;;EA0FhC,QAAQ,SAAS,KAAK,0BAA0B,OAAO,aAAa;;;;;;;;EAsDpE,MAAM,SAAS,KAAK;IAAoC;IAAe;;;;;;;;;;;;;;;;;;;;;EA+BvE,YACE;IAAU;IAAa;QACtB;IAAc;IAAe;;;;;;;;;EAsChC,QAAQ,gBAAgB;;EA6BxB,OAAO,wBAAwB,gBAAgB;;EAmC/C;;;;;;;;;;;;EAkBA,cAAc,eAAe,gBAAgB;;EAoC7C,WAAW;;;;;;;;;;;EAcX,sBAAsB;IAAmB;IAAe;;;EAgBxD,eAAe;;;;;;;;;;;;;KCzoBL;EACV;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;;KAGU;EACV,QAAQ;;EAER;EACA;EACA;;cAGW;;EAUX,YAAY,MAAM;;;;;;;EAqBZ,SAAS,kBAAgB,QAAQ;;;;;;EA8BjC,eAAe,iBAAiB,QAAQ;;;;;;EAwB9C,mBAAmB,SAAS,aAAa;;;;;;EAwBnC,gBAAgB,cAAc;IAAU,SAAS;IAAa;;;;;;;EASpE,kBACE,mBAAmB,eACnB;IACG,SAAS;IAAa;;EAc3B;;;;KCjGU;EACV;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;;KAGU;EACV;EACA;EACA;EACA;EACA;;;;;;;;;;;KAYU;EAEN;EACA;EACA;EACA;;EAEA;EACA;EACA;;EAEA;EAAsB;EAAoB;;KA6BpC;EACV,QAAQ;EACR,SAAS;EACT,YAAY;;;;;;;;;EASZ,KAAK;;cAiBM;;WACF,QAAQ;WACR,QAAQ;WACR,WAAW;EAkBpB,YAAY,MAAM;;MAoBd;EAIJ,SAAS,kBAAgB,QAAQ;;;;;;EAS3B,OAAO,kBAAgB,QAAQ;;;;;;;;;;;;;EA+B/B,kBAAkB;IACtB;IACA;;;;;;;;;IASA;IACA;;;;;;;;;;;;EAwBI,mBAAmB;IAAU;IAAa;;EAM1C,SAAS,QAAQ;;;;;;;;;;;EA4CjB,cAAc;IAAQ;IAAyB;MAAwB;IAEzE;IACA;IACA;IACA;IACA;IACA;;;;;;;EAyFE,aACJ,SAAS,aACT,iBACA,gBACC;IACC;IAAiB;IAAe,UAAU;;IACtC;;IACA;IAAuB;;;;;;;EAuBzB,cACJ,SAAS,aACT,kBACC;IACG;IAAiB;IAAe;MAAU;;IAAiB;;IAE3D;IACA;IACA;MAAU;MAA4B;;IACtC;IACA;;EAmBA,aAAa,SAAS,aAAa,kBAAe;IAIrC;IACJ;IACF;IACC;;;;;;;EAUR,WACJ,SAAS,aACT,iBACA,gBACC;IAAU;IAAiB;IAAe,UAAU;;;EAcjD,YACJ;IAAO;IAAqB;KAC5B,eACA;IAAQ;IAAuB;IAAsB;MACpD,QAAQ;;;;;;EAwBL,SAAS,QAAQ;MAwBnB;;EAKE,mBAAmB;;;;;;;;EAanB,iBAAiB,QACrB;IAAc;IAAqB;IAAiB;;;;;;;;EAuBhD,iBAAiB,kBAAkB;;;;;;;;;EA8DnC,cACJ,MAAM,KAAK;IACT;IACA;KAEF,OAAO,aACN,SACE;IACC;IACA;IACA;;EAoCA,eACJ,MAAM,KAAK;IACT;IACA;;IAEA;MAED;IACD,UAAU;IACV;IACA;IACA;IACA;IACA,WAAW;;EA4GP,SAAS,aAAa,gBAAgB,QAAQ;;;;;;;;;EAkD9C,eACJ,aACA;IAAQ;MACP;IACD,SAAS;IACT,QAAQ;IACR;;IAEA;;;;;;;;;EAiCI,gBACJ,aACA;IAAQ;MACP;IAAU,QAAQ;IAAe;;IAAqB;IAAc;;EAmBjE,iBACJ,aACA;IAAQ;IAAgB;MACvB;IACD;IACA;IACA;IACA;IACA;;;;;;;;;;;;;;;EA2HI,oBAAoB;IAEtB;IACA;IACA;IACA;IACA;IACA;IACA;IACA;;;;;;;;;EA8HE,eACJ,aACA,kBACA;IAAQ;MACP;IAAU;IAAc;IAAe;;;EAsCpC,SACJ,gBACA;IAAS;IAAgB;IAAmB;IAAoB;MAC/D;IAAU;IAAiB;IAAgB;;EA6BxC,aACJ,gBACA;IAAQ;IAA4B;MACnC;IAAU;IAAe;IAAgB;IAAqB;;EAqD3D,eAAe,iBAAiB;IACpC;IACA;IACA;IACA;;;;;;;;;;;;;;EAuCI,cACJ,cACA,mBACC;IACD;IACA;IACA;IACA;IACA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAqEI,YACJ;IAAU;IAA0B;KACpC;IACE;IACA;MAAU;MAAc;;IACxB;IACA;MAED,QAAQ;;;;;;;;;;;;EA0RL,eACJ;IAAQ;MACP,QAAQ;EAqFL,gBAAgB,mBAAmB;EAKnC,YAAY;IAChB;IACA;IACA;IACA;IACA;IACA;IACA;IACA;MACE;EAqCE,eACJ,aACA;IACE;IACA;IACA;IACA;IACA;IACA;MAED;;;;;;;;;;;;;;;;;;;;;cCj3DQ;KAED;EACV;EACA;EACA;;cAKW,YAAS,KAAS;cAGlB,YAAS,gBAAkB;;cA2B3B,qBAAkB,MAAU,iBAAe,YAAY;;;;;;;;;;;;;;KCzCxD,cAAc;;EAExB;EACA;EACA;EACA;EACA;EACA;;;;KC+GU;EACV,QAAQ;EACR,QAAQ,KAAK;EACb,SAAS;;EAET,uBAAuB;EACvB;;;;;;;EAOA;;cAGW;;;WA2CF,QAAQ,cAAc;EAO/B,YAAY,MAAM;;MAWd;;EAKJ,KAAK,UAAU,cAAc;;;;;;;;;;;;;;;;;EAyB7B,UAAU;;;;;;;;;;;EA+LJ,UAAU,mBAAmB;;;;;;EAwBnC,WAAW,mBAAmB;;;;;;EAiB9B,eAAY;IAA6B;;;EAgBzC;EAQA,OAAO;;EAKP,YAAY;;;;;;;;EAWN,oBAAoB,qBAAqB,oBAAoB;;;;;;EAgC7D,kBAAkB,sBAAsB;;EAcxC,IACJ,QAAQ,kBAAkB,kBAC1B,kCACC;IAAU,OAAO;IAAO;;;;;cCjiBhB;cACA;KAED;EACV,QAAQ;EACR,SAAS;;EAET,YAAY;;EAEZ,MAAM;;EAEN,sBAAsB;;KAGZ;EACV,QAAQ;EACR,QAAQ;;EAER,UAAU;;EAEV,SAAS;;;;;;;cAQE,eAAY,MAAU,wBAAsB;;;KCpC7C;;;;;EAKV;;;;;EAKA,UAAU;;;;;;;;;;;;;cAcC,gBAAa,QAChB,WAAS,QACT,iBAAe,KAClB"}
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-BANNirMx.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-BcVfuC1E.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 };
@@ -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: "c832367",
18
- gitCommitDate: "2026-10-30T14:15:32+01:00"
17
+ gitCommit: "b82ad61",
18
+ gitCommitDate: "2026-11-03T12:29:16+01:00"
19
19
  };
20
20
  //#endregion
21
21
  //#region src/client/errors.ts
@@ -156,15 +156,30 @@ const BODY_ROLE = "AXWebArea";
156
156
  * holds a deeply nested quoted message — the web area itself sits near the top.
157
157
  */
158
158
  const BODY_DEPTH = 8;
159
+ /** The window id an edit was refused for as being on another desktop; null for any other answer. */
160
+ const onAnotherDesktop = (result) => result.replaced === false && result.capability === "desktop" && typeof result.windowId === "number" ? result.windowId : null;
161
+ /** How long an edit waits for a composer brought from another desktop to arrive. */
162
+ const DESKTOP_TIMEOUT_MS = 3e3;
163
+ /** Between asks while it arrives. */
164
+ const DESKTOP_POLL_MS = 150;
159
165
  var MailAxLane = class MailAxLane {
160
166
  #channel;
161
- constructor(channel) {
167
+ /**
168
+ * Whether a draft ends by bringing back the app that was in front (config's
169
+ * `handBackAfterDraft`). Carried here so every edit and every `release`
170
+ * says it, whichever path made the draft.
171
+ */
172
+ #handBack;
173
+ #desktopTimeoutMs;
174
+ constructor(channel, opts) {
162
175
  this.#channel = channel;
176
+ this.#handBack = opts.handBack ?? false;
177
+ this.#desktopTimeoutMs = opts.desktopTimeoutMs ?? DESKTOP_TIMEOUT_MS;
163
178
  }
164
179
  /** Null when this server is not hosted by Cupertino — see the note above. */
165
- static open(env = process.env) {
180
+ static open(env = process.env, opts = {}) {
166
181
  const channel = openAxChannel(MAIL_SURFACE, env);
167
- return channel ? new MailAxLane(channel) : null;
182
+ return channel ? new MailAxLane(channel, opts) : null;
168
183
  }
169
184
  close() {
170
185
  this.#channel.close();
@@ -179,7 +194,12 @@ var MailAxLane = class MailAxLane {
179
194
  args
180
195
  });
181
196
  }
182
- /** Every open composer, with its handle and own text. */
197
+ /**
198
+ * Every open composer, with its handle and own text. Those on another
199
+ * desktop (a Space, or Mail full screen) are listed too, read where they
200
+ * are, with `onAnotherDesktop`: the app finds them by the window server's
201
+ * count, which Accessibility's own list does not reach.
202
+ */
183
203
  async composers(quoteChars) {
184
204
  return (await this.#call("mail_composers", quoteChars === void 0 ? {} : { quoteChars })).composers ?? [];
185
205
  }
@@ -187,9 +207,51 @@ var MailAxLane = class MailAxLane {
187
207
  * Edit a composer in one verified native step. The verb's JSON comes back
188
208
  * verbatim: a refusal is an answer, not an error. A failure of the call itself
189
209
  * (bad arguments, Accessibility not trusted) throws, as every `#call` does.
210
+ *
211
+ * A composer on another desktop is refused by the app before anything is
212
+ * touched, with its `windowId`. It is then brought forward here, which
213
+ * switches to its desktop, and asked about again until it is on the one
214
+ * shown or `desktopTimeoutMs` runs out: so every path that edits a
215
+ * composer (compose, revise, rebuild) reaches one wherever it is.
190
216
  */
191
217
  async editComposer(args) {
192
- return await this.#call("mail_composer_edit", { ...args });
218
+ const edit = async () => await this.#call("mail_composer_edit", {
219
+ ...args,
220
+ handBack: this.#handBack
221
+ });
222
+ let result = await edit();
223
+ const windowId = onAnotherDesktop(result);
224
+ if (windowId === null || !await this.#bringForward(windowId)) return result;
225
+ const deadline = Date.now() + this.#desktopTimeoutMs;
226
+ for (;;) {
227
+ result = await edit();
228
+ if (onAnotherDesktop(result) === null || Date.now() >= deadline) return result;
229
+ await new Promise((resolve) => setTimeout(resolve, DESKTOP_POLL_MS));
230
+ }
231
+ }
232
+ /**
233
+ * Bring the window `windowId` onto the desktop shown, through the app's
234
+ * `mail_bring_forward`, which activates Mail, raises the window and says
235
+ * whether it landed. False when it did not, when the person said no to
236
+ * being driven, and from an app that predates the verb: the edit's own
237
+ * refusal then stands, naming the window.
238
+ */
239
+ async #bringForward(windowId) {
240
+ try {
241
+ return (await this.#call("mail_bring_forward", { windowId })).broughtForward === true;
242
+ } catch {
243
+ return false;
244
+ }
245
+ }
246
+ /**
247
+ * End the driving session a draft opened, now rather than on the app's idle
248
+ * release 45 seconds later, which brought back the app the person had been
249
+ * in while they were reading the draft. Whether it does that is the setting.
250
+ * Best effort: the draft is saved whatever this answers, and the app does
251
+ * not end a session that also drove another application.
252
+ */
253
+ async release() {
254
+ await this.#call("mail_release", { handBack: this.#handBack }).catch(() => void 0);
193
255
  }
194
256
  /**
195
257
  * Can this process read Mail's windows, right now?
@@ -1644,8 +1706,12 @@ function maxQuoteLevel(el, depth) {
1644
1706
  * of a composer coming forward is worth less than a window stuck at [1, 1].
1645
1707
  *
1646
1708
  * Failure is reported, never fatal: a quoted send still beats a lost one.
1709
+ *
1710
+ * handBack false leaves Mail in front once the window is put back: a draft
1711
+ * the person is about to read (the Mail setting "Return to the previous app
1712
+ * after a draft", off).
1647
1713
  */
1648
- function stripCitation(windowName) {
1714
+ function stripCitation(windowName, handBack) {
1649
1715
  var SE = Application("System Events");
1650
1716
  var proc = SE.processes.byName("Mail");
1651
1717
 
@@ -1713,7 +1779,7 @@ function stripCitation(windowName) {
1713
1779
  // failure path too: a strip that threw must not cost the user their composer.
1714
1780
  unhide();
1715
1781
 
1716
- if (previous && previous !== "Mail") {
1782
+ if (handBack !== false && previous && previous !== "Mail") {
1717
1783
  try { SE.processes.byName(previous).frontmost = true; } catch (e) {}
1718
1784
  }
1719
1785
  return stripped;
@@ -2322,7 +2388,9 @@ const SEND_MESSAGE = script(`
2322
2388
 
2323
2389
  pause(1.2);
2324
2390
  var unquoted = false;
2325
- try { unquoted = stripCitation(String(p.subject || "")); } catch (e) { unquoted = false; }
2391
+ try {
2392
+ unquoted = stripCitation(String(p.subject || ""), p.sendNow || p.handBack !== false);
2393
+ } catch (e) { unquoted = false; }
2326
2394
 
2327
2395
  /*
2328
2396
  * Assigning content made Mail wrap the body in a quotation that Mail itself
@@ -2589,7 +2657,7 @@ const UPDATE_DRAFT = script(`
2589
2657
 
2590
2658
  pause(1.2);
2591
2659
  var unquoted = false;
2592
- try { unquoted = stripCitation(subject); } catch (e) { unquoted = false; }
2660
+ try { unquoted = stripCitation(subject, p.handBack !== false); } catch (e) { unquoted = false; }
2593
2661
 
2594
2662
  /*
2595
2663
  * Assigning content made Mail wrap the whole body in a hidden quotation, and
@@ -3119,7 +3187,8 @@ const REPLY_OR_FORWARD = script(`
3119
3187
  verifiedChars: verifiedChars, subject: subject });
3120
3188
  }
3121
3189
 
3122
- restore();
3190
+ // A draft is left for the person to read, unless the setting asks otherwise.
3191
+ if (p.handBack !== false) restore();
3123
3192
  return ok({
3124
3193
  sent: false,
3125
3194
  draft: true,
@@ -3519,7 +3588,7 @@ const composeNatively = async (lane, runner, params, opts = {}) => {
3519
3588
  bodyVerified: null,
3520
3589
  verifiedChars: 0,
3521
3590
  sent: false,
3522
- note: `Mail was asked to open a ${params.mode} window for "${subject}" and no such window was readable within ${composerTimeoutMs / 1e3}s, although Mail's other windows read fine — so this is not a permission. Nothing was written. The window may still be on screen: look for an empty ${params.mode} in Mail before retrying, because a retry would leave a second one behind. Windows visible at the time: ${JSON.stringify(reach.windows)}.` + interferenceNote(await watch.check())
3591
+ note: `Mail was asked to open a ${params.mode} window for "${subject}" and no such window was readable within ${composerTimeoutMs / 1e3}s, ` + ((reach.windows ?? []).length > 0 ? `although Mail's other windows read fine — so this is not a permission. ` : "and no Mail window could be read at all, on any desktop. Run apple_mail_diagnostics before retrying. ") + `Nothing was written. The window may still be on screen: look for an empty ${params.mode} in Mail before retrying, because a retry would leave a second one behind. Windows visible at the time: ${JSON.stringify(reach.windows)}.` + interferenceNote(await watch.check())
3523
3592
  };
3524
3593
  /**
3525
3594
  * The composer is no longer on screen, and nothing here closed it.
@@ -3611,15 +3680,18 @@ const composeNatively = async (lane, runner, params, opts = {}) => {
3611
3680
  verified: true,
3612
3681
  chars: verifiedChars
3613
3682
  } : null;
3614
- if (filling && !params.sendNow) return {
3615
- ok: true,
3616
- subject,
3617
- bodyVerified,
3618
- verifiedChars,
3619
- sent: false,
3620
- ...files.length > 0 ? { attachments: files.length } : {},
3621
- note: "Draft window is open in Mail for review."
3622
- };
3683
+ if (filling && !params.sendNow) {
3684
+ await lane.release();
3685
+ return {
3686
+ ok: true,
3687
+ subject,
3688
+ bodyVerified,
3689
+ verifiedChars,
3690
+ sent: false,
3691
+ ...files.length > 0 ? { attachments: files.length } : {},
3692
+ note: "Draft window is open in Mail for review."
3693
+ };
3694
+ }
3623
3695
  let sharing;
3624
3696
  try {
3625
3697
  sharing = (await lane.composers()).filter((c) => c.subject === subject);
@@ -3682,6 +3754,7 @@ const composeNatively = async (lane, runner, params, opts = {}) => {
3682
3754
  note: `The ${params.mode} for "${subject}" was composed, but Mail could not be brought to the front, so nothing was pressed and it was not ${action}. Its window is still open in Mail. Someone is probably using the Mac; retry once it is free, or finish it in Mail.` + interferenceNote(await watch.check())
3683
3755
  };
3684
3756
  const sent = params.sendNow ? await lane.composerGone(subject, sendTimeoutMs) : false;
3757
+ if (!params.sendNow) await lane.release();
3685
3758
  return {
3686
3759
  ok: params.sendNow ? sent : true,
3687
3760
  subject,
@@ -5139,6 +5212,11 @@ const nativeOnlyRefusal = (what) => ({
5139
5212
  reason: `${what} needs Cupertino's native composer, and this server was not started by Cupertino. Nothing was changed.`,
5140
5213
  hint: "Run the Mail server from Cupertino.app, or pass a ref and a whole body to rewrite the draft the older way."
5141
5214
  });
5215
+ /** A verified native edit ends the session it opened: see `MailAxLane.release`. */
5216
+ const released = async (lane, result) => {
5217
+ if (result.replaced === true) await lane.release();
5218
+ return result;
5219
+ };
5142
5220
  var AppleMailClient = class {
5143
5221
  config;
5144
5222
  runner;
@@ -5171,7 +5249,7 @@ var AppleMailClient = class {
5171
5249
  allowlist: opts.config.accounts,
5172
5250
  ttlMs: opts.config.mailboxCacheTtlMs
5173
5251
  });
5174
- this.#ax = opts.ax !== void 0 ? opts.ax : MailAxLane.open();
5252
+ this.#ax = opts.ax !== void 0 ? opts.ax : MailAxLane.open(process.env, { handBack: opts.config.handBackAfterDraft });
5175
5253
  }
5176
5254
  /** Which composer lane is live, for `diagnostics` to report. */
5177
5255
  get composerLane() {
@@ -6135,7 +6213,7 @@ var AppleMailClient = class {
6135
6213
  if (target.ref === void 0) {
6136
6214
  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.");
6137
6215
  if (!this.#ax) return nativeOnlyRefusal(target.composer !== void 0 ? "Editing a composer by handle" : "Editing the open composer");
6138
- return this.#editComposerDirectly(this.#ax, target.composer, opts, attachments);
6216
+ return released(this.#ax, await this.#editComposerDirectly(this.#ax, target.composer, opts, attachments));
6139
6217
  }
6140
6218
  if (opts.edits !== void 0 && !this.#ax) return nativeOnlyRefusal("Editing by find and replace");
6141
6219
  const decoded = decodeRef(target.ref);
@@ -6170,9 +6248,9 @@ var AppleMailClient = class {
6170
6248
  edits: opts.edits,
6171
6249
  attachments
6172
6250
  });
6173
- if (edited) return edited;
6251
+ if (edited) return released(lane, edited);
6174
6252
  }
6175
- return rebuildDraft({
6253
+ const rebuilt = await rebuildDraft({
6176
6254
  lane,
6177
6255
  runner: this.runner,
6178
6256
  messageFile: async (ref) => {
@@ -6193,6 +6271,7 @@ var AppleMailClient = class {
6193
6271
  subject: opts.subject,
6194
6272
  attachments
6195
6273
  });
6274
+ return released(lane, rebuilt);
6196
6275
  }
6197
6276
  if (opts.body === void 0) {
6198
6277
  const gone = "none is open for this one that this server can reach: it was not started by Cupertino";
@@ -6210,7 +6289,8 @@ var AppleMailClient = class {
6210
6289
  ...decodedTarget,
6211
6290
  body: opts.body,
6212
6291
  subject: opts.subject ?? null,
6213
- attachments
6292
+ attachments,
6293
+ handBack: this.config.handBackAfterDraft
6214
6294
  }));
6215
6295
  }
6216
6296
  /**
@@ -6335,7 +6415,7 @@ var AppleMailClient = class {
6335
6415
  });
6336
6416
  return {
6337
6417
  drafts,
6338
- note: composers.length === 0 ? "No compose window is open in Mail." : "`composer` is the window's handle, which apple_mail_update_draft takes to edit that window directly. Recipients are the names Mail shows in the window, not addresses — read a saved draft with apple_mail_get_message for those. `savedDrafts` are the copies Mail has autosaved under the same subject, newest first: a composer opened seconds ago may have none yet, and the newest one can lag what the window shows. The window is the current text." + (composers.some((c) => c.tab === "background") ? " Mail shows these drafts as tabs of one window. A draft with `tab: \"background\"` is a tab it is not showing: its text, quote and recipients are null because reading them would mean switching tabs, which listing never does. They are read once it is the selected tab (`tab: \"selected\"`): select it in Mail and list again, or edit it with apple_mail_update_draft, which selects its tab and checks it, and once the edit is saved leaves that tab shown in place of the one that was: tell the person which draft Mail now shows." : "") + (composers.some((c) => c.rebound === true) ? " A draft with `rebound: true` is a tab whose window Mail rebuilt since its handle was given, so the handle may now name another draft under the same title: it stays reference-only until its text is proved. Edit it by a ref from `savedDrafts`, which checks its text; after that verified edit, list again and the handle edits on its own." : "") + (index ? "" : " `savedDrafts` is null because the search index cannot be read.")
6418
+ note: composers.length === 0 ? "No compose window is open in Mail." : "`composer` is the window's handle, which apple_mail_update_draft takes to edit that window directly. Recipients are the names Mail shows in the window, not addresses — read a saved draft with apple_mail_get_message for those. `savedDrafts` are the copies Mail has autosaved under the same subject, newest first: a composer opened seconds ago may have none yet, and the newest one can lag what the window shows. The window is the current text." + (composers.some((c) => c.tab === "background") ? " Mail shows these drafts as tabs of one window. A draft with `tab: \"background\"` is a tab it is not showing: its text, quote and recipients are null because reading them would mean switching tabs, which listing never does. They are read once it is the selected tab (`tab: \"selected\"`): select it in Mail and list again, or edit it with apple_mail_update_draft, which selects its tab and checks it, and once the edit is saved leaves that tab shown in place of the one that was: tell the person which draft Mail now shows." : "") + (composers.some((c) => c.onAnotherDesktop === true) ? " A draft with `onAnotherDesktop: true` is on a desktop that is not the one shown (another Space, or Mail in full screen): it is read where it is, and editing it with apple_mail_update_draft brings Mail forward on that desktop first, which switches the person's screen to it." : "") + (composers.some((c) => c.rebound === true) ? " A draft with `rebound: true` is a tab whose window Mail rebuilt since its handle was given, so the handle may now name another draft under the same title: it stays reference-only until its text is proved. Edit it by a ref from `savedDrafts`, which checks its text; after that verified edit, list again and the handle edits on its own." : "") + (index ? "" : " `savedDrafts` is null because the search index cannot be read.")
6339
6419
  };
6340
6420
  }
6341
6421
  /** Drafts-mailbox messages carrying exactly this subject, newest first. */
@@ -6383,7 +6463,8 @@ var AppleMailClient = class {
6383
6463
  subject: opts.subject,
6384
6464
  body: opts.body,
6385
6465
  attachments,
6386
- sendNow: opts.sendNow
6466
+ sendNow: opts.sendNow,
6467
+ handBack: this.config.handBackAfterDraft
6387
6468
  });
6388
6469
  }
6389
6470
  async replyOrForward(ref, opts) {
@@ -6401,7 +6482,10 @@ var AppleMailClient = class {
6401
6482
  sendNow: opts.sendNow
6402
6483
  };
6403
6484
  if (this.#ax) return composeNatively(this.#ax, this.runner, params);
6404
- return this.runner.run(REPLY_OR_FORWARD, params);
6485
+ return this.runner.run(REPLY_OR_FORWARD, {
6486
+ ...params,
6487
+ handBack: this.config.handBackAfterDraft
6488
+ });
6405
6489
  }
6406
6490
  /**
6407
6491
  * The files a compose call names, checked before Mail is asked anything.
@@ -6536,6 +6620,13 @@ const ConfigSchema = BaseConfigSchema.extend({
6536
6620
  * reach a session. Off, no `events/*` method exists and nothing is declared.
6537
6621
  */
6538
6622
  allowEvents: z.boolean().default(false),
6623
+ /**
6624
+ * Once a draft is written or edited, bring back the app that was in front.
6625
+ * Off by default: most drafts are read and sent by the person, and handing
6626
+ * the front back hid the window they were about to read. A send, a refusal
6627
+ * and a failure are not drafts left to read, and hand back as they always did.
6628
+ */
6629
+ handBackAfterDraft: z.boolean().default(false),
6539
6630
  mailboxCacheTtlMs: z.number().int().min(0).max(36e5).default(6e4)
6540
6631
  }).strict();
6541
6632
  /**
@@ -6562,6 +6653,7 @@ const loadConfig = (env = process.env) => {
6562
6653
  allowFileSend: parseBool(env.APPLE_MAIL_ALLOW_FILE_SEND),
6563
6654
  allowWatches: parseBool(env.APPLE_MAIL_ALLOW_WATCHES),
6564
6655
  allowEvents: parseBool(env.APPLE_MAIL_ALLOW_EVENTS),
6656
+ handBackAfterDraft: parseBool(env.APPLE_MAIL_HAND_BACK_AFTER_DRAFT),
6565
6657
  mailboxCacheTtlMs: parseIntOpt(env.APPLE_MAIL_MAILBOX_CACHE_TTL_MS)
6566
6658
  };
6567
6659
  return parseConfig(ConfigSchema, raw);
@@ -7183,7 +7275,7 @@ const registerComposeTools = (server, client) => {
7183
7275
  });
7184
7276
  }));
7185
7277
  server.registerTool("apple_mail_reply_to_message", {
7186
- description: "Reply to a message. By default it opens a draft in Mail with the original quoted beneath your text, for the user to review. Your text goes in above the account's signature, which Mail adds and which is kept, image and all. Pass replyToAll to include every original recipient. Only pass sendNow: true (with confirm: true) when explicitly asked to send now. Success means the body was read back out of the composer window and matched, and only then may it be described to the user as ready. A failure is NOT automatically an empty draft: read the note, which says what was actually found — including that the composer was taken by someone using the Mac, in which case the reply may already have been SENT and a retry would send it twice. Filling the composer brings Mail to the front for a moment to paste; the clipboard is borrowed by the app and restored.",
7278
+ description: "Reply to a message. By default it opens a draft in Mail with the original quoted beneath your text, for the user to review. Your text goes in above the account's signature, which Mail adds and which is kept, image and all. Pass replyToAll to include every original recipient. Only pass sendNow: true (with confirm: true) when explicitly asked to send now. Success means the body was read back out of the composer window and matched, and only then may it be described to the user as ready. A failure is NOT automatically an empty draft: read the note, which says what was actually found — including that the composer was taken by someone using the Mac, in which case the reply may already have been SENT and a retry would send it twice. Filling the composer brings Mail to the front to paste, and a draft leaves it there for the person to read unless they set Mail to hand back; the clipboard is borrowed by the app and restored.",
7187
7279
  inputSchema: z.object({
7188
7280
  ref: messageRefArg,
7189
7281
  body: bodyArg,
@@ -7208,7 +7300,7 @@ const registerComposeTools = (server, client) => {
7208
7300
  });
7209
7301
  }));
7210
7302
  server.registerTool("apple_mail_forward_message", {
7211
- description: "Forward a message to new recipients. By default it opens a draft in Mail for review. Only pass sendNow: true (with confirm: true) when explicitly asked to send now. When a note is given, success means it was read back out of the composer window and matched. The note goes in above the account's signature, which Mail adds and which is kept, image and all. Filling the composer brings Mail to the front for a moment to paste; the clipboard is borrowed by the app and restored.",
7303
+ description: "Forward a message to new recipients. By default it opens a draft in Mail for review. Only pass sendNow: true (with confirm: true) when explicitly asked to send now. When a note is given, success means it was read back out of the composer window and matched. The note goes in above the account's signature, which Mail adds and which is kept, image and all. Filling the composer brings Mail to the front to paste, and a draft leaves it there for the person to read unless they set Mail to hand back; the clipboard is borrowed by the app and restored.",
7212
7304
  inputSchema: z.object({
7213
7305
  ref: messageRefArg,
7214
7306
  to: z.array(z.string().email()).min(1).describe("Who to forward to."),
@@ -7233,7 +7325,7 @@ const registerComposeTools = (server, client) => {
7233
7325
  });
7234
7326
  }));
7235
7327
  server.registerTool("apple_mail_update_draft", {
7236
- description: "Change an unsent draft in its open composer window in Mail: replace its text (`body`), change only some of it (`edits`), add files (`attachments`), or combine files with either — including a REPLY draft you have just written and been asked to revise or attach something to, which is the usual reason to reach for this. Name the draft one of three ways: `ref`, a saved draft's ref (apple_mail_list_open_drafts gives them under `savedDrafts`), whose window is found by its content; `composer`, a window's handle from apple_mail_list_open_drafts or a previous result, which edits that window directly; or neither, which edits the one compose window open and refuses when there are none or several, listing them. Not both ref and composer. `edits` are find-and-replace pairs applied to the text the sender wrote, never the quoted original: each `find` must match exactly once, ignoring differences in whitespace, and only the matched text is replaced, so the rest of the draft is untouched. Prefer them to `body` for a correction, because `body` replaces everything and anything you leave out is lost. Edits and body are exclusive. The edit is made in the draft's own window, so threading, earlier attachments and the quoted original all survive, no second draft appears, and the ref stays valid — though Mail may renumber a saved draft within seconds, so re-find it by subject rather than reusing a ref across turns. The app reads the window back before it reports anything, and saves only what it could verify. Mail comes to the front briefly to paste; the clipboard is borrowed by the app and restored. When Mail shows drafts as tabs of one window, a draft in a tab it is not showing is selected for the edit, and once saved that tab is LEFT SHOWN in place of the one that was (Mail does not say when a save has landed, and switching back early could save the other draft): tell the person which draft Mail now shows. By `composer` handle, such a tab is refused when another tab has the same title, since only a `ref` lets its text be checked; so is a handle listed with `rebound: true`, whose tab Mail rebuilt since it was listed and which may now be another draft: it stays reference-only until a verified edit by `ref` proves its text. It REFUSES rather than doing damage, and returns `replaced: false` with a reason when it does: when a `find` matches zero or several places, when two windows could be the draft, when the open window holds a different message, or when the draft's own text cannot be told apart from the quote. In every refusal nothing was changed. If the draft's window is not open (a `ref` with no window for it), the draft is REBUILT: a reply is reopened as a reply to its original, so it stays in the thread, filled with the draft's own formatted text (with your edits or body) and its files, saved, and the old draft deleted only once the new one is confirmed in Drafts. It refuses, changing nothing, for a forward, a reply whose original is not in Mail's index, an edit that runs across formatting, or a window already open under the subject; and if the quote Mail writes into the new reply is not the old one, it stops with that window open, unsaved, for you to close without saving. A rebuilt draft gets a new ref. The result's `method` says which route ran. In the result `filesAdded` names the files put in, and `attachmentsAdded` counts them.",
7328
+ description: "Change an unsent draft in its open composer window in Mail: replace its text (`body`), change only some of it (`edits`), add files (`attachments`), or combine files with either — including a REPLY draft you have just written and been asked to revise or attach something to, which is the usual reason to reach for this. Name the draft one of three ways: `ref`, a saved draft's ref (apple_mail_list_open_drafts gives them under `savedDrafts`), whose window is found by its content; `composer`, a window's handle from apple_mail_list_open_drafts or a previous result, which edits that window directly; or neither, which edits the one compose window open and refuses when there are none or several, listing them. Not both ref and composer. `edits` are find-and-replace pairs applied to the text the sender wrote, never the quoted original: each `find` must match exactly once, ignoring differences in whitespace, and only the matched text is replaced, so the rest of the draft is untouched. Prefer them to `body` for a correction, because `body` replaces everything and anything you leave out is lost. Edits and body are exclusive. The edit is made in the draft's own window, so threading, earlier attachments and the quoted original all survive, no second draft appears, and the ref stays valid — though Mail may renumber a saved draft within seconds, so re-find it by subject rather than reusing a ref across turns. The app reads the window back before it reports anything, and saves only what it could verify. Mail comes to the front to paste and stays there unless the person set Mail to hand back; the clipboard is borrowed by the app and restored. When Mail shows drafts as tabs of one window, a draft in a tab it is not showing is selected for the edit, and once saved that tab is LEFT SHOWN in place of the one that was (Mail does not say when a save has landed, and switching back early could save the other draft): tell the person which draft Mail now shows. By `composer` handle, such a tab is refused when another tab has the same title, since only a `ref` lets its text be checked; so is a handle listed with `rebound: true`, whose tab Mail rebuilt since it was listed and which may now be another draft: it stays reference-only until a verified edit by `ref` proves its text. It REFUSES rather than doing damage, and returns `replaced: false` with a reason when it does: when a `find` matches zero or several places, when two windows could be the draft, when the open window holds a different message, or when the draft's own text cannot be told apart from the quote. In every refusal nothing was changed. If the draft's window is not open (a `ref` with no window for it), the draft is REBUILT: a reply is reopened as a reply to its original, so it stays in the thread, filled with the draft's own formatted text (with your edits or body) and its files, saved, and the old draft deleted only once the new one is confirmed in Drafts. It refuses, changing nothing, for a forward, a reply whose original is not in Mail's index, an edit that runs across formatting, or a window already open under the subject; and if the quote Mail writes into the new reply is not the old one, it stops with that window open, unsaved, for you to close without saving. A rebuilt draft gets a new ref. The result's `method` says which route ran. In the result `filesAdded` names the files put in, and `attachmentsAdded` counts them.",
7237
7329
  inputSchema: z.object({
7238
7330
  ref: messageRefArg.optional(),
7239
7331
  composer: z.string().min(1).optional().describe("A compose window's handle (looks like mc-3), from apple_mail_list_open_drafts. Edits that window directly. Omit both ref and composer to edit the one open window. Not together with ref."),
@@ -8219,7 +8311,9 @@ const createServer = (opts) => {
8219
8311
  displayName: "Mail",
8220
8312
  era: opts.era ?? "legacy",
8221
8313
  source: service.source,
8222
- startTrigger: service.startTrigger
8314
+ startTrigger: service.startTrigger,
8315
+ ...opts.logger ? { logger: opts.logger } : {},
8316
+ ...opts.listens ? { listens: opts.listens } : {}
8223
8317
  });
8224
8318
  service.bind(registry);
8225
8319
  closers.push(() => {
@@ -8288,4 +8382,4 @@ const createServer = (opts) => {
8288
8382
  //#endregion
8289
8383
  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 };
8290
8384
 
8291
- //# sourceMappingURL=server-BANNirMx.js.map
8385
+ //# sourceMappingURL=server-BcVfuC1E.js.map