@mgcrea/mcp-apple-messages 1.3.0

package/dist/index.d.ts

@@ -0,0 +1,806 @@
+import { AppleAutomationError, AppleAutomationError as AppleMessagesError, BuildInfo, CORE_DATA_EPOCH_OFFSET, IndexUnavailableError, Logger, OsascriptRunner, ReadOnlyMode, SchemaDriftError, StoreFacts, SurfaceContext } from "@mgcrea/mcp-apple-core";
+import { AppleContactsClient } from "@mgcrea/mcp-apple-contacts";
+import { z } from "zod";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { DatabaseSync } from "node:sqlite";
+//#region src/build-info.d.ts
+declare const BUILD_INFO: BuildInfo;
+//#endregion
+//#region src/config.d.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.
+ */
+declare const ConfigSchema: z.ZodObject<{
+  allowWrites: z.ZodDefault<z.ZodBoolean>;
+  exposePrompts: z.ZodDefault<z.ZodBoolean>;
+  debug: z.ZodDefault<z.ZodBoolean>;
+  osascriptPath: z.ZodDefault<z.ZodString>;
+  osascriptTimeoutMs: z.ZodDefault<z.ZodNumber>;
+  maxResults: z.ZodDefault<z.ZodNumber>;
+  storePath: z.ZodOptional<z.ZodString>;
+  indexMode: z.ZodDefault<z.ZodEnum<{
+    auto: "auto";
+    immutable: "immutable";
+    off: "off";
+    ro: "ro";
+  }>>;
+  resolveContacts: z.ZodDefault<z.ZodBoolean>;
+  attachmentDir: z.ZodDefault<z.ZodString>;
+  defaultRangeDays: z.ZodDefault<z.ZodNumber>;
+  sendReconcileMs: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strict>;
+type Config = z.infer<typeof ConfigSchema>;
+declare const loadConfig: (env?: NodeJS.ProcessEnv) => Config;
+//#endregion
+//#region src/client/locate.d.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.
+ */
+declare const STORE_RELATIVE: string;
+/** Attachment bytes live here, referenced by `attachment.filename`. */
+declare const ATTACHMENTS_RELATIVE: string;
+type LocateResult = StoreFacts & {
+  storePath: string;
+  attachmentsPath: string;
+  /** Nothing outside this is copied out, whatever the store says. */
+  messagesRoot: string;
+  reason: string | null;
+};
+declare const defaultStorePath: (home?: string) => string;
+declare const locateStore: (opts?: {
+  storePath?: string | undefined;
+  home?: string;
+}) => LocateResult;
+//#endregion
+//#region src/client/store.d.ts
+declare const reactionLabel: (type: number) => string;
+type StoreCapabilities = {
+  fingerprint: string;
+  messageColumns: Set<string>;
+  chatColumns: Set<string>;
+  handleColumns: Set<string>;
+  attachmentColumns: Set<string>;
+  hasAttachments: boolean;
+  hasReactions: boolean;
+  hasThreads: boolean;
+  hasEdits: boolean;
+};
+type MessageRow = {
+  guid: string;
+  chatGuid: string | null;
+  chatName: string | null;
+  handle: string | null;
+  service: string | null;
+  isFromMe: boolean;
+  /** Apple-seconds. Render with `renderInstant`. */
+  sentAt: number | null;
+  readAt: number | null;
+  deliveredAt: number | null;
+  editedAt: number | null;
+  text: string | null;
+  /** Which lane answered — the column, or the decoder. */
+  textSource: "column" | "decoded" | "none";
+  subject: string | null;
+  isRead: boolean;
+  isSent: boolean;
+  isDelivered: boolean;
+  hasAttachments: boolean;
+  /** Set when this row is a tapback on another message rather than a message. */
+  reactionType: number | null;
+  reactionTarget: string | null;
+  /** Set when this message is a reply in a thread. */
+  threadOriginator: string | null;
+  /** Non-zero for a group event — someone joined, left, or renamed the chat. */
+  itemType: number | null;
+};
+type ChatRow = {
+  guid: string;
+  identifier: string | null;
+  displayName: string | null;
+  /** 43 is a group chat, 45 is one-to-one. Reported raw beside the boolean. */
+  style: number | null;
+  isGroup: boolean;
+  service: string | null;
+  participants: string[];
+  messages: number;
+  lastMessageAt: number | null;
+};
+type RangeQuery = {
+  chatGuid?: string | undefined;
+  fromApple?: number | undefined;
+  toApple?: number | undefined;
+  includeReactions?: boolean | undefined;
+  limit: number;
+};
+declare class MessagesStore {
+  #private;
+  readonly db: DatabaseSync;
+  readonly mode: string;
+  readonly caps: StoreCapabilities;
+  constructor(db: DatabaseSync, mode: string, caps: StoreCapabilities);
+  /**
+   * 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: RangeQuery): MessageRow[];
+  /**
+   * 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: string, limit: number, includeReactions?: boolean): MessageRow[];
+  byGuid(guid: string): MessageRow | null;
+  /** Tapbacks aimed at one message. */
+  reactionsFor(guid: string): {
+    type: number;
+    label: string;
+    handle: string | null;
+  }[];
+  /**
+   * 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: string): {
+    id: string | null;
+    path: string | null;
+    mimeType: string | null;
+    transferName: string | null;
+    bytes: number | null;
+    isSticker: boolean;
+  }[];
+  /** One attachment by its guid, wherever it hangs. Null when it is gone. */
+  attachmentById(id: string): {
+    id: string | null;
+    path: string | null;
+    mimeType: string | null;
+    transferName: string | null;
+    bytes: number | null;
+  } | null;
+  chats(limit: number): ChatRow[];
+  /** One chat, by the guid a ref carries. Null when it has been deleted. */
+  chatByGuid(guid: string): ChatRow | 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: readonly string[], limit?: number): ChatRow[];
+  /**
+   * 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: readonly string[], sinceApple: number, limit?: number): MessageRow[];
+  /** Every distinct handle in the store, for a bulk resolve. */
+  handles(): string[];
+  counts(): {
+    messages: number;
+    chats: number;
+    handles: number;
+    attachments: number;
+  };
+  close(): void;
+}
+declare const introspect: (db: DatabaseSync) => StoreCapabilities;
+declare const openStore: (path: string | null, mode: ReadOnlyMode, logger?: Logger) => MessagesStore | null;
+//#endregion
+//#region src/client/messages.d.ts
+/**
+ * Messages' one lane, plus the resolver.
+ *
+ * ## Why this depends on another surface
+ *
+ * `chat.db` records a correspondent as `+15551234567` and nothing else, so a
+ * server built on it alone answers *"+15551234567 said …"* — complete, and
+ * useless. `packages/contacts` exists because of that, and this is the consumer
+ * it was built for. It is a workspace import rather than an MCP call: reaching a
+ * function in the same repo through a protocol would be absurd.
+ *
+ * `docs/contacts.md` measured what to expect, and the numbers set the contract:
+ *
+ * | denominator                   | resolved |
+ * | ----------------------------- | -------- |
+ * | every handle ever seen        | 27.6%    |
+ * | messages in the last year     | 97.6%    |
+ * | the 25 busiest correspondents | 84%      |
+ *
+ * So **`unknown` is a normal outcome, not an error.** About one in six of even
+ * the busiest correspondents does not resolve, and a caller that treats that as
+ * a failure will be wrong several times on any real inbox. Every rendered
+ * correspondent therefore carries both the resolved name and the raw handle.
+ *
+ * ## Degrading
+ *
+ * If Contacts cannot be read — its own TCC grant, separate from Full Disk
+ * Access, and one the user may simply not have answered — resolution is skipped
+ * and handles are returned raw. That is a capability downgrade, reported through
+ * `diagnostics`, never a throw: a Messages server with no names is still a
+ * Messages server.
+ */
+type CreateClientOptions = {
+  config: Config;
+  logger?: Logger;
+  /** Injected by tests. */
+  home?: string;
+  /** Injected by tests, so no test reaches the developer's real address book. */
+  contacts?: AppleContactsClient | null;
+  /** Injected by tests, so no test sends a real message to a real person. */
+  osascript?: OsascriptRunner;
+};
+/**
+ * What a send actually knows, which is less than a caller might assume.
+ *
+ * `sent` means Messages accepted the command without throwing. `delivered` is
+ * not a field here at all, because nothing in either lane reports it at send
+ * time. What closes the gap is `message`: the row the file lane found afterwards
+ * — a real ref, usable with `apple_messages_get_message` like any other.
+ */
+type SendResult = {
+  sent: true;
+  /** Which rung of the ladder in `client/jxa/core.ts` answered. */
+  strategy: string;
+  targetKind: string;
+  /** The chat the file lane chose, when it could choose one. */
+  chatRef: string | null;
+  chat: string | null;
+  to: Correspondent | null;
+  /** Whether Messages had to be launched. A launch is visible to the user. */
+  launched: boolean;
+  /** `matched` | `pending` | `unavailable` — see `#reconcile`. */
+  reconciliation: string;
+  message: RenderedMessage | null;
+  note?: string;
+};
+type Correspondent = {
+  /** Always present. The raw `handle.id` from the store. */
+  handle: string | null;
+  /** Null when unresolved, which is normal — see above. */
+  name: string | null;
+  /** `resolved` | `unknown` | `ambiguous` | `shortcode` | `unavailable`. */
+  resolution: string;
+};
+type RenderedMessage = {
+  ref: string;
+  chatRef: string | null;
+  chat: string | null;
+  from: Correspondent;
+  fromMe: boolean;
+  sentAt: string | null;
+  editedAt: string | null;
+  text: string | null;
+  /** `column` | `decoded` | `none` — which lane produced the text. */
+  textSource: string;
+  subject: string | null;
+  service: string | null;
+  isRead: boolean;
+  hasAttachments: boolean;
+  /** Present only when this row is a reply. */
+  replyToRef?: string;
+  /** Present only when this row is a group event rather than a message. */
+  itemType?: number;
+};
+type RenderedChat = {
+  ref: string;
+  name: string | null;
+  isGroup: boolean;
+  service: string | null;
+  participants: Correspondent[];
+  messages: number;
+  lastMessageAt: string | null;
+};
+declare class AppleMessagesClient {
+  #private;
+  constructor(opts: CreateClientOptions);
+  get config(): Config;
+  located(): LocateResult;
+  store(): MessagesStore | null;
+  listMessages(opts: {
+    chatRef?: string | undefined;
+    fromApple?: number | undefined;
+    toApple?: number | undefined;
+    includeReactions?: boolean | undefined;
+    limit?: number | undefined;
+  }): RenderedMessage[];
+  searchMessages(query: string, limit?: number): RenderedMessage[];
+  getMessage(guid: string): (RenderedMessage & {
+    reactions: {
+      label: string;
+      from: Correspondent;
+    }[];
+    attachments: ReturnType<MessagesStore["attachmentsFor"]>;
+  }) | null;
+  /**
+   * 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.
+   */
+  saveAttachment(attachmentId: string, opts?: {
+    directory?: string | undefined;
+    overwrite?: boolean;
+  }): Promise<{
+    path: string;
+    bytes: number;
+    source: string;
+    mimeType: string | null;
+  }>;
+  listChats(limit?: number): RenderedChat[];
+  /**
+   * 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.
+   */
+  sendMessage(input: {
+    chatRef?: string | undefined;
+    to?: string | undefined;
+    text: string;
+    service?: string | undefined;
+  }): Promise<SendResult>;
+  /** Bounds for a range query, as apple-seconds. */
+  window(from?: Date, to?: Date): {
+    fromApple?: number;
+    toApple?: number;
+  };
+  status(): {
+    located: LocateResult;
+    store: {
+      opened: boolean;
+      mode: string | null;
+      fingerprint: string | null;
+    };
+    counts: ReturnType<MessagesStore["counts"]> | null;
+    contacts: {
+      enabled: boolean;
+      available: boolean;
+      resolved: number;
+    };
+  };
+  close(): void;
+}
+//#endregion
+//#region src/client/dates.d.ts
+/**
+ * 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.
+ */
+declare const appleSecondsSql: (column: string) => string;
+/** Apple-seconds to a JS Date. Null in, null out. */
+declare const fromAppleSeconds: (value: number | null) => Date | null;
+/** A JS Date to apple-seconds, for range bounds. */
+declare const toAppleSeconds: (date: Date) => number;
+/** ISO-8601, or null. What every date field on a result carries. */
+declare const renderInstant: (value: number | null) => string | null;
+//#endregion
+//#region src/client/errors.d.ts
+declare const MESSAGES_SURFACE: SurfaceContext;
+/**
+ * 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`.
+ */
+declare const MESSAGES_BUNDLE_ID = "com.apple.MobileSMS";
+/** A message ref no longer resolves — deleted, or the chat was cleared. */
+declare class MessageNotFoundError extends AppleAutomationError {
+  readonly name = "MessageNotFoundError";
+  constructor(ref: string);
+}
+/** A chat ref no longer resolves. */
+declare class ChatNotFoundError extends AppleAutomationError {
+  readonly name = "ChatNotFoundError";
+  constructor(ref: string);
+}
+/**
+ * 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.
+ */
+declare class MessagesUnavailableError extends AppleAutomationError {
+  readonly name = "MessagesUnavailableError";
+  constructor(reason: string);
+}
+/**
+ * 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.
+ */
+declare class SendTargetNotFoundError extends AppleAutomationError {
+  readonly name = "SendTargetNotFoundError";
+  constructor(recipient: string, attempts: readonly string[]);
+}
+/** Messages accepted the target and then refused the send itself. */
+declare class SendFailedError extends AppleAutomationError {
+  readonly name = "SendFailedError";
+  constructor(message: string, attempts: readonly string[]);
+}
+//#endregion
+//#region src/client/ref.d.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.
+ */
+declare const MESSAGE_REF_VERSION = "m1";
+declare const CHAT_REF_VERSION = "mc1";
+declare class InvalidMessageRefError extends AppleAutomationError {
+  readonly name = "InvalidMessageRefError";
+  constructor(raw: string, want: "message" | "chat");
+}
+declare const encodeMessageRef: (guid: string) => string;
+declare const encodeChatRef: (guid: string) => string;
+declare const decodeMessageRef: (raw: string) => string;
+declare const decodeChatRef: (raw: string) => string;
+//#endregion
+//#region src/client/typedstream.d.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.
+ */
+/**
+ * The message text.
+ *
+ * ## Text only, and that is now a measured decision rather than a shortcut
+ *
+ * `docs/messages.md` left this open: *"whether `attributedBody` carries
+ * formatting that matters, or is only ever a redundant copy of `text` plus
+ * attachment placeholders. This decides whether the decoder must preserve
+ * structure or merely extract a string."*
+ *
+ * It is the second. Two things settle it:
+ *
+ * 1. **Attribute values are back-REFERENCED, not inline.** Archiving an
+ *    attachment-shaped string through the real `NSArchiver` produces
+ *    `92 84 98 98 22 "__kIMFileTransferGUIDAttributeName" 86` — where `98` is an
+ *    index into the object table rather than a type encoding. Resolving those
+ *    means reconstructing the whole table, which is materially more code and
+ *    more ways to be silently wrong.
+ * 2. **Nothing needs it.** The one attribute worth having is the file-transfer
+ *    GUID, and attachments are already reachable relationally — 17,529 rows in
+ *    their own table, joined through `message_attachment_join`. The blob's copy
+ *    is redundant, and the placeholder character itself (U+FFFC) survives in the
+ *    text, so the position is not lost either.
+ *
+ * So this returns the backing string and says plainly that it stopped there.
+ * `hasAttributes` reports whether anything followed it, which is what a future
+ * decision to go further would be based on — a count, not a guess.
+ */
+type DecodedBody = {
+  ok: true;
+  text: string;
+  classes: string[];
+  /** Bytes remained after the backing store — attribute runs this does not decode. */
+  hasAttributes: boolean;
+  error: null;
+} | {
+  ok: false;
+  text?: undefined;
+  classes?: string[];
+  hasAttributes?: undefined;
+  error: string;
+};
+declare const decodeAttributedBody: (buffer: Uint8Array | null | undefined) => DecodedBody;
+/**
+ * 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.
+ */
+declare const outline: (buffer: Uint8Array, maxTokens?: number) => string[];
+//#endregion
+//#region src/client/jxa/core.d.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. */
+declare const PRELUDE = "\nObjC.import(\"AppKit\");\n\nfunction ok(data) { return JSON.stringify({ ok: true, data: data }); }\nfunction err(code, message, extra) {\n  var e = { code: code, message: String(message) };\n  if (extra) e.detail = extra;\n  return JSON.stringify({ ok: false, error: e });\n}\n\n/** Read one property defensively — every read on this surface is allowed to fail. */\nfunction prop(fn, fallback) {\n  try {\n    var v = fn();\n    return v === undefined ? fallback : v;\n  } catch (e) {\n    return fallback;\n  }\n}\n\nfunction isMessagesRunning() {\n  var apps = $.NSRunningApplication.runningApplicationsWithBundleIdentifier(\"com.apple.MobileSMS\");\n  return apps.count > 0;\n}\n\n/** The dictionary's service type enumeration: SMS, iMessage, RCS. */\nfunction serviceEnum(name) {\n  var s = String(name || \"\").toLowerCase();\n  if (s === \"sms\") return \"SMS\";\n  if (s === \"rcs\") return \"RCS\";\n  return \"iMessage\";\n}\n\n/**\n * Find something `send` will accept as its `to`.\n *\n * Ordered cheapest and most-likely-to-work first. Every rung is wrapped, every\n * failure is recorded, and the caller is told which one answered — on a surface\n * whose whole read half is known broken, \"it worked\" without \"how\" is not a\n * result anyone can act on later.\n */\nfunction resolveTarget(M, p, tried) {\n  var i;\n\n  // 1. The chat guid the file lane read out of chat.db. No enumeration.\n  if (p.chatGuid) {\n    try {\n      var chat = M.chats.byId(p.chatGuid);\n      chat.id();\n      return { target: chat, strategy: \"chat-guid\", kind: \"chat\" };\n    } catch (e) {\n      tried.push(\"chat-guid: \" + (e.message || e));\n    }\n  }\n\n  if (!p.handle) return null;\n\n  // 2. The guid Messages composes for a one-to-one chat, spelled the way the\n  //    store spells it: \"iMessage;-;+15551234567\". Constructed rather than read,\n  //    so it is below the real one and above everything that enumerates.\n  var services = p.service ? [serviceEnum(p.service)] : [\"iMessage\", \"SMS\", \"RCS\"];\n  for (i = 0; i < services.length; i++) {\n    var guess = services[i] + \";-;\" + p.handle;\n    try {\n      var guessed = M.chats.byId(guess);\n      guessed.id();\n      return { target: guessed, strategy: \"chat-guid-guess\", kind: \"chat\", guid: guess };\n    } catch (e2) {\n      tried.push(\"chat-guid-guess(\" + guess + \"): \" + (e2.message || e2));\n    }\n  }\n\n  // 3. A participant reached through its account. This enumerates, so it is\n  //    expected to fail with \"Application isn't running\" — kept because it is\n  //    the form every AppleScript example on the internet uses, and because if\n  //    launching the app does wake the scripting interface, this is what works.\n  for (i = 0; i < services.length; i++) {\n    try {\n      var accounts = M.accounts.whose({ serviceType: services[i] })();\n      for (var j = 0; j < accounts.length; j++) {\n        try {\n          var buddy = accounts[j].participants.whose({ handle: p.handle })()[0];\n          if (buddy) {\n            buddy.id();\n            return { target: buddy, strategy: \"account-participant\", kind: \"participant\" };\n          }\n        } catch (e4) {\n          tried.push(\"account-participant(\" + services[i] + \"): \" + (e4.message || e4));\n        }\n      }\n    } catch (e3) {\n      tried.push(\"accounts(\" + services[i] + \"): \" + (e3.message || e3));\n    }\n  }\n\n  // 4. The flat participant list, last because it is the widest enumeration.\n  try {\n    var flat = M.participants.whose({ handle: p.handle })()[0];\n    if (flat) {\n      flat.id();\n      return { target: flat, strategy: \"participant\", kind: \"participant\" };\n    }\n    tried.push(\"participant: no participant with that handle\");\n  } catch (e5) {\n    tried.push(\"participant: \" + (e5.message || e5));\n  }\n\n  return null;\n}\n";
+//#endregion
+//#region src/client/jxa/write.d.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.
+ */
+declare const SEND_MESSAGE = "\nObjC.import(\"AppKit\");\n\nfunction ok(data) { return JSON.stringify({ ok: true, data: data }); }\nfunction err(code, message, extra) {\n  var e = { code: code, message: String(message) };\n  if (extra) e.detail = extra;\n  return JSON.stringify({ ok: false, error: e });\n}\n\n/** Read one property defensively — every read on this surface is allowed to fail. */\nfunction prop(fn, fallback) {\n  try {\n    var v = fn();\n    return v === undefined ? fallback : v;\n  } catch (e) {\n    return fallback;\n  }\n}\n\nfunction isMessagesRunning() {\n  var apps = $.NSRunningApplication.runningApplicationsWithBundleIdentifier(\"com.apple.MobileSMS\");\n  return apps.count > 0;\n}\n\n/** The dictionary's service type enumeration: SMS, iMessage, RCS. */\nfunction serviceEnum(name) {\n  var s = String(name || \"\").toLowerCase();\n  if (s === \"sms\") return \"SMS\";\n  if (s === \"rcs\") return \"RCS\";\n  return \"iMessage\";\n}\n\n/**\n * Find something `send` will accept as its `to`.\n *\n * Ordered cheapest and most-likely-to-work first. Every rung is wrapped, every\n * failure is recorded, and the caller is told which one answered — on a surface\n * whose whole read half is known broken, \"it worked\" without \"how\" is not a\n * result anyone can act on later.\n */\nfunction resolveTarget(M, p, tried) {\n  var i;\n\n  // 1. The chat guid the file lane read out of chat.db. No enumeration.\n  if (p.chatGuid) {\n    try {\n      var chat = M.chats.byId(p.chatGuid);\n      chat.id();\n      return { target: chat, strategy: \"chat-guid\", kind: \"chat\" };\n    } catch (e) {\n      tried.push(\"chat-guid: \" + (e.message || e));\n    }\n  }\n\n  if (!p.handle) return null;\n\n  // 2. The guid Messages composes for a one-to-one chat, spelled the way the\n  //    store spells it: \"iMessage;-;+15551234567\". Constructed rather than read,\n  //    so it is below the real one and above everything that enumerates.\n  var services = p.service ? [serviceEnum(p.service)] : [\"iMessage\", \"SMS\", \"RCS\"];\n  for (i = 0; i < services.length; i++) {\n    var guess = services[i] + \";-;\" + p.handle;\n    try {\n      var guessed = M.chats.byId(guess);\n      guessed.id();\n      return { target: guessed, strategy: \"chat-guid-guess\", kind: \"chat\", guid: guess };\n    } catch (e2) {\n      tried.push(\"chat-guid-guess(\" + guess + \"): \" + (e2.message || e2));\n    }\n  }\n\n  // 3. A participant reached through its account. This enumerates, so it is\n  //    expected to fail with \"Application isn't running\" — kept because it is\n  //    the form every AppleScript example on the internet uses, and because if\n  //    launching the app does wake the scripting interface, this is what works.\n  for (i = 0; i < services.length; i++) {\n    try {\n      var accounts = M.accounts.whose({ serviceType: services[i] })();\n      for (var j = 0; j < accounts.length; j++) {\n        try {\n          var buddy = accounts[j].participants.whose({ handle: p.handle })()[0];\n          if (buddy) {\n            buddy.id();\n            return { target: buddy, strategy: \"account-participant\", kind: \"participant\" };\n          }\n        } catch (e4) {\n          tried.push(\"account-participant(\" + services[i] + \"): \" + (e4.message || e4));\n        }\n      }\n    } catch (e3) {\n      tried.push(\"accounts(\" + services[i] + \"): \" + (e3.message || e3));\n    }\n  }\n\n  // 4. The flat participant list, last because it is the widest enumeration.\n  try {\n    var flat = M.participants.whose({ handle: p.handle })()[0];\n    if (flat) {\n      flat.id();\n      return { target: flat, strategy: \"participant\", kind: \"participant\" };\n    }\n    tried.push(\"participant: no participant with that handle\");\n  } catch (e5) {\n    tried.push(\"participant: \" + (e5.message || e5));\n  }\n\n  return null;\n}\n\nfunction run(argv) {\n  var p = JSON.parse(argv[0]);\n  var M = Application(\"Messages\");\n\n  var wasRunning = isMessagesRunning();\n  if (!wasRunning && !p.allowLaunch) {\n    return err(\"APP_NOT_RUNNING\", \"Messages is not running.\");\n  }\n\n  var tried = [];\n  var resolved = resolveTarget(M, p, tried);\n  if (!resolved) {\n    return err(\n      \"SEND_TARGET_NOT_FOUND\",\n      \"Messages would not resolve a chat or participant for that recipient.\",\n      tried\n    );\n  }\n\n  try {\n    M.send(p.text, { to: resolved.target });\n  } catch (e) {\n    return err(\"SEND_FAILED\", e.message || e, tried);\n  }\n\n  return ok({\n    strategy: resolved.strategy,\n    targetKind: resolved.kind,\n    // Best effort, and allowed to be null: reading the id back is itself a read.\n    targetId: prop(function () { return String(resolved.target.id()); }, null),\n    launched: !wasRunning,\n    attempts: tried\n  });\n}\n";
+//#endregion
+//#region src/server.d.ts
+declare const SERVER_NAME: string;
+declare const SERVER_VERSION: string;
+type CreateServerOptions = {
+  config: Config;
+  logger?: Logger;
+  /** Injected by tests so nothing spawns a process or touches real Messages. */
+  osascript?: OsascriptRunner;
+  /** Injected by tests so discovery never reaches the developer's real home. */
+  home?: string;
+  /** Injected by tests, so no test reaches the developer's real address book. */
+  contacts?: ConstructorParameters<typeof AppleMessagesClient>[0]["contacts"];
+};
+type CreatedServer = {
+  server: McpServer;
+  client: AppleMessagesClient;
+};
+/**
+ * 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.
+ */
+declare const createServer: (opts: CreateServerOptions) => CreatedServer;
+//#endregion
+//#region src/tools/index.d.ts
+type ToolContext = {
+  /**
+   * Gates the two tools that change something outside this process.
+   *
+   * `send_message` is the only one that touches Messages.app, and it is also
+   * every Apple Event this server can send, because sending is the only thing
+   * Apple Events can do here — there is no read lane to fall back to and never
+   * can be. So with writes off this server remains inert with respect to
+   * Messages.app: it opens a file and nothing else.
+   *
+   * `save_attachment` is gated for a different reason. It sends no Apple Event
+   * and changes nothing in Messages; what it does is create a file on the
+   * user's disk, which Mail and Notes also treat as a write. The claim above
+   * survives it intact.
+   */
+  allowWrites: boolean;
+};
+/**
+ * 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.
+ */
+declare const registerTools: (server: McpServer, client: AppleMessagesClient, ctx: ToolContext) => void;
+//#endregion
+export { ATTACHMENTS_RELATIVE, AppleMessagesClient, AppleMessagesError, BUILD_INFO, type BuildInfo, CHAT_REF_VERSION, CORE_DATA_EPOCH_OFFSET, ChatNotFoundError, type ChatRow, type Config, type Correspondent, type CreateClientOptions, type CreateServerOptions, type DecodedBody, IndexUnavailableError, InvalidMessageRefError, type LocateResult, MESSAGES_BUNDLE_ID, MESSAGES_SURFACE, MESSAGE_REF_VERSION, MessageNotFoundError, type MessageRow, MessagesStore, MessagesUnavailableError, PRELUDE, type RangeQuery, type RenderedChat, type RenderedMessage, SEND_MESSAGE, SERVER_NAME, SERVER_VERSION, STORE_RELATIVE, SchemaDriftError, SendFailedError, type SendResult, SendTargetNotFoundError, type StoreCapabilities, type ToolContext, appleSecondsSql, createServer, decodeAttributedBody, decodeChatRef, decodeMessageRef, defaultStorePath, encodeChatRef, encodeMessageRef, fromAppleSeconds, introspect, loadConfig, locateStore, openStore, outline, reactionLabel, registerTools, renderInstant, toAppleSeconds };
+//# sourceMappingURL=index.d.ts.map