apple-tools-mcp 2.0.0 → 2.0.2

package/lib/contactsWrite.js

@@ -9,7 +9,15 @@
  * writing that database directly corrupts iCloud sync.
  */
 
-import { runAppleScript, asString, CONTACTS_TCC_GUIDANCE, ATTRIBUTION_GUIDANCE } from "./appleScript.js";
+import {
+  runAppleScript,
+  asString,
+  formatOsascriptDiagnostic,
+  CONTACTS_TCC_GUIDANCE,
+  CONTACTS_APP_NOT_RUNNING_GUIDANCE,
+  ATTRIBUTION_GUIDANCE
+} from "./appleScript.js";
+import { safeOpenApp } from "./shell.js";
 import {
   planWrite,
   normalizeList,
@@ -75,14 +83,128 @@ function childLines(items, kind, personVar) {
     .join("\n");
 }
 
+export const CONTACTS_READY_ATTEMPTS = 16;
+export const CONTACTS_READY_INTERVAL_MS = 500;
+export const CONTACTS_OPEN_RETRY_EVERY = 4;
+/** Wall-clock cap so ensure + CRUD stay under the 90s write-bridge timeout. */
+export const CONTACTS_READY_BUDGET_MS = 20000;
+export const CONTACTS_LAUNCH_TIMEOUT_MS = 4000;
+export const CONTACTS_READY_SCRIPT_TIMEOUT_MS = 2000;
+
+export function buildContactsLaunchScript() {
+  // launch only — activate waits until Contacts is frontmost and a slow
+  // cold start can ETIMEDOUT, which must not abort the ready poll as TCC.
+  return `tell application "Contacts" to launch`;
+}
+
+export function buildContactsReadyScript() {
+  return `tell application "Contacts" to get name`;
+}
+
+export function contactsAppIsReady(output) {
+  const text = String(output || "").trim().toLowerCase();
+  return text === "contacts" || text === "ready";
+}
+
+export function sleepMs(ms) {
+  if (!Number.isFinite(ms) || ms <= 0) return;
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, Math.min(ms, 5000));
+}
+
+/**
+ * Cold `tell application "Contacts"` under launchd often returns -600
+ * instead of auto-launching. Prefer `open -a Contacts` in *this* process
+ * (the write-bridge daemon when routed), then `launch` (not `activate`),
+ * then poll until a trivial AppleScript (`get name`) responds.
+ * A launch/ready ETIMEDOUT is a slow cold start, not Automation — keep polling.
+ */
+function isFatalContactsReadyKind(kind) {
+  return kind === "tcc" || kind === "attribution" || kind === "app_unavailable";
+}
+
+function tryOpenContacts(openApp) {
+  try {
+    openApp("Contacts");
+    return { ok: true };
+  } catch (e) {
+    return { ok: false, error: e && e.message ? e.message : String(e) };
+  }
+}
+
+export function ensureContactsAppReady({
+  run = runAppleScript,
+  sleep = sleepMs,
+  openApp = safeOpenApp,
+  attempts = CONTACTS_READY_ATTEMPTS,
+  intervalMs = CONTACTS_READY_INTERVAL_MS,
+  openRetryEvery = CONTACTS_OPEN_RETRY_EVERY,
+  budgetMs = CONTACTS_READY_BUDGET_MS,
+  launchTimeoutMs = CONTACTS_LAUNCH_TIMEOUT_MS,
+  readyTimeoutMs = CONTACTS_READY_SCRIPT_TIMEOUT_MS,
+  now = Date.now
+} = {}) {
+  const started = now();
+  const remaining = () => budgetMs - (now() - started);
+  const slice = (maxMs) => Math.max(0, Math.min(maxMs, remaining()));
+
+  tryOpenContacts(openApp);
+
+  const launchBudget = slice(launchTimeoutMs);
+  const launch = launchBudget > 0
+    ? run(buildContactsLaunchScript(), { timeout: launchBudget, appName: "Contacts" })
+    : { ok: false, kind: "app_not_running", error: "Contacts ensure budget exhausted before launch", output: "" };
+  if (!launch.ok && isFatalContactsReadyKind(launch.kind)) {
+    return launch;
+  }
+
+  const tries = Math.max(1, attempts);
+  const retryEvery = Math.max(0, openRetryEvery);
+  let last = launch;
+  for (let i = 0; i < tries; i++) {
+    if (remaining() <= 0) break;
+    if (i > 0 && retryEvery > 0 && i % retryEvery === 0) {
+      tryOpenContacts(openApp);
+    }
+    const readyBudget = slice(readyTimeoutMs);
+    if (readyBudget <= 0) break;
+    const ready = run(buildContactsReadyScript(), { timeout: readyBudget, appName: "Contacts" });
+    last = ready;
+    if (ready.ok && contactsAppIsReady(ready.output)) {
+      return { ok: true, kind: null };
+    }
+    if (!ready.ok && isFatalContactsReadyKind(ready.kind)) {
+      return ready;
+    }
+    const pause = slice(intervalMs);
+    if (i < tries - 1 && pause > 0) sleep(pause);
+  }
+
+  if (last && last.ok === false && isFatalContactsReadyKind(last.kind)) {
+    return last;
+  }
+  if (last && last.ok === false && last.kind === "app_not_running") {
+    return last;
+  }
+
+  return {
+    ok: false,
+    kind: "app_not_running",
+    error: (last && last.error) || (launch && launch.error) || "Contacts.app did not become ready after launch",
+    output: ""
+  };
+}
+
 function failure(action, summary, result, secrets = []) {
-  if (result.kind === "tcc") {
+  if (result.kind === "tcc" || result.kind === "timeout") {
     return `${action} failed — attempted to ${summary}. ${CONTACTS_TCC_GUIDANCE}`;
   }
   const raw = String(result.error || "");
   if (raw.includes("CONTACT_NOT_FOUND")) {
     return `${action} failed — attempted to ${summary}. No contact with that id was found; use the Contact ID from contacts_search or contacts_lookup.`;
   }
+  if (result.kind === "app_not_running") {
+    return `${action} failed — attempted to ${summary}. ${CONTACTS_APP_NOT_RUNNING_GUIDANCE} ${formatOsascriptDiagnostic(result)}`;
+  }
   if (result.kind === "attribution") {
     return `${action} failed — attempted to ${summary}. ${ATTRIBUTION_GUIDANCE}`;
   }
@@ -105,7 +227,7 @@ end tell
 return newId`;
 }
 
-export function contactsAdd(args = {}) {
+export function contactsAdd(args = {}, deps = {}) {
   const action = "contacts_add";
 
   const firstName = validateSubject(args.first_name);
@@ -140,6 +262,9 @@ export function contactsAdd(args = {}) {
   if (organization.text) properties.organization = organization.text;
   if (jobTitle.text) properties["job title"] = jobTitle.text;
 
+  const ready = ensureContactsAppReady(deps);
+  if (!ready.ok) return { ok: false, message: failure(action, summary, ready) };
+
   const result = runAppleScript(
     buildAddContactScript({ properties, emails: emails.emails, phones: phones.phones }),
     { timeout: 60000, appName: "Contacts" }
@@ -181,7 +306,7 @@ end tell
 return editedName`;
 }
 
-export function contactsEdit(args = {}) {
+export function contactsEdit(args = {}, deps = {}) {
   const action = "contacts_edit";
 
   const contactId = validateContactId(args.contact_id);
@@ -234,6 +359,9 @@ export function contactsEdit(args = {}) {
   });
   if (!plan.proceed) return { ok: true, message: plan.message, planned: true };
 
+  const ready = ensureContactsAppReady(deps);
+  if (!ready.ok) return { ok: false, message: failure(action, summary, ready) };
+
   const result = runAppleScript(
     buildEditContactScript({
       contactId,
@@ -269,7 +397,7 @@ end tell
 return removedName`;
 }
 
-export function contactsRemove(args = {}) {
+export function contactsRemove(args = {}, deps = {}) {
   const action = "contacts_remove";
 
   const contactId = validateContactId(args.contact_id);
@@ -287,6 +415,9 @@ export function contactsRemove(args = {}) {
   });
   if (!plan.proceed) return { ok: true, message: plan.message, planned: true };
 
+  const ready = ensureContactsAppReady(deps);
+  if (!ready.ok) return { ok: false, message: failure(action, summary, ready) };
+
   const result = runAppleScript(buildRemoveContactScript(contactId), { timeout: 60000, appName: "Contacts" });
   if (!result.ok) return { ok: false, message: failure(action, summary, result) };
 
@@ -298,3 +429,59 @@ export function contactsRemove(args = {}) {
     })
   };
 }
+
+/**
+ * First-run / upgrade probe: the Contacts write verb that triggers
+ * Automation → Contacts. Creates a clearly named throwaway person and
+ * deletes it in the same script so a completed run leaves no junk.
+ */
+export const CONTACTS_AUTOMATION_PROBE_FIRST = "ATM";
+export const CONTACTS_AUTOMATION_PROBE_LAST = "Permissions Probe";
+
+export function buildContactsAutomationProbeScript() {
+  return `tell application "Contacts"
+  set probe to make new person with properties {first name:${asString(CONTACTS_AUTOMATION_PROBE_FIRST)}, last name:${asString(CONTACTS_AUTOMATION_PROBE_LAST)}}
+  delete probe
+  save
+end tell
+return "OK"`;
+}
+
+export function buildContactsProbeCleanupScript() {
+  return `tell application "Contacts"
+  set leftovers to (every person whose first name is ${asString(CONTACTS_AUTOMATION_PROBE_FIRST)} and last name is ${asString(CONTACTS_AUTOMATION_PROBE_LAST)})
+  repeat with p in leftovers
+    delete p
+  end repeat
+  save
+end tell
+return "OK"`;
+}
+
+/**
+ * Live Contacts Apple Events check. Not a dry_run.
+ * @returns {{ ok: boolean, message: string, kind: string|null }}
+ */
+export function probeContactsAutomation(deps = {}) {
+  const action = "contacts_automation_probe";
+  const summary = "create and delete a throwaway Contacts person (Automation / AddressBook check)";
+  const ready = ensureContactsAppReady(deps);
+  if (!ready.ok) {
+    runAppleScript(buildContactsProbeCleanupScript(), { timeout: 30000, appName: "Contacts" });
+    return { ok: false, message: failure(action, summary, ready), kind: ready.kind };
+  }
+  const result = runAppleScript(buildContactsAutomationProbeScript(), { timeout: 60000, appName: "Contacts" });
+  // Best-effort cleanup if the probe created the person then failed mid-script.
+  runAppleScript(buildContactsProbeCleanupScript(), { timeout: 30000, appName: "Contacts" });
+  if (!result.ok) {
+    return { ok: false, message: failure(action, summary, result), kind: result.kind };
+  }
+  return {
+    ok: true,
+    kind: null,
+    message: writeSuccessMessage(
+      action,
+      "Contacts Automation allowed (created and deleted a throwaway contact)"
+    )
+  };
+}

package/lib/eventKitSession.js

@@ -0,0 +1,369 @@
+/**
+ * Long-lived EventKit JXA worker.
+ *
+ * writeOnly (EKAuthorizationStatus = 4) can create an EKEvent and read
+ * identifiers off that in-memory object, but cannot re-query via
+ * eventWithIdentifier / calendarItemsWithExternalIdentifier — Mini 2cdf44d
+ * failed add on a post-save lookup even though create returned ids.
+ *
+ * The indexer daemon therefore keeps one osascript process around and
+ * caches the EKEvent objects from create so edit/remove can call
+ * saveEvent / removeEvent without a fetch.
+ *
+ * stdin/stdout: one JSON object per line. Never interpolates commands
+ * into a shell (`spawn`, `shell: false`).
+ */
+
+import { spawn } from "child_process";
+import fs from "fs";
+import os from "os";
+import path from "path";
+
+let singleton = null;
+
+export function setEventKitSession(session) {
+  singleton = session || null;
+}
+
+export function getEventKitSession() {
+  return singleton;
+}
+
+export function shouldStartEventKitSession({
+  platform = process.platform,
+  env = process.env
+} = {}) {
+  if (platform !== "darwin") return false;
+  if (env.VITEST) return false;
+  if (env.APPLE_TOOLS_EVENTKIT_SESSION === "0") return false;
+  return true;
+}
+
+/**
+ * JXA worker: create caches the EKEvent; update/remove use the cache.
+ * create does not call findEventByIds.
+ */
+export function sessionPaths(home = process.env.HOME || "") {
+  const root = home ? path.join(home, ".apple-tools-mcp") : path.join(os.tmpdir(), "atm-eventkit");
+  const dir = path.join(root, "eventkit-session");
+  return {
+    root,
+    dir,
+    scriptPath: path.join(root, "eventkit-worker.jxa"),
+    cmdPath: path.join(dir, "cmd.json"),
+    rspPath: path.join(dir, "rsp.json")
+  };
+}
+
+export function buildEventKitWorkerScript(helpers, paths = {}) {
+  const cmdPath = JSON.stringify(paths.cmdPath || "");
+  const rspPath = JSON.stringify(paths.rspPath || "");
+  return `ObjC.import("EventKit");
+ObjC.import("Foundation");
+${helpers}
+
+var store = $.EKEventStore.alloc.init;
+var cache = {};
+
+function remember(ev) {
+  if (!ev) return;
+  var keys = [
+    jsString(ev.eventIdentifier),
+    jsString(ev.calendarItemIdentifier),
+    jsString(ev.calendarItemExternalIdentifier)
+  ];
+  for (var i = 0; i < keys.length; i++) {
+    if (keys[i]) cache[keys[i]] = ev;
+  }
+}
+
+function forget(ev) {
+  var keys = [];
+  for (var k in cache) keys.push(k);
+  for (var i = 0; i < keys.length; i++) {
+    if (cache[keys[i]] === ev) delete cache[keys[i]];
+  }
+}
+
+function resolve(ids) {
+  if (!ids) return null;
+  for (var i = 0; i < ids.length; i++) {
+    var id = ids[i];
+    if (id && cache[id]) return cache[id];
+  }
+  return findEventByIds(store, ids);
+}
+
+var cmdPath = ${cmdPath};
+var rspPath = ${rspPath};
+
+function writeReply(s) {
+  $.NSString.stringWithString(String(s) + "\\n").writeToFileAtomicallyEncodingError(rspPath, true, $.NSUTF8StringEncoding, null);
+}
+
+function fileExists(p) {
+  try { return !!$.NSFileManager.defaultManager.fileExistsAtPath(p); } catch (e) { return false; }
+}
+
+function readCmd() {
+  var str = $.NSString.stringWithContentsOfFileEncodingError(cmdPath, $.NSUTF8StringEncoding, null);
+  return jsString(str);
+}
+
+function removeCmd() {
+  try { $.NSFileManager.defaultManager.removeItemAtPathError(cmdPath, null); } catch (e) {}
+}
+
+function pickCalendar(calendarName) {
+  var defaultCal = null;
+  try { defaultCal = store.defaultCalendarForNewEvents; } catch (e) {}
+  var cals = null;
+  var count = 0;
+  try {
+    cals = store.calendarsForEntityType($.EKEntityTypeEvent);
+    count = cals ? Number(cals.count) : 0;
+  } catch (e) {}
+  var target = null;
+  var writables = [];
+  var wanted = String(calendarName || "").toLowerCase();
+  function matchesWanted(c) {
+    var t = titleOf(c).toLowerCase();
+    var id = identifierOf(c);
+    return (t && t === wanted) || (id && (id === calendarName || id.toLowerCase() === wanted));
+  }
+  for (var i = 0; i < count; i++) {
+    var c = cals.objectAtIndex(i);
+    var writable = true;
+    try { writable = !!c.allowsContentModifications; } catch (e) {}
+    if (!writable) continue;
+    writables.push(c);
+    if (matchesWanted(c)) {
+      target = c;
+      break;
+    }
+  }
+  if (!target && defaultCal && matchesWanted(defaultCal)) target = defaultCal;
+  if (!target && writables.length === 1) target = writables[0];
+  if (!target && defaultCal) target = defaultCal;
+  var status = $.EKEventStore.authorizationStatusForEntityType($.EKEntityTypeEvent);
+  if (!target) {
+    throw new Error("CALENDAR_NOT_FOUND status=" + status + " eventKitCalendars=" + count + " default=" + titleOf(defaultCal) + " defaultId=" + identifierOf(defaultCal));
+  }
+  return target;
+}
+
+function createEvent(cmd) {
+  var status = $.EKEventStore.authorizationStatusForEntityType($.EKEntityTypeEvent);
+  if (status === 1 || status === 2) throw new Error("EVENTKIT_DENIED status=" + status);
+  var target = pickCalendar(cmd.calendarName);
+  var event = null;
+  try { event = $.EKEvent.eventWithEventStore(store); } catch (e) {}
+  if (!event) {
+    try { event = $.EKEvent.alloc.initWithEventStore(store); } catch (e2) {}
+  }
+  if (!event) throw new Error("EVENTKIT_NO_EVENT status=" + status);
+  event.title = String(cmd.title || "");
+  event.startDate = $.NSDate.dateWithTimeIntervalSince1970(Number(cmd.startSec));
+  event.endDate = $.NSDate.dateWithTimeIntervalSince1970(Number(cmd.endSec));
+  event.allDay = !!cmd.allDay;
+  try { event.calendar = target; } catch (e) {}
+  try { if (event.setCalendar) event.setCalendar(target); } catch (e) {}
+  if (cmd.location) event.location = String(cmd.location);
+  if (cmd.notes) event.notes = String(cmd.notes);
+  var alerts = cmd.alerts || [];
+  if (alerts && alerts.length) {
+    var alarms = $.NSMutableArray.array;
+    for (var a = 0; a < alerts.length; a++) {
+      alarms.addObject($.EKAlarm.alarmWithRelativeOffset(-Number(alerts[a]) * 60));
+    }
+    event.alarms = alarms;
+  }
+  var err = Ref();
+  var ok = false;
+  try {
+    ok = store.saveEventSpanCommitError(event, $.EKSpanThisEvent, true, err);
+  } catch (e) {
+    throw new Error("EVENTKIT_SAVE_FAILED: " + String(e));
+  }
+  if (!ok) {
+    var desc = "unknown";
+    try { desc = String(err[0]); } catch (e) {}
+    throw new Error("EVENTKIT_SAVE_FAILED: " + desc + " status=" + status);
+  }
+  remember(event);
+  var externalId = "";
+  var localId = "";
+  var itemId = "";
+  try { externalId = jsString(event.calendarItemExternalIdentifier); } catch (e) {}
+  try { localId = jsString(event.eventIdentifier); } catch (e) {}
+  try { itemId = jsString(event.calendarItemIdentifier); } catch (e) {}
+  if (!externalId && !localId && !itemId) throw new Error("EVENTKIT_NO_ID status=" + status);
+  return externalId + "<<>>" + localId + "<<>>" + titleOf(target) + "<<>>" + itemId;
+}
+
+function updateEvent(cmd) {
+  var event = resolve(cmd.ids);
+  if (!event) {
+    var status = $.EKEventStore.authorizationStatusForEntityType($.EKEntityTypeEvent);
+    throw new Error("EVENTKIT_NOT_FOUND status=" + status + (status === 4 ? " writeOnly" : "") + " sessionMiss tried=" + (cmd.ids || []).join(","));
+  }
+  if (cmd.title !== undefined && cmd.title !== null) event.title = String(cmd.title);
+  if (cmd.location !== undefined && cmd.location !== null) event.location = String(cmd.location);
+  if (cmd.notes !== undefined && cmd.notes !== null) event.notes = String(cmd.notes);
+  if (cmd.startSec !== undefined && cmd.startSec !== null) {
+    event.startDate = $.NSDate.dateWithTimeIntervalSince1970(Number(cmd.startSec));
+  }
+  if (cmd.endSec !== undefined && cmd.endSec !== null) {
+    event.endDate = $.NSDate.dateWithTimeIntervalSince1970(Number(cmd.endSec));
+  }
+  if (cmd.clearAlerts) {
+    try { event.alarms = $.NSMutableArray.array; } catch (e) {}
+  }
+  var alerts = cmd.alerts || [];
+  if (alerts && alerts.length) {
+    var alarms = $.NSMutableArray.array;
+    for (var a = 0; a < alerts.length; a++) {
+      alarms.addObject($.EKAlarm.alarmWithRelativeOffset(-Number(alerts[a]) * 60));
+    }
+    event.alarms = alarms;
+  }
+  var err = Ref();
+  var ok = store.saveEventSpanCommitError(event, $.EKSpanThisEvent, true, err);
+  if (!ok) {
+    var desc = "unknown";
+    try { desc = String(err[0]); } catch (e) {}
+    throw new Error("EVENTKIT_SAVE_FAILED: " + desc);
+  }
+  remember(event);
+  return jsString(event.eventIdentifier) || jsString(event.calendarItemExternalIdentifier) || "1";
+}
+
+function removeEvent(cmd) {
+  var event = resolve(cmd.ids);
+  if (!event) {
+    var status = $.EKEventStore.authorizationStatusForEntityType($.EKEntityTypeEvent);
+    throw new Error("EVENTKIT_NOT_FOUND status=" + status + (status === 4 ? " writeOnly" : "") + " sessionMiss tried=" + (cmd.ids || []).join(","));
+  }
+  var err = Ref();
+  var ok = store.removeEventSpanCommitError(event, $.EKSpanThisEvent, true, err);
+  if (!ok) {
+    var desc = "unknown";
+    try { desc = String(err[0]); } catch (e) {}
+    throw new Error("EVENTKIT_REMOVE_FAILED: " + desc);
+  }
+  forget(event);
+  return "1";
+}
+
+function handle(cmd) {
+  if (!cmd || !cmd.op) throw new Error("EVENTKIT_BAD_CMD");
+  if (cmd.op === "ping") return "pong";
+  if (cmd.op === "create") return createEvent(cmd);
+  if (cmd.op === "update") return updateEvent(cmd);
+  if (cmd.op === "remove") return removeEvent(cmd);
+  if (cmd.op === "quit") return "bye";
+  throw new Error("EVENTKIT_BAD_OP");
+}
+
+while (true) {
+  if (!fileExists(cmdPath)) {
+    delay(0.05);
+    continue;
+  }
+  var line = readCmd();
+  removeCmd();
+  line = String(line || "").replace(/^\\s+|\\s+$/g, "");
+  if (!line) continue;
+  try {
+    var cmd = JSON.parse(line);
+    var output = handle(cmd);
+    writeReply(JSON.stringify({ ok: true, output: String(output == null ? "" : output) }));
+    if (cmd.op === "quit") break;
+  } catch (e) {
+    writeReply(JSON.stringify({ ok: false, error: String(e) }));
+  }
+}
+`;
+}
+
+export function workerScriptPath(home = process.env.HOME || "") {
+  return sessionPaths(home).scriptPath;
+}
+
+export function startEventKitSession({
+  helpers,
+  spawnImpl = spawn,
+  home = process.env.HOME || "",
+  timeoutMs = 30000,
+  sleep = (ms) => {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+  }
+} = {}) {
+  if (!helpers) throw new Error("EventKit worker helpers are required");
+  const paths = sessionPaths(home);
+  fs.mkdirSync(paths.dir, { recursive: true, mode: 0o700 });
+  try { fs.unlinkSync(paths.cmdPath); } catch { /* ignore */ }
+  try { fs.unlinkSync(paths.rspPath); } catch { /* ignore */ }
+  fs.writeFileSync(paths.scriptPath, buildEventKitWorkerScript(helpers, paths), { mode: 0o600 });
+
+  const child = spawnImpl("osascript", ["-l", "JavaScript", paths.scriptPath], {
+    stdio: ["ignore", "ignore", "pipe"],
+    shell: false
+  });
+
+  let dead = false;
+  if (child.on) {
+    child.on("exit", () => {
+      dead = true;
+    });
+  }
+
+  function request(cmd, waitMs = timeoutMs) {
+    if (dead) throw new Error("EVENTKIT_SESSION_DEAD");
+    try { fs.unlinkSync(paths.rspPath); } catch { /* ignore */ }
+    fs.writeFileSync(paths.cmdPath, JSON.stringify(cmd), { mode: 0o600 });
+    const deadline = Date.now() + waitMs;
+    while (Date.now() < deadline) {
+      if (fs.existsSync(paths.rspPath)) {
+        const text = fs.readFileSync(paths.rspPath, "utf8").trim();
+        try { fs.unlinkSync(paths.rspPath); } catch { /* ignore */ }
+        return JSON.parse(text);
+      }
+      sleep(20);
+    }
+    throw new Error("EVENTKIT_SESSION_TIMEOUT");
+  }
+
+  const pong = request({ op: "ping" });
+  if (!pong || pong.ok !== true || pong.output !== "pong") {
+    try { child.kill(); } catch { /* ignore */ }
+    throw new Error("EVENTKIT_SESSION_HANDSHAKE");
+  }
+
+  return {
+    request,
+    close() {
+      try { request({ op: "quit" }, 2000); } catch { /* ignore */ }
+      try { child.kill(); } catch { /* ignore */ }
+      dead = true;
+    }
+  };
+}
+
+export function ensureEventKitSession(opts = {}) {
+  if (singleton) return singleton;
+  if (!shouldStartEventKitSession(opts)) return null;
+  try {
+    singleton = startEventKitSession(opts);
+    return singleton;
+  } catch {
+    singleton = null;
+    return null;
+  }
+}
+
+export function closeEventKitSession() {
+  if (!singleton) return;
+  try { singleton.close(); } catch { /* ignore */ }
+  singleton = null;
+}