@mgcrea/mcp-apple-core 1.14.0 → 1.16.0

package/dist/index.js

@@ -1,9 +1,309 @@
+import { connect } from "node:net";
 import { accessSync, constants, readFileSync, statSync } from "node:fs";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
 import { execFile } from "node:child_process";
 import { createHash } from "node:crypto";
 import { DatabaseSync } from "node:sqlite";
+//#region src/errors.ts
+/** Base class so `toFailure` can carry structured detail through in one branch. */
+var AppleAutomationError = class extends Error {
+	name = "AppleAutomationError";
+	details;
+	constructor(message, details) {
+		super(message);
+		this.details = details;
+	}
+};
+/** The host process may not send Apple Events to the app (osascript -1743). */
+var TccDeniedError = class extends AppleAutomationError {
+	name = "TccDeniedError";
+	constructor(surface) {
+		super(`Not authorized to control ${surface.appName}. Grant it in System Settings > Privacy & Security > Automation > (the app running this server) > ${surface.appName}, then restart the server. If no entry appears, the first attempt was denied before the prompt could be answered — run \`tccutil reset AppleEvents\` and try again.`);
+	}
+};
+/** The app is not running and the operation refuses to launch it. */
+var AppNotRunningError = class extends AppleAutomationError {
+	name = "AppNotRunningError";
+	constructor(surface) {
+		super(`${surface.appName} is not running. Read tools do not launch it, because launching it steals focus and can start a sync. Open ${surface.appName} and retry.`);
+	}
+};
+/** The app was busy and refused the Apple Event (-1712). Retried once before surfacing. */
+var AppBusyError = class extends AppleAutomationError {
+	name = "AppBusyError";
+	constructor(surface) {
+		super(`${surface.appName} is busy (probably syncing) and did not answer in time. Retry in a few seconds.`);
+	}
+};
+/** osascript exceeded its budget and was killed. */
+var OsascriptTimeoutError = class extends AppleAutomationError {
+	name = "OsascriptTimeoutError";
+	constructor(timeoutMs, surface) {
+		super(`${surface.appName} did not answer within ${timeoutMs}ms. It may be mid-sync, or a permission prompt may be waiting on screen. Raise ${surface.envPrefix}_OSASCRIPT_TIMEOUT_MS if this is routine at your data size.`);
+	}
+};
+/**
+* A write was attempted while writes are disabled. Under the house pattern write
+* tools are not registered at all when `allowWrites` is off, so this is a
+* belt-and-braces guard for the library surface, not a path tools can reach.
+*/
+var WritesDisabledError = class extends AppleAutomationError {
+	name = "WritesDisabledError";
+	constructor(surface) {
+		super(`Writes are disabled. Set ${surface.envPrefix}_ALLOW_WRITES=1 to enable the mutating tools.`);
+	}
+};
+/** A read-only index could not be opened, so the file lane is unavailable. */
+var IndexUnavailableError = class extends AppleAutomationError {
+	name = "IndexUnavailableError";
+};
+/** The store's schema is not the one we know how to read. */
+var SchemaDriftError = class extends AppleAutomationError {
+	name = "SchemaDriftError";
+};
+/** The server is not running on macOS, or osascript is missing. */
+var PlatformError = class extends AppleAutomationError {
+	name = "PlatformError";
+};
+/** osascript exited 0 but did not produce the JSON envelope we require. */
+var ProtocolError = class extends AppleAutomationError {
+	name = "ProtocolError";
+};
+/** A local precondition failed before anything was sent to the app. */
+var PreconditionError = class extends AppleAutomationError {
+	name = "PreconditionError";
+};
+//#endregion
+//#region src/ax.ts
+/**
+* Borrowing the app's Accessibility driver.
+*
+* ## Why this exists at all
+*
+* `AXUIElementCopyAttributeValue` reads an attribute in **0.202 ms**. Reaching
+* the same attribute through `osascript` + JXA + System Events costs **47.4 ms**
+* — a 234x difference that is entirely transport, measured both ways on one
+* machine in `docs/desktop.md`. Every Accessibility number this repo recorded
+* before that document was taken through System Events, which is why the lane
+* was closed three times on figures that were pricing the wrong thing.
+*
+* The native call cannot be made from here. Node has no binding for it, and
+* more importantly the grant does not belong to node: TCC attaches
+* Accessibility to the **responsible GUI ancestor**, so it is Cupertino.app
+* that holds it. Hence a channel rather than a port — the app already runs the
+* driver, and `ServerHost` will lend it for one bundle id.
+*
+* ## The second grant this removes, which matters more than the speed
+*
+* Driving a UI through System Events needs Automation-to-System-Events **on top
+* of** Accessibility. Two grants, given in two different System Settings panes,
+* to reach one window. The native driver needs the first and not the second.
+*
+* ## Absence is the fallback, not an error
+*
+* `CUPERTINO_AX_SOCKET` and `CUPERTINO_AX_FOR` are set by `ServerLocator` and by
+* nothing else. A package installed from npm and run by hand has neither, and
+* that is the supported case: these are published artifacts that must work with
+* no app on the machine. `open()` returns null there, and the caller keeps
+* whatever lane it had. It never throws to say "no app".
+*
+* ## Lazy, deliberately
+*
+* Nothing connects at construction. `SurfaceCatalog` probes servers to learn
+* what they register, and a probe that opened a socket would make every capability
+* scan depend on the host being ready to answer one.
+*/
+/** The handshake `ServerHost` expects, and the reply it sends back. */
+const PROTOCOL = "cupertino/1";
+const LENT_SURFACE = "desktop";
+const OK = "ok";
+/**
+* How long one call may take.
+*
+* A walk carries its own five-second budget and the AX messaging timeout is two
+* seconds per element, so the ceiling that matters is the app's, not this one's.
+* This is only here so a host that stopped answering fails rather than hanging a
+* tool call forever.
+*/
+const CALL_TIMEOUT_MS = 3e4;
+/**
+* The app is there and said no, or stopped answering.
+*
+* Distinct from the null `openAxChannel` returns, which means there is no app
+* to ask — see the note there on why those two must not collapse.
+*/
+var AxChannelError = class extends AppleAutomationError {
+	name = "AxChannelError";
+	constructor(surface, message) {
+		super(`${surface.appName}: ${message}`, { surface: surface.appName });
+	}
+};
+/** What the host told us, when it refused the handshake. */
+const refusal = (line) => line.startsWith("err ") ? line.slice(4) : `unexpected handshake reply '${line}'`;
+/**
+* Open the channel, or return null when this server is not hosted by the app.
+*
+* Null and a throw are different answers and the difference is the whole
+* contract: null means "there is no app here, use your other lane", a throw
+* means "there is an app and it said no", which a caller must report rather
+* than paper over.
+*/
+const openAxChannel = (surface, env = process.env) => {
+	const socketPath = env.CUPERTINO_AX_SOCKET?.trim();
+	const identity = env.CUPERTINO_AX_FOR?.trim();
+	if (!socketPath || !identity) return null;
+	let socket = null;
+	let pending = Promise.resolve();
+	let nextId = 1;
+	const connectOnce = () => new Promise((resolve, reject) => {
+		const s = connect(socketPath);
+		let buffer = "";
+		const onError = (error) => {
+			s.destroy();
+			reject(new AxChannelError(surface, `cannot reach Cupertino: ${error.message}`));
+		};
+		s.once("error", onError);
+		s.setEncoding("utf8");
+		const onData = (chunk) => {
+			buffer += chunk;
+			const newline = buffer.indexOf("\n");
+			if (newline < 0) return;
+			const line = buffer.slice(0, newline).trim();
+			s.off("data", onData);
+			s.off("error", onError);
+			if (line !== OK) {
+				s.destroy();
+				reject(new AxChannelError(surface, refusal(line)));
+				return;
+			}
+			resolve(s);
+		};
+		s.on("data", onData);
+		s.write(`${PROTOCOL} ${LENT_SURFACE} for=${identity}\n`);
+	});
+	const request = async (payload) => {
+		socket ??= await connectOnce();
+		const live = socket;
+		const id = nextId++;
+		const line = `${JSON.stringify({
+			jsonrpc: "2.0",
+			id,
+			method: "tools/call",
+			params: {
+				name: payload.tool,
+				arguments: payload.args
+			}
+		})}\n`;
+		return new Promise((resolve, reject) => {
+			let buffer = "";
+			const timer = setTimeout(() => {
+				cleanup();
+				reject(new AxChannelError(surface, `${payload.tool} did not answer in ${CALL_TIMEOUT_MS}ms`));
+			}, CALL_TIMEOUT_MS);
+			const cleanup = () => {
+				clearTimeout(timer);
+				live.off("data", onData);
+				live.off("error", onError);
+				live.off("close", onClose);
+			};
+			const onError = (error) => {
+				cleanup();
+				reject(new AxChannelError(surface, `${payload.tool} failed: ${error.message}`));
+			};
+			const onClose = () => {
+				cleanup();
+				socket = null;
+				reject(new AxChannelError(surface, `Cupertino closed the connection during ${payload.tool}`));
+			};
+			const onData = (chunk) => {
+				buffer += chunk;
+				const newline = buffer.indexOf("\n");
+				if (newline < 0) return;
+				const raw = buffer.slice(0, newline);
+				cleanup();
+				let message;
+				try {
+					message = JSON.parse(raw);
+				} catch {
+					reject(new AxChannelError(surface, `unparseable reply to ${payload.tool}`));
+					return;
+				}
+				if (message.error) {
+					reject(new AxChannelError(surface, message.error.message ?? "unknown error"));
+					return;
+				}
+				const text = message.result?.content?.[0]?.text;
+				if (text === void 0) {
+					reject(new AxChannelError(surface, `empty reply to ${payload.tool}`));
+					return;
+				}
+				if (message.result?.isError === true) {
+					reject(new AxChannelError(surface, `${payload.tool}: ${text}`));
+					return;
+				}
+				try {
+					resolve(JSON.parse(text));
+				} catch {
+					resolve(text);
+				}
+			};
+			live.on("data", onData);
+			live.once("error", onError);
+			live.once("close", onClose);
+			live.write(line);
+		});
+	};
+	return {
+		call(payload) {
+			const result = pending.then(() => request(payload));
+			pending = result.then(() => void 0, () => void 0);
+			return result;
+		},
+		close() {
+			socket?.destroy();
+			socket = null;
+		}
+	};
+};
+/**
+* Start watching. `check()` answers for the span since this call.
+*
+* Returns null from `check()` when the question could not be asked at all,
+* which is not the same as "undisturbed" and must not be reported as it.
+*/
+const watchInterference = (channel) => {
+	const started = Date.now();
+	return { async check() {
+		const elapsedSeconds = (Date.now() - started) / 1e3;
+		try {
+			const secondsSinceInput = (await channel.call({
+				tool: "apple_desktop_user_activity",
+				args: {}
+			})).secondsSinceInput;
+			if (typeof secondsSinceInput !== "number") return null;
+			return {
+				disturbed: secondsSinceInput < elapsedSeconds,
+				secondsSinceInput,
+				elapsedSeconds
+			};
+		} catch {
+			return null;
+		}
+	} };
+};
+/**
+* The sentence to append to a failure, or "" when nothing useful can be said.
+*
+* Deliberately says nothing when the machine was quiet: a failure that reads
+* "nobody touched it" invites the reader to stop looking, and the point of this
+* is to send them to the RIGHT place rather than to reassure them.
+*/
+const interferenceNote = (found) => {
+	if (!found?.disturbed) return "";
+	return ` Someone used this Mac ${found.secondsSinceInput.toFixed(1)}s ago, during the ${found.elapsedSeconds.toFixed(1)}s this took — a keystroke or click lands wherever the focus is, so that alone can explain this. Retry with the machine idle before looking further.`;
+};
+//#endregion
 //#region src/build-info.ts
 /**
 * Read a package's own name and version at startup, so they are always accurate
@@ -22,6 +322,113 @@ const readPackageIdentity = (packageJsonUrl, fallback) => {
 	}
 };
 //#endregion
+//#region src/listing.ts
+/**
+* Trimming the SDK's own boilerplate out of `tools/list`.
+*
+* ## What this drops
+*
+* The SDK builds each tool's `inputSchema` from its zod shape at listing time,
+* and the generator stamps every one with
+* `"$schema": "http://json-schema.org/draft-07/schema#"`. Measured across the
+* eight servers with writes on, that one constant is 4,836 B of a 106,157 B
+* listing — 4.6%, paid by every client on every connect, to name a JSON Schema
+* draft the client already has to assume in order to read the rest of the
+* document. Nothing in the protocol reads it and no client needs it, so it is
+* the rare cut that is free rather than a trade.
+*
+* ## What this deliberately does NOT drop
+*
+* `"execution": {"taskSupport": "forbidden"}` is another 3,720 B (3.5%) of
+* identical constant — `registerTool` hardcodes it on every tool — and it looks
+* like the same kind of waste. It is not, and the difference is worth the
+* paragraph so nobody "finishes the job" later.
+*
+* Server-side the two spellings are the same: the SDK's `tools/call` path
+* branches only on `'required'` and `'optional'`, so an absent `execution` and
+* an explicit `'forbidden'` both fall through to the normal handler. Client-side
+* they are not. `taskSupport` is declared `.optional()` with no default, so
+* absence means "unspecified" rather than "forbidden", and a task-capable client
+* reading a listing with no `execution` is entitled to try task augmentation on
+* a tool that was registered without a task handler. `'forbidden'` is the value
+* that tells it not to. Dropping it would trade 930 tokens for a behavioural
+* change on a path nothing here tests.
+*
+* ## Why it is done to the outgoing frame
+*
+* The alternative seams are worse. The schema is generated inside the SDK, so
+* there is no option to pass; overriding the `tools/list` request handler means
+* reaching into `Server._requestHandlers`, a private field, and re-implementing
+* the listing it already builds. Wrapping `Transport.send` is public API, is
+* indifferent to how the listing was produced, and costs nothing on the frames
+* it does not match — every non-listing message is returned by identity below.
+*/
+/** The one key removed, spelled once. */
+const GENERATED_SCHEMA_KEY = "$schema";
+/**
+* A schema object without its `$schema` stamp, or the value unchanged.
+*
+* Returns the ORIGINAL reference when there is nothing to do, which is what
+* lets `trimToolListing` decide by identity whether it needs to rebuild
+* anything at all.
+*/
+const withoutSchemaKey = (schema) => {
+	if (schema === null || typeof schema !== "object" || Array.isArray(schema)) return schema;
+	if (!(GENERATED_SCHEMA_KEY in schema)) return schema;
+	const rest = { ...schema };
+	delete rest[GENERATED_SCHEMA_KEY];
+	return rest;
+};
+/**
+* Strip generated boilerplate from a `tools/list` reply, passing every other
+* message through untouched.
+*
+* Copies rather than mutates. The SDK hands out the registered tool's own
+* schema object, and deleting a key from it would edit the server's state from
+* a function whose job is to shape one reply.
+*/
+const trimToolListing = (message) => {
+	if (!("result" in message)) return message;
+	const result = message.result;
+	const tools = result?.tools;
+	if (!Array.isArray(tools)) return message;
+	let changed = false;
+	const trimmed = tools.map((tool) => {
+		if (tool === null || typeof tool !== "object") return tool;
+		const entry = tool;
+		const inputSchema = withoutSchemaKey(entry["inputSchema"]);
+		const outputSchema = withoutSchemaKey(entry["outputSchema"]);
+		if (inputSchema === entry["inputSchema"] && outputSchema === entry["outputSchema"]) return tool;
+		changed = true;
+		return {
+			...entry,
+			...entry["inputSchema"] === void 0 ? {} : { inputSchema },
+			...entry["outputSchema"] === void 0 ? {} : { outputSchema }
+		};
+	});
+	if (!changed) return message;
+	return {
+		...message,
+		result: {
+			...result,
+			tools: trimmed
+		}
+	};
+};
+/**
+* Wrap a transport so every listing it sends is trimmed on the way out.
+*
+* Mutates and returns the transport it was given rather than proxying it: the
+* SDK's `connect` reaches for `onmessage`, `onclose` and `onerror` on the very
+* object it was handed, and a Proxy or a subclass would have to keep those in
+* sync for no gain.
+*/
+const withTrimmedListing = (transport) => {
+	const send = transport.send.bind(transport);
+	transport.send = (message, options) => send(trimToolListing(message), options);
+	return transport;
+};
+//#endregion
 //#region src/cli.ts
 /**
 * Boot a server on stdio.
@@ -47,7 +454,7 @@ const runStdioServer = async (opts) => {
 		process.exit(1);
 	}
 	const { server, banner } = await opts.start(logger);
-	await server.connect(new StdioServerTransport());
+	await server.connect(withTrimmedListing(new StdioServerTransport()));
 	logger.warn(`${logPrefix} connected (${banner})`);
 	const shutdown = (signal) => {
 		logger.warn(`received ${signal}, shutting down`);
@@ -373,6 +780,26 @@ const BaseConfigSchema = z.object({
 	* nothing serves would be a dangling reference by configuration.
 	*/
 	exposePrompts: z.boolean().default(true),
+	/**
+	* Serve a searchable index and a dispatcher instead of the full tool list.
+	*
+	* OFF by default, and a COST knob like `exposePrompts` above rather than a
+	* safety gate — but unlike that one it is a knob that TRADES. See
+	* `facade.ts` for the mechanism; the trade is that a host's permission rule
+	* stops naming the individual tool and starts naming a direction: one rule
+	* for this surface's reads, one for its writes.
+	*
+	* What it buys, measured with writes on: ~26.5k tokens of tool definitions
+	* across the eight servers becomes a handful per surface. What it costs
+	* besides the permission granularity is a round trip — a model must search
+	* before it can call.
+	*
+	* Worth switching on only for a client that does not already defer tool
+	* schemas itself. Claude Code and Claude Desktop do, and gain nothing here
+	* while paying both costs, which is why the app declines to write the flag
+	* into their config files at all.
+	*/
+	lazyTools: z.boolean().default(false),
 	debug: z.boolean().default(false),
 	osascriptPath: z.string().default("/usr/bin/osascript"),
 	osascriptTimeoutMs: z.number().int().min(1e3).max(6e5).default(3e4),
@@ -394,74 +821,409 @@ const parseConfig = (schema, raw) => {
 	return parsed.data;
 };
 //#endregion
-//#region src/errors.ts
-/** Base class so `toFailure` can carry structured detail through in one branch. */
-var AppleAutomationError = class extends Error {
-	name = "AppleAutomationError";
-	details;
-	constructor(message, details) {
-		super(message);
-		this.details = details;
+//#region src/tools.ts
+/**
+* Compact, not pretty-printed.
+*
+* A model does not need the indentation, and it is not free: measured against
+* rows matching these servers' own types, `null, 2` adds 25-41% depending on how
+* many short keys a row carries - worst on the widest lists, which are exactly
+* the responses already big enough to matter. Every tool in every surface
+* returns through here, so this is the one place it is paid.
+*/
+const ok = (data) => ({ content: [{
+	type: "text",
+	text: JSON.stringify(data ?? { ok: true })
+}] });
+/**
+* Return text as-is. `ok()` JSON-stringifies, which turns a message body into
+* one escaped "Hi,\n\n…" line that no one can read.
+*/
+const okText = (text) => ({ content: [{
+	type: "text",
+	text
+}] });
+const fail = (message, extra) => ({
+	content: [{
+		type: "text",
+		text: JSON.stringify({
+			error: message,
+			...extra ? { details: extra } : {}
+		})
+	}],
+	isError: true
+});
+/** Render a thrown value as a tool error, preserving whatever detail it carried. */
+const toFailure = (err) => {
+	if (err instanceof AppleAutomationError) return fail(err.message, {
+		kind: err.name,
+		...err.details
+	});
+	if (err instanceof Error) {
+		const details = err.details;
+		return fail(err.message, details);
 	}
+	return fail("Unknown error", err);
 };
-/** The host process may not send Apple Events to the app (osascript -1743). */
-var TccDeniedError = class extends AppleAutomationError {
-	name = "TccDeniedError";
-	constructor(surface) {
-		super(`Not authorized to control ${surface.appName}. Grant it in System Settings > Privacy & Security > Automation > (the app running this server) > ${surface.appName}, then restart the server. If no entry appears, the first attempt was denied before the prompt could be answered — run \`tccutil reset AppleEvents\` and try again.`);
+/** Run a tool body, JSON-formatting the result and turning errors into a tool error. */
+const wrap = async (fn) => {
+	try {
+		return ok(await fn());
+	} catch (err) {
+		return toFailure(err);
 	}
 };
-/** The app is not running and the operation refuses to launch it. */
-var AppNotRunningError = class extends AppleAutomationError {
-	name = "AppNotRunningError";
-	constructor(surface) {
-		super(`${surface.appName} is not running. Read tools do not launch it, because launching it steals focus and can start a sync. Open ${surface.appName} and retry.`);
+/** Like `wrap`, but the body chooses its own result shape (e.g. a raw body). */
+const wrapResult = async (fn) => {
+	try {
+		return await fn();
+	} catch (err) {
+		return toFailure(err);
 	}
 };
-/** The app was busy and refused the Apple Event (-1712). Retried once before surfacing. */
-var AppBusyError = class extends AppleAutomationError {
-	name = "AppBusyError";
-	constructor(surface) {
-		super(`${surface.appName} is busy (probably syncing) and did not answer in time. Retry in a few seconds.`);
-	}
+/** Drop undefined values so we never send `{mailbox: undefined}` down a lane. */
+const compact = (obj) => Object.fromEntries(Object.entries(obj).filter(([, v]) => v !== void 0));
+const limitArg = z.number().int().min(1).max(200).optional().describe("Maximum number of results. Each tool states its own default; `maxResults` is the ceiling either way.");
+/**
+* Settle a caller's `limit` against the tool's default and the config ceiling.
+*
+* Written out by hand at twenty-odd call sites before this existed, in five
+* different spellings - and three surfaces spelled it `limit ?? maxResults`,
+* with no `Math.min` at all. That made their real default 200 while `limitArg`
+* told every model it was 25, so a model that trusted the description and
+* omitted the argument got eight times the rows it asked for.
+*
+* `fallback` is the tool's own documented default, not a global one: a mailbox
+* listing and a day of events do not want the same number.
+*/
+const resolveLimit = (limit, maxResults, fallback = 25) => Math.min(limit ?? fallback, maxResults);
+const confirmArg = z.literal(true).describe("Must be true. This action changes data and is not undoable from here.");
+//#endregion
+//#region src/facade.ts
+/**
+* A stand-in server that records what would have been registered.
+*
+* Typed as a whole `McpServer` and cast once, here, rather than narrowed to a
+* `Pick<…, "registerTool">` that every surface's `registerTools` would then
+* have to widen its parameter to accept — eight signatures and the ~95
+* functions beneath them, changed to describe a fact that is already true.
+*
+* The cast is safe by inspection, and the inspection is the point: all 95
+* `registerTool` call sites across the eight surfaces call this one method and
+* nothing else, and not one uses its return value. If a registrar ever reaches
+* for `registerPrompt` or `server.server`, it will fail here at runtime rather
+* than quietly registering into a void — which is why this returns a bare
+* object instead of a Proxy that would forward the difference to a real server
+* and half-register a surface.
+*/
+const recorder = (into) => ({ registerTool: (name, config, handler) => {
+	into.push({
+		name,
+		config,
+		handler
+	});
+} });
+/** Terms shorter than this are dropped: they match everything and rank nothing. */
+const SHORTEST_TERM = 3;
+/** How much of a description is printed per row. The whole of it is searched. */
+const SUMMARY_LIMIT = 160;
+const SEARCH_LIMIT = 25;
+/** Partial matches are low precision by construction, so fewer of them. */
+const PARTIAL_LIMIT = 10;
+const INDEX_LIMIT = 200;
+/**
+* Rank tiers, best first, SUMMED across the query's terms.
+*
+* Summing rather than taking the best single term is deliberate: a two-word
+* query scored on its luckiest word ranks a tool that matched one term above a
+* tool that matched both.
+*/
+const RANK = {
+	exactName: 0,
+	namePrefix: 1,
+	nameSubstring: 2,
+	summary: 3,
+	tail: 4,
+	missing: 5
 };
-/** osascript exceeded its budget and was killed. */
-var OsascriptTimeoutError = class extends AppleAutomationError {
-	name = "OsascriptTimeoutError";
-	constructor(timeoutMs, surface) {
-		super(`${surface.appName} did not answer within ${timeoutMs}ms. It may be mid-sync, or a permission prompt may be waiting on screen. Raise ${surface.envPrefix}_OSASCRIPT_TIMEOUT_MS if this is routine at your data size.`);
-	}
+const summarize = (description) => {
+	const flat = description.replace(/\s+/g, " ").trim();
+	return flat.length <= SUMMARY_LIMIT ? flat : `${flat.slice(0, 159).trimEnd()}…`;
+};
+const index = (decl) => {
+	const description = decl.config.description ?? "";
+	const summary = summarize(description);
+	return {
+		name: decl.name,
+		summary,
+		head: `${decl.name} ${summary}`.toLowerCase(),
+		whole: `${decl.name} ${description}`.toLowerCase()
+	};
 };
 /**
-* A write was attempted while writes are disabled. Under the house pattern write
-* tools are not registered at all when `allowWrites` is off, so this is a
-* belt-and-braces guard for the library surface, not a path tools can reach.
+* Regular plural fold, guarded.
+*
+* The guards are the whole point: without them `status` searches for `statu`,
+* `class` for `clas` and `focus` for `focu`, and a three-letter term like `ios`
+* loses a third of itself.
 */
-var WritesDisabledError = class extends AppleAutomationError {
-	name = "WritesDisabledError";
-	constructor(surface) {
-		super(`Writes are disabled. Set ${surface.envPrefix}_ALLOW_WRITES=1 to enable the mutating tools.`);
+const singular = (term) => {
+	if (term.length <= SHORTEST_TERM) return term;
+	if (term.endsWith("ss") || term.endsWith("us")) return term;
+	return term.endsWith("s") ? term.slice(0, -1) : term;
+};
+const queryTerms = (query) => {
+	const seen = /* @__PURE__ */ new Set();
+	const out = [];
+	for (const raw of query.toLowerCase().split(/\s+/)) {
+		const term = raw.trim();
+		if (term.length < SHORTEST_TERM || seen.has(term)) continue;
+		seen.add(term);
+		out.push(term);
 	}
+	return out;
 };
-/** A read-only index could not be opened, so the file lane is unavailable. */
-var IndexUnavailableError = class extends AppleAutomationError {
-	name = "IndexUnavailableError";
+const rankTerm = (term, entry) => {
+	const name = entry.name.toLowerCase();
+	const folded = singular(term);
+	const hit = (haystack) => haystack.includes(term) || haystack.includes(folded);
+	if (name === term) return RANK.exactName;
+	if (name.startsWith(term)) return RANK.namePrefix;
+	if (hit(name)) return RANK.nameSubstring;
+	if (hit(entry.head)) return RANK.summary;
+	if (hit(entry.whole)) return RANK.tail;
+	return RANK.missing;
 };
-/** The store's schema is not the one we know how to read. */
-var SchemaDriftError = class extends AppleAutomationError {
-	name = "SchemaDriftError";
+/**
+* Find tools for a query.
+*
+* An empty query returns the server's OWN order rather than an alphabetised
+* one: the registrars group related tools together, and sorting throws that
+* grouping away for no gain.
+*
+* Nothing may cache this keyed on the query — a row's tier is a property of the
+* query AND of the whole catalog it was ranked against.
+*/
+const find = (entries, query) => {
+	const terms = queryTerms(query);
+	if (terms.length === 0) return {
+		rows: entries.slice(0, INDEX_LIMIT),
+		matched: entries.length,
+		missed: [],
+		partial: false
+	};
+	const scored = entries.map((entry) => {
+		let total = 0;
+		let matched = 0;
+		const missed = [];
+		for (const term of terms) {
+			const rank = rankTerm(term, entry);
+			total += rank;
+			if (rank === RANK.missing) missed.push(term);
+			else matched += 1;
+		}
+		return {
+			entry,
+			total,
+			matched,
+			missed
+		};
+	});
+	const best = scored.reduce((acc, s) => Math.max(acc, s.matched), 0);
+	if (best === 0) return {
+		rows: [],
+		matched: 0,
+		missed: terms,
+		partial: false
+	};
+	const group = scored.filter((s) => s.matched === best).toSorted((a, b) => a.total - b.total || a.entry.name.localeCompare(b.entry.name));
+	const partial = best < terms.length;
+	const missed = partial ? terms.filter((t) => group.every((g) => g.missed.includes(t))) : [];
+	return {
+		rows: group.slice(0, partial ? PARTIAL_LIMIT : SEARCH_LIMIT).map((g) => g.entry),
+		matched: group.length,
+		missed,
+		partial
+	};
 };
-/** The server is not running on macOS, or osascript is missing. */
-var PlatformError = class extends AppleAutomationError {
-	name = "PlatformError";
+/**
+* Suggestions for a name that is not in the catalog.
+*
+* Substring search cannot find a string that appears nowhere, so a typo needs
+* its own answer: shared underscore-separated words first, then the longest
+* common prefix.
+*
+* Both comparisons run on the name with `apple_<surface>_` REMOVED. Every tool
+* on a surface shares that prefix, so comparing whole names makes every tool
+* share two words with every other and "did you mean" answers with the first
+* few tools in the catalog — worse than saying nothing, because it reads like a
+* real suggestion. Measured before the fix: `apple_mail_send_messge` suggested
+* `apple_mail_list_accounts`.
+*/
+const nearest = (names, wanted, prefix) => {
+	const strip = (n) => n.toLowerCase().startsWith(`${prefix}_`) ? n.slice(prefix.length + 1) : n;
+	const target = strip(wanted);
+	const words = new Set(target.toLowerCase().split("_").filter((w) => w.length >= SHORTEST_TERM));
+	const shared = names.filter((n) => strip(n).toLowerCase().split("_").some((w) => words.has(w)));
+	if (shared.length > 0) return shared.slice(0, 5);
+	const common = (n) => {
+		const candidate = strip(n).toLowerCase();
+		const lower = target.toLowerCase();
+		let i = 0;
+		while (i < candidate.length && i < lower.length && candidate[i] === lower[i]) i += 1;
+		return i;
+	};
+	const ranked = names.toSorted((a, b) => common(b) - common(a) || a.localeCompare(b));
+	const bestName = ranked[0];
+	if (bestName === void 0 || common(bestName) < SHORTEST_TERM) return [];
+	return ranked.filter((n) => common(n) >= SHORTEST_TERM).slice(0, 3);
 };
-/** osascript exited 0 but did not produce the JSON envelope we require. */
-var ProtocolError = class extends AppleAutomationError {
-	name = "ProtocolError";
+const renderSearch = (result, total, names) => {
+	if (result.rows.length === 0) return `No tool matches. ${total} tools are available — call ${names.search} with no query to list them all.`;
+	const rows = result.rows.map((r) => `${r.name} — ${r.summary}`).join("\n");
+	let notice = "";
+	if (result.partial) notice = `No tool matched every word${result.missed.length > 0 ? ` (no match for ${result.missed.join(", ")})` : ""}. Closest:\n`;
+	const footer = `${result.rows.length} of ${total} tools. Read a schema with ${names.describe}, then run it with ${names.call}.`;
+	return `${notice}${rows}\n\n${footer}`;
 };
-/** A local precondition failed before anything was sent to the app. */
-var PreconditionError = class extends AppleAutomationError {
-	name = "PreconditionError";
+/**
+* A tool's declaration as a client would have received it.
+*
+* Built from the recorded zod shape rather than re-derived by hand, so
+* `describe` and a non-lazy listing cannot drift. `$schema` is dropped for the
+* same reason `listing.ts` drops it from `tools/list`.
+*/
+const describe = (decl) => {
+	const shape = decl.config.inputSchema;
+	const schema = shape ? z.toJSONSchema(z.object(shape)) : void 0;
+	if (schema) delete schema["$schema"];
+	return {
+		name: decl.name,
+		...decl.config.description === void 0 ? {} : { description: decl.config.description },
+		...schema === void 0 ? {} : { inputSchema: schema },
+		...decl.config.annotations === void 0 ? {} : { annotations: decl.config.annotations }
+	};
+};
+/**
+* Run a recorded tool, reproducing the validation the SDK would have done.
+*
+* Under a facade the SDK never sees the real call, so it never parses the real
+* arguments. Skipping this would hand every handler unvalidated input — the one
+* way a facade can be actively less safe than the listing it replaced.
+*/
+const invoke = async (decl, args, extra) => {
+	const shape = decl.config.inputSchema;
+	if (!shape) return decl.handler(extra);
+	const parsed = await z.object(shape).safeParseAsync(args ?? {});
+	if (!parsed.success) {
+		const why = parsed.error.issues.map((i) => `${i.path.join(".") || "(root)"}: ${i.message}`).join("; ");
+		return fail(`Invalid arguments for ${decl.name}: ${why}`);
+	}
+	return decl.handler(parsed.data, extra);
+};
+/**
+* Register a surface's tools, either directly or behind the facade.
+*
+* The callback takes `allowWrites` rather than closing over it so the facade
+* can run it a second time with the gate forced shut and learn which tools are
+* writes. Everything else it needs — the client, the config — it closes over as
+* before.
+*/
+const withLazyTools = (server, opts, register) => {
+	if (!opts.lazy) {
+		register(server, opts.allowWrites);
+		return;
+	}
+	const all = [];
+	register(recorder(all), opts.allowWrites);
+	let writeNames = /* @__PURE__ */ new Set();
+	if (opts.allowWrites) {
+		const readsOnly = [];
+		register(recorder(readsOnly), false);
+		const readNames = new Set(readsOnly.map((d) => d.name));
+		writeNames = new Set(all.filter((d) => !readNames.has(d.name)).map((d) => d.name));
+	}
+	const prefix = `apple_${opts.surface}`;
+	const eagerName = `${prefix}_diagnostics`;
+	const eager = all.filter((d) => d.name === eagerName);
+	for (const decl of eager) server.registerTool(decl.name, decl.config, decl.handler);
+	const lazy = all.filter((d) => d.name !== eagerName);
+	const reads = lazy.filter((d) => !writeNames.has(d.name));
+	const writes = lazy.filter((d) => writeNames.has(d.name));
+	const byName = new Map(lazy.map((d) => [d.name, d]));
+	const readIndex = reads.map(index);
+	const writeIndex = writes.map(index);
+	const allIndex = [...readIndex, ...writeIndex];
+	const searchName = `${prefix}_search_tools`;
+	const describeName = `${prefix}_describe_tool`;
+	const callName = `${prefix}_call_tool`;
+	const callWriteName = `${prefix}_call_write_tool`;
+	server.registerTool(searchName, {
+		description: `Find ${opts.displayName} tools by what you want to do. This server loads its ${allIndex.length} tools on demand: they are not listed up front, and this is how you reach them. Returns matching tool names with a one-line summary each. Call with no query to list everything. Read a schema with ${describeName}, then run it with ${callName}` + (writes.length > 0 ? ` or ${callWriteName}` : "") + `.`,
+		inputSchema: { query: z.string().optional().describe("What you want to do, e.g. 'search messages' or 'unread'. Omit to list all.") },
+		annotations: {
+			readOnlyHint: true,
+			idempotentHint: true
+		}
+	}, ({ query }) => okText(renderSearch(find(allIndex, query ?? ""), allIndex.length, {
+		search: searchName,
+		describe: describeName,
+		call: callName
+	})));
+	server.registerTool(describeName, {
+		description: `Get the full description and input schema of one ${opts.displayName} tool, as it would have appeared in a normal tool listing. Find names with ${searchName} first.`,
+		inputSchema: { name: z.string().describe(`Exact tool name, e.g. ${lazy[0]?.name ?? callName}.`) },
+		annotations: {
+			readOnlyHint: true,
+			idempotentHint: true
+		}
+	}, ({ name }) => {
+		const decl = byName.get(name);
+		if (!decl) {
+			const suggestions = nearest([...byName.keys()], name, prefix);
+			return fail(`No tool named ${name}.` + (suggestions.length > 0 ? ` Did you mean: ${suggestions.join(", ")}?` : ""));
+		}
+		const runner = writeNames.has(name) ? callWriteName : callName;
+		return okText(`${JSON.stringify(describe(decl))}\n\nCall it with ${runner}: {"name": ${JSON.stringify(name)}, "arguments": {…}}.`);
+	});
+	server.registerTool(callName, {
+		description: `Run one of this server's read-only ${opts.displayName} tools. Find a name with ${searchName} and its arguments with ${describeName}. Reads only: it cannot reach ` + (writes.length > 0 ? `anything that changes ${opts.displayName} — those go through ${callWriteName}.` : `anything that changes ${opts.displayName}, and this server has writes turned off.`),
+		inputSchema: {
+			name: z.string().describe("Exact tool name to run."),
+			arguments: z.record(z.string(), z.unknown()).optional().describe("That tool's arguments.")
+		},
+		annotations: { readOnlyHint: true }
+	}, async ({ name, arguments: args }, extra) => {
+		const decl = byName.get(name);
+		if (!decl) {
+			const suggestions = nearest([...byName.keys()], name, prefix);
+			return fail(`No tool named ${name}.` + (suggestions.length > 0 ? ` Did you mean: ${suggestions.join(", ")}?` : ""));
+		}
+		if (writeNames.has(name)) return fail(`${name} changes ${opts.displayName}, so it cannot be run through ${callName}. Use ${callWriteName}.`);
+		return await invoke(decl, args, extra);
+	});
+	if (writes.length > 0) {
+		const writeList = writes.map((d) => d.name.slice(prefix.length + 1)).join(", ");
+		server.registerTool(callWriteName, {
+			description: `Run one of this server's ${writes.length} ${opts.displayName} tools that CHANGE data — ${writeList}. Find arguments with ${describeName}. Read-only tools go through ${callName} instead.`,
+			inputSchema: {
+				name: z.string().describe("Exact tool name to run."),
+				arguments: z.record(z.string(), z.unknown()).optional().describe("That tool's arguments.")
+			},
+			annotations: {
+				readOnlyHint: false,
+				destructiveHint: true
+			}
+		}, async ({ name, arguments: args }, extra) => {
+			const decl = byName.get(name);
+			if (!decl) {
+				const suggestions = nearest([...writeNames], name, prefix);
+				return fail(`No tool named ${name}.` + (suggestions.length > 0 ? ` Did you mean: ${suggestions.join(", ")}?` : ""));
+			}
+			if (!writeNames.has(name)) return fail(`${name} is read-only. Use ${callName}.`);
+			return await invoke(decl, args, extra);
+		});
+	}
 };
 //#endregion
 //#region src/fs.ts
@@ -966,84 +1728,6 @@ const openReadOnly = (path, mode, opts = {}) => {
 	throw new IndexUnavailableError(`Could not open ${opts.label ?? path} at ${path}: ${message}.${opts.hint ? ` ${opts.hint}` : ""}`);
 };
 //#endregion
-//#region src/tools.ts
-/**
-* Compact, not pretty-printed.
-*
-* A model does not need the indentation, and it is not free: measured against
-* rows matching these servers' own types, `null, 2` adds 25-41% depending on how
-* many short keys a row carries - worst on the widest lists, which are exactly
-* the responses already big enough to matter. Every tool in every surface
-* returns through here, so this is the one place it is paid.
-*/
-const ok = (data) => ({ content: [{
-	type: "text",
-	text: JSON.stringify(data ?? { ok: true })
-}] });
-/**
-* Return text as-is. `ok()` JSON-stringifies, which turns a message body into
-* one escaped "Hi,\n\n…" line that no one can read.
-*/
-const okText = (text) => ({ content: [{
-	type: "text",
-	text
-}] });
-const fail = (message, extra) => ({
-	content: [{
-		type: "text",
-		text: JSON.stringify({
-			error: message,
-			...extra ? { details: extra } : {}
-		})
-	}],
-	isError: true
-});
-/** Render a thrown value as a tool error, preserving whatever detail it carried. */
-const toFailure = (err) => {
-	if (err instanceof AppleAutomationError) return fail(err.message, {
-		kind: err.name,
-		...err.details
-	});
-	if (err instanceof Error) {
-		const details = err.details;
-		return fail(err.message, details);
-	}
-	return fail("Unknown error", err);
-};
-/** Run a tool body, JSON-formatting the result and turning errors into a tool error. */
-const wrap = async (fn) => {
-	try {
-		return ok(await fn());
-	} catch (err) {
-		return toFailure(err);
-	}
-};
-/** Like `wrap`, but the body chooses its own result shape (e.g. a raw body). */
-const wrapResult = async (fn) => {
-	try {
-		return await fn();
-	} catch (err) {
-		return toFailure(err);
-	}
-};
-/** Drop undefined values so we never send `{mailbox: undefined}` down a lane. */
-const compact = (obj) => Object.fromEntries(Object.entries(obj).filter(([, v]) => v !== void 0));
-const limitArg = z.number().int().min(1).max(200).optional().describe("Maximum number of results. Each tool states its own default; `maxResults` is the ceiling either way.");
-/**
-* Settle a caller's `limit` against the tool's default and the config ceiling.
-*
-* Written out by hand at twenty-odd call sites before this existed, in five
-* different spellings - and three surfaces spelled it `limit ?? maxResults`,
-* with no `Math.min` at all. That made their real default 200 while `limitArg`
-* told every model it was 25, so a model that trusted the description and
-* omitted the argument got eight times the rows it asked for.
-*
-* `fallback` is the tool's own documented default, not a global one: a mailbox
-* listing and a day of events do not want the same number.
-*/
-const resolveLimit = (limit, maxResults, fallback = 25) => Math.min(limit ?? fallback, maxResults);
-const confirmArg = z.literal(true).describe("Must be true. This action changes data and is not undoable from here.");
-//#endregion
-export { AppBusyError, AppNotRunningError, AppleAutomationError, BaseConfigSchema, CORE_DATA_EPOCH_OFFSET, IndexUnavailableError, OsascriptTimeoutError, PlatformError, PreconditionError, ProtocolError, RESOURCE_SCHEME, SchemaDriftError, TccDeniedError, WritesDisabledError, assertStaticScript, columnsOf, compact, confirmArg, createOsascriptRunner, describeAggregation, describeStore, detectEpoch, escapeLike, extractCode, fail, fingerprintSchema, groupByArg, inspectFile, limitArg, mapOsaError, ok, okText, openReadOnly, parseBool, parseConfig, parseIntOpt, parseList, project, promptArg, readPackageIdentity, registerSurfaceResources, registerWorkflowPrompt, requiredPromptArg, resolveLimit, runStdioServer, selectArg, surfaceUri, tableMap, toFailure, toFileUri, trimmed, withBusyRetry, wrap, wrapResult };
+export { AppBusyError, AppNotRunningError, AppleAutomationError, AxChannelError, BaseConfigSchema, CORE_DATA_EPOCH_OFFSET, IndexUnavailableError, OsascriptTimeoutError, PlatformError, PreconditionError, ProtocolError, RESOURCE_SCHEME, SchemaDriftError, TccDeniedError, WritesDisabledError, assertStaticScript, columnsOf, compact, confirmArg, createOsascriptRunner, describeAggregation, describeStore, detectEpoch, escapeLike, extractCode, fail, fingerprintSchema, groupByArg, inspectFile, interferenceNote, limitArg, mapOsaError, ok, okText, openAxChannel, openReadOnly, parseBool, parseConfig, parseIntOpt, parseList, project, promptArg, readPackageIdentity, registerSurfaceResources, registerWorkflowPrompt, requiredPromptArg, resolveLimit, runStdioServer, selectArg, surfaceUri, tableMap, toFailure, toFileUri, trimToolListing, trimmed, watchInterference, withBusyRetry, withLazyTools, withTrimmedListing, wrap, wrapResult };
 
 //# sourceMappingURL=index.js.map