@mgcrea/mcp-apple-messages 1.3.0

package/dist/server-DH4U3LBX.js

@@ -0,0 +1,2137 @@
+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, fail, fingerprintSchema, limitArg, ok, openReadOnly, parseBool, parseConfig, parseIntOpt, promptArg, readPackageIdentity, registerSurfaceResources, registerWorkflowPrompt, requiredPromptArg, 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, 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";
+//#region src/build-info.ts
+const pkg = readPackageIdentity(new URL("../package.json", import.meta.url), {
+	name: "@mgcrea/mcp-apple-messages",
+	version: "0.0.0"
+});
+const BUILD_INFO = {
+	name: pkg.name,
+	version: pkg.version,
+	gitCommit: "b0f25be",
+	gitCommitDate: "2026-08-26T18:45:17+02:00"
+};
+//#endregion
+//#region src/client/dates.ts
+/**
+* Messages' dates, which do not fit in a JavaScript number.
+*
+* `docs/messages.md` measured every populated date column as **nanoseconds since
+* 2001-01-01** — eighteen digits, about 7.9e17, two orders of magnitude past
+* `Number.MAX_SAFE_INTEGER`. `node:sqlite` throws on those rather than
+* truncating, which is correct of it and fatal to a naive `SELECT date`.
+*
+* The failure mode is what makes this worth its own module. Wrapped in the usual
+* try/catch the throw is swallowed and the column reports as EMPTY — the probe
+* did exactly that on its first granted run and announced "no dates present" for
+* all seven columns across 97,414 messages. A section written to catch a silent
+* 31-year error was itself silently wrong.
+*
+* ## The fix: divide in SQL, not in JavaScript
+*
+* `CAST(date AS REAL) / 1e9` never materialises the integer on the JS side, so
+* there is nothing to throw. Precision is fine: 7.9e8 seconds with a fractional
+* part is comfortably inside a double, and this surface has no use for
+* nanosecond resolution anyway.
+*
+* Every query in `store.ts` uses `APPLE_SECONDS_SQL`. Reading one of these
+* columns any other way is the bug.
+*/
+/** Seconds between 1970-01-01 and 2001-01-01. Same constant as `packages/core`. */
+/**
+* Below this, a value is seconds rather than nanoseconds.
+*
+* Messages switched around macOS 10.13 and old rows were not rewritten, so a
+* store with history from both eras carries both. 1e12 apple-seconds is the year
+* 33,658 and 1e12 apple-nanoseconds is 2001 — no real timestamp is near it in
+* either reading, which is what makes the split safe.
+*/
+const NANOSECOND_FLOOR = 0xe8d4a51000;
+/**
+* SQL that yields apple-SECONDS as a REAL, whichever unit the row holds.
+*
+* Done in SQL rather than in JS because the point is to never let the raw
+* 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`;
+/** Apple-seconds to a JS Date. Null in, null out. */
+const fromAppleSeconds = (value) => {
+	if (value === null || !Number.isFinite(value) || value === 0) return null;
+	return /* @__PURE__ */ new Date((value + CORE_DATA_EPOCH_OFFSET) * 1e3);
+};
+/** A JS Date to apple-seconds, for range bounds. */
+const toAppleSeconds = (date) => date.getTime() / 1e3 - CORE_DATA_EPOCH_OFFSET;
+/** ISO-8601, or null. What every date field on a result carries. */
+const renderInstant = (value) => fromAppleSeconds(value)?.toISOString() ?? null;
+//#endregion
+//#region src/client/errors.ts
+/**
+* Messages' error surface. The taxonomy lives in `@mgcrea/mcp-apple-core`; what
+* belongs here is the identity those messages are written against.
+*/
+const MESSAGES_SURFACE = {
+	appName: "Messages",
+	envPrefix: "APPLE_MESSAGES"
+};
+/**
+* Used by exactly one code path, and unused by every read.
+*
+* Messages is the one surface with NO Apple Events read lane at all — measured,
+* not assumed. `docs/messages.md` records every attempt failing, and the reason
+* is peculiar enough to write down: Messages answers "Application isn't running"
+* while `NSRunningApplication` reports it running, because it lives as a
+* windowless background process that declines to wake for a script. The liveness
+* check and the app's own answer disagree and neither is lying.
+*
+* The id is the liveness check for `send`, which is the only thing Apple Events
+* can do on this surface — see `client/jxa/core.ts`.
+*/
+const MESSAGES_BUNDLE_ID = "com.apple.MobileSMS";
+/** A message ref no longer resolves — deleted, or the chat was cleared. */
+var MessageNotFoundError = class extends AppleAutomationError {
+	name = "MessageNotFoundError";
+	constructor(ref) {
+		super(`No message for ref "${ref}". It was probably deleted since the search ran. Re-run the search to get a current ref.`, { ref });
+	}
+};
+/** A chat ref no longer resolves. */
+var ChatNotFoundError = class extends AppleAutomationError {
+	name = "ChatNotFoundError";
+	constructor(ref) {
+		super(`No chat for ref "${ref}". Use apple_messages_list_chats to get a current ref.`, { ref });
+	}
+};
+/**
+* The store could not be read.
+*
+* Its own error because this surface fails harder than any other: there is no
+* Apple Events fallback, so without Full Disk Access there is no server at all.
+* `docs/distribution.md`'s "try before you grant" was retired partly because of
+* this surface, and the message says so rather than implying a degraded mode
+* that does not exist.
+*/
+var MessagesUnavailableError = class extends AppleAutomationError {
+	name = "MessagesUnavailableError";
+	constructor(reason) {
+		super(reason, {});
+	}
+};
+/**
+* Messages would not accept any form of recipient for a send.
+*
+* Its own error because the cause is almost never the recipient. Every rung of
+* the ladder in `client/jxa/core.ts` except the first one enumerates something,
+* and enumeration is exactly what this app refuses — so the usual cause of this
+* error is that the chat is new (no guid in the store to address it by) rather
+* than that the person does not exist. The message says so, because "not found"
+* would send a caller looking for a typo that is not there.
+*/
+var SendTargetNotFoundError = class extends AppleAutomationError {
+	name = "SendTargetNotFoundError";
+	constructor(recipient, attempts) {
+		super(`Messages would not resolve "${recipient}" to a chat or participant, so nothing was sent. This usually means there is no existing conversation with them on this Mac: Messages refuses to enumerate participants for a script, so an existing chat is the only handle this server can address reliably. Open the conversation once in Messages.app and retry.`, {
+			recipient,
+			attempts: [...attempts]
+		});
+	}
+};
+/** Messages accepted the target and then refused the send itself. */
+var SendFailedError = class extends AppleAutomationError {
+	name = "SendFailedError";
+	constructor(message, attempts) {
+		super(`Messages refused the send: ${message}`, { attempts: [...attempts] });
+	}
+};
+//#endregion
+//#region src/client/jxa/core.ts
+/**
+* The Apple Events lane for Messages — which exists for exactly one verb.
+*
+* Every script here is a static constant. None may contain a template
+* interpolation: `assertStaticScript` rejects any script containing a dollar
+* sign followed by a brace, including one written inside the JXA source. Use
+* string concatenation in JXA code.
+*
+* Contract, shared with every other surface:
+*   - parameters arrive as `JSON.parse(argv[0])`
+*   - success returns `JSON.stringify({ok: true, data})`
+*   - an application-level failure returns `{ok: false, error: {code, message}}`
+*     and still exits 0, so a non-zero exit always means infrastructure.
+*
+* ## There is no read.ts here, and there never can be
+*
+* Adding a send did not add a read lane, and on this surface that is not a
+* policy choice — it is the measurement in `docs/messages.md`:
+*
+* | attempt          | result                                    |
+* | ---------------- | ----------------------------------------- |
+* | `chats()`        | `Error: Application isn't running.`       |
+* | `chats.id()`     | `TypeError: M.chats.id is not a function` |
+* | `participants()` | `Error: Application isn't running.`       |
+* | `buddies()`      | `Error: Application isn't running.`       |
+* | messages of chat | `Error: Application isn't running.`       |
+*
+* Messages answers "Application isn't running" while `NSRunningApplication`
+* reports it running, because it lives as a windowless background process that
+* declines to wake for a script. `test/jxa.test.ts` asserts `read.ts` does not
+* exist, so this cannot be re-added out of helpfulness.
+*
+* The consequence for the code below is concrete: **the target resolution steps
+* that enumerate anything are expected to fail**, which is why they are a ladder
+* and why every rung reports itself. The one rung that does not enumerate —
+* `chats.byId(guid)`, with the guid handed over by the file lane — is the one
+* this design is built around.
+*
+* ## What the dictionary actually offers
+*
+* MEASURED from `sdef /System/Applications/Messages.app` on macOS 26.6. Three
+* commands, and only one of them is a write:
+*
+*     send     text (or a file) to a participant or a chat
+*     login    log in to all accounts
+*     logout   log out of all accounts
+*
+* `login`/`logout` are not exposed as tools: logging a user out of iMessage on
+* every device is not something to do behind a tool call, and there is no read
+* to justify logging in.
+*
+* `send`'s direct parameter is typed `file` OR `text`. **This ships text only.**
+* The file form is one branch away and deliberately not taken: a tool that
+* transfers an arbitrary local path to a remote person is an exfiltration
+* primitive, and unlike the text form its blast radius is not bounded by what
+* the model can say. Recorded here so the omission reads as a decision.
+*
+* ## The `to` parameter, and why the file lane picks the target
+*
+* `send` takes a `participant` or a `chat`. Getting one of those normally means
+* enumerating, which is the thing that does not work here. But the `chat` class
+* carries `id` — "A guid identifier for this chat" — and the file lane already
+* holds `chat.guid` for all 1,027 chats on the measured store. So the read lane
+* chooses the target and the write lane addresses it by id, which is the only
+* arrangement where neither lane has to do the thing it cannot.
+*
+* That the two guids are the same string is NOT assumed. It is the exact class
+* of thing this project has been wrong about before — `docs/messages.md` calls
+* the id bridge "unanswerable by construction" because Messages returned no
+* identifier to bridge FROM. So `chats.byId` is rung one of a ladder, every rung
+* records why it failed, and the strategy that worked is reported back to the
+* caller in the tool result.
+*/
+/** The bundle id, which does not match the display name: Messages.app is still MobileSMS. */
+const PRELUDE = `
+ObjC.import("AppKit");
+
+function ok(data) { return JSON.stringify({ ok: true, data: data }); }
+function err(code, message, extra) {
+  var e = { code: code, message: String(message) };
+  if (extra) e.detail = extra;
+  return JSON.stringify({ ok: false, error: e });
+}
+
+/** Read one property defensively — every read on this surface is allowed to fail. */
+function prop(fn, fallback) {
+  try {
+    var v = fn();
+    return v === undefined ? fallback : v;
+  } catch (e) {
+    return fallback;
+  }
+}
+
+function isMessagesRunning() {
+  var apps = $.NSRunningApplication.runningApplicationsWithBundleIdentifier("com.apple.MobileSMS");
+  return apps.count > 0;
+}
+
+/** The dictionary's service type enumeration: SMS, iMessage, RCS. */
+function serviceEnum(name) {
+  var s = String(name || "").toLowerCase();
+  if (s === "sms") return "SMS";
+  if (s === "rcs") return "RCS";
+  return "iMessage";
+}
+
+/**
+ * Find something \`send\` will accept as its \`to\`.
+ *
+ * Ordered cheapest and most-likely-to-work first. Every rung is wrapped, every
+ * failure is recorded, and the caller is told which one answered — on a surface
+ * whose whole read half is known broken, "it worked" without "how" is not a
+ * result anyone can act on later.
+ */
+function resolveTarget(M, p, tried) {
+  var i;
+
+  // 1. The chat guid the file lane read out of chat.db. No enumeration.
+  if (p.chatGuid) {
+    try {
+      var chat = M.chats.byId(p.chatGuid);
+      chat.id();
+      return { target: chat, strategy: "chat-guid", kind: "chat" };
+    } catch (e) {
+      tried.push("chat-guid: " + (e.message || e));
+    }
+  }
+
+  if (!p.handle) return null;
+
+  // 2. The guid Messages composes for a one-to-one chat, spelled the way the
+  //    store spells it: "iMessage;-;+15551234567". Constructed rather than read,
+  //    so it is below the real one and above everything that enumerates.
+  var services = p.service ? [serviceEnum(p.service)] : ["iMessage", "SMS", "RCS"];
+  for (i = 0; i < services.length; i++) {
+    var guess = services[i] + ";-;" + p.handle;
+    try {
+      var guessed = M.chats.byId(guess);
+      guessed.id();
+      return { target: guessed, strategy: "chat-guid-guess", kind: "chat", guid: guess };
+    } catch (e2) {
+      tried.push("chat-guid-guess(" + guess + "): " + (e2.message || e2));
+    }
+  }
+
+  // 3. A participant reached through its account. This enumerates, so it is
+  //    expected to fail with "Application isn't running" — kept because it is
+  //    the form every AppleScript example on the internet uses, and because if
+  //    launching the app does wake the scripting interface, this is what works.
+  for (i = 0; i < services.length; i++) {
+    try {
+      var accounts = M.accounts.whose({ serviceType: services[i] })();
+      for (var j = 0; j < accounts.length; j++) {
+        try {
+          var buddy = accounts[j].participants.whose({ handle: p.handle })()[0];
+          if (buddy) {
+            buddy.id();
+            return { target: buddy, strategy: "account-participant", kind: "participant" };
+          }
+        } catch (e4) {
+          tried.push("account-participant(" + services[i] + "): " + (e4.message || e4));
+        }
+      }
+    } catch (e3) {
+      tried.push("accounts(" + services[i] + "): " + (e3.message || e3));
+    }
+  }
+
+  // 4. The flat participant list, last because it is the widest enumeration.
+  try {
+    var flat = M.participants.whose({ handle: p.handle })()[0];
+    if (flat) {
+      flat.id();
+      return { target: flat, strategy: "participant", kind: "participant" };
+    }
+    tried.push("participant: no participant with that handle");
+  } catch (e5) {
+    tried.push("participant: " + (e5.message || e5));
+  }
+
+  return null;
+}
+`;
+//#endregion
+//#region src/client/jxa/write.ts
+/**
+* One script, one verb.
+*
+* `send` is the only mutating command in the Messages dictionary that this
+* server exposes — see `core.ts` for the full list and for why `login`/`logout`
+* and the file form of `send` are left out.
+*
+* ## What this script deliberately does NOT do
+*
+* It does not report success from its own read-back, because there is nothing to
+* read back: `send` returns no value, and every read this app offers fails. A
+* script that answered `{ok: true}` and stopped would be claiming delivery on
+* the strength of a command that did not throw — the exact shape of "plausible,
+* wrong and silent" this repo keeps designing against.
+*
+* So the script's answer is deliberately narrow: **the send command was accepted
+* by Messages, and here is how the target was addressed.** Whether a row landed
+* is a question for the file lane, and `client/messages.ts` asks it immediately
+* afterwards by polling chat.db for the outgoing row. That split is the answer
+* to the open question `docs/messages.md` left — "whether a send should
+* re-resolve by scanning the store for a recent row on the target chat" — and it
+* is what makes a send reportable at all on a surface with no id bridge.
+*/
+const SEND_MESSAGE = `${PRELUDE}
+function run(argv) {
+  var p = JSON.parse(argv[0]);
+  var M = Application("Messages");
+
+  var wasRunning = isMessagesRunning();
+  if (!wasRunning && !p.allowLaunch) {
+    return err("APP_NOT_RUNNING", "Messages is not running.");
+  }
+
+  var tried = [];
+  var resolved = resolveTarget(M, p, tried);
+  if (!resolved) {
+    return err(
+      "SEND_TARGET_NOT_FOUND",
+      "Messages would not resolve a chat or participant for that recipient.",
+      tried
+    );
+  }
+
+  try {
+    M.send(p.text, { to: resolved.target });
+  } catch (e) {
+    return err("SEND_FAILED", e.message || e, tried);
+  }
+
+  return ok({
+    strategy: resolved.strategy,
+    targetKind: resolved.kind,
+    // Best effort, and allowed to be null: reading the id back is itself a read.
+    targetId: prop(function () { return String(resolved.target.id()); }, null),
+    launched: !wasRunning,
+    attempts: tried
+  });
+}
+`;
+//#endregion
+//#region src/client/locate.ts
+/**
+* Find Messages' store.
+*
+* The easiest locator in the repo: `~/Library/Messages/chat.db` is a constant,
+* with no generated directory name to list (Reminders) and no per-account fan-out
+* (Contacts). `statSync` succeeds on a TCC-protected file while `open` is denied,
+* so this distinguishes "not there" from "not allowed" with no permission at all
+* — which is most of what diagnostics is for on a surface where the grant is
+* mandatory.
+*/
+const STORE_RELATIVE = join("Library", "Messages", "chat.db");
+/** Attachment bytes live here, referenced by `attachment.filename`. */
+const ATTACHMENTS_RELATIVE = join("Library", "Messages", "Attachments");
+/**
+* The directory an attachment path is required to sit inside.
+*
+* Deliberately the Messages root rather than `Attachments` itself. Measured
+* shapes of `attachment.filename` include stickers, which Messages keeps in a
+* sibling directory, so confining to `Attachments` would refuse real files —
+* and confining to nothing at all would let a row in a database this server
+* does not write choose which file gets copied out.
+*/
+const MESSAGES_ROOT_RELATIVE = join("Library", "Messages");
+const defaultStorePath = (home = homedir()) => join(home, STORE_RELATIVE);
+const FDA_HINT = "Grant Full Disk Access to the app running this server (System Settings > Privacy & Security > Full Disk Access) and restart it. Granting it to Messages.app does nothing — the reader needs the permission. Unlike every other surface here, there is no Apple Events fallback: Messages has no read path in its scripting dictionary at all, so without this grant there is no server.";
+const locateStore = (opts = {}) => {
+	const home = opts.home ?? homedir();
+	const storePath = opts.storePath ?? defaultStorePath(home);
+	const facts = describeStore(storePath);
+	return {
+		...facts,
+		storePath,
+		attachmentsPath: join(home, ATTACHMENTS_RELATIVE),
+		messagesRoot: join(home, MESSAGES_ROOT_RELATIVE),
+		reason: facts.readable ? null : facts.exists ? `Found the Messages store at ${storePath} but cannot read it. ${FDA_HINT}` : opts.storePath ? `No file at ${storePath}. APPLE_MESSAGES_STORE points at nothing.` : `No Messages store at ${storePath}. Has Messages ever been set up on this account?`
+	};
+};
+//#endregion
+//#region src/client/ref.ts
+/**
+* Refs for messages and chats.
+*
+* ## 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.
+*
+* 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
+* schema already treats as stable.
+*
+* ## Why `m1:` and `mc1:`
+*
+* `c1:` is Calendar's, `r1:` is Reminders', `k1:` is Contacts'. A ref that
+* decodes under two surfaces would be worse than one that decodes under none,
+* so each prefix is claimed once and the version digit keeps a future scheme
+* change additive.
+*/
+const MESSAGE_REF_VERSION = "m1";
+const CHAT_REF_VERSION = "mc1";
+/**
+* A GUID is opaque and not always a UUID — measured shapes include
+* `iMessage;-;+15551234567` on chats, which carries semicolons and a phone
+* number. So the tail is greedy and nothing inside it is parsed.
+*/
+const MESSAGE_PATTERN = /^m1:(.+)$/;
+const CHAT_PATTERN = /^mc1:(.+)$/;
+const otherSurface = (raw) => {
+	if (raw.startsWith("c1:")) return " That one is a Calendar event ref.";
+	if (raw.startsWith("r1:")) return " That one is a Reminders ref.";
+	if (raw.startsWith("k1:")) return " That one is a Contacts ref.";
+	if (raw.startsWith("mc1:")) return " That one is a CHAT ref — this wants a message ref.";
+	if (raw.startsWith("m1:")) return " That one is a MESSAGE ref — this wants a chat ref.";
+	return "";
+};
+var InvalidMessageRefError = class extends AppleAutomationError {
+	name = "InvalidMessageRefError";
+	constructor(raw, want) {
+		super(`"${raw}" is not a ${want} ref. Refs come from apple_messages_* results and look like ${want === "message" ? "\"m1:<guid>\"" : "\"mc1:<guid>\""} — they are opaque and must not be constructed by hand.${otherSurface(raw)}`, { ref: raw });
+	}
+};
+const encodeMessageRef = (guid) => `m1:${guid}`;
+const encodeChatRef = (guid) => `mc1:${guid}`;
+const decodeMessageRef = (raw) => {
+	const m = MESSAGE_PATTERN.exec(raw.trim());
+	if (!m?.[1]) throw new InvalidMessageRefError(raw, "message");
+	return m[1];
+};
+const decodeChatRef = (raw) => {
+	const m = CHAT_PATTERN.exec(raw.trim());
+	if (!m?.[1]) throw new InvalidMessageRefError(raw, "chat");
+	return m[1];
+};
+//#endregion
+//#region src/client/typedstream.ts
+/**
+* NSArchiver `typedstream` reader — enough of it to pull the text out of a
+* Messages `attributedBody` blob.
+*
+* ## Why this has to exist
+*
+* `docs/messages.md` measured it: 97,092 of 97,414 messages carry a blob and
+* only 94,049 carry `text`. **The blob is the norm and `text` is the redundant
+* copy**, not the other way round. 3,043 messages — one in thirty-two — have an
+* empty `text` and content only in here, so a server that reads the column
+* returns nothing for them, silently and with no error to notice.
+*
+* The archive header is `04 0B streamtyped 81 E8 03`. Not `bplist00`, not gzip,
+* and not the protobuf that Notes turned out to hold, so none of the existing
+* decoders apply.
+*
+* ## The format, as far as this reader needs it
+*
+* A stream of tagged values. Integers are a single signed byte unless prefixed:
+*
+*     0x81  int16 follows (little-endian)
+*     0x82  int32 follows
+*     0x83  float or double follows
+*     0x84  START — a new class or object definition
+*     0x85  nil / empty
+*     0x86  END of the current object
+*     >=0x92 a back-reference; index = byte - 0x92
+*
+* Strings arrive length-prefixed. Class names and object contents both use that
+* shape, which is why this walks structurally instead of pattern-matching: the
+* same bytes mean different things depending on where you are.
+*
+* ## Honest failure, never a guess
+*
+* The Notes decoder was documented backwards because a `LIMIT 1` sample landed
+* on an outlier, and this project has now been bitten three times by a heuristic
+* that produced a plausible wrong answer. So there is no "longest printable run"
+* fallback here. If the structure does not parse, `ok` is false and the caller
+* counts it — and `text` remains available as the answer for the 96.5% of rows
+* that have one.
+*
+* Pure and I/O-free.
+*
+* ## Two copies, deliberately
+*
+* `scripts/lib/typedstream.mjs` is the same reader, and the probe uses it to
+* measure this one against a real store. They are kept in step by hand, as
+* `packages/notes/src/client/protobuf.ts` and `scripts/lib/note-protobuf.mjs`
+* already are: a probe that imported from a package would stop being runnable
+* before that package exists, which is the wrong way round.
+*/
+const SIGNATURE = "streamtyped";
+const TAG_I16 = 129;
+const TAG_I32 = 130;
+const TAG_DECIMAL = 131;
+const TAG_START = 132;
+const TAG_EMPTY = 133;
+const TAG_END = 134;
+/** Anything at or above this is an index into the table of things already seen. */
+const TAG_REFERENCE = 146;
+/** A blob larger than this is not a message; refuse rather than chew through it. */
+const MAX_BLOB_BYTES = 4194304;
+/**
+* Structural guard for the walk BEFORE the text is reached — class chains and
+* type encodings, which are a few dozen tokens on every blob measured. Reaching
+* this means the stream is not shaped like an archived attributed string.
+*/
+const MAX_TOKENS = 2e4;
+const utf8 = new TextDecoder("utf-8", { fatal: true });
+const latin1 = new TextDecoder("latin1");
+var Cursor = class {
+	buf;
+	pos;
+	constructor(buf) {
+		this.buf = buf;
+		this.pos = 0;
+	}
+	get done() {
+		return this.pos >= this.buf.length;
+	}
+	get remaining() {
+		return this.buf.length - this.pos;
+	}
+	byte() {
+		return this.buf[this.pos++];
+	}
+	peek() {
+		return this.buf[this.pos];
+	}
+	take(n) {
+		const out = this.buf.subarray(this.pos, this.pos + n);
+		this.pos += n;
+		return out;
+	}
+	/**
+	* A byte at an offset from the cursor. Every caller checks `remaining` first,
+	* so the index is in range — this exists to say that once rather than to
+	* scatter non-null assertions through the integer readers.
+	*/
+	at(offset) {
+		return this.buf[this.pos + offset];
+	}
+};
+/**
+* A signed integer, which is also how every length in the stream is written.
+*
+* Returns null rather than throwing on a truncated read — a truncated blob is a
+* finding, not a crash.
+*/
+const readInt = (c) => {
+	if (c.done) return null;
+	const b = c.byte();
+	if (b === TAG_I16) {
+		if (c.remaining < 2) return null;
+		const v = c.at(0) | c.at(1) << 8;
+		c.pos += 2;
+		return v > 32767 ? v - 65536 : v;
+	}
+	if (b === TAG_I32) {
+		if (c.remaining < 4) return null;
+		const v = (c.at(0) | c.at(1) << 8 | c.at(2) << 16 | c.at(3) << 24) >>> 0;
+		c.pos += 4;
+		return v > 2147483647 ? v - 4294967296 : v;
+	}
+	if (b === TAG_DECIMAL) return null;
+	return b > 127 ? b - 256 : b;
+};
+/** A length-prefixed string. `null` when the bytes are not valid UTF-8. */
+const readString = (c) => {
+	const len = readInt(c);
+	if (len === null || len < 0 || len > c.remaining) return null;
+	const bytes = c.take(len);
+	try {
+		return utf8.decode(bytes);
+	} catch {
+		return null;
+	}
+};
+/**
+* A length-prefixed UTF-8 payload — the `+` type encoding's value.
+*
+* The length is in BYTES, which is the trap: a 22-character string of accents
+* and kana declares 36. Slicing by character count would desynchronise the walk
+* and corrupt everything after it.
+*/
+const readByteArray = (c) => {
+	const len = readInt(c);
+	if (len === null || len < 0 || len > c.remaining) return null;
+	const bytes = c.take(len);
+	try {
+		return utf8.decode(bytes);
+	} catch {
+		return null;
+	}
+};
+/**
+* Validate the archive header and position the cursor after it.
+*
+* The system-version integer that follows the signature is read and discarded —
+* it is 1000 on every blob measured, and pinning it would reject a future macOS
+* for no reason.
+*/
+const readHeader = (c) => {
+	if (c.remaining < 16) return "too short to be a typedstream";
+	const version = c.byte();
+	const sigLen = c.byte();
+	if (sigLen !== 11) return `bad signature length ${sigLen}`;
+	const sig = latin1.decode(c.take(sigLen));
+	if (sig !== SIGNATURE) return `not a typedstream (signature ${JSON.stringify(sig)})`;
+	readInt(c);
+	return version === 4 ? null : `unexpected streamer version ${version}`;
+};
+const walk = (c) => {
+	const strings = [];
+	const classes = [];
+	let firstPayloadEnd = null;
+	let tokens = 0;
+	while (!c.done) {
+		if (++tokens > MAX_TOKENS) return {
+			strings,
+			classes,
+			firstPayloadEnd,
+			error: "token limit exceeded"
+		};
+		if (c.peek() !== TAG_START) {
+			c.pos += 1;
+			continue;
+		}
+		c.pos += 1;
+		if (c.peek() === TAG_START) continue;
+		const before = c.pos;
+		const encoding = readString(c);
+		if (encoding === null) {
+			c.pos = before;
+			continue;
+		}
+		if (encoding === "+") {
+			const value = readByteArray(c);
+			if (value === null) return {
+				strings,
+				classes,
+				firstPayloadEnd,
+				error: "truncated byte array"
+			};
+			strings.push(value);
+			firstPayloadEnd = c.pos;
+			return {
+				strings,
+				classes,
+				firstPayloadEnd,
+				error: null
+			};
+		}
+		if (/^[A-Za-z_][A-Za-z0-9_.]*$/.test(encoding) && encoding.length > 2) classes.push(encoding);
+	}
+	return {
+		strings,
+		classes,
+		firstPayloadEnd,
+		error: null
+	};
+};
+const decodeAttributedBody = (buffer) => {
+	if (!buffer || buffer.length === 0) return {
+		ok: false,
+		error: "empty blob"
+	};
+	if (buffer.length > MAX_BLOB_BYTES) return {
+		ok: false,
+		error: "blob too large"
+	};
+	const c = new Cursor(buffer);
+	const headerError = readHeader(c);
+	if (headerError) return {
+		ok: false,
+		error: headerError
+	};
+	const { strings, classes, error, firstPayloadEnd } = walk(c);
+	if (error) return {
+		ok: false,
+		error,
+		classes
+	};
+	if (strings.length === 0) return {
+		ok: false,
+		error: "no content string found",
+		classes
+	};
+	return {
+		ok: true,
+		text: strings[0],
+		classes,
+		/** Bytes remained after the backing store — attribute runs this does not decode. */
+		hasAttributes: firstPayloadEnd !== null && firstPayloadEnd < buffer.length - 2,
+		error: null
+	};
+};
+/**
+* A redacted structural outline of one blob.
+*
+* For measuring the format on a machine that has the data, without the report
+* ever carrying a message. Every string is reduced to its length and its
+* character class; only Apple's own constants survive as themselves.
+*/
+const outline = (buffer, maxTokens = 60) => {
+	const c = new Cursor(buffer);
+	const headerError = readHeader(c);
+	if (headerError) return [`ERROR ${headerError}`];
+	const out = [];
+	let tokens = 0;
+	while (!c.done && tokens < maxTokens) {
+		tokens += 1;
+		const b = c.peek();
+		if (b === TAG_START) {
+			c.pos += 1;
+			out.push("START");
+			continue;
+		}
+		if (b === TAG_EMPTY) {
+			c.pos += 1;
+			out.push("nil");
+			continue;
+		}
+		if (b === TAG_END) {
+			c.pos += 1;
+			out.push("END");
+			continue;
+		}
+		if (b >= TAG_REFERENCE) {
+			c.pos += 1;
+			out.push(`ref#${b - TAG_REFERENCE}`);
+			continue;
+		}
+		const before = c.pos;
+		const s = readString(c);
+		if (s === null) {
+			c.pos = before + 1;
+			out.push(`byte 0x${b.toString(16).padStart(2, "0")}`);
+			continue;
+		}
+		if (/^(NS|IM|__kIM|CF)[A-Za-z0-9_]*$/.test(s) || s.length <= 2) out.push(`"${s}"`);
+		else out.push(`<str len=${s.length} ${/^[\x20-\x7e]*$/.test(s) ? "ascii" : "unicode"}>`);
+	}
+	if (!c.done) out.push("…");
+	return out;
+};
+//#endregion
+//#region src/client/store.ts
+/**
+* Messages' file lane — the only lane there is.
+*
+* `docs/messages.md` measured every Apple Events read attempt failing, so unlike
+* every other surface here there is nothing to fall back to. That shapes two
+* things: `SchemaDriftError` is the only fatal condition, and a missing store is
+* reported as a reason rather than as an empty list.
+*
+* ## Three measurements this file is built on
+*
+* **The blob is the norm, and increasingly the only thing there.** 97,094 rows
+* carry `attributedBody` and 94,043 carry `text`; 3,051 have only the blob. That
+* 3.1% is an average over a decade, and it hides the real shape: measured
+* through this server, 2016-2025 are ~99% plain `text` and everything from
+* MARCH 2026 ONWARD is blob-only. A reader that selects `text` would today
+* report that the conversation stopped in February. Every read here goes through
+* `#body()`, which prefers the column and falls back to the decoder — validated
+* at **100.000% agreement across all 94,043 rows** where both exist, with zero failures
+* across all 97,094.
+*
+* **Dates do not fit in a JavaScript number.** See `dates.ts`. Every date column
+* is projected through `appleSecondsSql`, never selected raw.
+*
+* **Reactions are messages.** 2,788 rows carry `associated_message_type != 0`,
+* and a reader that does not filter them renders `Liked "see you at 8"` as if
+* somebody had typed it. Filtering is table stakes, not an enhancement.
+*/
+/** Tables the lane cannot work without. */
+const REQUIRED = [
+	"message",
+	"chat",
+	"handle"
+];
+const PROBED_FINGERPRINT = "87b01c58a631";
+const PROBED_MACOS = "26.6";
+/**
+* A tapback rather than something somebody typed.
+*
+* 2000–2005 add a reaction, 3000–3005 remove one; 0 is an ordinary message.
+* The ranges are Apple's and are not documented anywhere public, so the code
+* treats "not zero" as the test and only uses the ranges to LABEL — an
+* unrecognised value is still excluded from the conversation, which is the safe
+* direction.
+*/
+const REACTION_LABELS = {
+	2e3: "loved",
+	2001: "liked",
+	2002: "disliked",
+	2003: "laughed",
+	2004: "emphasized",
+	2005: "questioned"
+};
+const reactionLabel = (type) => {
+	if (REACTION_LABELS[type]) return REACTION_LABELS[type];
+	if (type >= 3e3 && type <= 3005) return `removed ${REACTION_LABELS[type - 1e3] ?? "reaction"}`;
+	return `reaction ${type}`;
+};
+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;
+var MessagesStore = class {
+	db;
+	mode;
+	caps;
+	constructor(db, mode, caps) {
+		this.db = db;
+		this.mode = mode;
+		this.caps = caps;
+	}
+	/** Project a column, or a typed NULL when this store does not have it. */
+	#col(present, table, name, alias = name) {
+		return present.has(name) ? `${table}."${name}" AS ${alias}` : `NULL AS ${alias}`;
+	}
+	#date(present, table, name, alias) {
+		return present.has(name) ? `${appleSecondsSql(`${table}."${name}"`)} AS ${alias}` : `NULL AS ${alias}`;
+	}
+	/**
+	* The text of a message, from whichever source has it.
+	*
+	* The column first because it is free, then the decoder. `textSource` is on
+	* every result so a caller can see which answered — and so the 3.1% that only
+	* the decoder can reach are visible rather than indistinguishable from empty.
+	*/
+	#body(row) {
+		const column = text(row.text);
+		if (column !== null) return {
+			text: column,
+			source: "column"
+		};
+		const blob = row.attributedBody;
+		if (blob instanceof Uint8Array && blob.length > 0) {
+			const decoded = decodeAttributedBody(blob);
+			if (decoded.ok && decoded.text.length > 0) return {
+				text: decoded.text,
+				source: "decoded"
+			};
+		}
+		return {
+			text: null,
+			source: "none"
+		};
+	}
+	#messageColumns() {
+		const m = this.caps.messageColumns;
+		return [
+			`m."guid" AS guid`,
+			`m."text" AS text`,
+			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"),
+			this.#col(m, "m", "is_read", "isRead"),
+			this.#col(m, "m", "is_sent", "isSent"),
+			this.#col(m, "m", "is_delivered", "isDelivered"),
+			this.#col(m, "m", "cache_has_attachments", "hasAttachments"),
+			this.#col(m, "m", "associated_message_type", "reactionType"),
+			this.#col(m, "m", "associated_message_guid", "reactionTarget"),
+			this.#col(m, "m", "thread_originator_guid", "threadOriginator"),
+			this.#col(m, "m", "item_type", "itemType"),
+			this.#date(m, "m", "date", "sentAt"),
+			this.#date(m, "m", "date_read", "readAt"),
+			this.#date(m, "m", "date_delivered", "deliveredAt"),
+			this.#date(m, "m", "date_edited", "editedAt"),
+			`h."id" AS handle`,
+			`c."guid" AS chatGuid`,
+			this.#col(this.caps.chatColumns, "c", "display_name", "chatName")
+		].join(",\n           ");
+	}
+	#joins() {
+		return `LEFT JOIN "handle" h ON h."ROWID" = m."handle_id"
+       LEFT JOIN "chat_message_join" cmj ON cmj."message_id" = m."ROWID"
+       LEFT JOIN "chat" c ON c."ROWID" = cmj."chat_id"`;
+	}
+	#toRow(r) {
+		const body = this.#body(r);
+		return {
+			guid: String(r.guid),
+			chatGuid: text(r.chatGuid),
+			chatName: text(r.chatName),
+			handle: text(r.handle),
+			service: text(r.service),
+			isFromMe: bool(r.isFromMe),
+			sentAt: num(r.sentAt),
+			readAt: num(r.readAt),
+			deliveredAt: num(r.deliveredAt),
+			editedAt: num(r.editedAt),
+			text: body.text,
+			textSource: body.source,
+			subject: text(r.subject),
+			isRead: bool(r.isRead),
+			isSent: bool(r.isSent),
+			isDelivered: bool(r.isDelivered),
+			hasAttachments: bool(r.hasAttachments),
+			reactionType: num(r.reactionType) || null,
+			reactionTarget: text(r.reactionTarget),
+			threadOriginator: text(r.threadOriginator),
+			itemType: num(r.itemType)
+		};
+	}
+	/**
+	* A window of messages, newest first.
+	*
+	* Reactions are excluded by default. They are rows in this table like any
+	* other, and 2,788 of them would otherwise appear as messages reading
+	* `Liked "see you at 8"` — which is not something anybody typed.
+	*/
+	range(q) {
+		const m = this.caps.messageColumns;
+		const where = [];
+		const params = [];
+		if (q.chatGuid) {
+			where.push(`c."guid" = ?`);
+			params.push(q.chatGuid);
+		}
+		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)`);
+		const sql = `
+      SELECT ${this.#messageColumns()}
+        FROM "message" m
+        ${this.#joins()}
+       ${where.length ? `WHERE ${where.join("\n         AND ")}` : ""}
+       ORDER BY m."date" DESC
+       LIMIT ${Math.max(1, Math.trunc(q.limit))}`;
+		return this.db.prepare(sql).all(...params).map((r) => this.#toRow(r));
+	}
+	/**
+	* Text search, in two passes — and the second one is the point.
+	*
+	* Pass 1 is `LIKE` on the column: measured at **16 ms over 97,416 rows** with
+	* 27 existing indexes, so there is no index-vs-scan tradeoff to litigate and
+	* no FTS table to build.
+	*
+	* Pass 2 covers what pass 1 structurally cannot. 3,051 messages have an empty
+	* `text` and content only in `attributedBody`, and no amount of SQL reaches
+	* inside a blob. Decoding them costs about **6 ms** — the decoder runs at
+	* 2 ms per thousand — so completeness here is nearly free, and a search that
+	* silently omitted one message in thirty-two would be the worst kind of wrong.
+	*/
+	search(query, limit, includeReactions = false) {
+		const m = this.caps.messageColumns;
+		const needle = `%${escapeLike(query)}%`;
+		const reactionFilter = !includeReactions && m.has("associated_message_type") ? `AND (m."associated_message_type" IS NULL OR m."associated_message_type" = 0)` : "";
+		const cap = Math.max(1, Math.trunc(limit));
+		const results = this.db.prepare(`SELECT ${this.#messageColumns()}
+           FROM "message" m
+           ${this.#joins()}
+          WHERE m."text" LIKE ? ESCAPE '\\' ${reactionFilter}
+          ORDER BY m."date" DESC
+          LIMIT ${cap}`).all(needle).map((r) => this.#toRow(r));
+		if (results.length >= cap || !m.has("attributedBody")) return results;
+		const blobOnly = this.db.prepare(`SELECT ${this.#messageColumns()}
+           FROM "message" m
+           ${this.#joins()}
+          WHERE (m."text" IS NULL OR m."text" = '')
+            AND m."attributedBody" IS NOT NULL ${reactionFilter}
+          ORDER BY m."date" DESC`).all();
+		const lowered = query.toLowerCase();
+		for (const raw of blobOnly) {
+			if (results.length >= cap) break;
+			const row = this.#toRow(raw);
+			if (row.text && row.text.toLowerCase().includes(lowered)) results.push(row);
+		}
+		return results.slice(0, cap);
+	}
+	byGuid(guid) {
+		const rows = this.db.prepare(`SELECT ${this.#messageColumns()}
+           FROM "message" m
+           ${this.#joins()}
+          WHERE m."guid" = ?
+          LIMIT 1`).all(guid);
+		return rows[0] ? this.#toRow(rows[0]) : null;
+	}
+	/** Tapbacks aimed at one message. */
+	reactionsFor(guid) {
+		if (!this.caps.hasReactions) return [];
+		return this.db.prepare(`SELECT m."associated_message_type" AS type, h."id" AS handle
+           FROM "message" m
+           LEFT JOIN "handle" h ON h."ROWID" = m."handle_id"
+          WHERE m."associated_message_guid" LIKE ? ESCAPE '\\'
+            AND m."associated_message_type" > 0
+          ORDER BY m."date" ASC`).all(`%${escapeLike(guid)}`).flatMap((r) => {
+			const type = num(r.type);
+			if (type === null) return [];
+			return [{
+				type,
+				label: reactionLabel(type),
+				handle: text(r.handle)
+			}];
+		});
+	}
+	/**
+	* The attachments on one message.
+	*
+	* `id` is `attachment.guid`, for the reason `ref.ts` gives at length about
+	* messages: the ROWID is faster and gets REUSED. Every "delete this
+	* conversation" frees a block of attachment ids for the next insert, so a
+	* caller that listed attachments in one turn and saved one two turns later
+	* would write out a different file, silently. The guid is `UNIQUE NOT NULL`
+	* in the shipped schema and is what Apple's own sync joins on.
+	*
+	* `path` is the raw `filename` column, reported so a caller can see WHERE the
+	* bytes are before asking for them — it is frequently `~`-prefixed, and it is
+	* empty for an attachment iCloud has offloaded.
+	*/
+	attachmentsFor(guid) {
+		if (!this.caps.hasAttachments) return [];
+		const a = this.caps.attachmentColumns;
+		return this.db.prepare(`SELECT ${this.#col(a, "a", "guid", "id")},
+                ${this.#col(a, "a", "filename", "path")},
+                ${this.#col(a, "a", "mime_type", "mimeType")},
+                ${this.#col(a, "a", "transfer_name", "transferName")},
+                ${this.#col(a, "a", "total_bytes", "bytes")},
+                ${this.#col(a, "a", "is_sticker", "isSticker")}
+           FROM "attachment" a
+           JOIN "message_attachment_join" maj ON maj."attachment_id" = a."ROWID"
+           JOIN "message" m ON m."ROWID" = maj."message_id"
+          WHERE m."guid" = ?`).all(guid).map((r) => ({
+			id: text(r.id),
+			path: text(r.path),
+			mimeType: text(r.mimeType),
+			transferName: text(r.transferName),
+			bytes: num(r.bytes),
+			isSticker: num(r.isSticker) === 1
+		}));
+	}
+	/** One attachment by its guid, wherever it hangs. Null when it is gone. */
+	attachmentById(id) {
+		if (!this.caps.hasAttachments) return null;
+		const a = this.caps.attachmentColumns;
+		if (!a.has("guid")) return null;
+		const row = this.db.prepare(`SELECT ${this.#col(a, "a", "guid", "id")},
+                ${this.#col(a, "a", "filename", "path")},
+                ${this.#col(a, "a", "mime_type", "mimeType")},
+                ${this.#col(a, "a", "transfer_name", "transferName")},
+                ${this.#col(a, "a", "total_bytes", "bytes")}
+           FROM "attachment" a WHERE a."guid" = ? LIMIT 1`).get(id);
+		if (!row) return null;
+		return {
+			id: text(row.id),
+			path: text(row.path),
+			mimeType: text(row.mimeType),
+			transferName: text(row.transferName),
+			bytes: num(row.bytes)
+		};
+	}
+	chats(limit) {
+		return this.#chats("", [], limit);
+	}
+	/** One chat, by the guid a ref carries. Null when it has been deleted. */
+	chatByGuid(guid) {
+		return this.#chats(`WHERE c."guid" = ?`, [guid], 1)[0] ?? null;
+	}
+	/**
+	* The chats that already exist with a set of handles, newest first.
+	*
+	* This is what makes a send addressable at all. Messages will not enumerate
+	* participants for a script, so the write lane cannot look a person up — but
+	* it can address a chat by guid, and the guid lives here. The read lane
+	* choosing the target for the write lane is the whole arrangement; see
+	* `client/jxa/core.ts`.
+	*
+	* Handles are matched as given. Suffix matching happens a layer up in
+	* `client/messages.ts`, where `packages/contacts`' measured `suffixKey` is
+	* available and the candidate list is the store's own 1,075 handles.
+	*/
+	chatsForHandles(handles, limit = 10) {
+		if (!handles.length) return [];
+		const marks = handles.map(() => "?").join(", ");
+		return this.#chats(`WHERE c."ROWID" IN (
+           SELECT chj."chat_id"
+             FROM "chat_handle_join" chj
+             JOIN "handle" h2 ON h2."ROWID" = chj."handle_id"
+            WHERE h2."id" IN (${marks}))`, [...handles], limit);
+	}
+	/**
+	* Outgoing messages in a set of chats since an instant — the send's receipt.
+	*
+	* `docs/messages.md` recorded that Apple Events returns no chat identifier, so
+	* a send "cannot report what it wrote by id". That is true of the write lane
+	* alone and false of the pair: the row Messages writes for an outgoing message
+	* is an ordinary row in this table, and a narrow window plus the target chat
+	* identifies it. Matching on text as well would be wrong — two identical
+	* messages a minute apart are a normal thing to send — so the caller passes a
+	* `sinceApple` taken immediately BEFORE the send and takes the oldest match.
+	*/
+	sentSince(chatGuids, sinceApple, limit = 10) {
+		const m = this.caps.messageColumns;
+		if (!chatGuids.length || !m.has("date")) return [];
+		const marks = chatGuids.map(() => "?").join(", ");
+		const fromMe = m.has("is_from_me") ? `AND m."is_from_me" = 1` : "";
+		return this.db.prepare(`SELECT ${this.#messageColumns()}
+           FROM "message" m
+           ${this.#joins()}
+          WHERE c."guid" IN (${marks})
+            AND ${appleSecondsSql("m.\"date\"")} >= ?
+            ${fromMe}
+          ORDER BY m."date" ASC
+          LIMIT ${Math.max(1, Math.trunc(limit))}`).all(...[...chatGuids, sinceApple]).map((r) => this.#toRow(r));
+	}
+	#chats(where, params, limit) {
+		const c = this.caps.chatColumns;
+		const rows = this.db.prepare(`SELECT c."ROWID" AS rowid,
+                c."guid" AS guid,
+                ${this.#col(c, "c", "chat_identifier", "identifier")},
+                ${this.#col(c, "c", "display_name", "displayName")},
+                ${this.#col(c, "c", "style")},
+                ${this.#col(c, "c", "service_name", "service")},
+                COUNT(cmj."message_id") AS messages,
+                ${appleSecondsSql("MAX(m.\"date\")")} AS lastMessageAt
+           FROM "chat" c
+           LEFT JOIN "chat_message_join" cmj ON cmj."chat_id" = c."ROWID"
+           LEFT JOIN "message" m ON m."ROWID" = cmj."message_id"
+          ${where}
+          GROUP BY c."ROWID"
+          ORDER BY MAX(m."date") DESC
+          LIMIT ${Math.max(1, Math.trunc(limit))}`).all(...params);
+		const participants = this.#participants(rows.map((r) => Number(r.rowid)));
+		return rows.map((r) => {
+			const style = num(r.style);
+			return {
+				guid: String(r.guid),
+				identifier: text(r.identifier),
+				displayName: text(r.displayName),
+				style,
+				isGroup: style === 43 || (participants.get(Number(r.rowid))?.length ?? 0) > 1,
+				service: text(r.service),
+				participants: participants.get(Number(r.rowid)) ?? [],
+				messages: Number(r.messages ?? 0),
+				lastMessageAt: num(r.lastMessageAt)
+			};
+		});
+	}
+	#participants(chatRowIds) {
+		const out = /* @__PURE__ */ new Map();
+		if (!chatRowIds.length) return out;
+		const marks = chatRowIds.map(() => "?").join(", ");
+		const rows = this.db.prepare(`SELECT chj."chat_id" AS chatId, h."id" AS handle
+           FROM "chat_handle_join" chj
+           JOIN "handle" h ON h."ROWID" = chj."handle_id"
+          WHERE chj."chat_id" IN (${marks})`).all(...chatRowIds);
+		for (const r of rows) {
+			const id = Number(r.chatId);
+			const handle = text(r.handle);
+			if (!handle) continue;
+			const bucket = out.get(id);
+			if (bucket) bucket.push(handle);
+			else out.set(id, [handle]);
+		}
+		return out;
+	}
+	/** Every distinct handle in the store, for a bulk resolve. */
+	handles() {
+		return this.db.prepare(`SELECT DISTINCT "id" AS id FROM "handle" WHERE "id" IS NOT NULL AND "id" <> ''`).all().flatMap((r) => {
+			const h = text(r.id);
+			return h ? [h] : [];
+		});
+	}
+	counts() {
+		const one = (sql) => {
+			try {
+				return Number(this.db.prepare(sql).get().c ?? 0);
+			} catch {
+				return 0;
+			}
+		};
+		return {
+			messages: one(`SELECT COUNT(*) AS c FROM "message"`),
+			chats: one(`SELECT COUNT(*) AS c FROM "chat"`),
+			handles: one(`SELECT COUNT(*) AS c FROM "handle"`),
+			attachments: this.caps.hasAttachments ? one(`SELECT COUNT(*) AS c FROM "attachment"`) : 0
+		};
+	}
+	close() {
+		try {
+			this.db.close();
+		} catch {}
+	}
+};
+const introspect = (db) => {
+	const messageColumns = new Set(columnsOf(db, "message"));
+	const chatColumns = new Set(columnsOf(db, "chat"));
+	const handleColumns = new Set(columnsOf(db, "handle"));
+	for (const t of REQUIRED) if ((t === "message" ? messageColumns : t === "chat" ? chatColumns : handleColumns).size === 0) throw new SchemaDriftError(`This Messages store has no ${t} table. It was probed on macOS ${PROBED_MACOS} with schema fingerprint ${PROBED_FINGERPRINT} (a PROBE fingerprint — compare it against another probe run, not against the one diagnostics reports); re-run \`pnpm probe:messages\` to see what changed.`);
+	const attachmentColumns = new Set(columnsOf(db, "attachment"));
+	return {
+		fingerprint: fingerprintSchema(db),
+		messageColumns,
+		chatColumns,
+		handleColumns,
+		attachmentColumns,
+		hasAttachments: attachmentColumns.size > 0 && columnsOf(db, "message_attachment_join").length > 0,
+		hasReactions: messageColumns.has("associated_message_type"),
+		hasThreads: messageColumns.has("thread_originator_guid"),
+		hasEdits: messageColumns.has("date_edited")
+	};
+};
+const openStore = (path, mode, logger) => {
+	if (!path) return null;
+	const { db, mode: used, validated } = openReadOnly(path, mode, {
+		label: "Messages store",
+		envVar: "APPLE_MESSAGES_INDEX_MODE",
+		validate: introspect,
+		fatal: (err) => err instanceof SchemaDriftError,
+		onFallback: () => logger?.debug?.("opened the Messages store with immutable=1, which skips the write-ahead log — recent messages may be missing until Messages checkpoints. The measured WAL was ~0.5 MB.")
+	});
+	return new MessagesStore(db, used, validated);
+};
+//#endregion
+//#region src/client/messages.ts
+var AppleMessagesClient = class {
+	#config;
+	#logger;
+	#home;
+	#located = null;
+	#store = null;
+	#storeTried = false;
+	#contacts;
+	#contactsTried;
+	#resolved = /* @__PURE__ */ new Map();
+	/**
+	* Built even when writes are off, and that costs nothing.
+	*
+	* `createOsascriptRunner` spawns no process until something calls it, and with
+	* `allowWrites` off nothing does — the send tool is never registered. So this
+	* server still sends no Apple Event and still asks for no Automation grant in
+	* its default configuration, which is the claim `surfaces.json` makes.
+	*/
+	#runner;
+	constructor(opts) {
+		this.#config = opts.config;
+		this.#logger = opts.logger;
+		this.#home = opts.home;
+		this.#contacts = opts.contacts ?? null;
+		this.#contactsTried = opts.contacts !== void 0;
+		this.#runner = opts.osascript ?? createOsascriptRunner({
+			surface: MESSAGES_SURFACE,
+			osascriptPath: opts.config.osascriptPath,
+			timeoutMs: opts.config.osascriptTimeoutMs,
+			...opts.logger ? { logger: opts.logger } : {}
+		});
+	}
+	get config() {
+		return this.#config;
+	}
+	located() {
+		this.#located ??= locateStore({
+			storePath: this.#config.storePath,
+			...this.#home ? { home: this.#home } : {}
+		});
+		return this.#located;
+	}
+	store() {
+		if (this.#storeTried) return this.#store;
+		this.#storeTried = true;
+		if (this.#config.indexMode === "off") return null;
+		const located = this.located();
+		if (!located.readable) return null;
+		const mode = this.#config.indexMode === "auto" ? "ro" : this.#config.indexMode;
+		this.#store = openStore(located.storePath, mode, this.#logger);
+		return this.#store;
+	}
+	/**
+	* Never `[]` when the store is missing.
+	*
+	* An empty list is a valid answer to "no messages match", and this surface has
+	* no second lane to produce one from. Callers get a reason instead — and on
+	* this surface the reason is load-bearing, because the fix is a permission.
+	*/
+	#require() {
+		const store = this.store();
+		if (store) return store;
+		if (this.#config.indexMode === "off") throw new IndexUnavailableError("The Messages index is disabled (APPLE_MESSAGES_INDEX_MODE=off). This surface has no Apple Events read lane at all, so nothing can be read until it is re-enabled.");
+		throw new MessagesUnavailableError(this.located().reason ?? "No readable Messages store was found.");
+	}
+	#contactsClient() {
+		if (this.#contactsTried) return this.#contacts;
+		this.#contactsTried = true;
+		if (!this.#config.resolveContacts) return null;
+		try {
+			this.#contacts = new AppleContactsClient({
+				config: loadConfig({}),
+				...this.#logger ? { logger: this.#logger } : {},
+				...this.#home ? { home: this.#home } : {}
+			});
+		} catch (err) {
+			this.#logger?.debug?.(`contacts resolver unavailable: ${String(err)}`);
+			this.#contacts = null;
+		}
+		return this.#contacts;
+	}
+	/**
+	* Resolve a batch, memoised for the life of the process.
+	*
+	* Batched because building the lookup walks every contact once (3 ms on the
+	* measured store) and every subsequent handle is a map hit. Memoised because a
+	* conversation renders the same correspondent hundreds of times.
+	*/
+	#resolve(handles) {
+		const wanted = [...new Set(handles.filter((h) => Boolean(h)))].filter((h) => !this.#resolved.has(h));
+		if (!wanted.length) return;
+		const contacts = this.#contactsClient();
+		if (!contacts) return;
+		try {
+			for (const r of contacts.resolve(wanted).results) this.#resolved.set(r.handle, r);
+		} catch (err) {
+			this.#logger?.debug?.(`resolve failed: ${String(err)}`);
+			this.#contacts = null;
+		}
+	}
+	#correspondent(handle) {
+		if (!handle) return {
+			handle: null,
+			name: null,
+			resolution: "unknown"
+		};
+		const hit = this.#resolved.get(handle);
+		if (!hit) return {
+			handle,
+			name: null,
+			resolution: this.#contacts ? "unknown" : "unavailable"
+		};
+		return {
+			handle,
+			name: hit.name,
+			resolution: hit.status
+		};
+	}
+	#render(rows) {
+		this.#resolve(rows.map((r) => r.handle));
+		return rows.map((r) => ({
+			ref: encodeMessageRef(r.guid),
+			chatRef: r.chatGuid ? encodeChatRef(r.chatGuid) : null,
+			chat: r.chatName,
+			from: r.isFromMe ? {
+				handle: null,
+				name: "me",
+				resolution: "self"
+			} : this.#correspondent(r.handle),
+			fromMe: r.isFromMe,
+			sentAt: renderInstant(r.sentAt),
+			editedAt: renderInstant(r.editedAt),
+			text: r.text,
+			textSource: r.textSource,
+			subject: r.subject,
+			service: r.service,
+			isRead: r.isRead,
+			hasAttachments: r.hasAttachments,
+			...r.threadOriginator ? { replyToRef: encodeMessageRef(r.threadOriginator) } : {},
+			...r.itemType ? { itemType: r.itemType } : {}
+		}));
+	}
+	listMessages(opts) {
+		return this.#render(this.#require().range({
+			...opts.chatRef ? { chatGuid: opts.chatRef } : {},
+			...opts.fromApple === void 0 ? {} : { fromApple: opts.fromApple },
+			...opts.toApple === void 0 ? {} : { toApple: opts.toApple },
+			...opts.includeReactions === void 0 ? {} : { includeReactions: opts.includeReactions },
+			limit: opts.limit ?? this.#config.maxResults
+		}));
+	}
+	searchMessages(query, limit) {
+		return this.#render(this.#require().search(query, limit ?? this.#config.maxResults));
+	}
+	getMessage(guid) {
+		const store = this.#require();
+		const row = store.byGuid(guid);
+		if (!row) return null;
+		const reactions = store.reactionsFor(guid);
+		this.#resolve(reactions.map((r) => r.handle));
+		const [rendered] = this.#render([row]);
+		return {
+			...rendered,
+			reactions: reactions.map((r) => ({
+				label: r.label,
+				from: this.#correspondent(r.handle)
+			})),
+			attachments: store.attachmentsFor(guid)
+		};
+	}
+	/**
+	* Copy one attachment out of the Messages store onto disk.
+	*
+	* ## Why this is a copy and not an extraction
+	*
+	* Mail's equivalent has to parse MIME out of an `.emlx` because the bytes are
+	* inside the message file. Messages does not work that way: `attachment` rows
+	* point at real files under `~/Library/Messages`, so the work here is finding
+	* the row, deciding the path is one we are willing to read, and copying.
+	*
+	* ## Two boundaries, not one
+	*
+	* The DESTINATION boundary is the same one Mail and Notes enforce:
+	* `attachmentDir` is a confinement, `directory` may only select inside it, and
+	* the leaf name is `basename`d because it comes from whoever sent the message.
+	*
+	* The SOURCE boundary is this surface's own. `filename` comes out of a
+	* database this server never writes, and it is a fully-qualified path: taken
+	* at face value it names any file the process can read. So it is required to
+	* resolve inside the Messages root before a single byte is read. That check
+	* has never fired on a real store and is not expected to — it is here so that
+	* the day the schema surprises us, the surprise is a refusal.
+	*/
+	async saveAttachment(attachmentId, opts = {}) {
+		const meta = this.#require().attachmentById(attachmentId);
+		if (!meta) throw new PreconditionError(`No attachment with id "${attachmentId}". Ids come from apple_messages_get_message and are the attachment's guid; the message may have been deleted since it was listed.`);
+		if (!meta.path) throw new PreconditionError("That attachment has no file path in the store, which normally means iCloud has offloaded it. Open the conversation in Messages to download it, then try again.");
+		const home = this.#home ?? homedir();
+		const expanded = meta.path.startsWith("~/") ? join(home, meta.path.slice(2)) : meta.path;
+		const source = resolve(expanded);
+		const root = resolve(this.located().messagesRoot);
+		if (source !== root && !source.startsWith(root + sep)) throw new PreconditionError(`Refusing to read ${source}: it is outside ${root}, and this tool only copies files Messages itself stores.`);
+		if (!existsSync(source) || !statSync(source).isFile()) throw new PreconditionError(`The store names ${source} but there is no file there. Messages prunes attachment bytes while keeping the row, so this is a normal state for an old conversation.`);
+		const dest = resolve(this.#config.attachmentDir);
+		const dir = opts.directory ? resolve(dest, opts.directory) : dest;
+		if (dir !== dest && !dir.startsWith(dest + sep)) throw new PreconditionError(`Refusing to write outside ${dest}. Set APPLE_MESSAGES_ATTACHMENT_DIR to change the destination.`);
+		const name = basename(meta.transferName ?? basename(source));
+		const target = resolve(join(dir, name));
+		if (target !== join(dir, name) || !target.startsWith(dir + sep)) throw new PreconditionError(`Refusing to write outside ${dir}.`);
+		if (existsSync(target) && !opts.overwrite) throw new PreconditionError(`${target} already exists; refusing to overwrite it.`);
+		const bytes = readFileSync(source);
+		mkdirSync(dir, { recursive: true });
+		writeFileSync(target, bytes, { mode: 384 });
+		return {
+			path: target,
+			bytes: bytes.length,
+			source,
+			mimeType: meta.mimeType
+		};
+	}
+	listChats(limit) {
+		const rows = this.#require().chats(limit ?? this.#config.maxResults);
+		this.#resolve(rows.flatMap((c) => c.participants));
+		return rows.map((c) => ({
+			ref: encodeChatRef(c.guid),
+			name: c.displayName ?? (c.participants.length === 1 && c.participants[0] ? this.#correspondent(c.participants[0]).name ?? c.participants[0] : null),
+			isGroup: c.isGroup,
+			service: c.service,
+			participants: c.participants.map((h) => this.#correspondent(h)),
+			messages: c.messages,
+			lastMessageAt: renderInstant(c.lastMessageAt)
+		}));
+	}
+	/**
+	* Pick the chat to address, using the store.
+	*
+	* Handles are matched the way `packages/contacts` measured them rather than by
+	* string equality: a caller who types `06 12 34 56 78` and a store that holds
+	* `+33612345678` are the same person, and `suffixKey`'s last-9 rule is what
+	* says so. The candidate set is the store's own handles — 1,075 on the
+	* measured machine — so this is a scan over a list that is already in memory.
+	*/
+	#chatFor(input) {
+		const store = this.store();
+		if (input.chatRef) {
+			const guid = decodeChatRef(input.chatRef);
+			const chat = store?.chatByGuid(guid) ?? null;
+			if (store && !chat) throw new ChatNotFoundError(input.chatRef);
+			return {
+				guid,
+				chat,
+				handle: chat?.participants[0] ?? null
+			};
+		}
+		const to = input.to?.trim();
+		if (!to) return {
+			guid: null,
+			chat: null,
+			handle: null
+		};
+		if (!store) return {
+			guid: null,
+			chat: null,
+			handle: to
+		};
+		const kind = handleKind(to);
+		const wantedSuffix = kind === "phone" ? suffixKey(to) : null;
+		const wantedEmail = kind === "email" ? emailKey(to) : null;
+		const candidates = store.handles().filter((h) => {
+			if (h === to) return true;
+			if (wantedEmail) return emailKey(h) === wantedEmail;
+			if (wantedSuffix) return suffixKey(h) === wantedSuffix;
+			return false;
+		});
+		if (!candidates.length) return {
+			guid: null,
+			chat: null,
+			handle: to
+		};
+		const direct = store.chatsForHandles(candidates, 25).find((c) => !c.isGroup) ?? null;
+		return {
+			guid: direct?.guid ?? null,
+			chat: direct,
+			handle: candidates[0] ?? to
+		};
+	}
+	/**
+	* 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
+	* re-resolve by scanning the store for a recent row on the target chat" — and
+	* this is the answer, because the alternative is a send that can report
+	* nothing at all. Apple Events hands back no identifier of any kind.
+	*
+	* Three things make the match safe rather than merely plausible:
+	*
+	*   1. `since` is taken BEFORE the send, so nothing earlier can match.
+	*   2. The window is scoped to the target chat.
+	*   3. Text is compared when it is available, which separates our row from one
+	*      the user sent from their phone in the same second. Only when it is not
+	*      available does the oldest row in the window win.
+	*
+	* A miss is `pending`, never an error: the send already happened, and iMessage
+	* writes its row asynchronously. Reporting a failure there would be the worst
+	* possible lie — it would invite a retry that sends the message twice.
+	*/
+	async #reconcile(guid, since, text) {
+		const deadline = Date.now() + this.#config.sendReconcileMs;
+		for (;;) {
+			this.#invalidate();
+			const store = this.store();
+			if (!store) return null;
+			const rows = store.sentSince([guid], since, 10);
+			const hit = rows.find((r) => r.text !== null && r.text === text) ?? rows[0];
+			if (hit) return this.#render([hit])[0] ?? null;
+			if (Date.now() >= deadline) return null;
+			await new Promise((resolve) => setTimeout(resolve, 250));
+		}
+	}
+	#invalidate() {
+		this.#store?.close();
+		this.#store = null;
+		this.#storeTried = false;
+	}
+	/**
+	* Send one message. A real one, to a real person, immediately.
+	*
+	* Everything difficult about this is in `client/jxa/core.ts`; what is left
+	* here is choosing the target from the file lane and reconciling afterwards.
+	*/
+	async sendMessage(input) {
+		const { guid, chat, handle } = this.#chatFor(input);
+		const since = toAppleSeconds(/* @__PURE__ */ new Date(Date.now() - 2e3));
+		let data;
+		try {
+			data = await withBusyRetry(() => this.#runner.run(SEND_MESSAGE, {
+				...guid ? { chatGuid: guid } : {},
+				...handle ? { handle } : {},
+				...input.service ? { service: input.service } : {},
+				text: input.text,
+				allowLaunch: true
+			}));
+		} catch (err) {
+			const details = err?.details;
+			const attempts = Array.isArray(details?.detail) ? details.detail : [];
+			const message = err instanceof Error ? err.message : String(err);
+			if (details?.code === "SEND_TARGET_NOT_FOUND") throw new SendTargetNotFoundError(input.chatRef ?? input.to ?? "", attempts);
+			if (details?.code === "SEND_FAILED") throw new SendFailedError(message, attempts);
+			throw err;
+		}
+		const message = guid ? await this.#reconcile(guid, since, input.text) : null;
+		if (handle) this.#resolve([handle]);
+		return {
+			sent: true,
+			strategy: typeof data.strategy === "string" ? data.strategy : "unknown",
+			targetKind: typeof data.targetKind === "string" ? data.targetKind : "unknown",
+			chatRef: guid ? encodeChatRef(guid) : null,
+			chat: chat?.displayName ?? null,
+			to: handle ? this.#correspondent(handle) : null,
+			launched: data.launched === true,
+			reconciliation: message ? "matched" : guid ? "pending" : "unavailable",
+			message,
+			...message ? {} : { note: guid ? "Messages accepted the send, but no matching row had appeared in the store yet. That is normal for a slow network — re-run apple_messages_list_messages on this chat rather than sending again." : "Messages accepted the send, but there was no existing chat to reconcile it against, so no ref can be reported for it. Read the chat back once it exists." }
+		};
+	}
+	/** Bounds for a range query, as apple-seconds. */
+	window(from, to) {
+		return {
+			...from ? { fromApple: toAppleSeconds(from) } : {},
+			...to ? { toApple: toAppleSeconds(to) } : {}
+		};
+	}
+	status() {
+		const store = this.store();
+		return {
+			located: this.located(),
+			store: {
+				opened: Boolean(store),
+				mode: store?.mode ?? null,
+				fingerprint: store?.caps.fingerprint ?? null
+			},
+			counts: store?.counts() ?? null,
+			contacts: {
+				enabled: this.#config.resolveContacts,
+				available: Boolean(this.#contactsClient()),
+				resolved: this.#resolved.size
+			}
+		};
+	}
+	close() {
+		this.#store?.close();
+		this.#store = null;
+		this.#storeTried = false;
+		this.#contacts?.close();
+		this.#resolved.clear();
+	}
+};
+//#endregion
+//#region src/config.ts
+/**
+* Configuration is environment-only — this server holds no secret at all, its
+* access is the macOS permission the user granted.
+*
+* `allowWrites` is inherited from `BaseConfigSchema` and, since 1.2.0, means
+* something here: it gates the one mutating tool, `send_message`. With it off
+* this server registers no write tool and therefore sends no Apple Event at all,
+* which is what keeps its "no Automation grant" claim true by default.
+*
+* `docs/messages.md` recorded why sending went unprobed for so long — "probing
+* it would mean sending a real message to a real person" — and left the id
+* bridge open, because Apple Events returns no chat identifier to reconcile
+* against. `sendReconcileMs` is that decision made: the file lane finds the row
+* instead.
+*/
+const ConfigSchema = BaseConfigSchema.extend({
+	/** Explicit store path. Bypasses discovery — for tests and forensic copies. */
+	storePath: z.string().optional(),
+	indexMode: z.enum([
+		"auto",
+		"ro",
+		"immutable",
+		"off"
+	]).default("auto"),
+	/**
+	* Look names up in Contacts.
+	*
+	* On by default: without it this server answers "+15551234567 said …", which
+	* is why `packages/contacts` was built. Off is for a machine where the
+	* Contacts permission has not been granted and the prompt is unwelcome — the
+	* resolver degrades to raw handles either way, so this only decides whether it
+	* is attempted.
+	*/
+	resolveContacts: z.boolean().default(true),
+	/**
+	* The only directory `save_attachment` may write into.
+	*
+	* A boundary rather than a default: the tool's `directory` argument selects a
+	* subdirectory of this and cannot escape it. Saving is write-gated for the
+	* same reason it is in Mail and Notes — it puts a file on the user's disk,
+	* even though it changes nothing in Messages.
+	*/
+	attachmentDir: z.string().default(join(homedir(), "Downloads")),
+	/** Window for a range query that names only a start. */
+	defaultRangeDays: z.number().int().min(1).max(3660).default(30),
+	/**
+	* How long to wait for a sent message to appear in the store.
+	*
+	* Messages writes the outgoing row asynchronously, so a send that returns
+	* instantly has usually not been written yet. Five seconds is generous for a
+	* local write and short enough that a tool call does not hang on a bad
+	* network; a miss is reported as `pending`, never as a failure. Zero means one
+	* immediate check and no polling, which is what the test suite uses.
+	*/
+	sendReconcileMs: z.number().int().min(0).max(6e4).default(5e3)
+}).strict();
+const loadConfig$1 = (env = process.env) => parseConfig(ConfigSchema, {
+	allowWrites: parseBool(env.APPLE_MESSAGES_ALLOW_WRITES),
+	exposePrompts: parseBool(env.APPLE_MESSAGES_EXPOSE_PROMPTS),
+	debug: parseBool(env.APPLE_MESSAGES_DEBUG),
+	storePath: trimmed(env.APPLE_MESSAGES_STORE),
+	indexMode: trimmed(env.APPLE_MESSAGES_INDEX_MODE),
+	resolveContacts: parseBool(env.APPLE_MESSAGES_RESOLVE_CONTACTS),
+	attachmentDir: trimmed(env.APPLE_MESSAGES_ATTACHMENT_DIR),
+	defaultRangeDays: parseIntOpt(env.APPLE_MESSAGES_DEFAULT_RANGE_DAYS),
+	sendReconcileMs: parseIntOpt(env.APPLE_MESSAGES_SEND_RECONCILE_MS),
+	osascriptPath: trimmed(env.APPLE_MESSAGES_OSASCRIPT_PATH),
+	osascriptTimeoutMs: parseIntOpt(env.APPLE_MESSAGES_OSASCRIPT_TIMEOUT_MS),
+	maxResults: parseIntOpt(env.APPLE_MESSAGES_MAX_RESULTS)
+});
+//#endregion
+//#region src/guide.ts
+/**
+* The Messages operating manual, served as `cupertino://messages/guide` and
+* embedded ahead of every Messages prompt. Static by design — see the note in
+* the Mail guide.
+*/
+const MESSAGES_GUIDE = `# Apple Messages — how to drive this server
+
+## Refs are opaque
+
+Chats come back as \`mc1:<guid>\`, messages as \`m1:<guid>\`. Pass them back
+verbatim; never construct one.
+
+## Full Disk Access is mandatory here, unlike every other surface
+
+There is no Apple Events read lane to fall back on. Measured: Messages answers
+"Application isn't running" even while it is running, because it is a windowless
+background process that declines to wake for a script. Without the grant this
+server can do **nothing** on the read side — that is a permission problem, not
+an empty message history.
+
+## Which tool, under which constraint
+
+- **\`apple_messages_list_chats\`** first, when you need to know which
+  conversation you are looking at.
+- **\`apple_messages_list_messages\`** reads one conversation in order.
+- **\`apple_messages_search_messages\`** searches across them.
+- **\`apple_messages_get_message\`** returns one message with its tapbacks and
+  attachments.
+
+## Handles are not names
+
+A chat identifies people by phone number or email address. Names come from
+Contacts, which has its own separate permission, so \`unknown\` is a normal
+outcome — about one in six of even the busiest correspondents has no card. When
+diagnostics reports \`contacts.available: false\`, **nobody looked at all** and
+every handle is raw. Do not present a raw handle as though the person is
+unidentified when the truth is that lookup was never possible.
+
+## Two things that look like missing messages and are not
+
+**Recent messages are stored as blobs.** Messages stopped writing the plain
+\`text\` column between late February and late March 2026; everything since lives
+only as an archived blob, which this server decodes. \`textSource\` on each result
+says which lane answered. A reader without the decoder would report that the
+conversation stopped in February — if you ever see history that appears to end
+there, that is this, not silence.
+
+**Tapbacks are rows in the message table.** They are filtered out of
+conversations and reported on the message they target. A "liked" is not a reply
+and should not be summarised as one.
+
+## Sending
+
+\`apple_messages_send_message\` exists only when writes are enabled, and it is the
+**only** thing this server can change — the dictionary has no edit, delete,
+mark-as-read or reaction command.
+
+Sending is real and immediate. There is no draft state, no undo, and no
+confirmation step after the call. Confirm the recipient handle with the user
+before sending, exactly as it will be used.
+
+Messages hands back no identifier for what it sent, so the sent row is found by
+re-reading the store. \`reconciliation: "pending"\` means it has not appeared yet.
+That is **not a failure and must not be retried** — retrying sends the message
+twice.
+`;
+//#endregion
+//#region src/prompts.ts
+const CTX = {
+	surface: "messages",
+	guide: MESSAGES_GUIDE
+};
+/**
+* Messages' workflow prompts.
+*
+* The send prompt carries the only genuinely irreversible action in this
+* bundle. Everywhere else a mistake leaves a draft, an extra reminder or a
+* wrong-looking event; here it puts words in someone's pocket under the user's
+* name, with no undo and no draft state to catch it.
+*/
+const registerPrompts = (server, allowWrites) => {
+	registerWorkflowPrompt(server, CTX, {
+		name: "apple_messages_catch_up",
+		title: "Catch up on a conversation",
+		description: "Read back what has been said in a chat and what is waiting on a reply, with handles resolved to names where that is actually possible. Read-only.",
+		argsSchema: {
+			chat: promptArg("Who or which chat — a name, a handle, or a chat ref. Omit for recent chats."),
+			since: promptArg("How far back, e.g. \"yesterday\", \"last week\". Defaults to recent history.")
+		},
+		build: ({ chat, since }) => `Catch me up on ${chat ? `the conversation with ${chat}` : "my recent messages"}${since ? `, covering ${since}` : ""}.
+
+1. \`apple_messages_list_chats\` to find ${chat ? "the right conversation. If several match, ask which rather than picking." : "what has been active."}
+2. \`apple_messages_list_messages\` over that chat${since ? " with a date bound" : ""}.
+3. Summarise what was actually said and, most importantly, **what is waiting on
+   me** — a question asked and not answered is the thing worth surfacing.
+4. Where a handle has no name, say so and show the handle raw. Do not guess who
+   it is from context. If \`contacts.available\` is false in diagnostics, say that
+   names could not be looked up at all — that is different from these people
+   being unknown.
+
+Ignore tapbacks as messages; they are reactions on the message they target and
+a "liked" is not a reply. If the history appears to stop in early 2026, that is
+the blob-storage change described in the guide, not the end of the conversation
+— check \`textSource\` before reporting a gap.`
+	});
+	if (!allowWrites) return;
+	registerWorkflowPrompt(server, CTX, {
+		name: "apple_messages_send",
+		title: "Send a message",
+		description: "Compose and send an iMessage or SMS. Requires writes. Sending is immediate and cannot be undone — this prompt confirms the recipient before anything goes out.",
+		argsSchema: {
+			to: requiredPromptArg("Who to send to — a name, phone number or email address."),
+			message: promptArg("What to say, or the gist of it. Omit to be asked.")
+		},
+		build: ({ to, message }) => `Send a message to ${to}.${message ? `\n\nWhat it should say: ${message}` : ""}
+
+1. Work out the exact handle. \`apple_messages_list_chats\` to find an existing
+   conversation with this person — an established chat is better evidence of the
+   right handle than an address book match, because it is the one they actually
+   reply on.
+2. Read the last few messages in that chat. It tells you which language they
+   write in, how formal they are, and whether something is already pending.
+3. **Show the user the exact handle and the exact text, and wait for them to
+   confirm.** There is no draft state here and no undo: the call sends. A
+   message to the wrong handle cannot be recalled, and it is sent under the
+   user's name.
+4. On confirmation, \`apple_messages_send_message\`.
+5. If the result says \`reconciliation: "pending"\`, **the message was sent.**
+   Messages returns no identifier, so the sent row is found by re-reading the
+   store and has not appeared yet. Do not retry — retrying sends it twice. Say
+   it went out and that confirmation is lagging.`
+	});
+};
+//#endregion
+//#region src/tools/util.ts
+const chatRefArg = z.string().optional().describe("An opaque chat ref from apple_messages_list_chats (looks like \"mc1:<guid>\"). Do not construct one by hand.");
+const messageRefArg = z.string().min(1).describe("An opaque message ref from a list or search result (looks like \"m1:<guid>\"). Do not construct one by hand.");
+const fromArg = z.string().optional().describe("Start of the window, ISO-8601 — \"2026-08-01\" or \"2026-08-01T09:00\".");
+const toArg = z.string().optional().describe("End of the window, ISO-8601. Defaults to now.");
+const includeReactionsArg = z.boolean().optional().describe("Include tapbacks as if they were messages. Off by default, and you almost never want it on: a tapback renders as `Liked \"see you at 8\"`, which nobody typed. Use apple_messages_get_message to see the reactions on a specific message instead.");
+//#endregion
+//#region src/tools/diagnostics.ts
+/**
+* Build the report.
+*
+* Split out of the tool registration so the `cupertino://messages/diagnostics`
+* resource can serve the same bytes. Two renderings of one probe: duplicated,
+* the resource and the tool would drift, and the disagreement would surface as
+* "the diagnostics lied" — the one thing this file must never do.
+*/
+const buildDiagnostics = async (client) => {
+	const status = client.status();
+	const writes = client.config.allowWrites;
+	return {
+		server: {
+			name: BUILD_INFO.name,
+			version: BUILD_INFO.version
+		},
+		settings: { exposePrompts: client.config.exposePrompts },
+		lane: {
+			reads: "file lane (read-only SQLite)",
+			writes: writes ? "apple_messages_send_message, over Apple Events. The only mutating command the Messages dictionary offers." : "off — APPLE_MESSAGES_ALLOW_WRITES is not set, so the send tool is not registered and this server sends no Apple Event at all.",
+			appleEvents: "no read path exists, and never will. Measured: every read attempt fails, and Messages answers \"Application isn't running\" even while it is running, because it is a windowless background process that declines to wake for a script. Sending is the one thing that works."
+		},
+		store: {
+			path: status.located.storePath,
+			exists: status.located.exists,
+			readable: status.located.readable,
+			opened: status.store.opened,
+			mode: status.store.mode,
+			fingerprint: status.store.fingerprint,
+			counts: status.counts,
+			reason: status.located.reason
+		},
+		contacts: status.contacts,
+		caveats: [
+			"Full Disk Access is MANDATORY here, unlike every other surface in this bundle. There is no Apple Events read lane to fall back to, so without the grant this server can do nothing at all.",
+			"Messages stopped writing the plain `text` column between late February and late March 2026: every message since is stored only as an archived blob, which is decoded here. `textSource` on each result says which lane answered. Across all history the blob-only share is about 3%, but for anything recent it is ~100%, so a reader without the decoder would report that the conversation stopped in February.",
+			"Names come from Contacts, which has its own separate permission. `unknown` is a normal outcome and not an error — about one in six of even the busiest correspondents has no contact card. When `contacts.available` is false, nobody looked at all and every handle is raw.",
+			"Tapbacks are rows in the message table. They are filtered out of conversations by default and reported on the message they target instead.",
+			writes ? "Sending is real and immediate, and it is the ONLY thing this server can change — the dictionary has no edit, delete, mark-as-read or reaction command. Messages hands back no identifier for what it sent, so the sent row is found by re-reading the store; `reconciliation: \"pending\"` means it has not appeared yet, which is not a failure and must not be retried." : "This server cannot send: APPLE_MESSAGES_ALLOW_WRITES is off. With it on, one tool appears — apple_messages_send_message — and it is the only mutating command the Messages dictionary offers."
+		]
+	};
+};
+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: {},
+		annotations: { readOnlyHint: true }
+	}, async () => wrap(() => buildDiagnostics(client)));
+};
+//#endregion
+//#region src/tools/actions.ts
+const registerActionTools = (server, client) => {
+	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. 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.",
+		inputSchema: {
+			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).describe("Exactly what to send. Sent verbatim."),
+			service: z.enum([
+				"imessage",
+				"sms",
+				"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,
+			idempotentHint: false
+		}
+	}, async ({ chatRef, to, text, service }) => wrap(async () => {
+		if (Boolean(chatRef) === Boolean(to)) throw new PreconditionError("Give exactly one of chatRef or to. chatRef targets an existing conversation and is the reliable form; to addresses a phone number or email directly.");
+		return client.sendMessage({
+			...chatRef ? { chatRef } : {},
+			...to ? { to } : {},
+			...service ? { service } : {},
+			text
+		});
+	}));
+};
+//#endregion
+//#region src/tools/attachments.ts
+/**
+* Saving an attachment out of a conversation.
+*
+* ## Why this is not in `actions.ts`
+*
+* That file's argument is that Messages' scripting dictionary has exactly one
+* usable verb, so this server has exactly one mutating tool — and that with
+* writes off it sends no Apple Event at all. Both remain true with this tool
+* registered: it opens a file and writes a file, and never speaks to
+* Messages.app. Filing it next to `send` would quietly weaken a claim
+* `diagnostics` makes about what the write gate buys.
+*
+* ## Why it is behind the write gate anyway
+*
+* It puts a file on the user's disk. Mail and Notes made the same call for the
+* same reason, and the three should not disagree about it: a user who has not
+* turned writes on has not agreed to this server creating files.
+*/
+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: {
+			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,
+			idempotentHint: false
+		}
+	}, async ({ attachmentId, directory, overwrite }) => wrap(async () => client.saveAttachment(attachmentId, {
+		...directory ? { directory } : {},
+		...overwrite ? { overwrite } : {}
+	})));
+};
+//#endregion
+//#region src/tools/chats.ts
+/**
+* NOTE ON `async` BELOW: core's `wrap` is typed `() => Promise<T>` because most
+* surfaces reach Apple Events. Messages reads synchronous SQLite and never
+* leaves the process, so the thunks are marked async here rather than widening a
+* shared signature for every surface to accommodate one.
+*/
+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 },
+		annotations: { readOnlyHint: true }
+	}, async ({ limit }) => wrap(async () => client.listChats(limit)));
+};
+//#endregion
+//#region src/tools/messages.ts
+/** ISO-8601 in, or a clear refusal. No relative grammar on this surface yet. */
+const parseBound = (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;
+};
+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: {
+			chatRef: chatRefArg,
+			from: fromArg,
+			to: toArg,
+			includeReactions: includeReactionsArg,
+			limit: limitArg
+		},
+		annotations: { readOnlyHint: true }
+	}, async ({ chatRef, from, to, includeReactions, limit }) => wrap(async () => {
+		const window = client.window(parseBound(from, "from"), parseBound(to, "to"));
+		return client.listMessages({
+			...chatRef ? { chatRef: decodeChatRef(chatRef) } : {},
+			...window,
+			...includeReactions === void 0 ? {} : { includeReactions },
+			...limit === void 0 ? {} : { limit }
+		});
+	}));
+	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: {
+			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 },
+		annotations: { readOnlyHint: true }
+	}, async ({ ref }) => wrapResult(async () => {
+		const message = client.getMessage(decodeMessageRef(ref));
+		if (!message) return fail(`No message for ref "${ref}". It was probably deleted since the search ran. Re-run the search to get a current ref.`);
+		return ok(message);
+	}));
+};
+//#endregion
+//#region src/tools/index.ts
+/**
+* Register the Apple Messages tools.
+*
+* Five 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`.
+*
+* The registered set does NOT vary with whether the store is readable. That is a
+* runtime condition, and MCP clients cache the tool list.
+*/
+const registerTools = (server, client, ctx) => {
+	registerDiagnosticsTools(server, client);
+	registerChatTools(server, client);
+	registerMessageTools(server, client);
+	if (!ctx.allowWrites) return;
+	registerActionTools(server, client);
+	registerAttachmentTools(server, client);
+};
+//#endregion
+//#region src/server.ts
+const SERVER_NAME = BUILD_INFO.name;
+const SERVER_VERSION = BUILD_INFO.version;
+/**
+* Build the server. Side-effect free: it opens no database and reads no file,
+* so a test can construct it freely and every external dependency arrives
+* through an option.
+*/
+const createServer = (opts) => {
+	const { config } = opts;
+	const server = new McpServer({
+		name: SERVER_NAME,
+		version: SERVER_VERSION
+	});
+	const client = new AppleMessagesClient({
+		config,
+		...opts.logger ? { logger: opts.logger } : {},
+		...opts.osascript ? { osascript: opts.osascript } : {},
+		...opts.home ? { home: opts.home } : {},
+		...opts.contacts === void 0 ? {} : { contacts: opts.contacts }
+	});
+	registerTools(server, client, { allowWrites: config.allowWrites });
+	if (config.exposePrompts) {
+		registerPrompts(server, config.allowWrites);
+		registerSurfaceResources(server, {
+			surface: "messages",
+			displayName: "Messages",
+			guide: MESSAGES_GUIDE,
+			diagnostics: () => buildDiagnostics(client)
+		});
+	}
+	return {
+		server,
+		client
+	};
+};
+//#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-DH4U3LBX.js.map