@mgcrea/mcp-apple-messages 1.31.0 → 1.34.0

package/dist/{server-C3O37bOh.js → server-D-2jgV-B.js}

@@ -1,10 +1,10 @@
-import { AppleAutomationError, AppleAutomationError as AppleMessagesError, BaseConfigSchema, CORE_DATA_EPOCH_OFFSET, IndexUnavailableError, IndexUnavailableError as IndexUnavailableError$1, PreconditionError, SchemaDriftError, SchemaDriftError as SchemaDriftError$1, buildBaseDiagnostics, columnsOf, confirmArg, createOsascriptRunner, describeAggregation, describeStore, escapeLike, extractCode, fail, fingerprintSchema, groupByArg, limitArg, ok, openReadOnly, parseBool, parseBound, parseConfig, parseIntOpt, promptArg, readPackageIdentity, registerSurfaceResources, registerWorkflowPrompt, requiredPromptArg, resolveLimit, trimmed, withBusyRetry, withLazyTools, wrap, wrapResult, writeConfinedFile } from "@mgcrea/mcp-apple-core";
+import { AppleAutomationError, AppleAutomationError as AppleMessagesError, BaseConfigSchema, CORE_DATA_EPOCH_OFFSET, IndexUnavailableError, IndexUnavailableError as IndexUnavailableError$1, PreconditionError, SchemaDriftError, SchemaDriftError as SchemaDriftError$1, buildBaseDiagnostics, columnsOf, confirmArg, createOsascriptRunner, createWatches, describeAggregation, describeStore, escapeLike, extractCode, fail, fileIdentity, fileTrigger, fingerprintSchema, groupByArg, isoMs, limitArg, normalizeFilter, occurrenceTimestamp, ok, openReadOnly, parseBool, parseBound, parseConfig, parseIntOpt, parseSenderArgs, promptArg, readPackageIdentity, registerEvents, registerSurfaceResources, registerWorkflowPrompt, requiredPromptArg, resolveLimit, sameFile, trimmed, withBusyRetry, withLazyTools, wrap, wrapResult, writeConfinedFile } from "@mgcrea/mcp-apple-core";
 import { existsSync, readFileSync, statSync } from "node:fs";
 import { homedir } from "node:os";
-import { basename, isAbsolute, join, resolve, sep } from "node:path";
+import { basename, dirname, isAbsolute, join, resolve, sep } from "node:path";
 import { AppleContactsClient, emailKey, handleKind, loadConfig, suffixKey } from "@mgcrea/mcp-apple-contacts";
 import { z } from "zod";
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { McpServer } from "@modelcontextprotocol/server";
 //#region src/build-info.ts
 const pkg = readPackageIdentity(new URL("../package.json", import.meta.url), {
 	name: "@mgcrea/mcp-apple-messages",
@@ -13,8 +13,8 @@ const pkg = readPackageIdentity(new URL("../package.json", import.meta.url), {
 const BUILD_INFO = {
 	name: pkg.name,
 	version: pkg.version,
-	gitCommit: "cf7ad84",
-	gitCommitDate: "2026-10-25T15:13:25+01:00"
+	gitCommit: "735f35d",
+	gitCommitDate: "2026-10-29T10:51:42+01:00"
 };
 //#endregion
 //#region src/client/dates.ts
@@ -491,13 +491,12 @@ const locateStore = (opts = {}) => {
 *
 * ## Why a GUID rather than a rowid
 *
-* Both exist, and the rowid is faster to look up. The GUID wins anyway because
-* **rowids are reused.** SQLite hands a deleted row's id to the next insert
-* unless the table is `AUTOINCREMENT`, and Messages deletes constantly — every
-* "delete this conversation" frees a block of them. A ref handed to a model in
-* one turn and used two turns later would then resolve to a DIFFERENT message,
-* with no error anywhere. That is the failure this project keeps designing
-* against: plausible, wrong, and silent.
+* Both exist, and the rowid is faster to look up. The GUID wins anyway, and not
+* because rowids are reused: `message` is `AUTOINCREMENT`, so a deleted row's id
+* is never handed to a later insert (the watch cursor relies on exactly that,
+* and `watch.test.ts` pins it). A rowid is a position in this one database file.
+* It means nothing on another device or after a sync rebuilds the store, whereas
+* the GUID is the message's own identity and travels with it.
 *
 * The GUID is also what Apple itself joins on — `associated_message_guid` for
 * reactions, `thread_originator_guid` for replies — so it is the identifier the
@@ -974,12 +973,17 @@ var MessagesStore = class {
 			source: "none"
 		};
 	}
-	#messageColumns() {
+	/**
+	* `bodies: false` projects NULL for both text columns, for a read that never
+	* shows a body: `#toRow` would otherwise decode `attributedBody` on every row
+	* only for the caller to drop it.
+	*/
+	#messageColumns({ bodies = true } = {}) {
 		const m = this.caps.messageColumns;
 		return [
 			`m."guid" AS guid`,
-			`m."text" AS text`,
-			m.has("attributedBody") ? `m."attributedBody" AS attributedBody` : `NULL AS attributedBody`,
+			bodies ? `m."text" AS text` : `NULL AS text`,
+			bodies && m.has("attributedBody") ? `m."attributedBody" AS attributedBody` : `NULL AS attributedBody`,
 			this.#col(m, "m", "subject"),
 			this.#col(m, "m", "service"),
 			this.#col(m, "m", "is_from_me", "isFromMe"),
@@ -1068,6 +1072,40 @@ var MessagesStore = class {
        LIMIT ${Math.max(1, Math.trunc(q.limit))}`;
 		return this.db.prepare(sql).all(...params).map((r) => this.#toRow(r));
 	}
+	/** Highest message ROWID now, or 0 for an empty store. The watch cursor's head. */
+	headRowid() {
+		return this.db.prepare(`SELECT MAX("ROWID") AS head FROM "message"`).get().head ?? 0;
+	}
+	/**
+	* Messages with ROWID above `after`, ascending, at most `limit`.
+	*
+	* Nothing is filtered out, reactions and my own messages included: a watch
+	* cursor advances over every ROWID and the caller decides what is excluded.
+	* `message` is AUTOINCREMENT, so a ROWID is never handed out twice and the
+	* cursor can only move forward.
+	*
+	* Exactly one row per ROWID. `#joins` yields a row per chat for a message in
+	* several, which would give one cursor two rows and spend two slots of a read's
+	* limit on one message, so the chat here is picked: the lowest `chat_id`.
+	*
+	* No text: a watch carries metadata only, so `text` is always null here and
+	* the scan never pays for decoding a body.
+	*/
+	arrivalsAfter(after, limit) {
+		const sql = `
+      SELECT m."ROWID" AS rowid, ${this.#messageColumns({ bodies: false })}
+        FROM "message" m
+        LEFT JOIN "handle" h ON h."ROWID" = m."handle_id"
+        LEFT JOIN "chat" c ON c."ROWID" =
+          (SELECT MIN(cmj."chat_id") FROM "chat_message_join" cmj WHERE cmj."message_id" = m."ROWID")
+       WHERE m."ROWID" > ?
+       ORDER BY m."ROWID" ASC
+       LIMIT ?`;
+		return this.db.prepare(sql).all(after, Math.max(1, Math.trunc(limit))).map((r) => ({
+			...this.#toRow(r),
+			rowid: Number(r.rowid)
+		}));
+	}
 	/**
 	* Text search, in two passes — and the second one is the point.
 	*
@@ -1864,14 +1902,14 @@ var AppleMessagesClient = class {
 	* answered zero while `send_message` to that same string worked. One
 	* surface, two ideas of what a handle is.
 	*/
-	#handlesLike(handle) {
+	#handlesLike(handle, pool) {
 		const store = this.store();
 		if (!store) return [];
 		const wanted = handle.trim();
 		const kind = handleKind(wanted);
 		const wantedSuffix = kind === "phone" ? suffixKey(wanted) : null;
 		const wantedEmail = kind === "email" ? emailKey(wanted) : null;
-		return store.handles().filter((h) => {
+		return (pool ?? store.handles()).filter((h) => {
 			if (h === wanted) return true;
 			if (wantedEmail) return emailKey(h) === wantedEmail;
 			if (wantedSuffix) return suffixKey(h) === wantedSuffix;
@@ -1879,6 +1917,25 @@ var AppleMessagesClient = class {
 		});
 	}
 	/**
+	* The stored spellings that name the same correspondent as `typed`. Candidates,
+	* not answers: a locally-spelled number reaches `+33…` here, so a caller that
+	* needs an exact spelling still has to compare. `[]` when the store is closed.
+	* `pool` is the store's handles when the caller already read them.
+	*/
+	storeHandlesFor(typed, pool) {
+		return this.#handlesLike(typed, pool);
+	}
+	/**
+	* The open store and the file it came from, for a watch. Throws the same
+	* reason every other read throws when the store is off or unreadable.
+	*/
+	watchStore() {
+		return {
+			store: this.#require(),
+			path: this.located().storePath
+		};
+	}
+	/**
 	* Find the row Messages wrote, or say plainly that it was not found.
 	*
 	* `docs/messages.md` left this as an open question — "whether a send should
@@ -2131,7 +2188,27 @@ const ConfigSchema = BaseConfigSchema.extend({
 	* reassuring one. `attachmentDir` is a real boundary because it constrains
 	* where this server WRITES, which nothing else on this surface can do.
 	*/
-	allowFileSend: z.boolean().default(false)
+	allowFileSend: z.boolean().default(false),
+	/**
+	* Lets a client register a watch on handles or email domains and be told when
+	* a matching message arrives. Off by default, and independent of `allowWrites`
+	* and `exposePrompts`.
+	*
+	* Not a write gate: a watch only reads chat.db. It is a gate because it is the
+	* one thing here that runs unasked, a file watcher in a process that otherwise
+	* has none, and because the handle filter it takes decides whose messages may
+	* reach a session without the model asking for it. Off, neither watch tool is
+	* registered and the server does not declare `resources.subscribe`.
+	*/
+	allowWatches: z.boolean().default(false),
+	/**
+	* Serves the draft MCP Events extension (`messages.received`) to clients on the 2026
+	* protocol. Off by default, and independent of `allowWatches`, `allowWrites` and
+	* `exposePrompts`. Like a watch it only reads chat.db, and is gated for the same
+	* reason: it runs unasked, and its handle filter decides whose messages may reach a
+	* session. Off, no `events/*` method exists and nothing is declared.
+	*/
+	allowEvents: z.boolean().default(false)
 }).strict();
 const loadConfig$1 = (env = process.env) => parseConfig(ConfigSchema, {
 	allowWrites: parseBool(env.APPLE_MESSAGES_ALLOW_WRITES),
@@ -2145,6 +2222,8 @@ const loadConfig$1 = (env = process.env) => parseConfig(ConfigSchema, {
 	sendReconcileMs: parseIntOpt(env.APPLE_MESSAGES_SEND_RECONCILE_MS),
 	allowCodes: parseBool(env.APPLE_MESSAGES_ALLOW_CODES),
 	allowFileSend: parseBool(env.APPLE_MESSAGES_ALLOW_FILE_SEND),
+	allowWatches: parseBool(env.APPLE_MESSAGES_ALLOW_WATCHES),
+	allowEvents: parseBool(env.APPLE_MESSAGES_ALLOW_EVENTS),
 	osascriptPath: trimmed(env.APPLE_MESSAGES_OSASCRIPT_PATH),
 	osascriptTimeoutMs: parseIntOpt(env.APPLE_MESSAGES_OSASCRIPT_TIMEOUT_MS),
 	maxResults: parseIntOpt(env.APPLE_MESSAGES_MAX_RESULTS)
@@ -2212,6 +2291,45 @@ there, that is this, not silence.
 conversations and reported on the message they target. A "liked" is not a reply
 and should not be summarised as one.
 
+## Watches
+
+\`apple_messages_watch\` and \`apple_messages_unwatch\` exist only when the watch
+gate (\`APPLE_MESSAGES_ALLOW_WATCHES\`) is on. If you cannot see them, watches
+are off.
+
+- **A filter is required.** Give \`from\` or \`domains\` (email handles only; a
+  phone number never matches a domain). There is no watch on all messages.
+- **Spell phone numbers in international form**: \`+33612345678\`, with no trunk
+  \`0\` and no \`(0)\`. Spaces and punctuation are ignored, but a local spelling
+  such as \`06 12 34 56 78\` never matches. An entry the store does not hold is
+  kept without spaces or punctuation, lowercased, and listed in \`unresolved\`.
+  That is NOT proof the person has not written: it fires only if the store later
+  holds exactly that spelling. When the store holds near misses they come back
+  as \`suggestions\` (\`typed\`, \`candidates\`); retry with the right spelling.
+- **Check the watch yourself.** \`apple_messages_watch\` returns a handle and a
+  \`uri\`. Only the host can subscribe to that uri, there is no tool for it, and
+  many hosts never do: Claude Code does not, in either protocol (checked on
+  2.1.311). So do not promise the user a push. The watch still works: read the
+  uri whenever you want to know what came in.
+- **\`after\` is yours to keep.** A read returns what arrived since the watch
+  began, or since the \`after\` you pass, oldest first. The \`cursor\` it returns
+  is the last row scanned; pass it back as \`after\` next time. The server does
+  not remember what you have seen. When \`more\` is true, read again from
+  \`cursor\`.
+- **Reads carry no text.** Each message is \`id\`, \`handle\`, \`chat\` and \`date\`.
+  Use \`apple_messages_get_message\` with that \`id\` for the text.
+- **Your own messages, tapbacks and group events never fire a watch.** A group
+  event is a rename, or someone joining or leaving.
+- **Limits.** At most 10 watches per connection and 50 entries across \`from\`
+  and \`domains\` in one watch. A read returns at most 50 matches and scans at
+  most 1,000 rows; \`more\` says when either stopped it.
+- **Messages need not be running.** The store is written by the system, not by
+  the app, so a watch works with Messages closed.
+- Watches end with the connection: after a reconnect, call
+  \`apple_messages_watch\` again. Reading a watch that does not exist is a
+  not-found error, which is also what a reconnect looks like. A uri with a query
+  other than \`after\` is refused as a bad query.
+
 ## Sending
 
 \`apple_messages_send_message\` exists only when writes are enabled, and it is the
@@ -2366,11 +2484,94 @@ const buildDiagnostics = async (client) => {
 const registerDiagnosticsTools = (server, client) => {
 	server.registerTool("apple_messages_diagnostics", {
 		description: "Report whether the Messages store could be opened, how much is in it, whether names are being resolved, and what this server cannot do. Start here when a read returns nothing.",
-		inputSchema: {},
+		inputSchema: z.object({}),
 		annotations: { readOnlyHint: true }
 	}, async () => wrap(() => buildDiagnostics(client)));
 };
 //#endregion
+//#region src/tools/events.ts
+/**
+* Messages' `messages.received` event type for the draft MCP Events extension.
+*
+* It is an adapter over a `MessagesWatchService`, the same store handle, handle
+* resolution and trigger a watch uses. The service handed over must be its own,
+* never one bound to a watch registry: events and watches then keep separate
+* handles on chat.db and both are closed with the connection.
+*/
+const Args = z.object({
+	from: z.array(z.string().min(1)).optional(),
+	domains: z.array(z.string().min(1)).optional()
+});
+const messagesEventAdapter = (service) => ({
+	descriptor: {
+		name: "messages.received",
+		description: "New messages from chosen handles. Give `from` (email addresses, or phone numbers in international form such as +33612345678) and/or `domains` (email handles only; matches the domain and its subdomains); a sender is required. Metadata only, so fetch the text with apple_messages_get_message and the `id`. Your own messages and tapbacks never match. Needs Full Disk Access; Messages does not have to be running.",
+		delivery: ["poll", "push"],
+		inputSchema: {
+			type: "object",
+			properties: {
+				from: {
+					type: "array",
+					items: {
+						type: "string",
+						minLength: 1
+					},
+					description: "Email addresses, or phone numbers in international form (+33612345678: no trunk 0, no (0)); spaces and punctuation are ignored, but a local spelling like 06 12 34 56 78 never matches. An entry the store does not hold is kept without spaces or punctuation, lowercased: it fires only if the store later holds exactly that spelling."
+				},
+				domains: {
+					type: "array",
+					items: {
+						type: "string",
+						minLength: 1
+					},
+					description: "Email domains, e.g. acme.com. Matches only email handles, never a phone number."
+				}
+			},
+			anyOf: [{ required: ["from"] }, { required: ["domains"] }]
+		},
+		payloadSchema: {
+			type: "object",
+			properties: {
+				id: { type: "string" },
+				chat: { type: ["string", "null"] },
+				handle: { type: ["string", "null"] },
+				date: { type: ["string", "null"] }
+			},
+			required: [
+				"id",
+				"chat",
+				"handle",
+				"date"
+			]
+		}
+	},
+	parseArguments: (args) => parseSenderArgs("messages.received", Args, args, {
+		open: () => service.ensure(),
+		resolve: async ({ from, domains }) => {
+			const resolved = service.resolveFrom(from ?? []).from;
+			return {
+				...resolved.length > 0 ? { from: resolved } : {},
+				...domains ? { domains } : {}
+			};
+		}
+	}),
+	occurrence: (row) => ({
+		eventId: row.key,
+		timestamp: occurrenceTimestamp(row.date),
+		data: {
+			id: row.id,
+			chat: row.chat,
+			handle: row.handle,
+			date: row.date
+		}
+	}),
+	timestampMs: (row) => isoMs(row.date),
+	source: service.source,
+	ensure: () => service.refresh(),
+	identity: () => service.identity(),
+	startTrigger: (onChange) => service.startTrigger(onChange)
+});
+//#endregion
 //#region src/tools/actions.ts
 /**
 * The payload half of the description, which changes with `allowFileSend` — the
@@ -2381,7 +2582,7 @@ const PAYLOAD_HELP = (allowFileSend) => "Send exactly ONE thing per call: text,
 const registerActionTools = (server, client, ctx) => {
 	server.registerTool("apple_messages_send_message", {
 		description: "Send a message to an existing conversation or to a phone number / email address. This sends a REAL message from the user's own iMessage/SMS account, immediately and irreversibly. There is no unsend, no draft and no preview: the recipient's phone buzzes as soon as this returns. Messages may be launched to do it, which the user will see. Confirm the exact wording and the exact recipient with the user before calling this. Sending a file is the same act and less recoverable: once it leaves this Mac the recipient has a copy, so confirm WHICH file with the user, by name, before calling this with an attachment. Prefer chatRef from apple_messages_list_chats over a raw handle: Messages refuses to enumerate participants for a script, so an existing conversation is the only target this server can address reliably — a handle with no conversation on this Mac will usually fail rather than start a new thread. The result reports which targeting strategy worked, and reconciles against the message store to hand back a real message ref: reconciliation `matched` means the sent row was found and `message` is it, `pending` means Messages accepted the send but has not written the row yet (normal on a slow network — read the chat back, do NOT send again), and `unavailable` means there was no existing chat to look in. " + PAYLOAD_HELP(ctx.allowFileSend),
-		inputSchema: {
+		inputSchema: z.object({
 			chatRef: z.string().optional().describe("An opaque chat ref from apple_messages_list_chats (\"mc1:<guid>\"). The reliable way to target a send. Do not construct one by hand."),
 			to: z.string().optional().describe("A phone number or email address, when there is no chat ref. Matched against the store's own handles by last-9-digits, so local and international spellings of the same number both work."),
 			text: z.string().min(1).optional().describe("Exactly what to send, verbatim. Give this OR an attachment, never both in one call."),
@@ -2393,7 +2594,7 @@ const registerActionTools = (server, client, ctx) => {
 				"rcs"
 			]).optional().describe("Which service to prefer when addressing a handle with no existing chat. Ignored when chatRef is given, since the chat already knows its service."),
 			confirm: confirmArg
-		},
+		}),
 		annotations: {
 			readOnlyHint: false,
 			destructiveHint: true,
@@ -2442,11 +2643,11 @@ const registerActionTools = (server, client, ctx) => {
 const registerAttachmentTools = (server, client) => {
 	server.registerTool("apple_messages_save_attachment", {
 		description: "Save one attachment from a conversation to disk — a photo, a video, a PDF, a voice memo. Take the `id` from an attachment on apple_messages_get_message. Needs Full Disk Access, like every read here. It can only write into APPLE_MESSAGES_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 Messages. An attachment iCloud has offloaded has no bytes on this Mac and is refused with that reason — open the conversation in Messages to pull it down first.",
-		inputSchema: {
+		inputSchema: z.object({
 			attachmentId: z.string().min(1).describe("The `id` of an attachment from apple_messages_get_message. Opaque; do not construct one, and do not pass the file path shown next to it."),
 			directory: z.string().optional().describe("Override the target directory. Must still resolve inside the configured one."),
 			overwrite: z.boolean().optional().describe("Replace an existing file. Default false.")
-		},
+		}),
 		annotations: {
 			readOnlyHint: false,
 			destructiveHint: false,
@@ -2468,7 +2669,7 @@ const registerAttachmentTools = (server, client) => {
 const registerChatTools = (server, client) => {
 	server.registerTool("apple_messages_list_chats", {
 		description: "List conversations, most recently active first, with their participants and message counts. Names come from Contacts where they resolve; where they do not, the raw phone number or email is shown and `resolution` says why. Use the returned ref to read one conversation with apple_messages_list_messages.",
-		inputSchema: { limit: limitArg },
+		inputSchema: z.object({ limit: limitArg }),
 		annotations: { readOnlyHint: true }
 	}, async ({ limit }) => wrap(async () => client.listChats(limit)));
 };
@@ -2503,11 +2704,11 @@ CHECK \`ageSeconds\` BEFORE USING A CODE. An expired code is still in the store
 A \`matched\` value ending in \`-ambiguous\` means the message held more than one plausible code and this tool did not guess — confirm which one is wanted.
 
 Returning nothing is the normal result when no code has arrived. It does NOT mean the code was missed, and it is not a reason to re-run with a longer window: if a code was sent it is in the store within seconds. Prefer asking the user to trigger a new one.`,
-		inputSchema: {
+		inputSchema: z.object({
 			service: z.string().optional().describe("Narrow to one issuer by matching the sender or the message text — \"Google\", \"bank\", \"Github\". Case-insensitive substring. Omit to see every recent code."),
 			withinMinutes: z.number().int().min(1).max(MAX_WINDOW_MINUTES).optional().describe(`How far back to look, in minutes. Default ${DEFAULT_WINDOW_MINUTES}, max ${MAX_WINDOW_MINUTES}. Keep it short: a code older than a few minutes has usually expired, and a wide window just returns history.`),
 			limit: limitArg
-		},
+		}),
 		annotations: {
 			readOnlyHint: true,
 			idempotentHint: false
@@ -2571,7 +2772,7 @@ Returning nothing is the normal result when no code has arrived. It does NOT mea
 const registerCountTools = (server, client) => {
 	server.registerTool("apple_messages_count_messages", {
 		description: "Count messages without reading them. Answers 'how many', 'how many did I send', 'who do I message most' and 'which month was busiest' as arithmetic the store does, rather than a page of conversations you tally by hand. Every result splits `sent` and `received`.\n\n`groupBy` counts per day, month, chat, handle or direction, over EVERY match rather than the first `limit` of them — `limit` caps how many groups come back. Grouping by handle is the one to reach for when a person has several conversations, since apple_messages_list_chats already gives you per-CHAT totals.\n\nCounts metadata only: there is no text filter here, because message bodies from 2026 onward live in an archived blob that SQL cannot see, and a count that quietly skipped them would look exactly like a correct one. Use apple_messages_search_messages for anything about what was said. Tapbacks are excluded unless you ask for them.",
-		inputSchema: {
+		inputSchema: z.object({
 			chatRef: chatRefArg,
 			handle: z.string().optional().describe("Only messages with this correspondent — a phone number or email. Spellings of the same number match each other, so \"06 12 34 56 78\" and \"+33612345678\" are the same person, exactly as they are for send_message. A fragment that resolves to nobody falls back to a substring match. Spans every chat they appear in, which is the difference from chatRef."),
 			direction: z.enum(["sent", "received"]).optional().describe("Only what you sent, or only what you received. Omit for both."),
@@ -2580,7 +2781,7 @@ const registerCountTools = (server, client) => {
 			includeReactions: includeReactionsArg,
 			groupBy: groupByArg(COUNT_GROUP_FIELDS, "Day and month buckets are LOCAL calendar dates."),
 			limit: limitArg
-		},
+		}),
 		annotations: { readOnlyHint: true }
 	}, async ({ chatRef, handle, direction, from, to, includeReactions, groupBy, limit }) => wrap(async () => {
 		const window = client.window(bound(from, "from", "start"), bound(to, "to", "end"));
@@ -2621,13 +2822,13 @@ const closeRange = (from, to, days) => {
 const registerMessageTools = (server, client) => {
 	server.registerTool("apple_messages_list_messages", {
 		description: "Read messages, newest first — the whole store, or one conversation, or a date window. Tapbacks are excluded by default because they are rows in the same table and would otherwise read as messages nobody typed.\n\nEvery message carries `from.name` where Contacts resolves it and `from.handle` always. `from.resolution` is worth reading: `unknown` is COMMON AND NOT AN ERROR — measured on a real store, about one in six of even the busiest correspondents has no contact card.",
-		inputSchema: {
+		inputSchema: z.object({
 			chatRef: chatRefArg,
 			from: fromArg,
 			to: toArg,
 			includeReactions: includeReactionsArg,
 			limit: limitArg
-		},
+		}),
 		annotations: { readOnlyHint: true }
 	}, async ({ chatRef, from, to, includeReactions, limit }) => wrap(async () => {
 		const fromDate = bound(from, "from", "start");
@@ -2641,15 +2842,15 @@ const registerMessageTools = (server, client) => {
 	}));
 	server.registerTool("apple_messages_search_messages", {
 		description: "Search message text across every conversation. Matches are substring and case-insensitive.\n\nThis searches ALL messages, including the roughly 3% whose text lives only in an archived blob rather than in a plain column — those are invisible to any SQL query and are decoded here. `textSource` on each result says which produced it.",
-		inputSchema: {
+		inputSchema: z.object({
 			query: z.string().min(1).describe("Text to look for."),
 			limit: limitArg
-		},
+		}),
 		annotations: { readOnlyHint: true }
 	}, async ({ query, limit }) => wrap(async () => client.searchMessages(query, limit)));
 	server.registerTool("apple_messages_get_message", {
 		description: "One message in full, with its tapbacks and attachments. Reactions are reported here rather than mixed into the conversation, which is the whole reason list_messages filters them out.",
-		inputSchema: { ref: messageRefArg },
+		inputSchema: z.object({ ref: messageRefArg }),
 		annotations: { readOnlyHint: true }
 	}, async ({ ref }) => wrapResult(async () => {
 		const message = client.getMessage(decodeMessageRef(ref));
@@ -2658,6 +2859,284 @@ const registerMessageTools = (server, client) => {
 	}));
 };
 //#endregion
+//#region src/client/watch.ts
+var MessagesArrivalSource = class {
+	#store;
+	constructor(opts) {
+		this.#store = opts.store;
+	}
+	head() {
+		return this.#store.headRowid();
+	}
+	since(after, limit) {
+		return this.#store.arrivalsAfter(after, limit).map((r) => {
+			const excluded = r.isFromMe || r.reactionType !== null || r.itemType !== null && r.itemType !== 0;
+			return {
+				cursor: r.rowid,
+				key: r.guid,
+				sender: r.handle?.trim().toLowerCase() || null,
+				...excluded ? { excluded: true } : {},
+				id: encodeMessageRef(r.guid),
+				chat: r.chatGuid ? encodeChatRef(r.chatGuid) : null,
+				handle: r.handle,
+				date: renderInstant(r.sentAt)
+			};
+		});
+	}
+};
+//#endregion
+//#region src/tools/watch.ts
+/**
+* Messages' side of incoming watches: the lazily opened source, the trigger, the
+* handle resolution and the two tools.
+*
+* ## Why the source is lazy
+*
+* `createWatches` needs an `ArrivalSource` when the server is built, but a server
+* is built far more often than it is used (`serveStdio` makes one per
+* `server/discover` probe and throws it away). So the source handed over is an
+* adapter that delegates to a `MessagesArrivalSource` built by `ensure()`, which
+* runs on the first `watch` call. A server that never sees one opens nothing.
+*
+* ## Messages need not be running
+*
+* `imagent` writes chat.db, not Messages.app, so there is no running check and no
+* lookup to refresh: the trigger just ticks the registry.
+*
+* ## The watch keeps its own handle, and reopens it when the file is replaced
+*
+* A connection opened on chat.db reads that inode for as long as it lives. A
+* store rebuilt as a new file and renamed over the old name leaves it reading
+* the deleted one: nothing new ever arrives there, and nothing errors. So the
+* service records the file's inode when it opens, compares on every trigger, and
+* reopens before the tick when it changed. The registry then sees the renumbered
+* head below its mark and resets without notifying, which is what a rebuild is.
+*
+* The handle is the service's own rather than the client's: the client closes
+* its store to reopen it after a send (`#reconcile`), which would close a shared
+* handle under a running watch, and reopening the client's would change what
+* every other tool reads in the middle of its call.
+*
+* ## Handles
+*
+* A watch's `from` holds exact store spellings, because the source stamps each row
+* with `handle.id` lowercased and core compares for equality. What the caller types
+* is resolved against the store's handles first (see `resolveFrom`).
+*/
+const walReason = (noun) => `The Messages store was opened in immutable mode, which cannot see its WAL, so the newest messages are exactly what a ${noun} would miss. APPLE_MESSAGES_INDEX_MODE=immutable asks for that: set it to auto or ro, or unset it, then try again.`;
+/** How a handle compares: emails case-folded, phone numbers without their punctuation. */
+const handleKey = (value) => {
+	const v = value.trim().toLowerCase();
+	return v.includes("@") ? v : v.replaceAll(/[\s.\-()]/g, "");
+};
+var MessagesWatchService = class {
+	#client;
+	#logger;
+	#noun;
+	#registry;
+	#inner;
+	#dir;
+	/** The service's own handle on chat.db, never the client's. */
+	#store;
+	#path;
+	#identity = null;
+	#reopenFailing = false;
+	#init;
+	/** What `createWatches` is given. Delegates to the source `ensure()` builds. */
+	source = {
+		head: () => this.#ready().head(),
+		since: (after, limit) => this.#ready().since(after, limit)
+	};
+	constructor(opts) {
+		this.#client = opts.client;
+		this.#logger = opts.logger;
+		this.#noun = opts.mode === "events" ? "subscription" : "watch";
+	}
+	/** How many watches this connection holds. */
+	get count() {
+		return this.#registry?.size ?? 0;
+	}
+	/** Called once, by `createServer`, after `createWatches` returns. */
+	bind(registry) {
+		this.#registry = registry;
+	}
+	#ready() {
+		if (!this.#inner) throw new Error("The messages watch source was used before it was set up.");
+		return this.#inner;
+	}
+	/**
+	* Open the store and build the source, once. Concurrency-safe: two simultaneous
+	* `watch` calls share the promise. A failure is not kept, so a later call runs
+	* setup again.
+	*/
+	ensure() {
+		this.#init ??= Promise.resolve().then(() => this.#setUp()).catch((err) => {
+			this.#init = void 0;
+			throw err;
+		});
+		return this.#init;
+	}
+	/**
+	* `ensure`, then reopen chat.db if it was replaced since. What an events poll
+	* or tick runs before it reads: a poll has no trigger to notice a rebuild for
+	* it, and without this would read the deleted file for as long as the
+	* connection lives. `ensure` itself does not reopen, so watches are unchanged.
+	*/
+	async refresh() {
+		await this.ensure();
+		this.#reopenIfReplaced();
+	}
+	#setUp() {
+		const { store, path } = this.#client.watchStore();
+		if (store.mode !== "ro") throw new PreconditionError(walReason(this.#noun));
+		this.#open(path);
+		this.#dir = dirname(path);
+	}
+	/** Open (or reopen) the service's own handle, and only then let go of the old one. */
+	#open(path) {
+		const identity = fileIdentity(path);
+		const store = openStore(path, "ro", this.#logger);
+		if (!store) throw new PreconditionError("The Messages store was not located.");
+		const old = this.#store;
+		this.#store = store;
+		this.#path = path;
+		this.#identity = identity;
+		this.#inner = new MessagesArrivalSource({ store });
+		old?.close();
+	}
+	/**
+	* Reopen when chat.db is now a different file. A path that cannot be read is
+	* a replacement in progress, so it is left for the next trigger. A reopen that
+	* fails keeps the old handle and is logged once until one succeeds.
+	*/
+	#reopenIfReplaced() {
+		if (!this.#path) return;
+		const now = fileIdentity(this.#path);
+		if (now === null || this.#identity !== null && sameFile(now, this.#identity)) return;
+		try {
+			this.#open(this.#path);
+			this.#reopenFailing = false;
+		} catch (err) {
+			if (!this.#reopenFailing) this.#logger?.warn?.("watch: chat.db was replaced and could not be reopened", err);
+			this.#reopenFailing = true;
+		}
+	}
+	/** What `createWatches` is given as `startTrigger`. Reads the directory now, not at construction. */
+	startTrigger = (onChange) => {
+		if (!this.#dir) throw new Error("A watch trigger was started before the store was located.");
+		return fileTrigger({
+			dir: this.#dir,
+			names: ["chat.db", "chat.db-wal"],
+			...this.#logger ? { logger: this.#logger } : {}
+		})(() => this.onTrigger(onChange));
+	};
+	/** The trigger's callback: reopen a replaced store, then tick. */
+	onTrigger(tick) {
+		this.#reopenIfReplaced();
+		tick();
+	}
+	/** The file identity of the chat.db the service reads now, or null when it is unknown or unreadable. */
+	identity() {
+		return this.#identity;
+	}
+	/** Close the service's own handle. Called when the connection ends. */
+	close() {
+		this.#store?.close();
+		this.#store = void 0;
+		this.#inner = void 0;
+		this.#path = void 0;
+		this.#init = void 0;
+	}
+	remove(id) {
+		return this.#registry?.remove(id) ?? false;
+	}
+	/**
+	* Turn what the caller typed into exact store spellings.
+	*
+	* `storeHandlesFor` is a candidate list (a local "06 12 ..." reaches "+33 6 12 ..."),
+	* so a typed value counts as resolved only when a candidate equals it after
+	* normalisation. A short "+336" therefore resolves nothing, rather than every
+	* French number. What does not resolve is kept, normalised and lowercased, and
+	* reported (with `suggestions` when the store holds near misses).
+	*/
+	resolveFrom(typed) {
+		const from = [];
+		const unresolved = [];
+		const suggestions = [];
+		const pool = this.#store?.handles();
+		for (const entry of typed) {
+			const key = handleKey(entry);
+			if (key === "") continue;
+			const candidates = this.#client.storeHandlesFor(entry, pool);
+			const exact = candidates.filter((h) => handleKey(h) === key);
+			if (exact.length > 0) from.push(...exact);
+			else {
+				from.push(key);
+				unresolved.push(key);
+				if (candidates.length > 0) suggestions.push({
+					typed: entry,
+					candidates
+				});
+			}
+		}
+		return {
+			from: [...new Set(from)],
+			unresolved: [...new Set(unresolved)],
+			suggestions
+		};
+	}
+	async add(input) {
+		const registry = this.#registry;
+		if (!registry) throw new Error("Messages watches are not bound to a registry.");
+		normalizeFilter({
+			...input.from ? { from: input.from } : {},
+			...input.domains ? { domains: input.domains } : {}
+		});
+		await this.ensure();
+		const { from, unresolved, suggestions } = this.resolveFrom(input.from ?? []);
+		const filter = normalizeFilter({
+			...from.length ? { from } : {},
+			...input.domains ? { domains: input.domains } : {}
+		});
+		return {
+			watch: registry.add(filter),
+			unresolved,
+			suggestions
+		};
+	}
+};
+const registerWatchTools = (server, service) => {
+	server.registerTool("apple_messages_watch", {
+		description: "Watch for new messages from chosen handles. Give `from` (email addresses, or phone numbers in international form such as +33612345678) and/or `domains` (email handles only; matches the domain and its subdomains); a sender is required, there is no watch on all messages. Returns a handle and its `uri`. Read the uri to see what arrived since the watch began (or since `after`): a host that subscribes is told when to read it, but many never do, so check it yourself rather than promising the user a notification. Metadata only, so fetch the text with apple_messages_get_message and the `id`. The watch lasts as long as this connection. Your own messages and tapbacks never match. Needs Full Disk Access; Messages does not have to be running.",
+		inputSchema: z.object({
+			from: z.array(z.string().min(1)).optional().describe("Email addresses, or phone numbers in international form (+33612345678: no trunk 0, no (0)); spaces and punctuation are ignored, but a local spelling like 06 12 34 56 78 never matches. An entry the store does not hold is kept without spaces or punctuation, lowercased, and listed in `unresolved`, which does not prove the person has not written: it fires only if the store later holds exactly that spelling. Near misses come back as `suggestions` to retry with."),
+			domains: z.array(z.string().min(1)).optional().describe("Email domains, e.g. acme.com. Matches only email handles, never a phone number.")
+		}),
+		annotations: { readOnlyHint: true }
+	}, async ({ from, domains }) => wrap(async () => {
+		const { watch, unresolved, suggestions } = await service.add({
+			from,
+			domains
+		});
+		return {
+			watch: watch.id,
+			uri: watch.uri,
+			filter: {
+				from: watch.filter.from,
+				domains: watch.filter.domains
+			},
+			cursor: watch.createdAt,
+			unresolved,
+			...suggestions.length ? { suggestions } : {}
+		};
+	}));
+	server.registerTool("apple_messages_unwatch", {
+		description: "Stop a watch made by apple_messages_watch, by its `watch` id. Returns whether one was removed. Watches also end on their own when the connection closes, so this is only needed to free one of the ten a connection may hold.",
+		inputSchema: z.object({ watch: z.string().min(1).describe("The `watch` id from apple_messages_watch.") }),
+		annotations: { readOnlyHint: true }
+	}, async ({ watch }) => wrap(async () => ({ removed: service.remove(watch) })));
+};
+//#endregion
 //#region src/tools/index.ts
 /**
 * Register the Apple Messages tools.
@@ -2666,7 +3145,8 @@ const registerMessageTools = (server, client) => {
 * surface the flag carries a permission claim as well as a safety one: with it
 * off no Apple Event is ever sent, so no Automation grant is ever requested.
 * What is needed either way is Full Disk Access, absolutely — see `diagnostics`.
-* One further read, `find_codes`, only when `allowCodes` is on.
+* One further read, `find_codes`, only when `allowCodes` is on. Two more, the watch
+* tools, only when `allowWatches` is on (`ctx.watches`).
 *
 * The registered set is a pure function of STATIC CONFIGURATION, never of
 * runtime state. In particular it does NOT vary with whether the store is
@@ -2687,6 +3167,7 @@ const registerTools = (server, client, ctx) => {
 	registerMessageTools(server, client);
 	registerCountTools(server, client);
 	if (ctx.allowCodes) registerCodeTools(server, client);
+	if (ctx.watches) registerWatchTools(server, ctx.watches);
 	if (!ctx.allowWrites) return;
 	registerActionTools(server, client, ctx);
 	registerAttachmentTools(server, client);
@@ -2713,6 +3194,47 @@ const createServer = (opts) => {
 		...opts.home ? { home: opts.home } : {},
 		...opts.contacts === void 0 ? {} : { contacts: opts.contacts }
 	});
+	const closers = [];
+	let watches;
+	if (config.allowWatches) {
+		watches = new MessagesWatchService({
+			client,
+			...opts.logger ? { logger: opts.logger } : {}
+		});
+		const service = watches;
+		const registry = createWatches(server, {
+			surface: "messages",
+			displayName: "Messages",
+			era: opts.era ?? "legacy",
+			source: service.source,
+			startTrigger: service.startTrigger
+		});
+		service.bind(registry);
+		closers.push(() => {
+			registry.close();
+			service.close();
+		});
+	}
+	let events;
+	if (config.allowEvents) {
+		events = new MessagesWatchService({
+			client,
+			mode: "events",
+			...opts.logger ? { logger: opts.logger } : {}
+		});
+		const service = events;
+		const served = registerEvents(server, {
+			era: opts.era ?? "legacy",
+			adapters: [messagesEventAdapter(service)]
+		});
+		closers.push(() => {
+			served.close();
+			service.close();
+		});
+	}
+	if (closers.length > 0) server.server.onclose = () => {
+		for (const close of closers) close();
+	};
 	withLazyTools(server, {
 		surface: "messages",
 		displayName: "Messages",
@@ -2721,7 +3243,8 @@ const createServer = (opts) => {
 	}, (target, allowWrites) => registerTools(target, client, {
 		allowWrites,
 		allowCodes: config.allowCodes,
-		allowFileSend: config.allowFileSend
+		allowFileSend: config.allowFileSend,
+		watches
 	}));
 	if (config.exposePrompts) {
 		registerPrompts(server, config.allowWrites);
@@ -2734,10 +3257,12 @@ const createServer = (opts) => {
 	}
 	return {
 		server,
-		client
+		client,
+		watches,
+		events
 	};
 };
 //#endregion
 export { MESSAGES_SURFACE as A, toAppleSeconds as B, locateStore as C, ChatNotFoundError as D, AppleMessagesError as E, SendTargetNotFoundError as F, CORE_DATA_EPOCH_OFFSET as I, appleSecondsSql as L, MessagesUnavailableError as M, SchemaDriftError$1 as N, IndexUnavailableError$1 as O, SendFailedError as P, fromAppleSeconds as R, defaultStorePath as S, PRELUDE as T, BUILD_INFO as V, decodeMessageRef as _, loadConfig$1 as a, ATTACHMENTS_RELATIVE as b, introspect as c, decodeAttributedBody as d, outline as f, decodeChatRef as g, MESSAGE_REF_VERSION as h, registerTools as i, MessageNotFoundError as j, MESSAGES_BUNDLE_ID as k, openStore as l, InvalidMessageRefError as m, SERVER_VERSION as n, AppleMessagesClient as o, CHAT_REF_VERSION as p, createServer as r, MessagesStore as s, SERVER_NAME as t, reactionLabel as u, encodeChatRef as v, SEND_MESSAGE as w, STORE_RELATIVE as x, encodeMessageRef as y, renderInstant as z };
 
-//# sourceMappingURL=server-C3O37bOh.js.map
+//# sourceMappingURL=server-D-2jgV-B.js.map