@ai-agent-forge/plugin-desktop-macos-input 0.0.0-stage → 0.88.4

package/dist/macos-ax-adapter.js

@@ -0,0 +1,805 @@
+/**
+ * macOS Accessibility driver (query + bounded input actions) and the input
+ * adapter facade for this package. Structurally mirrors the Windows package's
+ * `windows-uia-adapter.ts` + `windows-input-adapter.ts` (inlined from
+ * agent-forge `src/plugins/desktop/*`, D-075 S3) with these deliberate
+ * differences:
+ * - Driver boundary is `osascript -l JavaScript -e <script>` (JXA) instead of
+ *   PowerShell UIA. The query script walks the System Events accessibility
+ *   tree (`Application("com.apple.systemevents")`); the action script re-locates the
+ *   observed target by its deterministic enumeration identity
+ *   (`window-<pid>-<windowIndex>` / `<windowId>:<role>:<childIndex>`; Windows
+ *   uses native HWND handles instead — mac AX exposes no stable handles).
+ * - Bounded actions: focus (frontmost + AXRaise / AXFocused), click
+ *   (AXPress with a CGEvent coordinate-click fallback, plus screen-coordinate
+ *   click targets — click-only by ruling), type (focus + System Events
+ *   keystroke), key (System Events keyCode/keystroke over a minimal SendKeys
+ *   aligned table, parsed host-side), scroll (CGEvent scroll wheel).
+ * - The facade exposes no replay method (this package ships no replay);
+ *   sensitive actions stay behind the shared `requiresDesktopUserConfirmation`
+ *   fail-closed gate.
+ * - Non-darwin platforms never throw at import or call time: probe reports
+ *   `{available:false, reason:"macOS Accessibility requires darwin"}` and
+ *   every tool returns an explicit `unsupported` result. Missing
+ *   Accessibility (assistive access) permission is reported fail-closed as
+ *   `accessibility-permission-required`; no degraded mode.
+ * This file is a deliberate copy shared (not imported) with the observe
+ * package's adapter; the observe copy carries the query script only.
+ */
+import { spawnSync as nodeSpawnSync } from "node:child_process";
+import { detachedFreeze } from "@agent-forge/plugin-sdk";
+import { requiresDesktopUserConfirmation } from "./types.js";
+const READONLY_CAPABILITIES = ["desktop-session", "desktop-uia", "desktop-input"];
+const SUPPORTED_ACTIONS = ["focus", "click", "type", "key", "scroll"];
+const error = (code, message, causeCode) => ({
+    version: 1,
+    code,
+    message,
+    ...(causeCode === undefined ? {} : { causeCode }),
+});
+const unsupported = (operationId, reason, causeCode = "platform-unavailable") => ({
+    version: 1,
+    operationId,
+    status: "unsupported",
+    summary: reason,
+    error: error(causeCode === "action-unsupported" ? "action_unsupported" : "platform_unavailable", reason, causeCode),
+});
+const rectangle = (raw) => ({
+    x: Number.isFinite(raw.x) ? Number(raw.x) : 0,
+    y: Number.isFinite(raw.y) ? Number(raw.y) : 0,
+    width: Number.isFinite(raw.width) ? Number(raw.width) : 0,
+    height: Number.isFinite(raw.height) ? Number(raw.height) : 0,
+});
+const isPermissionReason = (value) => /assistive access|not authorized|accessibility-permission-required/i.test(value);
+/**
+ * JXA observation script. Enumerates every non-background System Events
+ * process's windows (caps: 64 windows, 256 controls total, mirroring the
+ * projection budgets) with role/name/position/size/enabled/value per control,
+ * plus the frontmost process's focused element matched by role and frame.
+ * Permission or automation failures are reported in-band as
+ * `{available:false, reason:...}` so the probe can classify them; the reason
+ * literal `accessibility-permission-required` is reserved for missing
+ * Accessibility (assistive access) grants.
+ */
+const QUERY_SCRIPT = `
+var se = Application('com.apple.systemevents');
+function safe(fn) { try { return fn(); } catch (e) { return undefined; } }
+function rectOf(el) {
+  var p = safe(function() { return el.position(); });
+  var z = safe(function() { return el.size(); });
+  if (p === undefined || z === undefined || p.length < 2 || z.length < 2) return {x: 0, y: 0, width: 0, height: 0};
+  return {x: Math.round(p[0]), y: Math.round(p[1]), width: Math.round(z[0]), height: Math.round(z[1])};
+}
+function axReason(e) {
+  var msg = String(e && e.message !== undefined ? e.message : e);
+  var num = e && typeof e.errorNumber === 'number' ? e.errorNumber : 0;
+  if (msg.indexOf('assistive access') !== -1 || msg.indexOf('not authorized') !== -1 ||
+      num === -25211 || num === -1719 || num === -1743) return 'accessibility-permission-required';
+  return msg;
+}
+try {
+  var out = {available: true, windows: [], controls: [], focusedControlId: null};
+  var procs = se.processes();
+  var focused = null;
+  for (var fi = 0; fi < procs.length; fi++) {
+    var fp = procs[fi];
+    if (safe(function() { return fp.frontmost(); }) !== true) continue;
+    var fe = safe(function() { return fp.attributes['AXFocusedUIElement'].value(); });
+    if (fe !== undefined) focused = {role: safe(function() { return fe.role(); }), rect: rectOf(fe)};
+    break;
+  }
+  var windowCount = 0;
+  var controlCount = 0;
+  for (var pi = 0; pi < procs.length && windowCount < 64; pi++) {
+    var proc = procs[pi];
+    if (safe(function() { return proc.backgroundOnly(); }) === true) continue;
+    var wins = safe(function() { return proc.windows(); });
+    if (wins === undefined || wins.length === 0) continue;
+    var pid = safe(function() { return proc.unixId(); });
+    var pname = safe(function() { return proc.name(); });
+    if (typeof pname !== 'string' || pname.length === 0) pname = 'unknown';
+    for (var wi = 0; wi < wins.length && windowCount < 64; wi++) {
+      var win = wins[wi];
+      var winRect = rectOf(win);
+      var winId = 'window-' + pid + '-' + wi;
+      windowCount++;
+      out.windows.push({id: winId, processId: pid, processName: pname,
+        name: safe(function() { return win.name(); }) || '', x: winRect.x, y: winRect.y,
+        width: winRect.width, height: winRect.height});
+      var contents = safe(function() { return win.entireContents(); });
+      if (contents === undefined) continue;
+      for (var ci = 0; ci < contents.length && controlCount < 256; ci++) {
+        var el = contents[ci];
+        var role = safe(function() { return el.role(); });
+        if (typeof role !== 'string' || role.length === 0) continue;
+        var r = rectOf(el);
+        var controlId = winId + ':' + role + ':' + ci;
+        var value = safe(function() { return el.value(); });
+        out.controls.push({windowId: winId, controlId: controlId, role: role,
+          name: safe(function() { return el.name(); }) || safe(function() { return el.title(); }) || '',
+          enabled: safe(function() { return el.enabled(); }) !== false,
+          value: typeof value === 'string' && value.length > 0 ? value : undefined,
+          x: r.x, y: r.y, width: r.width, height: r.height});
+        controlCount++;
+        if (focused !== null && out.focusedControlId === null && role === focused.role &&
+            r.x === focused.rect.x && r.y === focused.rect.y &&
+            r.width === focused.rect.width && r.height === focused.rect.height) {
+          out.focusedControlId = controlId;
+        }
+      }
+    }
+  }
+  JSON.stringify(out);
+} catch (e) {
+  JSON.stringify({available: false, reason: axReason(e)});
+}`;
+/**
+ * JXA bounded-input script. Reads the JSON payload from
+ * `AGENT_FORGE_MACOS_AX_INPUT`: `{kind, target:{windowId?, controlId?,
+ * coordinates?}, text?, key:{keyCode?, text?, modifiers?},
+ * scroll:{up, lines}}`. The target is re-located through the same
+ * deterministic enumeration the query script used; an unfound identity is a
+ * stale target. Output: `{ok:true}` or `{ok:false, code, reason}`.
+ */
+const ACTION_SCRIPT = `
+ObjC.import('CoreGraphics');
+var se = Application('com.apple.systemevents');
+function safe(fn) { try { return fn(); } catch (e) { return undefined; } }
+function rectOf(el) {
+  var p = safe(function() { return el.position(); });
+  var z = safe(function() { return el.size(); });
+  if (p === undefined || z === undefined || p.length < 2 || z.length < 2) return {x: 0, y: 0, width: 0, height: 0};
+  return {x: Math.round(p[0]), y: Math.round(p[1]), width: Math.round(z[0]), height: Math.round(z[1])};
+}
+function findProcess(pid) {
+  var procs = se.processes();
+  for (var i = 0; i < procs.length; i++) {
+    if (safe(function() { return procs[i].unixId(); }) === pid) return procs[i];
+  }
+  return undefined;
+}
+function parseWindowId(windowId) {
+  var m = /^window-(\\d+)-(\\d+)$/.exec(String(windowId));
+  return m === null ? undefined : {pid: Number(m[1]), index: Number(m[2])};
+}
+function findWindow(windowId) {
+  var parsed = parseWindowId(windowId);
+  if (parsed === undefined) return undefined;
+  var proc = findProcess(parsed.pid);
+  if (proc === undefined) return undefined;
+  var wins = safe(function() { return proc.windows(); });
+  if (wins === undefined || parsed.index >= wins.length) return undefined;
+  return {proc: proc, win: wins[parsed.index]};
+}
+function findControl(windowId, controlId) {
+  var located = findWindow(windowId);
+  if (located === undefined) return undefined;
+  var parts = String(controlId).split(':');
+  if (parts.length < 3) return undefined;
+  var index = Number(parts[parts.length - 1]);
+  var role = parts[parts.length - 2];
+  var contents = safe(function() { return located.win.entireContents(); });
+  if (contents === undefined || index >= contents.length) return undefined;
+  var el = contents[index];
+  if (safe(function() { return el.role(); }) !== role) return undefined;
+  return {proc: located.proc, win: located.win, el: el};
+}
+function cgClick(x, y) {
+  var pt = {x: x, y: y};
+  var move = $.CGEventCreateMouseEvent($(), $.kCGEventMouseMoved, pt, $.kCGMouseButtonLeft);
+  $.CGEventPost($.kCGHIDEventTap, move);
+  var down = $.CGEventCreateMouseEvent($(), $.kCGEventLeftMouseDown, pt, $.kCGMouseButtonLeft);
+  $.CGEventPost($.kCGHIDEventTap, down);
+  var up = $.CGEventCreateMouseEvent($(), $.kCGEventLeftMouseUp, pt, $.kCGMouseButtonLeft);
+  $.CGEventPost($.kCGHIDEventTap, up);
+}
+function cgScroll(x, y, lines, up) {
+  var pt = {x: x, y: y};
+  var move = $.CGEventCreateMouseEvent($(), $.kCGEventMouseMoved, pt, $.kCGMouseButtonLeft);
+  $.CGEventPost($.kCGHIDEventTap, move);
+  var ev = $.CGEventCreateScrollWheelEvent($(), $.kCGScrollEventUnitLine, 1, up ? lines : -lines);
+  $.CGEventPost($.kCGHIDEventTap, ev);
+}
+function setFocused(el) {
+  try { el.focused = true; return true; } catch (e) { return false; }
+}
+try {
+  var payload = JSON.parse($.NSProcessInfo.processInfo.environment.objectForKey('AGENT_FORGE_MACOS_AX_INPUT').js);
+  var target = payload.target || {};
+  var el = undefined;
+  var win = undefined;
+  var proc = undefined;
+  if (target.windowId !== undefined && target.controlId !== undefined) {
+    var control = findControl(target.windowId, target.controlId);
+    if (control === undefined) throw {stale: true};
+    el = control.el; win = control.win; proc = control.proc;
+  } else if (target.windowId !== undefined) {
+    var located = findWindow(target.windowId);
+    if (located === undefined) throw {stale: true};
+    win = located.win; proc = located.proc;
+  }
+  if (payload.kind === 'focus') {
+    if (el !== undefined) {
+      if (!setFocused(el)) throw {reason: 'focus_failed'};
+    } else if (win !== undefined) {
+      try { proc.frontmost = true; } catch (e) {}
+      if (safe(function() { return win.actions['AXRaise'].perform(); }) === undefined && safe(function() { return proc.frontmost(); }) !== true) {
+        throw {reason: 'focus_failed'};
+      }
+    } else {
+      throw {reason: 'ax_action_exception'};
+    }
+  } else if (payload.kind === 'click') {
+    if (target.coordinates !== undefined) {
+      cgClick(Number(target.coordinates.x), Number(target.coordinates.y));
+    } else if (el !== undefined) {
+      var performed = false;
+      try { el.actions['AXPress'].perform(); performed = true; } catch (e) {}
+      if (!performed) {
+        var r = rectOf(el);
+        if (r.width <= 0 && r.height <= 0) throw {reason: 'press_unavailable'};
+        cgClick(r.x + Math.floor(r.width / 2), r.y + Math.floor(r.height / 2));
+      }
+    } else if (win !== undefined) {
+      var wr = rectOf(win);
+      cgClick(wr.x + Math.floor(wr.width / 2), wr.y + Math.floor(wr.height / 2));
+    } else {
+      throw {reason: 'ax_action_exception'};
+    }
+  } else if (payload.kind === 'type') {
+    if (el !== undefined && !setFocused(el)) throw {reason: 'focus_failed'};
+    if (el === undefined && win !== undefined) {
+      try { proc.frontmost = true; } catch (e) {}
+    }
+    se.keystroke(String(payload.text));
+  } else if (payload.kind === 'key') {
+    if (el !== undefined && !setFocused(el)) throw {reason: 'focus_failed'};
+    var using = Array.isArray(payload.key.modifiers) && payload.key.modifiers.length > 0 ? {using: payload.key.modifiers} : {};
+    if (typeof payload.key.keyCode === 'number') {
+      se.keyCode(payload.key.keyCode, using);
+    } else {
+      se.keystroke(String(payload.key.text), using);
+    }
+  } else if (payload.kind === 'scroll') {
+    var center = target.coordinates !== undefined
+      ? {x: Number(target.coordinates.x), y: Number(target.coordinates.y)}
+      : (el !== undefined ? rectOf(el) : (win !== undefined ? rectOf(win) : {x: 0, y: 0, width: 0, height: 0}));
+    cgScroll(center.x + Math.floor((center.width || 0) / 2), center.y + Math.floor((center.height || 0) / 2),
+      Number(payload.scroll.lines), payload.scroll.up === true);
+  } else {
+    throw {reason: 'ax_action_exception'};
+  }
+  JSON.stringify({ok: true});
+} catch (e) {
+  if (e && e.stale === true) {
+    JSON.stringify({ok: false, code: 'stale_target', reason: 'ax_action_exception'});
+  } else {
+    var reason = e && typeof e.reason === 'string' ? e.reason : 'ax_action_exception';
+    JSON.stringify({ok: false, code: 'action_failed', reason: reason});
+  }
+}`;
+const parseJson = (stdout) => {
+    try {
+        const parsed = JSON.parse(stdout.trim());
+        return typeof parsed === "object" && parsed !== null ? parsed : undefined;
+    }
+    catch {
+        return undefined;
+    }
+};
+/**
+ * Minimal SendKeys-aligned key grammar, parsed host-side because JXA has no
+ * SendKeys equivalent. Grammar: optional modifier prefixes (`+` shift,
+ * `^` control, `%` option — the Windows SendKeys mapping) followed by either
+ * one `{NAME}` special key or exactly one literal character.
+ */
+const MAC_KEY_CODES = Object.freeze({
+    RETURN: 36,
+    ENTER: 36,
+    TAB: 48,
+    ESC: 53,
+    ESCAPE: 53,
+    DEL: 117,
+    DELETE: 117,
+    BS: 51,
+    BKSP: 51,
+    BACKSPACE: 51,
+    UP: 126,
+    DOWN: 125,
+    LEFT: 123,
+    RIGHT: 124,
+    HOME: 115,
+    END: 119,
+    PGUP: 116,
+    PAGEUP: 116,
+    PGDN: 121,
+    PAGEDOWN: 121,
+    SPACE: 49,
+    F1: 122,
+    F2: 120,
+    F3: 99,
+    F4: 118,
+    F5: 96,
+    F6: 97,
+    F7: 98,
+    F8: 100,
+    F9: 101,
+    F10: 109,
+    F11: 103,
+    F12: 111,
+});
+const parseMacKey = (key) => {
+    const modifiers = [];
+    let index = 0;
+    for (; index < key.length; index += 1) {
+        const modifier = key[index];
+        if (modifier === "+")
+            modifiers.push("shift down");
+        else if (modifier === "^")
+            modifiers.push("control down");
+        else if (modifier === "%")
+            modifiers.push("option down");
+        else
+            break;
+    }
+    const unit = key.slice(index);
+    const braced = /^\{([A-Z0-9]+)\}$/.exec(unit);
+    if (braced !== null) {
+        const keyCode = MAC_KEY_CODES[braced[1] ?? ""];
+        if (keyCode === undefined)
+            return undefined;
+        return { keyCode, ...(modifiers.length === 0 ? {} : { modifiers }) };
+    }
+    if (unit.length !== 1)
+        return undefined;
+    return { text: unit, ...(modifiers.length === 0 ? {} : { modifiers }) };
+};
+const parseMacScroll = (text) => {
+    const match = /^(up|down)(?::(\d+))?$/.exec(text);
+    if (match === null)
+        return undefined;
+    const lines = match[2] === undefined ? 3 : Number(match[2]);
+    if (lines < 1 || lines > 100)
+        return undefined;
+    return { up: match[1] === "up", lines };
+};
+export class MacosAccessibilityDriver {
+    driverId = "macos-ax";
+    driverVersion = "1.0.0";
+    command;
+    timeoutMs;
+    platform;
+    spawn;
+    sessions = new Map();
+    targets = new Map();
+    sessionTargetKeys = new Map();
+    latestObservationIds = new Map();
+    observedSessions = new Set();
+    nextSessionId = 1;
+    nextObservationId = 1;
+    constructor(options = {}) {
+        this.command = options.command ?? "osascript";
+        // 60s: Apple events from an SSH (Background launchd) session run ~100x
+        // slower than a GUI session — one full enumeration measured 38s there;
+        // GUI sessions complete in seconds and stay unaffected by the raise.
+        this.timeoutMs = options.timeoutMs ?? 60_000;
+        this.platform = options.platform ?? process.platform;
+        this.spawn =
+            options.spawnSync ??
+                ((command, args, spawnOptions) => nodeSpawnSync(command, args, spawnOptions));
+    }
+    probe() {
+        if (this.platform !== "darwin") {
+            return {
+                available: false,
+                platform: this.platform,
+                driver: "macos-ax",
+                reason: "macOS Accessibility requires darwin",
+            };
+        }
+        const run = this.run(QUERY_SCRIPT);
+        if (run === undefined)
+            return {
+                available: false,
+                platform: this.platform,
+                driver: "macos-ax",
+                reason: "macOS Accessibility requires darwin",
+            };
+        if (run.failed)
+            return {
+                available: false,
+                platform: this.platform,
+                driver: "macos-ax",
+                reason: isPermissionReason(run.stderr) ? "accessibility-permission-required" : "osascript is unavailable",
+            };
+        const raw = parseJson(run.stdout);
+        if (raw === undefined)
+            return {
+                available: false,
+                platform: this.platform,
+                driver: "macos-ax",
+                reason: "osascript is unavailable",
+            };
+        if (raw.available === true)
+            return {
+                available: true,
+                platform: this.platform,
+                driver: "macos-ax",
+                capabilities: READONLY_CAPABILITIES,
+            };
+        const reason = typeof raw.reason === "string" && raw.reason.trim() !== "" ? raw.reason : "macOS Accessibility probe failed";
+        return { available: false, platform: this.platform, driver: "macos-ax", reason };
+    }
+    openSession(request) {
+        const probe = this.probe();
+        if (!probe.available)
+            return {
+                status: "unsupported",
+                error: error("platform_unavailable", probe.reason ?? "macOS Accessibility is unavailable", "platform-unavailable"),
+            };
+        const session = detachedFreeze({
+            version: 1,
+            sessionId: `desktop-macos-session-${this.nextSessionId++}`,
+            isolation: request.isolation,
+            status: "ready",
+            ...(request.applicationId === undefined ? {} : { applicationId: request.applicationId }),
+        });
+        this.sessions.set(session.sessionId, session);
+        return { status: "succeeded", session };
+    }
+    observe(sessionId) {
+        const session = this.sessions.get(sessionId);
+        if (session === undefined)
+            return this.failed("observe", "session_not_found", "Session does not exist");
+        if (session.status === "stopped")
+            return this.cancelled("observe", "Session has been stopped");
+        const run = this.run(QUERY_SCRIPT);
+        const raw = run === undefined || run.failed ? undefined : parseJson(run.stdout);
+        if (raw === undefined || raw.available !== true) {
+            this.invalidateObservation(sessionId);
+            return unsupported("observe", "macOS Accessibility observation failed");
+        }
+        return this.toObservation(session, raw);
+    }
+    execute(request) {
+        const session = this.sessions.get(request.sessionId);
+        if (session === undefined)
+            return this.failed(request.operationId, "session_not_found", "Session does not exist");
+        if (session.status === "stopped")
+            return this.cancelled(request.operationId, "Session has been stopped");
+        if (requiresDesktopUserConfirmation(request.action.kind))
+            return {
+                version: 1,
+                operationId: request.operationId,
+                status: "needs_user",
+                summary: `User confirmation required for ${request.action.kind}`,
+                error: error("needs_user", `The ${request.action.kind} action is paused for the user`, request.action.kind),
+            };
+        if (!SUPPORTED_ACTIONS.includes(request.action.kind))
+            return unsupported(request.operationId, "The selected macOS Accessibility adapter does not support this action", "action-unsupported");
+        if (request.action.target === undefined)
+            return this.failed(request.operationId, "target_required", "This desktop action requires an observed target");
+        if (request.action.target.kind === "coordinates" && request.action.kind !== "click")
+            return this.failed(request.operationId, "coordinates_unsupported", "Coordinate targets are supported by the click action only");
+        if (request.action.kind === "type" && typeof request.action.text !== "string")
+            return this.failed(request.operationId, "text_required", "Type action requires text");
+        if (request.action.kind === "key" && typeof request.action.key !== "string")
+            return this.failed(request.operationId, "key_required", "Key action requires a key sequence");
+        if (request.action.kind === "scroll" && typeof request.action.text !== "string")
+            return this.failed(request.operationId, "direction_required", "Scroll action requires an up/down direction");
+        const postconditions = request.postconditions ?? [];
+        if (postconditions.length > 0 && request.reobserveAfterAction === false)
+            return this.failed(request.operationId, "reobserve_required", "Postconditions require an action re-observation");
+        const payload = this.actionPayload(request);
+        if (payload === undefined)
+            return this.failed(request.operationId, payloadErrorCode(request.action), payloadErrorMessage(request.action));
+        const raw = this.run(ACTION_SCRIPT, payload);
+        if (raw === undefined || raw.failed)
+            return unsupported(request.operationId, "macOS Accessibility action failed");
+        const parsed = parseJson(raw.stdout);
+        if (parsed === undefined)
+            return unsupported(request.operationId, "macOS Accessibility action failed");
+        if (parsed.ok !== true) {
+            if (parsed.code === "stale_target") {
+                this.invalidateObservation(request.sessionId);
+                return this.failed(request.operationId, "stale_target", "Target identity is stale; reobserve the desktop before retrying");
+            }
+            const causeCode = typeof parsed.reason === "string" &&
+                ["focus_failed", "press_unavailable", "coordinate_click_failed", "ax_action_exception"].includes(parsed.reason)
+                ? parsed.reason
+                : "ax_action_exception";
+            return this.failed(request.operationId, "action_failed", "Accessibility action failed", causeCode);
+        }
+        const observation = request.reobserveAfterAction === false ? undefined : this.observe(request.sessionId);
+        const verification = this.verifyPostconditions(postconditions, observation);
+        if (postconditions.length > 0 && verification.status === "unknown")
+            return {
+                version: 1,
+                operationId: request.operationId,
+                status: "failed",
+                summary: "Desktop action completed but could not be re-observed",
+                verification,
+                error: error("verification_unavailable", "The requested desktop state could not be re-observed", "reobserve-failed"),
+            };
+        if (verification.status === "failed")
+            return {
+                version: 1,
+                operationId: request.operationId,
+                status: "failed",
+                summary: "Desktop action completed but a postcondition failed",
+                ...(observation !== undefined && "observationId" in observation ? { observation } : {}),
+                verification,
+                error: error("postcondition_failed", "The requested desktop state was not observed", "verification-failed"),
+            };
+        return {
+            version: 1,
+            operationId: request.operationId,
+            status: "succeeded",
+            summary: "Desktop action completed through macOS Accessibility",
+            ...(observation !== undefined && "observationId" in observation ? { observation } : {}),
+            verification,
+        };
+    }
+    stop(sessionId) {
+        const session = this.sessions.get(sessionId);
+        if (session === undefined)
+            return this.failed("stop", "session_not_found", "Session does not exist");
+        const stopped = detachedFreeze({ ...session, status: "stopped" });
+        this.sessions.set(sessionId, stopped);
+        this.invalidateObservation(sessionId);
+        return stopped;
+    }
+    actionPayload(request) {
+        const target = request.action.target;
+        if (target === undefined)
+            return undefined;
+        const resolvedTarget = target.kind === "coordinates"
+            ? { coordinates: { x: target.x, y: target.y } }
+            : (this.resolveTarget(request.sessionId, target) ?? undefined);
+        if (resolvedTarget === undefined)
+            return undefined;
+        if (request.action.kind === "key") {
+            const key = parseMacKey(request.action.key ?? "");
+            if (key === undefined)
+                return undefined;
+            return { kind: request.action.kind, target: resolvedTarget, key };
+        }
+        if (request.action.kind === "scroll") {
+            const scroll = parseMacScroll(request.action.text ?? "");
+            if (scroll === undefined)
+                return undefined;
+            return { kind: request.action.kind, target: resolvedTarget, scroll };
+        }
+        return {
+            kind: request.action.kind,
+            target: resolvedTarget,
+            ...(request.action.text === undefined ? {} : { text: request.action.text }),
+        };
+    }
+    run(script, payload) {
+        if (this.platform !== "darwin")
+            return undefined;
+        const env = {};
+        for (const key of ["PATH", "HOME", "TMPDIR", "USER", "LOGNAME"]) {
+            const value = process.env[key];
+            if (value !== undefined)
+                env[key] = value;
+        }
+        if (payload !== undefined)
+            env.AGENT_FORGE_MACOS_AX_INPUT = JSON.stringify(payload);
+        const result = this.spawn(this.command, ["-l", "JavaScript", "-e", script], {
+            encoding: "utf8",
+            timeout: this.timeoutMs,
+            windowsHide: true,
+            env,
+        });
+        if (result.error !== undefined || result.status !== 0)
+            return { stdout: result.stdout, stderr: result.stderr ?? "", failed: true };
+        return { stdout: result.stdout, stderr: result.stderr ?? "", failed: false };
+    }
+    toObservation(session, raw) {
+        this.invalidateObservation(session.sessionId);
+        const observationId = `desktop-macos-observation-${this.nextObservationId++}`;
+        const targetKeys = new Set();
+        this.sessionTargetKeys.set(session.sessionId, targetKeys);
+        const windows = [];
+        for (const item of raw.windows ?? []) {
+            if (typeof item.id !== "string" || item.id === "")
+                continue;
+            const windowId = item.id;
+            windows.push({
+                version: 1,
+                windowId,
+                appId: `process:${Number(item.processId ?? 0)}`,
+                title: item.name ?? "",
+                bounds: rectangle(item),
+            });
+        }
+        const visibleWindows = session.applicationId === undefined
+            ? windows
+            : windows.filter((window) => window.appId === session.applicationId);
+        for (const window of visibleWindows) {
+            const key = this.targetKey(session.sessionId, "window", window.windowId);
+            this.targets.set(key, { sessionId: session.sessionId, observationId, windowId: window.windowId });
+            targetKeys.add(key);
+        }
+        const controls = [];
+        for (const item of raw.controls ?? []) {
+            if (typeof item.windowId !== "string" || !visibleWindows.some((window) => window.windowId === item.windowId))
+                continue;
+            const controlId = item.controlId ?? "";
+            const key = this.targetKey(session.sessionId, "control", controlId);
+            this.targets.set(key, {
+                sessionId: session.sessionId,
+                observationId,
+                windowId: item.windowId,
+                controlId,
+            });
+            targetKeys.add(key);
+            controls.push({
+                version: 1,
+                controlId,
+                windowId: item.windowId,
+                role: item.role ?? "",
+                name: item.name ?? "",
+                bounds: rectangle(item),
+                enabled: item.enabled !== false,
+                ...(typeof item.value === "string" && item.value.length > 0 ? { value: item.value } : {}),
+            });
+        }
+        const focusedControlId = typeof raw.focusedControlId === "string" &&
+            controls.some((control) => control.controlId === raw.focusedControlId)
+            ? raw.focusedControlId
+            : undefined;
+        const observation = detachedFreeze({
+            version: 1,
+            sessionId: session.sessionId,
+            observationId,
+            source: "macos-ax",
+            windows: visibleWindows,
+            controls,
+            ...(focusedControlId !== undefined ? { focusedControlId } : {}),
+        });
+        this.latestObservationIds.set(session.sessionId, observationId);
+        this.observedSessions.add(session.sessionId);
+        return observation;
+    }
+    resolveTarget(sessionId, target) {
+        const identity = target.kind === "control" ? target.controlId : target.windowId;
+        const record = this.targets.get(this.targetKey(sessionId, target.kind, identity));
+        if (record === undefined ||
+            record.sessionId !== sessionId ||
+            record.observationId !== this.latestObservationIds.get(sessionId))
+            return undefined;
+        return {
+            windowId: record.windowId,
+            ...(record.controlId === undefined ? {} : { controlId: record.controlId }),
+        };
+    }
+    targetKey(sessionId, kind, identity) {
+        return `${sessionId}:${kind}:${identity}`;
+    }
+    invalidateObservation(sessionId) {
+        for (const key of this.sessionTargetKeys.get(sessionId) ?? [])
+            this.targets.delete(key);
+        this.sessionTargetKeys.delete(sessionId);
+        this.latestObservationIds.delete(sessionId);
+    }
+    verifyPostconditions(postconditions, observation) {
+        if (postconditions.length === 0)
+            return { status: "passed", checks: [] };
+        if (observation === undefined || !("observationId" in observation))
+            return { status: "unknown", checks: ["observation-unavailable"] };
+        const checks = [];
+        for (const condition of postconditions) {
+            const passed = this.checkPostcondition(condition, observation);
+            checks.push(`${condition.kind}:${passed ? "passed" : "failed"}`);
+            if (!passed)
+                return { status: "failed", checks };
+        }
+        return { status: "passed", checks };
+    }
+    checkPostcondition(condition, observation) {
+        if (condition.kind === "window-exists")
+            return observation.windows.some((window) => window.windowId === condition.windowId);
+        if (condition.kind === "control-exists")
+            return observation.controls.some((control) => control.controlId === condition.controlId);
+        if (condition.kind === "focused")
+            return observation.focusedControlId === condition.controlId;
+        const target = condition.target;
+        if (target.kind === "window") {
+            const window = observation.windows.find((item) => item.windowId === target.windowId);
+            if (window === undefined || condition.property !== "name")
+                return false;
+            return window.title === condition.expected;
+        }
+        // A coordinate target identifies no observed control, so it can never
+        // satisfy a property-equals postcondition.
+        if (target.kind === "coordinates")
+            return false;
+        const control = observation.controls.find((item) => {
+            if (item.controlId !== target.controlId)
+                return false;
+            return target.windowId === undefined || item.windowId === target.windowId;
+        });
+        if (control === undefined)
+            return false;
+        if (condition.property === "enabled")
+            return control.enabled === condition.expected;
+        if (condition.property === "name")
+            return control.name === condition.expected;
+        return control.value === condition.expected;
+    }
+    failed(operationId, code, message, causeCode) {
+        return { version: 1, operationId, status: "failed", summary: message, error: error(code, message, causeCode) };
+    }
+    cancelled(operationId, message) {
+        return {
+            version: 1,
+            operationId,
+            status: "cancelled",
+            summary: message,
+            error: error("cancelled", message, "stopped"),
+        };
+    }
+}
+const payloadErrorCode = (action) => {
+    if (action.kind === "key")
+        return "key_unsupported";
+    if (action.kind === "scroll")
+        return "direction_invalid";
+    return "target_not_found";
+};
+const payloadErrorMessage = (action) => {
+    if (action.kind === "key")
+        return "Key sequence does not match the supported macOS key grammar";
+    if (action.kind === "scroll")
+        return "Scroll direction must be up or down with optional :lines";
+    return "Target identity was not observed by macOS Accessibility";
+};
+/**
+ * The production input facade intentionally exposes no replay method. The
+ * driver remains responsible for using observed Accessibility identities
+ * (or explicit click coordinates) rather than global keyboard injection.
+ */
+export class DesktopMacosInputAdapter {
+    adapterId = "desktop-macos-ax";
+    adapterVersion = "1.0.0";
+    driver;
+    constructor(driver = new MacosAccessibilityDriver()) {
+        this.driver = driver;
+    }
+    probe() {
+        return this.driver.probe();
+    }
+    openSession(request) {
+        return this.driver.openSession(request);
+    }
+    observe(sessionId) {
+        return this.driver.observe(sessionId);
+    }
+    reobserve(sessionId) {
+        return this.driver.observe(sessionId);
+    }
+    execute(request) {
+        if (requiresDesktopUserConfirmation(request.action.kind)) {
+            return {
+                version: 1,
+                operationId: request.operationId,
+                status: "needs_user",
+                summary: `User confirmation required for ${request.action.kind}`,
+                error: {
+                    version: 1,
+                    code: "needs_user",
+                    message: `The ${request.action.kind} action is paused for the user`,
+                    causeCode: request.action.kind,
+                },
+            };
+        }
+        return this.driver.execute(request);
+    }
+    stop(sessionId) {
+        return this.driver.stop(sessionId);
+    }
+}
+//# sourceMappingURL=macos-ax-adapter.js.map