Cupertino 1.3.0

Two new mutations for Mail (a mailbox, and a rewrite of an unsent draft) and one for Messages (saving an attachment), plus Calendar's first read of the negative space between events. Every server also exposes prompts and resources now, not only tools — see docs/prompts-and-resources.md.

Added

• Calendar answers "when am I free". apple_calendar_find_availability returns the gaps between events, inside working hours, long enough to hold a meeting of a given length. It is not list_events with arithmetic bolted on: it returns the COMPLEMENT of what it read, so every shortfall that merely under-informs a listing instead invents a slot that is already booked. The busy set is complete or there is no answer — a saturated scan, a store that expands no repeating events, and a window past the occurrence cache's edge each return degraded: true with a reason rather than a short list. An empty slots means booked; degraded means unknown, and the two are never the same value. Declined and cancelled events do not block time; all-day events do not either, but they are reported next to the slots so a holiday is visible before it is booked over. Working hours default to 09:00–18:00 on weekdays and are set by APPLE_CALENDAR_WORKDAY_START, APPLE_CALENDAR_WORKDAY_END and APPLE_CALENDAR_WORKDAYS.

• Messages can save an attachment. apple_messages_save_attachment copies a photo, video, PDF or voice memo out of a conversation. Mail and Notes have had this since 1.0; Messages listed attachments and then left you with no way to get one. Write-gated like the other two, because it puts a file on the user's disk — it sends no Apple Event and changes nothing in Messages, so the claim that writes-off means no Automation grant still holds. Attachments now carry an id (the attachment's guid, never its reusable ROWID) on apple_messages_get_message. An attachment iCloud has offloaded is reported as offloaded rather than as a failure.

• Every server now exposes prompts and resources, not just tools. Three resources per surface: cupertino://<surface>/guide is the operating manual and is STATIC, so it still reads on a server whose every grant is denied — which is exactly when it is worth reading; cupertino://<surface>/diagnostics serves the diagnostics tool's own payload, addressable without spending a call and before the confusing answer rather than after it; and cupertino://<surface>/inventory holds the accounts, mailboxes, folders, lists or calendars that every other tool takes as an argument. Contacts, Messages and Safari register only the first two — a contact is reached by searching and never by naming its store, chats are unbounded, and history, tabs and the Reading List are three queries rather than three folders. A resource read that fails returns degraded DATA rather than a JSON-RPC error, because a protocol error would delete the diagnostics report at the one moment anyone wants it. The scheme is cupertino:// and not apple://: a URI scheme is a namespace claim, and taking Apple's would read as the affiliation the README disclaims.

• Thirteen workflow prompts, one to three per surface. They hold what no tool description can: not what a call does, but what order the calls go in. apple_mail_triage searches instead of paging; apple_mail_draft_reply reads the thread first and fills the body, because reply_to_message without one leaves an EMPTY draft that must never be reported as a written reply; apple_reminders_capture_action_items searches before creating, because nothing on that surface deduplicates; apple_calendar_schedule says out loud that nobody was invited, since this server has no attendees parameter anywhere on purpose; apple_contacts_who_is refuses to guess between ambiguous matches; apple_messages_send confirms the handle before an action with no undo, and treats reconciliation: "pending" as SENT rather than as something to retry. Each prompt embeds its surface guide, so a host expanding one hands the model the reference with the task. Write-gated prompts follow the write tools exactly — with writes off they are not refused, they are not registered.

• Mail can rewrite an unsent draft. apple_mail_update_draft replaces a saved draft's body. Mail offers no way to edit one — message.content is read-only and the dictionary has no open and no edit command — so the tool recreates the draft and deletes the original only once the replacement is confirmed present in Drafts, never the other way round. It refuses rather than doing damage: a reply or forward draft (recreating it would drop In-Reply-To and silently start a new thread), a draft carrying attachments (they cannot be re-attached), and anything outside the Drafts mailbox (deleting a sent message and writing a lookalike is not editing). In every refusal the original is untouched. The dictionary evidence behind all of this is now written down in docs/mail-compose.md, including that outgoing message.html content is documented by Apple as "Does nothing at all (deprecated)" — a write-only property that accepts every assignment and does nothing, which is the first thing anyone tries. Two further findings came from probing a live Mail and contradict the dictionary outright: account.draftsMailbox is declared readable and raises "Can't get object." on every account (iCloud, IMAP, Exchange), so the Drafts mailbox is discovered through the unified All Drafts mailbox instead of trusting the documented property; and a freshly saved draft's row id is rewritten by sync within seconds, killing any reference held across it, so the original is refetched by id immediately before deletion. save() itself works and lands in under 400 ms.

• APPLE_<SURFACE>_EXPOSE_PROMPTS turns the prompts and resources off, defaulting to ON — the opposite of ALLOW_WRITES, and deliberately. That one is a safety invariant; this is a cost knob in the family of MAX_RESULTS, and modelling it on the write gate would muddy the gate that matters. Measured across all seven servers with writes on, the prompt and resource listings come to ~3.4k tokens against ~18.5k for the tool definitions — about 18% on top of a bill tools dominate either way, with resource contents costing nothing until something reads one. One flag covers both, because a prompt embeds its surface guide and prompts without resources would name a cupertino://…/guide that nothing serves. With it off the capability is never declared, so a client asking gets "method not found" rather than an empty list. diagnostics reports the flag on every surface, since that tool is still registered when the resources are not.

• The app shows each surface's live tool, prompt and resource catalog. A Capabilities card on the surface detail pane spawns that surface's server and asks it directly — initialize, tools/list, prompts/list, resources/list — rather than keeping a hand-written copy that could drift from the servers it describes. Cached per surface AND per write setting, so flipping Allow writes re-probes instead of showing a stale list: that is the point, because this is the only place the app's long-standing claim that writes-off means the mutating tools (and now the prompts that end in one) are never registered rather than refused is actually demonstrated, on screen, live.

• Mail can create a mailbox. apple_mail_create_mailbox makes the folder that apple_mail_move_messages needs to move into — nested with /, or local under On My Mac when no account is named. Calling it for a name that already exists does nothing and says so, so it is safe to call before a move. On a server account it creates the folder ON THE SERVER, which syncs to every device; the tool's description says so and it takes confirm.

Fixed

• The Activity window under-reported what an agent did. RequestObserver named the tool behind a tools/call and counted it, but let prompts/get and resources/read fall through as bare method names that counted as nothing — so expanding a write workflow like apple_mail_draft_reply logged less than a single read. Both now log what they reached for, and both count. The footer under the log grew to match ("Tool, prompt and resource names only — never arguments, message contents or results"): it is load-bearing rather than decoration, and the alternative to growing it was leaving it false.

• The host stopped answering after about 64 sessions, silently. ServerHost ran every blocking part of a session — the two pumps, the stderr drain, and the group.wait() that outlives them — on libdispatch's global queues, which are a bounded pool of roughly 64 threads per QoS. A blocked thread is not an available one, so sessions consumed the pool rather than sharing it, and past the limit newly submitted blocks were never scheduled at all. The block that never ran was serve(client): accept kept succeeding, so every new bridge completed its connect, wrote its handshake, and then waited forever on a reply from a function that had not started. Nothing logged an error, because from the host's side nothing had failed. Measured on a host up three days: 68 threads parked in _dispatch_group_wait_slow, acceptLoop healthy and blocked in accept, 68 server processes still alive because their pumps had never run to hand them an EOF, 955 open descriptors, and a probe getting zero bytes back in eight seconds from a socket that accepted it in two. Pumps, drains and sessions now each get a thread of their own, and the stderr drain is no longer a member of the group that gates teardown — logging is not plumbing, and a group member that only ends when the child exits makes every teardown hostage to the child agreeing to go.

• A wedged host produced immortal bridges instead of an error. cupertino-bridge waited on the handshake reply with no deadline and nothing watching stdin, so a host that accepted but never answered left the relay alive indefinitely — 67 of them parented to launchd, each still pinning a session's descriptors and threads on the app side, which fed the condition that caused it. The handshake now has a 15s SO_RCVTIMEO and says what it means, and the relay ends when either direction closes: previously only Cupertino hanging up could end it, so a host that quit was never reason enough for the bridge to stop.

• Four tools returned their payload wrapped twice. wrap() JSON-encodes whatever its body returns, and apple_messages_get_message, apple_contacts_get_contact, apple_contacts_create_contact and apple_contacts_update_contact had bodies that returned ok(…) themselves — so the text a client received was a serialised tool result with the real answer one decode further in. The same mistake swallowed fail(): a ref that no longer resolved came back as a SUCCESSFUL call carrying isError as data. All four now use wrapResult(). Nothing caught it because every assertion read a field off the parsed text and got undefined, which reads as "absent" rather than "wrapped twice"; there are now tests on the envelope itself.