@mgcrea/mcp-apple-messages 1.10.0 → 1.12.0

package/README.md

@@ -66,7 +66,16 @@ That is a capability downgrade reported through `diagnostics`, never a throw.
 
 ## Tools
 
-Read: `diagnostics`, `list_chats`, `list_messages`, `search_messages`, `get_message`.
+Read: `diagnostics`, `list_chats`, `list_messages`, `search_messages`, `get_message`,
+`count_messages`.
+
+`count_messages` is the arithmetic lane: totals with a sent/received split, and `groupBy` for counts
+per day, month, chat, handle or direction. It aggregates in SQL over every match, so "who do I
+message most" costs one small result rather than a page of conversations tallied by hand — and
+grouping by **handle** spans the several chats one person can occupy, which the per-chat totals on
+`list_chats` cannot add together. Metadata only, deliberately: message bodies from 2026 onward live
+in an archived blob that SQL cannot read, so a text filter here would return a number that looks
+right and silently omits the recent half of the store.
 
 Opt-in read: `find_codes`, behind `APPLE_MESSAGES_ALLOW_CODES` — see [Configuration](#configuration).
 Off by default, and not covered by the write gate.

package/dist/cli.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { A as MESSAGES_SURFACE, V as BUILD_INFO, a as loadConfig, r as createServer } from "./server-BExbW9RO.js";
+import { A as MESSAGES_SURFACE, V as BUILD_INFO, a as loadConfig, r as createServer } from "./server-CPDQqGEn.js";
 import { runStdioServer } from "@mgcrea/mcp-apple-core";
 //#region src/cli.ts
 const LOG_PREFIX = "apple-messages-mcp";

package/dist/index.d.ts

@@ -133,6 +133,46 @@ type RangeQuery = {
   includeReactions?: boolean | undefined;
   limit: number;
 };
+/**
+ * What `countMessages` can group on.
+ *
+ * Metadata only, and that is the design rather than a first cut. Anything
+ * derived from message TEXT is unavailable to SQL here: from March 2026 onward
+ * the body lives only in `attributedBody`, which is why `search` carries a
+ * second decode pass. A `GROUP BY` over `text LIKE ?` would return a number
+ * shaped exactly like a correct one while missing every recent message, so this
+ * lane never offers one.
+ */
+declare const COUNT_GROUP_FIELDS: readonly ["day", "month", "chat", "handle", "direction"];
+type CountGroupField = (typeof COUNT_GROUP_FIELDS)[number];
+type CountQuery = {
+  chatGuid?: string | undefined;
+  /** Substring of a handle — a phone number or an email address. */
+  handle?: string | undefined;
+  direction?: "sent" | "received" | undefined;
+  fromApple?: number | undefined;
+  toApple?: number | undefined;
+  includeReactions?: boolean | undefined;
+  /** Caps the number of GROUPS, never the messages counted. */
+  limit: number;
+};
+type CountTotals = {
+  total: number;
+  /** Null when the store has no `is_from_me` column to split on. */
+  sent: number | null;
+  received: number | null;
+  firstAt: number | null;
+  lastAt: number | null;
+};
+type CountBucket = CountTotals & {
+  key: string | null;
+  label: string | null;
+};
+type CountGroups = {
+  groups: CountBucket[];
+  totalGroups: number;
+  totalRows: number;
+};
 declare class MessagesStore {
   #private;
   readonly db: DatabaseSync;
@@ -235,6 +275,21 @@ declare class MessagesStore {
     handles: number;
     attachments: number;
   };
+  /**
+   * Count messages, optionally per group, over every match rather than a page.
+   *
+   * `limit` caps the number of GROUPS returned, never the messages counted —
+   * the same rule Mail's query lane is built on. An aggregate computed over a
+   * truncated page is not so much a wrong answer as a confidently wrong one:
+   * "my three busiest conversations" and "the three busiest among the twenty
+   * rows we happened to read" are the same shape, and nothing marks which you
+   * got. `totalRows` is therefore always reported.
+   *
+   * Every count is `COUNT(DISTINCT m."ROWID")`. The chat join is one row per
+   * (chat, message) pair, so a message filed in two chats would otherwise be
+   * counted twice in a total that is not itself per-chat.
+   */
+  countMessages(q: CountQuery, field?: CountGroupField): CountTotals | CountGroups;
   close(): void;
 }
 declare const introspect: (db: DatabaseSync) => StoreCapabilities;
@@ -351,6 +406,21 @@ type RenderedChat = {
   messages: number;
   lastMessageAt: string | null;
 };
+/** The counts every shape of `countMessages` reports, dates rendered. */
+type RenderedCount = {
+  total: number;
+  sent: number | null;
+  received: number | null;
+  firstAt: string | null;
+  lastAt: string | null;
+};
+type RenderedCountGroup = RenderedCount & {
+  key: string | null;
+  /** A display form of `key`: a chat's name, a handle's contact. */
+  label: string | null;
+  /** Present only on chat groups, so the group can be read straight back. */
+  ref?: string;
+};
 declare class AppleMessagesClient {
   #private;
   constructor(opts: CreateClientOptions);
@@ -400,6 +470,21 @@ declare class AppleMessagesClient {
     mimeType: string | null;
   }>;
   listChats(limit?: number): RenderedChat[];
+  /**
+   * Count messages, optionally grouped — the cheap-answer lane on this surface.
+   *
+   * Deliberately metadata-only. The expensive questions here are "how many" and
+   * "how many per X", and the store answers both in SQL without a message body
+   * ever reaching the context window. Anything text-derived stays with
+   * `searchMessages`, which has the decode pass that makes it complete.
+   */
+  countMessages(q: Omit<CountQuery, "limit"> & {
+    limit?: number | undefined;
+  }, groupBy?: CountGroupField): RenderedCount | {
+    groups: RenderedCountGroup[];
+    totalGroups: number;
+    totalRows: number;
+  };
   /**
    * Send one message. A real one, to a real person, immediately.
    *
@@ -838,7 +923,7 @@ type ToolContext = {
 /**
  * Register the Apple Messages tools.
  *
- * Five reads, always. Two writes, only when `allowWrites` is on — and on this
+ * Six reads, always. Two writes, only when `allowWrites` is on — and on this
  * 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`.

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","names":[],"sources":["../src/build-info.ts","../src/config.ts","../src/client/locate.ts","../src/client/store.ts","../src/client/messages.ts","../src/client/dates.ts","../src/client/errors.ts","../src/client/ref.ts","../src/client/typedstream.ts","../src/client/jxa/core.ts","../src/client/jxa/write.ts","../src/server.ts","../src/tools/index.ts"],"mappings":"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"}
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/build-info.ts","../src/config.ts","../src/client/locate.ts","../src/client/store.ts","../src/client/messages.ts","../src/client/dates.ts","../src/client/errors.ts","../src/client/ref.ts","../src/client/typedstream.ts","../src/client/jxa/core.ts","../src/client/jxa/write.ts","../src/server.ts","../src/tools/index.ts"],"mappings":"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"}

package/dist/index.js

@@ -1,2 +1,2 @@
-import { A as MESSAGES_SURFACE, B as toAppleSeconds, C as locateStore, D as ChatNotFoundError, E as AppleMessagesError, F as SendTargetNotFoundError, I as CORE_DATA_EPOCH_OFFSET, L as appleSecondsSql, M as MessagesUnavailableError, N as SchemaDriftError, O as IndexUnavailableError, P as SendFailedError, R as fromAppleSeconds, S as defaultStorePath, T as PRELUDE, V as BUILD_INFO, _ as decodeMessageRef, a as loadConfig, b as ATTACHMENTS_RELATIVE, c as introspect, d as decodeAttributedBody, f as outline, g as decodeChatRef, h as MESSAGE_REF_VERSION, i as registerTools, j as MessageNotFoundError, k as MESSAGES_BUNDLE_ID, l as openStore, m as InvalidMessageRefError, n as SERVER_VERSION, o as AppleMessagesClient, p as CHAT_REF_VERSION, r as createServer, s as MessagesStore, t as SERVER_NAME, u as reactionLabel, v as encodeChatRef, w as SEND_MESSAGE, x as STORE_RELATIVE, y as encodeMessageRef, z as renderInstant } from "./server-BExbW9RO.js";
+import { A as MESSAGES_SURFACE, B as toAppleSeconds, C as locateStore, D as ChatNotFoundError, E as AppleMessagesError, F as SendTargetNotFoundError, I as CORE_DATA_EPOCH_OFFSET, L as appleSecondsSql, M as MessagesUnavailableError, N as SchemaDriftError, O as IndexUnavailableError, P as SendFailedError, R as fromAppleSeconds, S as defaultStorePath, T as PRELUDE, V as BUILD_INFO, _ as decodeMessageRef, a as loadConfig, b as ATTACHMENTS_RELATIVE, c as introspect, d as decodeAttributedBody, f as outline, g as decodeChatRef, h as MESSAGE_REF_VERSION, i as registerTools, j as MessageNotFoundError, k as MESSAGES_BUNDLE_ID, l as openStore, m as InvalidMessageRefError, n as SERVER_VERSION, o as AppleMessagesClient, p as CHAT_REF_VERSION, r as createServer, s as MessagesStore, t as SERVER_NAME, u as reactionLabel, v as encodeChatRef, w as SEND_MESSAGE, x as STORE_RELATIVE, y as encodeMessageRef, z as renderInstant } from "./server-CPDQqGEn.js";
 export { ATTACHMENTS_RELATIVE, AppleMessagesClient, AppleMessagesError, BUILD_INFO, CHAT_REF_VERSION, CORE_DATA_EPOCH_OFFSET, ChatNotFoundError, IndexUnavailableError, InvalidMessageRefError, MESSAGES_BUNDLE_ID, MESSAGES_SURFACE, MESSAGE_REF_VERSION, MessageNotFoundError, MessagesStore, MessagesUnavailableError, PRELUDE, SEND_MESSAGE, SERVER_NAME, SERVER_VERSION, STORE_RELATIVE, SchemaDriftError, SendFailedError, SendTargetNotFoundError, appleSecondsSql, createServer, decodeAttributedBody, decodeChatRef, decodeMessageRef, defaultStorePath, encodeChatRef, encodeMessageRef, fromAppleSeconds, introspect, loadConfig, locateStore, openStore, outline, reactionLabel, registerTools, renderInstant, toAppleSeconds };

package/dist/{server-BExbW9RO.js → server-CPDQqGEn.js}

@@ -1,4 +1,4 @@
-import { AppleAutomationError, AppleAutomationError as AppleMessagesError, BaseConfigSchema, CORE_DATA_EPOCH_OFFSET, IndexUnavailableError, IndexUnavailableError as IndexUnavailableError$1, PreconditionError, SchemaDriftError, SchemaDriftError as SchemaDriftError$1, columnsOf, confirmArg, createOsascriptRunner, describeStore, escapeLike, extractCode, fail, fingerprintSchema, limitArg, ok, openReadOnly, parseBool, parseConfig, parseIntOpt, promptArg, readPackageIdentity, registerSurfaceResources, registerWorkflowPrompt, requiredPromptArg, resolveLimit, trimmed, withBusyRetry, wrap, wrapResult } 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, columnsOf, confirmArg, createOsascriptRunner, describeAggregation, describeStore, escapeLike, extractCode, fail, fingerprintSchema, groupByArg, limitArg, ok, openReadOnly, parseBool, parseConfig, parseIntOpt, promptArg, readPackageIdentity, registerSurfaceResources, registerWorkflowPrompt, requiredPromptArg, resolveLimit, trimmed, withBusyRetry, wrap, wrapResult } from "@mgcrea/mcp-apple-core";
 import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { basename, isAbsolute, join, resolve, sep } from "node:path";
@@ -13,8 +13,8 @@ const pkg = readPackageIdentity(new URL("../package.json", import.meta.url), {
 const BUILD_INFO = {
 	name: pkg.name,
 	version: pkg.version,
-	gitCommit: "372c3c1",
-	gitCommitDate: "2026-09-02T22:36:25+02:00"
+	gitCommit: "25c3fa5",
+	gitCommitDate: "2026-09-03T18:51:51+02:00"
 };
 //#endregion
 //#region src/client/dates.ts
@@ -59,6 +59,18 @@ const NANOSECOND_FLOOR = 0xe8d4a51000;
 * integer reach `node:sqlite`'s value conversion.
 */
 const appleSecondsSql = (column) => `CASE WHEN ${column} IS NULL THEN NULL WHEN ABS(CAST(${column} AS REAL)) > ${NANOSECOND_FLOOR} THEN CAST(${column} AS REAL) / 1000000000.0 ELSE CAST(${column} AS REAL) END`;
+/**
+* SQL that buckets an apple-date column into a LOCAL calendar day or month.
+*
+* Local, not UTC, and that is a deliberate divergence from Mail's equivalent in
+* `packages/mail/src/client/envelope.ts`. "How many messages on the 3rd" is a
+* question about the calendar the person was living in, and texting peaks late:
+* with a UTC bucket, every message a user in CEST sends after 02:00 lands in the
+* previous day. Mail's buckets are UTC and answering that is a separate call.
+*
+* `format` is a literal from this module's callers, never caller text.
+*/
+const appleDateBucketSql = (column, format) => `strftime('${format}', datetime(${appleSecondsSql(column)} + ${CORE_DATA_EPOCH_OFFSET}, 'unixepoch', 'localtime'))`;
 /** Apple-seconds to a JS Date. Null in, null out. */
 const fromAppleSeconds = (value) => {
 	if (value === null || !Number.isFinite(value) || value === 0) return null;
@@ -900,6 +912,23 @@ const reactionLabel = (type) => {
 	if (type >= 3e3 && type <= 3005) return `removed ${REACTION_LABELS[type - 1e3] ?? "reaction"}`;
 	return `reaction ${type}`;
 };
+/**
+* What `countMessages` can group on.
+*
+* Metadata only, and that is the design rather than a first cut. Anything
+* derived from message TEXT is unavailable to SQL here: from March 2026 onward
+* the body lives only in `attributedBody`, which is why `search` carries a
+* second decode pass. A `GROUP BY` over `text LIKE ?` would return a number
+* shaped exactly like a correct one while missing every recent message, so this
+* lane never offers one.
+*/
+const COUNT_GROUP_FIELDS = [
+	"day",
+	"month",
+	"chat",
+	"handle",
+	"direction"
+];
 const num = (v) => typeof v === "number" ? v : null;
 const text = (v) => typeof v === "string" && v.length > 0 ? v : null;
 const bool = (v) => v === 1 || v === true;
@@ -1282,6 +1311,150 @@ var MessagesStore = class {
 			attachments: this.caps.hasAttachments ? one(`SELECT COUNT(*) AS c FROM "attachment"`) : 0
 		};
 	}
+	/**
+	* Count messages, optionally per group, over every match rather than a page.
+	*
+	* `limit` caps the number of GROUPS returned, never the messages counted —
+	* the same rule Mail's query lane is built on. An aggregate computed over a
+	* truncated page is not so much a wrong answer as a confidently wrong one:
+	* "my three busiest conversations" and "the three busiest among the twenty
+	* rows we happened to read" are the same shape, and nothing marks which you
+	* got. `totalRows` is therefore always reported.
+	*
+	* Every count is `COUNT(DISTINCT m."ROWID")`. The chat join is one row per
+	* (chat, message) pair, so a message filed in two chats would otherwise be
+	* counted twice in a total that is not itself per-chat.
+	*/
+	countMessages(q, field) {
+		const params = [];
+		const from = this.#countFrom(q, field);
+		const where = this.#countPredicate(q, params);
+		const totals = this.#countExprs();
+		if (!field) {
+			const row = this.db.prepare(`SELECT ${totals} FROM "message" m ${from} WHERE ${where}`).get(...params);
+			return this.#toTotals(row);
+		}
+		const { key, label } = this.#countGroupExpr(field);
+		const countParams = [];
+		const countWhere = this.#countPredicate(q, countParams);
+		const totalsRow = this.db.prepare(`SELECT COUNT(DISTINCT m."ROWID") AS totalRows,
+                COUNT(DISTINCT ${key}) + MAX(CASE WHEN ${key} IS NULL THEN 1 ELSE 0 END)
+                  AS totalGroups
+           FROM "message" m ${from}
+          WHERE ${countWhere}`).get(...countParams);
+		return {
+			groups: this.db.prepare(`SELECT ${key} AS key, ${label} AS label, ${totals}
+           FROM "message" m ${from}
+          WHERE ${where}
+          GROUP BY ${key}
+          -- Count first so \`limit\` yields a top-N; the key breaks ties, so
+          -- running the same question twice cannot reshuffle equal groups.
+          ORDER BY total DESC, key ASC
+          LIMIT ${Math.max(1, Math.trunc(q.limit))}`).all(...params).map((r) => ({
+				key: r.key === null ? null : String(r.key),
+				label: text(r.label),
+				...this.#toTotals(r)
+			})),
+			totalRows: Number(totalsRow.totalRows ?? 0),
+			totalGroups: Number(totalsRow.totalGroups ?? 0)
+		};
+	}
+	/**
+	* Join only what the question needs.
+	*
+	* Not an optimisation — a correctness choice. The chat join multiplies a
+	* message by the chats it belongs to, so it is absent unless a chat is being
+	* filtered on or grouped by.
+	*/
+	#countFrom(q, field) {
+		const parts = [];
+		if (q.handle || field === "handle") parts.push(`LEFT JOIN "handle" h ON h."ROWID" = m."handle_id"`);
+		if (q.chatGuid || field === "chat") parts.push(`LEFT JOIN "chat_message_join" cmj ON cmj."message_id" = m."ROWID"`, `LEFT JOIN "chat" c ON c."ROWID" = cmj."chat_id"`);
+		return parts.join("\n           ");
+	}
+	/**
+	* Shared by the totals and the grouped statement so the two cannot drift: a
+	* filter that narrowed the listing but not its aggregate would make "sent to
+	* this chat in August" quietly count the whole store.
+	*/
+	#countPredicate(q, params) {
+		const m = this.caps.messageColumns;
+		const where = [];
+		if (q.chatGuid) {
+			where.push(`c."guid" = ?`);
+			params.push(q.chatGuid);
+		}
+		if (q.handle) {
+			where.push(`h."id" LIKE ? ESCAPE '\\'`);
+			params.push(`%${escapeLike(q.handle)}%`);
+		}
+		if (q.direction && m.has("is_from_me")) {
+			where.push(`m."is_from_me" = ?`);
+			params.push(q.direction === "sent" ? 1 : 0);
+		}
+		if (q.fromApple !== void 0 && m.has("date")) {
+			where.push(`${appleSecondsSql("m.\"date\"")} >= ?`);
+			params.push(q.fromApple);
+		}
+		if (q.toApple !== void 0 && m.has("date")) {
+			where.push(`${appleSecondsSql("m.\"date\"")} < ?`);
+			params.push(q.toApple);
+		}
+		if (!q.includeReactions && m.has("associated_message_type")) where.push(`(m."associated_message_type" IS NULL OR m."associated_message_type" = 0)`);
+		return where.length ? where.join(" AND ") : "1 = 1";
+	}
+	/** The count columns every shape of this query selects. */
+	#countExprs() {
+		const m = this.caps.messageColumns;
+		const split = m.has("is_from_me");
+		return `COUNT(DISTINCT m."ROWID") AS total,
+              ${split ? `COUNT(DISTINCT CASE WHEN m."is_from_me" = 1 THEN m."ROWID" END)` : "NULL"} AS sent,
+              ${split ? `COUNT(DISTINCT CASE WHEN m."is_from_me" = 0 THEN m."ROWID" END)` : "NULL"} AS received,
+              ${m.has("date") ? appleSecondsSql("MIN(m.\"date\")") : "NULL"} AS firstAt,
+              ${m.has("date") ? appleSecondsSql("MAX(m.\"date\")") : "NULL"} AS lastAt`;
+	}
+	/**
+	* The column expression each groupable field aggregates on.
+	*
+	* A key here is the ONLY thing that reaches the statement — the tool matches
+	* the caller's string against `COUNT_GROUP_FIELDS` and passes the matched
+	* literal, so no caller-controlled text is ever interpolated. `label` goes
+	* through MAX() because everything outside GROUP BY has to be aggregated, and
+	* it is constant within a group anyway.
+	*/
+	#countGroupExpr(field) {
+		switch (field) {
+			case "day": return {
+				key: appleDateBucketSql("m.\"date\"", "%Y-%m-%d"),
+				label: "NULL"
+			};
+			case "month": return {
+				key: appleDateBucketSql("m.\"date\"", "%Y-%m"),
+				label: "NULL"
+			};
+			case "chat": return {
+				key: `c."guid"`,
+				label: `MAX(COALESCE(NULLIF(c."display_name", ''), c."chat_identifier"))`
+			};
+			case "handle": return {
+				key: `h."id"`,
+				label: "NULL"
+			};
+			case "direction": return {
+				key: `CASE WHEN m."is_from_me" = 1 THEN 'sent' ELSE 'received' END`,
+				label: "NULL"
+			};
+		}
+	}
+	#toTotals(r) {
+		return {
+			total: Number(r.total ?? 0),
+			sent: num(r.sent),
+			received: num(r.received),
+			firstAt: num(r.firstAt),
+			lastAt: num(r.lastAt)
+		};
+	}
 	close() {
 		try {
 			this.db.close();
@@ -1319,6 +1492,14 @@ const openStore = (path, mode, logger) => {
 };
 //#endregion
 //#region src/client/messages.ts
+/** Apple-seconds to ISO on the two date fields every count carries. */
+const renderCount = (c) => ({
+	total: c.total,
+	sent: c.sent,
+	received: c.received,
+	firstAt: renderInstant(c.firstAt),
+	lastAt: renderInstant(c.lastAt)
+});
 var AppleMessagesClient = class {
 	#config;
 	#logger;
@@ -1591,6 +1772,33 @@ var AppleMessagesClient = class {
 		}));
 	}
 	/**
+	* Count messages, optionally grouped — the cheap-answer lane on this surface.
+	*
+	* Deliberately metadata-only. The expensive questions here are "how many" and
+	* "how many per X", and the store answers both in SQL without a message body
+	* ever reaching the context window. Anything text-derived stays with
+	* `searchMessages`, which has the decode pass that makes it complete.
+	*/
+	countMessages(q, groupBy) {
+		const result = this.#require().countMessages({
+			...q,
+			limit: resolveLimit(q.limit, this.#config.maxResults)
+		}, groupBy);
+		if (!("groups" in result)) return renderCount(result);
+		const groups = result.groups;
+		if (groupBy === "handle") this.#resolve(groups.map((g) => g.key));
+		return {
+			groups: groups.map((g) => ({
+				key: g.key,
+				label: groupBy === "handle" ? this.#correspondent(g.key).name ?? g.label : g.label,
+				...groupBy === "chat" && g.key ? { ref: encodeChatRef(g.key) } : {},
+				...renderCount(g)
+			})),
+			totalGroups: result.totalGroups,
+			totalRows: result.totalRows
+		};
+	}
+	/**
 	* Pick the chat to address, using the store.
 	*
 	* Handles are matched the way `packages/contacts` measured them rather than by
@@ -1944,6 +2152,16 @@ an empty message history.
 - **\`apple_messages_search_messages\`** searches across them.
 - **\`apple_messages_get_message\`** returns one message with its tapbacks and
   attachments.
+- **Anything that is a NUMBER** — how many, how many did I send, who do I write
+  to most, which month was busiest — is \`apple_messages_count_messages\`, with
+  \`groupBy\` for a breakdown by day, month, chat, handle or direction. It
+  counts every match rather than a page, so never tally a listing by hand: past
+  the first \`limit\` that answer is simply wrong. Group by **handle** rather
+  than chat when the question is about a PERSON — one person can hold several
+  conversations, and \`list_chats\` counts each separately.
+- It counts metadata only, and there is no text filter on it. "How many times
+  did we say X" is not a question this surface can answer by counting: see the
+  blob below.
 
 ## Handles are not names
 
@@ -2291,6 +2509,62 @@ Returning nothing is the normal result when no code has arrived. It does NOT mea
 	}));
 };
 //#endregion
+//#region src/tools/counts.ts
+/** ISO-8601 in, or a clear refusal. Same grammar as `list_messages`. */
+const parseBound$1 = (raw, field) => {
+	if (raw === void 0) return void 0;
+	const d = new Date(raw);
+	if (Number.isNaN(d.getTime())) throw new Error(`Could not read ${field} from ${JSON.stringify(raw)}. Use ISO-8601: "2026-08-01" or "2026-08-01T09:00".`);
+	return d;
+};
+/**
+* The cheap-answer lane on this surface: counts, and counts per group.
+*
+* Narrower than Mail's `apple_mail_query` on purpose. Mail's version also
+* projects rows, because a mail row is mostly metadata and dropping half of it
+* saves real tokens; a Messages row's bulk IS its text, and a message listing
+* without the text is rarely the question. What was actually missing here is
+* arithmetic: a sent/received split, per-period volume, and per-handle totals
+* across the several chats one person can occupy — none of which
+* `apple_messages_list_chats` can answer, and all of which otherwise mean
+* paging conversations into the context to tally them by hand.
+*
+* Metadata only, and that boundary is load-bearing rather than a first cut: see
+* `COUNT_GROUP_FIELDS` in `store.ts` for why a text-derived aggregate cannot be
+* offered on a store whose recent bodies live in a blob.
+*/
+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: {
+			chatRef: chatRefArg,
+			handle: z.string().optional().describe("Only messages with this correspondent — a phone number or email, matched as a substring. 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."),
+			from: fromArg,
+			to: z.string().optional().describe("End of the window, ISO-8601, exclusive. Omit to count up to now."),
+			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(parseBound$1(from, "from"), parseBound$1(to, "to"));
+		const result = client.countMessages({
+			...chatRef ? { chatGuid: decodeChatRef(chatRef) } : {},
+			...handle === void 0 ? {} : { handle },
+			...direction === void 0 ? {} : { direction },
+			...window,
+			...includeReactions === void 0 ? {} : { includeReactions },
+			...limit === void 0 ? {} : { limit }
+		}, groupBy);
+		if (!("groups" in result)) return result;
+		return describeAggregation(groupBy, result.groups.map(({ total, ...rest }) => ({
+			...rest,
+			count: total
+		})), result);
+	}));
+};
+//#endregion
 //#region src/tools/messages.ts
 /** ISO-8601 in, or a clear refusal. No relative grammar on this surface yet. */
 const parseBound = (raw, field) => {
@@ -2360,7 +2634,7 @@ const registerMessageTools = (server, client) => {
 /**
 * Register the Apple Messages tools.
 *
-* Five reads, always. Two writes, only when `allowWrites` is on — and on this
+* Six reads, always. Two writes, only when `allowWrites` is on — and on this
 * 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`.
@@ -2383,6 +2657,7 @@ const registerTools = (server, client, ctx) => {
 	registerDiagnosticsTools(server, client);
 	registerChatTools(server, client);
 	registerMessageTools(server, client);
+	registerCountTools(server, client);
 	if (ctx.allowCodes) registerCodeTools(server, client);
 	if (!ctx.allowWrites) return;
 	registerActionTools(server, client, ctx);
@@ -2432,4 +2707,4 @@ const createServer = (opts) => {
 //#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-BExbW9RO.js.map
+//# sourceMappingURL=server-CPDQqGEn.js.map