feat: list notifications and act on one through Notification Center's custom actions (#74)

Author: iamnbutler

dist/build.js

@@ -56,6 +56,7 @@ const patches = [
     "peekaboo-dialog-path.patch",
     "peekaboo-drag-path.patch",
     "peekaboo-minimized-close-test.patch",
+    "peekaboo-notification-actions.patch",
 ].map((name) => join(native, "patches", name));
 function spawn(command, env) {
     return spawnSync(command[0], command.slice(1), { encoding: "utf8", env: env ?? process.env });

dist/client.js

@@ -6,6 +6,7 @@ import { join } from "node:path";
 import { promisify } from "node:util";
 import { failureAvailability, windowAvailability } from "./availability.js";
 import { DESKTOP_BUTTONS, DESKTOP_CLICKS, DESKTOP_DIRECTIONS, DESKTOP_ELEMENT_ACTIONS, DESKTOP_MODIFIERS, DESKTOP_SELECTIONS, isDesktopAction, isDesktopKey, isDesktopManagement, } from "./protocol.js";
+import { NOTIFICATIONS_MS, notificationAction, readNotifications, validateNotificationAction, } from "./notifications.js";
 import { waitFor } from "./wait.js";
 const exec = promisify(execFile);
 const MAX_TEXT = 32_000;
@@ -575,6 +576,10 @@ function validateAction(request) {
         }
         return validateKey(request);
     }
+    if (request.op === "notification-action") {
+        validateNotificationAction(request);
+        return;
+    }
     if (typeof request.snapshot !== "string" || !request.snapshot || request.snapshot.length > 256) {
         throw new Error("Use the snapshot_id from a fresh desktop_inspect result.");
     }
@@ -1191,6 +1196,8 @@ async function execute(native, request, abort) {
             "inspect",
             "read",
             "wait",
+            "notifications",
+            "notification-action",
             "screen",
             "click",
             "type",
@@ -1238,6 +1245,30 @@ async function execute(native, request, abort) {
             }),
         }, request, abort);
     }
+    // Notifications compose several reads, each with its own 30-second limit, under one overall limit.
+    if (request.op === "notifications" || request.op === "notification-action") {
+        const signal = AbortSignal.any([...(abort ? [abort] : []), AbortSignal.timeout(NOTIFICATIONS_MS)]);
+        const io = {
+            observe: (read, signal) => execute(native, read, signal),
+            perform: (input, signal, onDispatch) => native(["action"], signal, { input: JSON.stringify(input), onDispatch }),
+        };
+        if (request.op === "notifications") {
+            if (Object.keys(request).some((key) => key !== "op"))
+                throw new Error("Reading notifications takes no arguments.");
+            return { text: bounded(await readNotifications(io, signal), "notifications") };
+        }
+        try {
+            const { data, outcome } = await notificationAction(io, request, signal);
+            return actionResult(data, outcome);
+        }
+        catch (error) {
+            return actionResult({
+                outcome: "refused",
+                reason: (error instanceof Error ? error.message : String(error)).slice(0, 2000),
+                message: "No input was sent.",
+            }, "refused");
+        }
+    }
     const deadline = new AbortController();
     const timer = setTimeout(() => deadline.abort(new Error("Native desktop operation timed out after 30 seconds.")), 30_000);
     const signal = abort ? AbortSignal.any([abort, deadline.signal]) : deadline.signal;

dist/notifications.d.ts

@@ -0,0 +1,49 @@
+import type { DesktopRequest, DesktopResult } from "./protocol.js";
+/** Notification Center's process; its banners, alerts and open panel are windows of it. */
+export declare const NOTIFICATION_CENTER = "com.apple.notificationcenterui";
+/** Under the 60-second request timeout common MCP clients use. */
+export declare const NOTIFICATIONS_MS = 50000;
+type Json = Record<string, unknown>;
+export type NotificationIO = {
+    /** One ordinary read: apps, windows or inspect. */
+    observe(request: DesktopRequest, signal: AbortSignal): Promise<DesktopResult>;
+    /** One native action request; `onDispatch` runs once input may have been sent. */
+    perform(input: Json, signal: AbortSignal, onDispatch: () => void): Promise<Json>;
+};
+export type NotificationEntry = {
+    id: string;
+    pid: number;
+    window_id: number;
+    kind: string;
+    app: string | null;
+    title: string | null;
+    subtitle: string | null;
+    body: string | null;
+    time: string | null;
+    description: string | null;
+    texts: string[];
+    stack: boolean;
+    actions: string[];
+};
+/** Current banners and alerts, and the entries of an open Notification Center, each with an action ID. */
+export declare function readNotifications(io: NotificationIO, signal: AbortSignal): Promise<Json>;
+export declare function validateNotificationAction(request: {
+    id?: unknown;
+    action?: unknown;
+}): {
+    snapshot: string;
+    element: string;
+    action: string;
+};
+/**
+ * Opens, closes or runs one listed action of one notification through Accessibility, then reads again: the
+ * result is completed only when the notification is gone, otherwise unknown.
+ */
+export declare function notificationAction(io: NotificationIO, request: {
+    id: string;
+    action: string;
+}, signal: AbortSignal): Promise<{
+    data: Json;
+    outcome: "completed" | "refused" | "unknown";
+}>;
+export {};