@mgcrea/mcp-apple-maps 1.15.0 → 1.17.0

package/dist/{server-CpYiHM_a.js → server-C_leu2E0.js}

@@ -1,4 +1,4 @@
-import { AppleAutomationError, AppleAutomationError as AppleMapsError, BaseConfigSchema, CORE_DATA_EPOCH_OFFSET, IndexUnavailableError, SchemaDriftError, SchemaDriftError as SchemaDriftError$1, columnsOf, compact, describeStore, detectEpoch, escapeLike, fail, fingerprintSchema, inspectFile, limitArg, ok, openReadOnly, parseBool, parseConfig, parseIntOpt, promptArg, readPackageIdentity, registerSurfaceResources, registerWorkflowPrompt, resolveLimit, trimmed, withLazyTools, wrap, wrapResult } from "@mgcrea/mcp-apple-core";
+import { AppleAutomationError, AppleAutomationError as AppleMapsError, BaseConfigSchema, CORE_DATA_EPOCH_OFFSET, IndexUnavailableError, SchemaDriftError, SchemaDriftError as SchemaDriftError$1, columnsOf, compact, describeStore, detectEpoch, escapeLike, fail, fingerprintSchema, inspectFile, interferenceNote, limitArg, ok, openAxChannel, openReadOnly, parseBool, parseConfig, parseIntOpt, promptArg, readPackageIdentity, registerSurfaceResources, registerWorkflowPrompt, resolveLimit, trimmed, watchInterference, withLazyTools, wrap, wrapResult } from "@mgcrea/mcp-apple-core";
 import { readdirSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
@@ -15,8 +15,8 @@ const pkg = readPackageIdentity(new URL("../package.json", import.meta.url), {
 const BUILD_INFO = {
 	name: pkg.name,
 	version: pkg.version,
-	gitCommit: "dfc8616",
-	gitCommitDate: "2026-09-06T00:04:53+02:00"
+	gitCommit: "d05a45c",
+	gitCommitDate: "2026-09-07T16:21:19+02:00"
 };
 //#endregion
 //#region src/client/dates.ts
@@ -238,6 +238,296 @@ const locateStore = (opts = {}) => {
 	};
 };
 //#endregion
+//#region src/client/ax.ts
+/**
+* Maps' place card, driven through Cupertino's native Accessibility driver.
+*
+* ## Why this exists beside the SQL lane rather than replacing it
+*
+* `client/write.ts` writes favourites by copying a record Maps minted and
+* INSERTing it. That lane is correct and stays: pressing the card's `AddButton`
+* does not create a favourite. `docs/desktop.md` measured it — the press lands
+* an **unfiled saved place** and `ZFAVORITEITEM` was 26 rows before and 26
+* after. The two lanes address different objects.
+*
+* What this reaches is the set the SQL lane does not offer at all:
+*
+*   * **The Places library** — `add_to_places` / `delete_from_places`.
+*   * **Guide membership** — `docs/maps.md` lists it as unbuilt: "Adding a place
+*     to a collection needs one `Z_6PLACES` join row".
+*
+* ## The safety argument, which is the real reason to prefer it here
+*
+* The store is mirrored by `NSPersistentCloudKitContainer` and mirroring does
+* not wait to be told, so a malformed row is not a local mistake — it reaches
+* every device on the account. `write.ts` carries the rule that keeps SQL safe:
+* never fabricate a place record, only copy one Maps wrote. **A write made
+* through the interface cannot be malformed at all**, because Maps performs it.
+* Where both lanes could do a job, this one has the smaller blast radius.
+*
+* ## The cost, which is the same one the SQL lane pays
+*
+* Reaching the card means opening `maps://?q=<name>&ll=<lat>,<lon>`, so the
+* place is left in **Recents** whether or not anything is kept. That is the
+* mechanism rather than an oversight, and every tool built on this says so.
+*/
+const MAPS_BUNDLE = "com.apple.Maps";
+/** Identifiers Maps sets on the card. Unlocalised, unlike every name here. */
+const CARD = {
+	add: "AddButton",
+	more: "MoreButton",
+	card: "PlaceCardViewController",
+	addToGuides: "add_to_guides",
+	deleteFromPlaces: "delete_from_places",
+	addToPlaces: "add_to_places",
+	picker: "GuidesPickerView",
+	guideRow: "UserGuidesPickerRowCell",
+	done: "CardButtonTypeDone",
+	close: "CardButtonTypeClose"
+};
+const defaultOpenUrl$1 = (url) => {
+	execFileSync("/usr/bin/open", ["-g", url], {
+		timeout: 1e4,
+		stdio: "ignore"
+	});
+};
+/**
+* `"Favorites, 3 places"` -> `{ name: "Favorites", places: 3 }`.
+*
+* The count is a bonus and the name is the point, so a row whose shape is not
+* recognised keeps its whole label as the name rather than being dropped. A
+* guide that cannot be matched is worse than one with an odd name.
+*/
+const parseGuideRow = (label) => {
+	const match = /^(.*),\s*(\d+)\s+places?$/.exec(label);
+	if (!match?.[1]) return {
+		name: label,
+		places: null
+	};
+	return {
+		name: match[1],
+		places: Number(match[2])
+	};
+};
+const DEFAULT_WAITS = {
+	card: 1e4,
+	sheet: 4e3
+};
+var MapsAxLane = class MapsAxLane {
+	#channel;
+	#openUrl;
+	#waits;
+	constructor(channel, openUrl, waits) {
+		this.#channel = channel;
+		this.#openUrl = openUrl;
+		this.#waits = waits;
+	}
+	/** Null when this server is not hosted by Cupertino — see `core/src/ax.ts`. */
+	static open(env = process.env, openUrl = defaultOpenUrl$1, waits = {}) {
+		const channel = openAxChannel(MAPS_SURFACE, env);
+		return channel ? new MapsAxLane(channel, openUrl, {
+			...DEFAULT_WAITS,
+			...waits
+		}) : null;
+	}
+	close() {
+		this.#channel.close();
+	}
+	/** Start watching for someone using the Mac during a sequence. */
+	watch() {
+		return watchInterference(this.#channel);
+	}
+	#call(tool, args = {}) {
+		return this.#channel.call({
+			tool: `apple_desktop_${tool}`,
+			args
+		});
+	}
+	async #tree() {
+		return (await this.#call("ui_tree", {
+			bundleId: MAPS_BUNDLE,
+			detail: "all",
+			maxDepth: 20,
+			maxNodes: 4e3,
+			budgetSeconds: 20
+		})).elements ?? [];
+	}
+	/**
+	* Wait for an element rather than for a duration.
+	*
+	* `docs/desktop.md` calls this the trap that cost it the most: a card's chrome
+	* appears before its content, so no fixed settle time is correct. Cheap here —
+	* a whole Maps walk is ~0.17 s.
+	*/
+	async #poll(match, timeoutMs = this.#waits.card) {
+		const deadline = Date.now() + timeoutMs;
+		let lastError = null;
+		for (;;) {
+			try {
+				const found = (await this.#tree()).find(match);
+				if (found) return found;
+				lastError = null;
+			} catch (error) {
+				lastError = error;
+			}
+			if (Date.now() >= deadline) {
+				if (lastError) throw lastError;
+				return null;
+			}
+			await new Promise((resolve) => setTimeout(resolve, 300));
+		}
+	}
+	/**
+	* Open a place and wait for its card.
+	*
+	* The combined `q=` and `ll=` form, because a coordinate positions the map and
+	* a NAME selects a place — `write.ts` records the same thing for the same
+	* reason.
+	*/
+	async openCard(place) {
+		this.#openUrl(`maps://?q=${encodeURIComponent(place.name)}&ll=${place.latitude},${place.longitude}`);
+		return await this.#poll((e) => e.id === CARD.add) !== null;
+	}
+	/**
+	* Is this place saved?
+	*
+	* Read off `AddButton`'s NAME, which is the state bit. `docs/desktop.md`
+	* corrected itself on this: `FavoriteButton` reports identical attributes
+	* either way, and the sibling carries `"Add"` versus `"Added"`.
+	*
+	* Localised, and that is a real limit rather than an oversight — there is no
+	* unlocalised state anywhere on this card.
+	*/
+	async isSaved() {
+		const add = await this.#poll((e) => e.id === CARD.add, this.#waits.sheet);
+		if (!add?.name) return null;
+		return add.name !== "Add";
+	}
+	/**
+	* Open the card's overflow menu and return its items.
+	*
+	* POLLED, not settled. The first version asked for the items in the same
+	* breath as the press and got an empty list every time — the menu takes on the
+	* order of half a second to appear — and then reported "the overflow menu did
+	* not open", which is a sentence about Maps rather than about the race. That
+	* is this repo's own rule broken in the file that quotes it: **poll for the
+	* control, never wait a fixed time for it.**
+	*/
+	async #openMenu() {
+		const more = await this.#poll((e) => e.id === CARD.more);
+		if (!more) return [];
+		await this.#call("press", { handle: more.handle });
+		const deadline = Date.now() + this.#waits.sheet;
+		for (;;) {
+			const items = await this.#call("find_elements", {
+				bundleId: MAPS_BUNDLE,
+				role: "AXMenuItem"
+			});
+			if (items.elements?.length) return items.elements;
+			if (Date.now() >= deadline) return [];
+			await new Promise((resolve) => setTimeout(resolve, 250));
+		}
+	}
+	async #dismiss() {
+		await this.#call("key", {
+			key: "escape",
+			modifiers: []
+		});
+	}
+	/**
+	* Save the open place into the Places library.
+	*
+	* Two presses, not one: `AddButton` raises a **"Name This Location"** sheet
+	* and nothing is written until its `Save` is pressed. The sheet REPLACES the
+	* window list — a full walk during it returns the sheet and nothing else — so
+	* the card's elements are unreachable until it closes, and `Save` carries no
+	* `AXIdentifier`, which is why it is addressed by name.
+	*/
+	async savePlace() {
+		const add = await this.#poll((e) => e.id === CARD.add);
+		if (!add) return false;
+		await this.#call("press", { handle: add.handle });
+		const save = await this.#poll((e) => e.role === "AXButton" && e.name === "Save", this.#waits.sheet);
+		if (!save) return false;
+		await this.#call("press", { handle: save.handle });
+		return true;
+	}
+	/**
+	* Remove the open place from the Places library.
+	*
+	* The menu item is `delete_from_places`, and it is only present when the place
+	* IS saved — the same slot carries `add_to_places` when it is not. So its
+	* absence is a state reading rather than a failure, and this reports which.
+	*/
+	async removePlace() {
+		const items = await this.#openMenu();
+		if (!items.length) return "no-menu";
+		const remove = items.find((e) => e.id === CARD.deleteFromPlaces);
+		if (!remove) {
+			await this.#dismiss();
+			return items.some((e) => e.id === CARD.addToPlaces) ? "not-saved" : "no-menu";
+		}
+		await this.#call("press", { handle: remove.handle });
+		return "removed";
+	}
+	/**
+	* Every guide Maps knows about, read off its own picker.
+	*
+	* This is the authoritative list, and it is not the same as the store's:
+	* `docs/desktop.md` found the picker showing a "Favorites" guide that
+	* `apple_maps_list_collections` does not return. Read here as a side effect of
+	* being on the way to a write, rather than as a tool of its own — reaching it
+	* needs a place card, which needs a `maps://` open, which leaves a Recents
+	* entry. That is too much side effect for something calling itself a read.
+	*
+	* Leaves the picker OPEN, because the caller is normally about to press a row.
+	*/
+	async openGuidePicker() {
+		const items = await this.#openMenu();
+		const guides = items.find((e) => e.id === CARD.addToGuides);
+		if (!guides) {
+			if (items.length) await this.#dismiss();
+			return null;
+		}
+		await this.#call("press", { handle: guides.handle });
+		if (!await this.#poll((e) => e.id === CARD.picker, this.#waits.sheet)) return null;
+		return (await this.#tree()).filter((e) => e.id === CARD.guideRow && e.name).map((e) => parseGuideRow(e.name));
+	}
+	/** Press one guide row, then Done. Returns false if no row matched. */
+	async chooseGuide(name) {
+		const wanted = name.toLowerCase();
+		const row = (await this.#tree()).find((e) => e.id === CARD.guideRow && parseGuideRow(e.name ?? "").name.toLowerCase() === wanted);
+		if (!row) return false;
+		await this.#call("press", { handle: row.handle });
+		const done = await this.#poll((e) => e.id === CARD.done, this.#waits.sheet);
+		if (!done) return false;
+		await this.#call("press", { handle: done.handle });
+		return true;
+	}
+	/**
+	* Re-open the card and read the state bit, which is the only way to verify.
+	*
+	* **A write closes the card.** Saving through the naming sheet dismisses the
+	* whole place card and returns Maps to its main view, so reading `AddButton`
+	* straight after a press finds nothing and reports "the card does not say it
+	* is saved" — which is a sentence about the write having failed, when what
+	* actually happened is that the thing being read went away.
+	*
+	* So verification re-opens the place first. That costs another `maps://`,
+	* which is free in the sense that matters: the Recents entry this leaves was
+	* already left by opening the card in the first place.
+	*/
+	async verifySaved(place) {
+		if (!await this.openCard(place)) return null;
+		return this.isSaved();
+	}
+	/** Abandon the picker without filing anything. */
+	async cancelGuidePicker() {
+		const close = await this.#poll((e) => e.id === CARD.close, this.#waits.sheet);
+		if (close) await this.#call("press", { handle: close.handle });
+	}
+};
+//#endregion
 //#region src/client/ref.ts
 /**
 * Refs for places and collections.
@@ -1038,6 +1328,10 @@ const openStore = (opts) => {
 * Hence: never fabricate a place record, only ever copy one Maps wrote.
 */
 const STORAGE_POLL_MS = 250;
+/** A pause that yields the event loop, unlike `Atomics.wait`, which does not. */
+const sleep = (ms) => new Promise((resolve) => {
+	setTimeout(resolve, ms);
+});
 /**
 * Progress, on stderr.
 *
@@ -1221,7 +1515,17 @@ var MapsWriter = class {
 	*              poll with a short-lived read-only handle each time.
 	*   3. WRITE — open read-write, insert, close.
 	*/
-	addFavorite(input) {
+	/**
+	* Async because the seed can take THIRTY SECONDS.
+	*
+	* When the place is not already in the store this asks Maps to mint it
+	* through the URL scheme and then polls for the row to appear. That poll used
+	* `Atomics.wait`, which blocks the thread — and this server is single
+	* threaded, so for the whole seed it answered nothing at all: not a ping, not
+	* a cancellation, not another tool call. A sleep that yields costs the same
+	* wall clock and leaves the server able to speak.
+	*/
+	async addFavorite(input) {
 		const hasCoords = input.latitude !== void 0 && input.longitude !== void 0;
 		const lat = input.latitude ?? 0;
 		const lon = input.longitude ?? 0;
@@ -1264,7 +1568,7 @@ var MapsWriter = class {
 				} finally {
 					probe.close();
 				}
-				if (!donor) Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, STORAGE_POLL_MS);
+				if (!donor) await sleep(STORAGE_POLL_MS);
 				polls += 1;
 				if (polls % 8 === 0) progress(`still waiting (${polls * (STORAGE_POLL_MS / 1e3)}s)…`);
 			}
@@ -1294,22 +1598,23 @@ var MapsWriter = class {
 		progress("writing the favourite");
 		const db = this.#open();
 		try {
-			const favEnt = this.#entity(db, "FavoriteItem");
-			const mixEnt = this.#entity(db, "MixinMapItem");
-			const favPk = this.#nextPk(db, "FavoriteItem", "ZFAVORITEITEM");
-			const mixPk = this.#nextPk(db, "MixinMapItem", "ZMIXINMAPITEM");
 			const now = Date.now() / 1e3 - CORE_DATA_EPOCH_OFFSET;
 			const id = uuidBytes();
 			const label = input.name ?? donor.name ?? input.query;
-			const position = Number(db.prepare(`SELECT COUNT(*) AS c FROM ZFAVORITEITEM`).get().c);
+			let favPk = 0;
 			db.exec("BEGIN IMMEDIATE");
 			try {
+				const favEnt = this.#entity(db, "FavoriteItem");
+				const mixEnt = this.#entity(db, "MixinMapItem");
+				favPk = this.#nextPk(db, "FavoriteItem", "ZFAVORITEITEM");
+				const mixPk = this.#nextPk(db, "MixinMapItem", "ZMIXINMAPITEM");
+				const position = Number(db.prepare(`SELECT COUNT(*) AS c FROM ZFAVORITEITEM`).get().c);
 				db.prepare(`INSERT INTO "ZFAVORITEITEM"
              (Z_PK, Z_ENT, Z_OPT, ZHIDDEN, ZPOSITIONINDEX, ZSOURCE, ZTYPE, ZVERSION,
               ZMAPITEM, ZMUID, ZCREATETIME, ZMODIFICATIONTIME, ZMAPITEMLASTREFRESHED,
               ZLATITUDE, ZLONGITUDE, ZMAPITEMNAME, ZMAPITEMADDRESS, ZMAPITEMCATEGORY,
               ZIDENTIFIER)
-           VALUES (?, ?, 1, 0, ?, 0, 1, 2, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(favPk, favEnt, position, mixPk, donor.muid === null ? null : Number(donor.muid), now, now, now, donor.lat, donor.lon, label, donor.address, donor.category, id);
+           VALUES (?, ?, 1, 0, ?, 0, 1, 2, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(favPk, favEnt, position, mixPk, donor.muid === null ? null : BigInt(donor.muid), now, now, now, donor.lat, donor.lon, label, donor.address, donor.category, id);
 				db.prepare(`INSERT INTO "ZMIXINMAPITEM"
              (Z_PK, Z_ENT, Z_OPT, ZFAVORITEITEM, ZCREATETIME, ZMODIFICATIONTIME,
               ZLATITUDE, ZLONGITUDE, ZMAPITEMSTORAGE)
@@ -1381,6 +1686,14 @@ const summariseEntity = (e) => ({
 });
 var AppleMapsClient = class {
 	#config;
+	/**
+	* The interface lane, when this server is hosted by Cupertino.
+	*
+	* Null when it is not, which is the supported case rather than a fault: the
+	* npm package has to work with no app on the machine. `tools/index.ts` skips
+	* registering the tools that need it.
+	*/
+	#ax;
 	#logger;
 	#home;
 	#located = null;
@@ -1388,12 +1701,16 @@ var AppleMapsClient = class {
 	#storeError = null;
 	constructor(opts) {
 		this.#config = opts.config;
+		this.#ax = opts.ax !== void 0 ? opts.ax : MapsAxLane.open();
 		this.#logger = opts.logger;
 		this.#home = opts.home;
 	}
 	get config() {
 		return this.#config;
 	}
+	get axLane() {
+		return this.#ax;
+	}
 	located() {
 		this.#located ??= locateStore({
 			storePath: this.#config.storePath,
@@ -1748,7 +2065,13 @@ const buildDiagnostics = async (client) => {
 				working: status.store.opened
 			},
 			appleEvents: "none — Maps is not scriptable",
-			writes: "none — this server registers no mutating tool. The store is mirrored to iCloud by NSPersistentCloudKitContainer, so a write is an edit to one replica of a synchronising graph underneath a running app. That was never probed."
+			writes: {
+				enabled: client.config.allowWrites,
+				lane: "SQL, directly into the Core Data store. Maps ships no scripting dictionary and registers no App Intents on macOS, so there is no lane where the app performs the write on our behalf — this is the only surface here that writes its own store.",
+				seeding: "A place is only real to Maps if it carries a ZMAPITEMSTORAGE blob, which this repo cannot generate. Opening maps://?q=<name>&ll=<lat>,<lon> through LaunchServices makes Maps mint one, and that record is copied. The place is therefore left in Recents whether or not the favourite is kept, and resolving it can take tens of seconds.",
+				blastRadius: "The store is mirrored by NSPersistentCloudKitContainer, and mirroring does not wait to be told. A malformed row is not a local mistake: it reaches every device on the account as soon as Maps next runs. Hence the rule in client/write.ts — never fabricate a place record, only ever copy one Maps wrote.",
+				tools: client.config.allowWrites ? ["apple_maps_add_favorite", "apple_maps_remove_favorite"] : []
+			}
 		},
 		store: {
 			path: located.storePath,
@@ -1786,6 +2109,138 @@ const registerDiagnosticsTools = (server, client) => {
 	}, async () => wrap(() => buildDiagnostics(client)));
 };
 //#endregion
+//#region src/tools/ax-writes.ts
+/**
+* The tools that go through Maps' own interface rather than its store.
+*
+* ## Why these are not in `writes.ts`
+*
+* Different lane, different objects, different failure modes. `writes.ts` writes
+* SQL into the Core Data store and reaches **favourites**; these press controls
+* on a place card and reach the **Places library** and **guide membership** —
+* two sets the SQL lane does not offer at all. `docs/maps.md` lists guide
+* membership as unbuilt for exactly that reason.
+*
+* ## Registered only when the app is hosting this server
+*
+* The Accessibility grant belongs to Cupertino.app, not to node, so a package
+* installed from npm and run by hand has no lane here and these tools are not
+* registered at all — the same rule the write gate follows, so a host is never
+* told about a tool that cannot work for it.
+*
+* ## What every description has to say
+*
+* **It opens Maps and leaves the place in Recents.** Reaching a card means
+* opening `maps://`, which is how the SQL lane seeds a record too. There is no
+* way to have the card without the Recents entry.
+*
+* **It moves the user's screen.** Unlike a SQL write, this brings a window
+* forward and presses things in it. That is worth stating plainly.
+*/
+const noCard = (query, disturbed) => fail(`Maps did not show a place card for "${query}" within 10s. Nothing was changed. The coordinates may not resolve to a place Maps recognises, or Maps may not have finished loading it.` + disturbed);
+const registerAxWriteTools = (server, lane) => {
+	const place = {
+		query: z.string().min(1).describe("The place's name, as you would type it into Maps' search field."),
+		latitude: z.number().min(-90).max(90).describe("Latitude of the place."),
+		longitude: z.number().min(-180).max(180).describe("Longitude of the place.")
+	};
+	const openCard = async (args) => lane.openCard({
+		name: args.query,
+		latitude: args.latitude,
+		longitude: args.longitude
+	});
+	server.registerTool("apple_maps_save_place", {
+		description: "Save a place into Maps' Places library, by pressing Add on its card. This is NOT a favourite: the Pinned list is a different set, written by apple_maps_add_favorite. Maps performs the write itself, so it cannot produce a malformed record. SIDE EFFECTS: opens Maps, brings its window forward, and leaves the place in the user's Recents. Syncs to the user's other Apple devices. Needs Accessibility for Cupertino.",
+		inputSchema: place,
+		annotations: {
+			readOnlyHint: false,
+			destructiveHint: false,
+			idempotentHint: true
+		}
+	}, async (args) => wrapResult(async () => {
+		const watch = lane.watch();
+		const disturbed = async () => interferenceNote(await watch.check());
+		if (!await openCard(args)) return noCard(args.query, await disturbed());
+		if (await lane.isSaved() === true) return ok({
+			saved: true,
+			alreadySaved: true,
+			query: args.query
+		});
+		if (!await lane.savePlace()) return fail(`The card for "${args.query}" opened but the naming sheet did not, so nothing was saved. The card may still be on screen.` + await disturbed());
+		return await lane.verifySaved({
+			name: args.query,
+			latitude: args.latitude,
+			longitude: args.longitude
+		}) === true ? ok({
+			saved: true,
+			alreadySaved: false,
+			query: args.query
+		}) : fail(`"${args.query}" was pressed through the save sheet but its card does not report it as saved, so this MUST NOT be reported as done. Check Maps.` + await disturbed());
+	}));
+	server.registerTool("apple_maps_remove_saved_place", {
+		description: "Remove a place from Maps' Places library, through the card's overflow menu. This does NOT touch favourites — use apple_maps_remove_favorite for those. SIDE EFFECTS: opens Maps, brings its window forward, and leaves the place in the user's Recents. Syncs to the user's other Apple devices. Needs Accessibility for Cupertino.",
+		inputSchema: place,
+		annotations: {
+			readOnlyHint: false,
+			destructiveHint: true,
+			idempotentHint: true
+		}
+	}, async (args) => wrapResult(async () => {
+		const watch = lane.watch();
+		const disturbed = async () => interferenceNote(await watch.check());
+		if (!await openCard(args)) return noCard(args.query, await disturbed());
+		const outcome = await lane.removePlace();
+		if (outcome === "not-saved") return ok({
+			removed: false,
+			wasSaved: false,
+			query: args.query
+		});
+		if (outcome === "no-menu") return fail(`The card for "${args.query}" opened but its overflow menu did not, so nothing was removed.` + await disturbed());
+		return await lane.verifySaved({
+			name: args.query,
+			latitude: args.latitude,
+			longitude: args.longitude
+		}) === false ? ok({
+			removed: true,
+			wasSaved: true,
+			query: args.query
+		}) : fail(`"${args.query}" was pressed through Delete from Places but its card still reports it as saved, so this MUST NOT be reported as done. Check Maps.` + await disturbed());
+	}));
+	server.registerTool("apple_maps_add_place_to_guide", {
+		description: "File a place into one of Maps' Guides, through the card's Add to Guides picker. This is the write apple_maps_list_collections has no counterpart for. IT CANNOT CONFIRM ITSELF: Maps does not expose whether the place ended up in the guide, so the result says filed: \"unverified\" and it must not be reported as done. The guide must already exist; when the name does not match, the refusal lists every guide Maps offers, which is the authoritative list and can differ from what apple_maps_list_collections returns. SIDE EFFECTS: opens Maps, brings its window forward, and leaves the place in the user's Recents. Syncs to the user's other Apple devices. Needs Accessibility for Cupertino.",
+		inputSchema: {
+			...place,
+			guide: z.string().min(1).describe("Name of the guide to file it into, as Maps shows it.")
+		},
+		annotations: {
+			readOnlyHint: false,
+			destructiveHint: false,
+			idempotentHint: true
+		}
+	}, async (args) => wrapResult(async () => {
+		const watch = lane.watch();
+		const disturbed = async () => interferenceNote(await watch.check());
+		if (!await openCard(args)) return noCard(args.query, await disturbed());
+		const guides = await lane.openGuidePicker();
+		if (guides === null) return fail(`The card for "${args.query}" opened but its Add to Guides picker did not, so nothing was filed.` + await disturbed());
+		if (!await lane.chooseGuide(args.guide)) {
+			await lane.cancelGuidePicker();
+			return fail(`Maps offers no guide called "${args.guide}", so nothing was filed. It offers: ${guides.map((g) => g.name).join(", ")}.`, { guides: compactGuides(guides) });
+		}
+		return ok({
+			filed: "unverified",
+			query: args.query,
+			guide: args.guide,
+			guides: compactGuides(guides),
+			note: "The guide row and then Done were pressed. Maps does not expose whether the place ended up in the guide — the picker's counts do not refresh in the accessibility tree — so this MUST NOT be reported to the user as filed. Check Maps."
+		});
+	}));
+};
+const compactGuides = (guides) => guides.map((g) => g.places === null ? { name: g.name } : {
+	name: g.name,
+	places: g.places
+});
+//#endregion
 //#region src/tools/places.ts
 /**
 * The place tools.
@@ -1863,10 +2318,11 @@ const registerPlaceTools = (server, client) => {
 		}
 	}, async ({ ref, limit }) => wrapResult(async () => {
 		const collectionId = client.collectionRowId(decodeCollectionRef(ref));
+		if (collectionId === null) return fail(`No collection matches ${ref}. Refs come from apple_maps_list_collections and go stale when a guide is deleted or renamed away.`);
 		const capped = resolveLimit(limit, client.config.maxResults);
 		const result = client.places("collection-item", {
 			limit: capped,
-			collectionId: collectionId ?? void 0
+			collectionId
 		});
 		if (!client.collections({ limit: 1e3 }).itemsEnumerable) return fail("This store does not expose which collection an item belongs to, so its places cannot be listed. The collection itself and its place count are still readable through apple_maps_list_collections.");
 		return ok(compact({
@@ -1988,7 +2444,7 @@ const registerWriteTools = (server, client) => {
 			idempotentHint: true
 		}
 	}, async ({ query, latitude, longitude, name }) => wrapResult(async () => {
-		const result = client.writer().addFavorite({
+		const result = await client.writer().addFavorite({
 			query,
 			latitude,
 			longitude,
@@ -2041,6 +2497,8 @@ const registerTools = (server, client, ctx) => {
 	registerPlaceTools(server, client);
 	if (!ctx.allowWrites) return;
 	registerWriteTools(server, client);
+	const ax = client.axLane;
+	if (ax) registerAxWriteTools(server, ax);
 };
 //#endregion
 //#region src/server.ts
@@ -2089,4 +2547,4 @@ const createServer = (opts) => {
 //#endregion
 export { fromStoreTime as A, MAPS_SURFACE as C, UndatableStoreError as D, SchemaDriftError$1 as E, resolveEpoch as M, BUILD_INFO as N, APPLE_SECONDS as O, MAPS_BUNDLE_ID as S, PlaceNotFoundError as T, defaultDirectory as _, loadConfig as a, AppleMapsError as b, introspect as c, InvalidMapsRefError as d, PLACE_REF_VERSION as f, encodePlaceRef as g, encodeCollectionRef as h, registerTools as i, renderInstant as j, CORE_DATA_EPOCH_OFFSET as k, openStore as l, decodePlaceRef as m, SERVER_VERSION as n, AppleMapsClient as o, decodeCollectionRef as p, createServer as r, MapsStore as s, SERVER_NAME as t, COLLECTION_REF_VERSION as u, defaultStorePath as v, MapsStoreUnavailableError as w, IndexUnavailableError as x, locateStore as y };
 
-//# sourceMappingURL=server-CpYiHM_a.js.map
+//# sourceMappingURL=server-C_leu2E0.js.map