ucu-mcp 0.5.2 → 0.6.2

package/CHANGELOG.md

@@ -5,6 +5,74 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.6.2] - 2026-06-17
+
+修 `normalizeAppName` 名字匹配 bug + 清理死代码 + 补 TTL 测试。
+
+### Fixed
+
+- **selectWindowForApp 名字匹配 bug**（`helpers.ts`）：`normalizeAppName` 只做 `trim().toLowerCase()`，导致 `"cc-switch"`（用户输入）无法匹配 `"CC Switch"`（`NSRunningApplication.localizedName`）。fix：drop 所有非字母数字字符（`.replace(/[^a-z0-9]/g, "")`），所有变体归一化到 `"ccswitch"`。之前 `focus_app("cc-switch")` 因名字 mismatch 退到 tray fallback，误诊为 per-process 失效。
+- **appNameMatches 死代码清理**：去掉 startsWith/includes 带空格的条件（normalize 后无空格，永不命中），改为 includes 双向匹配。
+
+### Added
+
+- **denied/granted TTL 时效测试**（`permissions.test.ts`）：用 fake timers 验证 denied 1s / granted 5s 后 cache 失效重查（之前 Sync 73 记录说写了但未 commit）。
+
+### 真机验证
+
+- per-process 对 ZCode（原生 SwiftUI）完全生效：click(735,478) 返回 dispatch:per-pid，Warp 始终前台不被抢。
+
+## [0.6.1] - 2026-06-17
+
+响应流程并行化 + 短期缓存，降低 describe_screen / screenshot(describe) / focus_app 延迟。
+
+### Changed
+
+- **并发收集 describe_screen 4 源**：OCR + AX + foreground + screen 用 `Promise.all` 并发（之前串行）。
+- **并发 getSafetyContext**：listWindows + browser context 并行。
+- **并发 screenshot + describe**：`screenshot(describe:true)` 的截图和描述生成并行。
+- **listWindows in-flight 去重**：并发请求共享同一个 promise，避免重复 windowlist-helper 子进程。
+- **getScreenSize 实例缓存**：5s TTL。
+
+### Added
+
+- **permission check cache**（`permissions.ts`）：granted 5s / denied 1s TTL。denied 短 TTL 让用户授权后快速生效。
+- **AXPress spin 可调**：80ms→50ms 默认，env `UCU_AXPRESS_SPIN_MS` 可调（max 80ms）。
+
+### Tests
+
+- permission cache 测试、AXPress spin timing 测试。326 passed。
+
+## [0.6.0] - 2026-06-17
+
+对标 Codex 原生 computer use：输入注入走 per-process 路径，不移动全局光标、不抢前台。仅 Mac 端（与 Codex mac 版一致，Win 版只前台）。
+
+### Added — 核心后台能力
+
+- **skylight-helper（native/skylight/main.swift）**：第 4 个 Swift native helper。dlopen SkyLight.framework，`SLEventPostToPid`（私有 SPI）按 PID 投递鼠标事件——绕开全局 HID 流，光标不动。完整 cua-driver 配方：NSEvent bridge 构建（绕开 Chromium renderer 过滤）+ field 40 pid latch + `CGEventSetWindowLocation` + focus-without-raise（`SLPSPostEventRecordTo` 248-byte event record，不调 `SLPSSetFrontProcessWithOptions`）+ (-1,-1) primer 欺骗 Chromium user-activation gate。键盘走公开 `CGEventPostToPid`。frontmost/canvas app 自动 fallback HID-tap。
+- **pid/windowNumber 透传链**：`WindowInfo`/`AppTarget` 加 `windowNumber`（真实 CGWindowID，window.ts 原本丢弃了）。`macos/input.ts` 读 `activeTarget` 透传到 `utils/input.ts`。`utils/input.ts` 函数加 `target` 参数，pid>0 走 skylight-helper，否则 fallback cgevent-helper（HID-tap）。
+- **AX 保活（方向4b 根因修复）**：skylight-helper 的 `keepAlive` 命令写 `AXManualAccessibility`/`AXEnhancedUserInterface` + 订阅 remote-aware AX observer（`_AXObserverAddNotificationAndCheckRemote`，符号缺失时 fallback 公开 API）。focusApp 成功后调用，保活目标 AX 树（被遮挡的 Electron/Tauri 不再冻结 → AXPress 不再静默失败）。
+- **tray per-process**：`MenuBarExtraItem` 加 `pid` 字段，findMenuBarExtra 捕获 SystemUIServer pid。focusApp 建 tray target 时用真实 host pid（非 0），tray 坐标点击也走 per-process。
+- **dispatch 信号透出**：所有输入工具返回 `result.dispatch`（`"per-pid" | "hid-tap"`）。hid-tap 时附 warning。doctor 检测 skylight-helper 可用性。
+- **DispatchMethod 类型**（base.ts）：Platform 接口 mouse/keyboard 方法返回 `Promise<DispatchMethod | void>`。
+
+### Changed
+
+- **element.ts 坐标 fallback 迁移**：`JXA_COORDINATE_CLICK`（JXA HID-tap）重命名为 `JXA_BOUNDS_CENTER`（只算中心坐标）。clickElement/clickMenuBarExtra 的坐标点击退出 JXA，改在 TS 层调 `this.click()`（走 per-process）。
+- SKILL.md：加 "Dispatch method (v0.6.0+)" 节 + Operating Rules 加 "focus_app before input"。
+
+### 真机验证（2026-06-17）
+
+- ✅ skylight-helper ping 返回 `{"ok":true,"skylight":true}`（SPI 全加载）。
+- ✅ 对后台 Finder pid click(100,100) 返回 `method:per-pid`，光标不跳到 (100,100)（HID-tap 会直接跳过去）——核心承诺验证。
+- ✅ keepAlive 对 Finder pid 返回 `method:ax-keepalive`。
+- ✅ 310 tests passed（4 native helpers 全编译）。
+
+### 已知限制
+
+- Canvas/GPU app（Blender/Unity/游戏）的 event loop 只接受 HID-tap → 自动 fallback，返回 `dispatch:"hid-tap"` + warning。
+- `_AXObserverAddNotificationAndCheckRemote` 符号在本机未通过 dlsym 解析（remote:false），但 AXManualAccessibility/AXEnhancedUserInterface 属性写入生效（覆盖非 Chromium 场景）。
+
 ## [0.5.2] - 2026-06-17
 
 Agent Skill 重写为 CLI agent 优先（Claude Code / Codex / OpenCode 都是 stdio CLI 环境）。

package/dist/src/mcp/tools/app-tools.js

@@ -122,10 +122,12 @@ export function registerAppTools(registerTool) {
             const cgevent = resolveHelperPath(["native", "cgevent", "cgevent-helper"]);
             const ocr = resolveHelperPath(["native", "ocr", "ocr-helper"]);
             const windowlist = resolveHelperPath(["native", "windowlist", "windowlist-helper"]);
+            const skylight = resolveHelperPath(["native", "skylight", "skylight-helper"]);
             nativeHelpers = {
                 cgevent: { ok: cgevent.path !== null, path: cgevent.path, tried: cgevent.tried },
                 ocr: { ok: ocr.path !== null, path: ocr.path, tried: ocr.tried },
                 windowlist: { ok: windowlist.path !== null, path: windowlist.path, tried: windowlist.tried },
+                skylight: { ok: skylight.path !== null, path: skylight.path, tried: skylight.tried },
             };
         }
         let readiness = "ready";
@@ -153,6 +155,11 @@ export function registerAppTools(registerTool) {
                 readiness = readiness === "ready" ? "degraded" : readiness;
                 issues.push("Native windowlist helper not found (window enumeration will fall back to slow JXA). Run `npm run build` to compile it.");
             }
+            if (!nativeHelpers.skylight.ok) {
+                // skylight missing → per-process posting unavailable; input falls back to
+                // HID-tap (moves cursor). Note as info, not degraded, since HID-tap still works.
+                issues.push("Native skylight helper not found (per-process event posting unavailable — clicks/typing will move the cursor via HID-tap). Run `npm run build` to compile it.");
+            }
         }
         const electronHint = "If the target app is Electron (e.g. CC Switch, VS Code, Discord), list_windows may return [] even with Accessibility granted to your terminal. Grant Accessibility to the Electron app itself in System Settings > Privacy & Security > Accessibility, and restart the app. Pixel-level workaround: use screenshot + ocr to locate UI elements by text, then click(x, y) at the detected bounding box coordinates. Alternatively, modify the app\'s config file or database directly.";
         const clients = {};

package/dist/src/mcp/tools/helpers.js

@@ -42,28 +42,38 @@ export async function resolvePoint(x, y, windowId) {
 export async function getSafetyContext(windowId) {
     const target = activeTargetContext;
     const effectiveWindowId = windowId ?? target?.windowId;
-    let windowTitle;
-    if (effectiveWindowId) {
-        try {
-            const windows = await getPlatform().listWindows();
-            const win = windows.find(w => w.id === effectiveWindowId);
-            windowTitle = win?.title;
-        }
-        catch { /* best effort */ }
-    }
-    if (!windowTitle && target?.title) {
-        windowTitle = target.title;
-    }
-    let url;
-    const platform = getPlatform();
-    if (platform.getActiveBrowserContext) {
-        try {
-            const appName = target?.appName;
-            const ctx = await platform.getActiveBrowserContext(appName);
-            url = ctx?.url;
-        }
-        catch { /* best effort */ }
-    }
+    // Resolve window title and browser URL concurrently; they have no dependency.
+    const [windowTitleResult, urlResult] = await Promise.all([
+        (async () => {
+            if (!effectiveWindowId)
+                return undefined;
+            try {
+                const windows = await getPlatform().listWindows();
+                const win = windows.find((w) => w.id === effectiveWindowId);
+                return win?.title;
+            }
+            catch {
+                /* best effort */
+                return undefined;
+            }
+        })(),
+        (async () => {
+            const platform = getPlatform();
+            if (!platform.getActiveBrowserContext)
+                return undefined;
+            try {
+                const appName = target?.appName;
+                const ctx = await platform.getActiveBrowserContext(appName);
+                return ctx?.url;
+            }
+            catch {
+                /* best effort */
+                return undefined;
+            }
+        })(),
+    ]);
+    const windowTitle = windowTitleResult || target?.title;
+    const url = urlResult;
     return { windowTitle, url };
 }
 export function jsonText(value) {

package/dist/src/mcp/tools/input-tools.js

@@ -1,5 +1,11 @@
 import { z } from "zod";
 import { getPlatform, resolvePoint, getSafetyContext, withSafety, actionResponse, captureAfterFields, } from "./helpers.js";
+/** Warning text emitted when an input action had to fall back to HID-tap (moves the cursor). */
+const HID_TAP_WARNING = "Event dispatched via global HID tap (moved the cursor / may disturb foreground). This happens for frontmost or canvas/GPU apps where per-process posting is filtered.";
+function dispatchWarnings(dispatch) {
+    // undefined means JXA fallback (HID-tap) or no target — warn in both cases.
+    return dispatch === "per-pid" ? [] : [HID_TAP_WARNING];
+}
 export function registerInputTools(registerTool) {
     registerTool("click", "Click at screen coordinates", {
         x: z.number().describe("X coordinate"), y: z.number().describe("Y coordinate"),
@@ -9,8 +15,8 @@ export function registerInputTools(registerTool) {
     }, async (params) => {
         const pt = await resolvePoint(params.x, params.y, params.windowId);
         const safetyCtx = await getSafetyContext(params.windowId);
-        await withSafety({ action: "click", params: { x: pt.x, y: pt.y, ...safetyCtx }, requiresAccessibility: true, execute: () => getPlatform().click(pt.x, pt.y, params.button) });
-        return actionResponse("click", { clicked: true, x: pt.x, y: pt.y }, { x: pt.x, y: pt.y, windowId: params.windowId }, params.captureAfter, params.captureFormat, params.captureMaxWidth);
+        const dispatch = await withSafety({ action: "click", params: { x: pt.x, y: pt.y, ...safetyCtx }, requiresAccessibility: true, execute: () => getPlatform().click(pt.x, pt.y, params.button) });
+        return actionResponse("click", { clicked: true, x: pt.x, y: pt.y, dispatch: dispatch ?? "hid-tap" }, { x: pt.x, y: pt.y, windowId: params.windowId }, params.captureAfter, params.captureFormat, params.captureMaxWidth, dispatchWarnings(dispatch));
     });
     registerTool("double_click", "Double-click at screen coordinates", {
         x: z.number().describe("X coordinate"), y: z.number().describe("Y coordinate"),
@@ -20,8 +26,8 @@ export function registerInputTools(registerTool) {
     }, async (params) => {
         const pt = await resolvePoint(params.x, params.y, params.windowId);
         const safetyCtx = await getSafetyContext(params.windowId);
-        await withSafety({ action: "double_click", params: { x: pt.x, y: pt.y, doubleClick: true, ...safetyCtx }, requiresAccessibility: true, execute: () => getPlatform().click(pt.x, pt.y, params.button, true) });
-        return actionResponse("double_click", { doubleClicked: true, x: pt.x, y: pt.y }, { x: pt.x, y: pt.y, windowId: params.windowId }, params.captureAfter, params.captureFormat, params.captureMaxWidth);
+        const dispatch = await withSafety({ action: "double_click", params: { x: pt.x, y: pt.y, doubleClick: true, ...safetyCtx }, requiresAccessibility: true, execute: () => getPlatform().click(pt.x, pt.y, params.button, true) });
+        return actionResponse("double_click", { doubleClicked: true, x: pt.x, y: pt.y, dispatch: dispatch ?? "hid-tap" }, { x: pt.x, y: pt.y, windowId: params.windowId }, params.captureAfter, params.captureFormat, params.captureMaxWidth, dispatchWarnings(dispatch));
     });
     registerTool("scroll", "Scroll at coordinates", {
         x: z.number().describe("X coordinate"), y: z.number().describe("Y coordinate"),
@@ -32,8 +38,8 @@ export function registerInputTools(registerTool) {
         const pt = await resolvePoint(params.x, params.y, params.windowId);
         const deltaX = params.deltaX ?? 0;
         const safetyCtx = await getSafetyContext(params.windowId);
-        await withSafety({ action: "scroll", params: { x: pt.x, y: pt.y, ...safetyCtx }, requiresAccessibility: true, execute: () => getPlatform().scroll(pt.x, pt.y, deltaX, params.deltaY) });
-        return actionResponse("scroll", { scrolled: true, x: pt.x, y: pt.y }, { x: pt.x, y: pt.y, windowId: params.windowId }, params.captureAfter, params.captureFormat, params.captureMaxWidth);
+        const dispatch = await withSafety({ action: "scroll", params: { x: pt.x, y: pt.y, ...safetyCtx }, requiresAccessibility: true, execute: () => getPlatform().scroll(pt.x, pt.y, deltaX, params.deltaY) });
+        return actionResponse("scroll", { scrolled: true, x: pt.x, y: pt.y, dispatch: dispatch ?? "hid-tap" }, { x: pt.x, y: pt.y, windowId: params.windowId }, params.captureAfter, params.captureFormat, params.captureMaxWidth, dispatchWarnings(dispatch));
     });
     registerTool("drag", "Drag from one point to another", {
         startX: z.number().describe("Start X"), startY: z.number().describe("Start Y"),
@@ -46,8 +52,8 @@ export function registerInputTools(registerTool) {
         const start = await resolvePoint(params.startX, params.startY, params.windowId);
         const end = await resolvePoint(params.endX, params.endY, params.windowId);
         const safetyCtx = await getSafetyContext(params.windowId);
-        await withSafety({ action: "drag", params: { startX: start.x, startY: start.y, endX: end.x, endY: end.y, ...safetyCtx }, requiresAccessibility: true, execute: () => getPlatform().drag(start.x, start.y, end.x, end.y, params.button, params.duration) });
-        return actionResponse("drag", { dragged: true, startX: start.x, startY: start.y, endX: end.x, endY: end.y }, { startX: start.x, startY: start.y, endX: end.x, endY: end.y, windowId: params.windowId }, params.captureAfter, params.captureFormat, params.captureMaxWidth);
+        const dispatch = await withSafety({ action: "drag", params: { startX: start.x, startY: start.y, endX: end.x, endY: end.y, ...safetyCtx }, requiresAccessibility: true, execute: () => getPlatform().drag(start.x, start.y, end.x, end.y, params.button, params.duration) });
+        return actionResponse("drag", { dragged: true, startX: start.x, startY: start.y, endX: end.x, endY: end.y, dispatch: dispatch ?? "hid-tap" }, { startX: start.x, startY: start.y, endX: end.x, endY: end.y, windowId: params.windowId }, params.captureAfter, params.captureFormat, params.captureMaxWidth, dispatchWarnings(dispatch));
     });
     registerTool("move", "Move cursor to coordinates", {
         x: z.number().describe("X coordinate"), y: z.number().describe("Y coordinate"),
@@ -56,8 +62,8 @@ export function registerInputTools(registerTool) {
     }, async (params) => {
         const pt = await resolvePoint(params.x, params.y, params.windowId);
         const safetyCtx = await getSafetyContext(params.windowId);
-        await withSafety({ action: "move", params: { x: pt.x, y: pt.y, ...safetyCtx }, requiresAccessibility: true, execute: () => getPlatform().move(pt.x, pt.y) });
-        return actionResponse("move", { moved: true, x: pt.x, y: pt.y }, { x: pt.x, y: pt.y, windowId: params.windowId }, params.captureAfter, params.captureFormat, params.captureMaxWidth);
+        const dispatch = await withSafety({ action: "move", params: { x: pt.x, y: pt.y, ...safetyCtx }, requiresAccessibility: true, execute: () => getPlatform().move(pt.x, pt.y) });
+        return actionResponse("move", { moved: true, x: pt.x, y: pt.y, dispatch: dispatch ?? "hid-tap" }, { x: pt.x, y: pt.y, windowId: params.windowId }, params.captureAfter, params.captureFormat, params.captureMaxWidth, dispatchWarnings(dispatch));
     });
     registerTool("get_cursor_position", "Get current cursor position", {}, async () => {
         const pos = await withSafety({ action: "get_cursor_position", params: {}, execute: () => Promise.resolve(getPlatform().getCursorPosition()) });

package/dist/src/mcp/tools/keyboard-tools.js

@@ -1,6 +1,10 @@
 import { z } from "zod";
 import { UnsupportedParameterError } from "../../util/errors.js";
 import { getPlatform, getSafetyContext, withSafety, actionResponse, captureAfterFields, } from "./helpers.js";
+function keyDispatchWarnings(dispatch) {
+    // undefined means JXA fallback (HID-tap) or no target — warn in both cases.
+    return dispatch === "per-pid" ? [] : ["Key event dispatched via global HID tap (no target pid available; may affect foreground). Use focus_app first to enable per-process posting."];
+}
 export function registerKeyboardTools(registerTool) {
     registerTool("type_text", "Type text at the current cursor position", {
         text: z.string().describe("Text to type"), delay: z.number().optional().describe("Delay between keystrokes in ms"),
@@ -10,8 +14,8 @@ export function registerKeyboardTools(registerTool) {
         if (params.windowId)
             throw new UnsupportedParameterError("windowId-targeted keyboard typing is not implemented");
         const safetyCtx = await getSafetyContext();
-        await withSafety({ action: "type_text", params: { text: params.text, ...safetyCtx }, requiresAccessibility: true, execute: () => getPlatform().type(params.text, params.delay) });
-        return actionResponse("type_text", { typed: true, charCount: params.text.length }, {}, params.captureAfter, params.captureFormat, params.captureMaxWidth);
+        const dispatch = await withSafety({ action: "type_text", params: { text: params.text, ...safetyCtx }, requiresAccessibility: true, execute: () => getPlatform().type(params.text, params.delay) });
+        return actionResponse("type_text", { typed: true, charCount: params.text.length, dispatch: dispatch ?? "hid-tap" }, {}, params.captureAfter, params.captureFormat, params.captureMaxWidth, keyDispatchWarnings(dispatch));
     });
     registerTool("press_key", "Press a keyboard shortcut", {
         keys: z.array(z.string()).optional().describe("Keys to press simultaneously — special keys (enter/escape/tab/f1-f12/arrows...), single letters a-z, or single digits 0-9"),
@@ -29,7 +33,7 @@ export function registerKeyboardTools(registerTool) {
         if (keys.length === 0)
             throw new UnsupportedParameterError("press_key requires at least one key");
         const safetyCtx = await getSafetyContext();
-        await withSafety({ action: "press_key", params: { keys, ...safetyCtx }, requiresAccessibility: true, execute: () => getPlatform().key(keys) });
-        return actionResponse("press_key", { pressed: true, keys }, {}, params.captureAfter, params.captureFormat, params.captureMaxWidth);
+        const dispatch = await withSafety({ action: "press_key", params: { keys, ...safetyCtx }, requiresAccessibility: true, execute: () => getPlatform().key(keys) });
+        return actionResponse("press_key", { pressed: true, keys, dispatch: dispatch ?? "hid-tap" }, {}, params.captureAfter, params.captureFormat, params.captureMaxWidth, keyDispatchWarnings(dispatch));
     });
 }

package/dist/src/mcp/tools/screen-tools.js

@@ -24,73 +24,102 @@ function maskSensitiveFields(el) {
  * is collected independently inside try/catch. Failures go to `errors` and set the
  * corresponding status; the function never throws. This is the text fallback for
  * environments where image content blocks are downgraded to URLs.
+ *
+ * Sources are collected concurrently because they have no data dependencies.
  */
 async function buildScreenDescription(opts) {
     const platform = getPlatform();
     const errors = [];
     const capturedAt = new Date().toISOString();
-    // screen — sync, almost never fails
-    let screen;
-    try {
-        screen = platform.getScreenSize(opts.display);
-    }
-    catch (e) {
-        screen = { width: 0, height: 0, scaleFactor: 1, estimated: true };
-        errors.push({ source: "screen", message: `getScreenSize failed: ${e.message}` });
-    }
-    // foreground window — listApps() isFrontmost → listWindows() filter by processName + isOnScreen
-    let foregroundWindow;
-    try {
-        if (platform.listApps) {
+    const collectScreen = async () => {
+        try {
+            return { ok: true, value: platform.getScreenSize(opts.display) };
+        }
+        catch (e) {
+            return { ok: false, error: `getScreenSize failed: ${e.message}` };
+        }
+    };
+    const collectForeground = async () => {
+        try {
+            if (!platform.listApps)
+                return { ok: true, value: undefined };
             const apps = await platform.listApps();
             const front = apps.find((a) => a.isFrontmost);
-            if (front) {
-                const wins = await platform.listWindows(true);
-                foregroundWindow = wins.find((w) => w.processName === front.name && w.isOnScreen);
-            }
+            if (!front)
+                return { ok: true, value: undefined };
+            const wins = await platform.listWindows(true);
+            return { ok: true, value: wins.find((w) => w.processName === front.name && w.isOnScreen) };
+        }
+        catch (e) {
+            return { ok: false, error: `foreground window resolution failed: ${e.message}` };
+        }
+    };
+    const collectOcr = async () => {
+        if (!opts.runOcr) {
+            return { ok: true, value: { blocks: [], fullText: "", status: "skipped" } };
         }
-    }
-    catch (e) {
-        errors.push({ source: "foreground", message: `foreground window resolution failed: ${e.message}` });
-    }
-    // OCR — cap blocks to ocrBlocks via slice
-    let ocr;
-    if (opts.runOcr) {
         try {
             const result = await platform.ocr(opts.display);
-            ocr = {
-                blocks: result.elements.slice(0, opts.ocrBlocks),
-                fullText: result.fullText,
-                status: "ok",
+            return {
+                ok: true,
+                value: {
+                    blocks: result.elements.slice(0, opts.ocrBlocks),
+                    fullText: result.fullText,
+                    status: "ok",
+                },
             };
         }
         catch (e) {
-            ocr = { blocks: [], fullText: "", status: "failed" };
-            errors.push({ source: "ocr", message: `ocr failed: ${e.message}` });
+            return {
+                ok: false,
+                value: { blocks: [], fullText: "", status: "failed" },
+                error: `ocr failed: ${e.message}`,
+            };
+        }
+    };
+    const collectAx = async () => {
+        if (!opts.includeAx) {
+            return { ok: true, value: { status: "skipped" } };
         }
-    }
-    else {
-        ocr = { blocks: [], fullText: "", status: "skipped" };
-    }
-    // AX — getWindowState with depth cap, password masking applied
-    let ax;
-    if (opts.includeAx) {
         const effectiveWindowId = opts.windowId ?? getActiveTarget()?.windowId;
         try {
             const cappedDepth = Math.min(opts.axDepth, 10);
             const state = await platform.getWindowState(effectiveWindowId, cappedDepth, true);
             maskSensitiveFields(state.tree);
             maskSensitiveFields(state.focusedElement);
-            ax = { elements: state.tree, status: "ok", windowId: effectiveWindowId };
+            return {
+                ok: true,
+                value: { elements: state.tree, status: "ok", windowId: effectiveWindowId },
+            };
         }
         catch (e) {
-            ax = { status: "failed", windowId: effectiveWindowId };
-            errors.push({ source: "ax", message: `getWindowState failed: ${e.message}` });
+            return {
+                ok: false,
+                value: { status: "failed", windowId: effectiveWindowId },
+                error: `getWindowState failed: ${e.message}`,
+            };
         }
-    }
-    else {
-        ax = { status: "skipped" };
-    }
+    };
+    const [screenResult, foregroundResult, ocrResult, axResult] = await Promise.all([
+        collectScreen(),
+        collectForeground(),
+        collectOcr(),
+        collectAx(),
+    ]);
+    const screen = screenResult.ok
+        ? screenResult.value
+        : { width: 0, height: 0, scaleFactor: 1, estimated: true };
+    if (!screenResult.ok)
+        errors.push({ source: "screen", message: screenResult.error });
+    const foregroundWindow = foregroundResult.ok ? foregroundResult.value : undefined;
+    if (!foregroundResult.ok)
+        errors.push({ source: "foreground", message: foregroundResult.error });
+    const ocr = ocrResult.ok ? ocrResult.value : ocrResult.value ?? { blocks: [], fullText: "", status: "failed" };
+    if (!ocrResult.ok)
+        errors.push({ source: "ocr", message: ocrResult.error });
+    const ax = axResult.ok ? axResult.value : axResult.value ?? { status: "failed" };
+    if (!axResult.ok)
+        errors.push({ source: "ax", message: axResult.error });
     return { capturedAt, screen, foregroundWindow, ocr, ax, errors };
 }
 export function registerScreenTools(registerTool) {
@@ -110,7 +139,7 @@ export function registerScreenTools(registerTool) {
         if (params.windowId && params.region)
             throw new UnsupportedParameterError("screenshot windowId cannot be combined with region");
         const options = { format: params.format, maxWidth: params.maxWidth };
-        const buf = await withSafety({
+        const screenshotPromise = withSafety({
             action: "screenshot",
             params,
             requiresScreenRecording: true,
@@ -120,17 +149,20 @@ export function registerScreenTools(registerTool) {
                     : Promise.reject(new UnsupportedParameterError("window screenshots are not implemented on this platform"))
                 : getPlatform().screenshot(params.display, params.region, options),
         });
-        const content = [{ type: "image", data: buf.toString("base64"), mimeType: `image/${params.format}` }];
-        if (params.describe) {
-            const opts = params.describeOptions ?? { axDepth: 3, ocrBlocks: 50, includeAx: true };
-            const desc = await buildScreenDescription({
+        const describeOpts = params.describeOptions ?? { axDepth: 3, ocrBlocks: 50, includeAx: true };
+        const descriptionPromise = params.describe
+            ? buildScreenDescription({
                 display: params.display,
                 runOcr: true,
-                includeAx: opts.includeAx ?? true,
-                axDepth: opts.axDepth ?? 3,
-                ocrBlocks: opts.ocrBlocks ?? 50,
+                includeAx: describeOpts.includeAx ?? true,
+                axDepth: describeOpts.axDepth ?? 3,
+                ocrBlocks: describeOpts.ocrBlocks ?? 50,
                 windowId: params.windowId,
-            });
+            })
+            : Promise.resolve(undefined);
+        const [buf, desc] = await Promise.all([screenshotPromise, descriptionPromise]);
+        const content = [{ type: "image", data: buf.toString("base64"), mimeType: `image/${params.format}` }];
+        if (desc) {
             content.push(jsonText(desc));
         }
         return { content };

package/dist/src/platform/base.d.ts

@@ -31,6 +31,8 @@ export interface WindowInfo {
     };
     isMinimized: boolean;
     isOnScreen: boolean;
+    /** Real CGWindowID (kCGWindowNumber) — needed for per-process event posting (focus-without-raise). Undefined for JXA-fallback enumeration. */
+    windowNumber?: number;
 }
 export interface AppInfo {
     name: string;
@@ -45,6 +47,8 @@ export interface AppTarget {
     windowId?: string;
     title?: string;
     capturedAt: string;
+    /** Real CGWindowID for per-process event posting (focus-without-raise). Absent for tray targets. */
+    windowNumber?: number;
 }
 export interface BrowserContext {
     appName: string;
@@ -162,6 +166,13 @@ export interface ScreenDescription {
         message: string;
     }>;
 }
+/**
+ * How an input event was dispatched. "per-pid" = posted to the target process
+ * via SLEventPostToPid/CGEventPostToPid (no global cursor move, no foreground
+ * theft — Codex-style background operation). "hid-tap" = posted to the global
+ * HID event tap (moves the cursor; fallback when no pid or skylight unavailable).
+ */
+export type DispatchMethod = "per-pid" | "hid-tap";
 export interface Platform {
     screenshot(display?: number, region?: ScreenRegion, options?: ScreenshotOptions): Promise<Buffer>;
     screenshotWindow?(windowId: string, options?: ScreenshotOptions): Promise<Buffer>;
@@ -171,14 +182,14 @@ export interface Platform {
     getActiveBrowserContext?(app?: string): Promise<BrowserContext | undefined>;
     listWindows(includeMinimized?: boolean): Promise<WindowInfo[]>;
     getWindowState(windowId?: string, depth?: number, includeBounds?: boolean): Promise<WindowState>;
-    click(x: number, y: number, button?: "left" | "right" | "middle", doubleClick?: boolean): Promise<void>;
-    move(x: number, y: number): Promise<void>;
-    drag(startX: number, startY: number, endX: number, endY: number, button?: "left" | "right" | "middle", duration?: number): Promise<void>;
-    scroll(x: number, y: number, deltaX: number, deltaY: number): Promise<void>;
+    click(x: number, y: number, button?: "left" | "right" | "middle", doubleClick?: boolean): Promise<DispatchMethod | void>;
+    move(x: number, y: number): Promise<DispatchMethod | void>;
+    drag(startX: number, startY: number, endX: number, endY: number, button?: "left" | "right" | "middle", duration?: number): Promise<DispatchMethod | void>;
+    scroll(x: number, y: number, deltaX: number, deltaY: number): Promise<DispatchMethod | void>;
     getCursorPosition(): CursorPosition;
     ocr(display?: number, region?: ScreenRegion): Promise<OcrResult>;
-    type(text: string, delay?: number): Promise<void>;
-    key(keys: string[]): Promise<void>;
+    type(text: string, delay?: number): Promise<DispatchMethod | void>;
+    key(keys: string[]): Promise<DispatchMethod | void>;
     findElement(options: FindElementOptions): Promise<FindElementResponse>;
     clickElement(elementId: string, app?: string): Promise<ClickResult>;
     typeInElement(elementId: string, text: string, app?: string, clearFirst?: boolean): Promise<void>;

package/dist/src/platform/macos/base.d.ts

@@ -1,8 +1,8 @@
-import type { Platform, WindowInfo, AppTarget } from "../base.js";
+import type { Platform, WindowInfo, AppTarget, ScreenSize } from "../base.js";
 import type { CachedElementDescriptor, MacOSPlatformOptions } from "./helpers.js";
 import { saveFocus, restoreFocus } from "./focus.js";
 import { screenshot, screenshotWindow, getScreenSize, isScreenLocked, ocr } from "./screen.js";
-import { listApps, focusApp, getActiveBrowserContext, listWindows } from "./window.js";
+import { listApps, focusApp, getActiveBrowserContext, listWindows, keepTargetAxAlive } from "./window.js";
 import { getWindowState, findElement } from "./ax-tree.js";
 import { click, move, drag, scroll, getCursorPosition, type as typeMethod, key } from "./input.js";
 import { clickElement, typeInElement, setElementValue, findMenuBarExtra, clickMenuBarExtra } from "./element.js";
@@ -18,7 +18,13 @@ export declare class MacOSPlatform implements Platform {
         cachedAt: number;
         windows: WindowInfo[];
     } | undefined;
-    windowCacheInFlight: boolean;
+    windowCachePromise: Promise<WindowInfo[]> | undefined;
+    readonly screenSizeCacheTtlMs = 5000;
+    screenSizeCache: {
+        display: number;
+        cachedAt: number;
+        size: ScreenSize;
+    } | undefined;
     activeTarget: AppTarget | undefined;
     savedFocus: {
         appName: string;
@@ -29,6 +35,8 @@ export declare class MacOSPlatform implements Platform {
     evictOverflowCacheEntries(): void;
     isCacheEntryExpired(descriptor: CachedElementDescriptor): boolean;
     validateActiveTarget(): Promise<void>;
+    /** @internal Test hook to clear the screen-size cache. */
+    __resetScreenSizeCache(): void;
     saveFocus: typeof saveFocus;
     restoreFocus: typeof restoreFocus;
     screenshot: typeof screenshot;
@@ -39,6 +47,7 @@ export declare class MacOSPlatform implements Platform {
     listApps: typeof listApps;
     focusApp: typeof focusApp;
     getActiveBrowserContext: typeof getActiveBrowserContext;
+    keepTargetAxAlive: typeof keepTargetAxAlive;
     listWindows: typeof listWindows;
     getWindowState: typeof getWindowState;
     findElement: typeof findElement;

package/dist/src/platform/macos/base.js

@@ -1,7 +1,7 @@
 import { TargetStaleError } from "../../util/errors.js";
 import { saveFocus, restoreFocus } from "./focus.js";
 import { screenshot, screenshotWindow, getScreenSize, isScreenLocked, ocr } from "./screen.js";
-import { listApps, focusApp, getActiveBrowserContext, listWindows } from "./window.js";
+import { listApps, focusApp, getActiveBrowserContext, listWindows, keepTargetAxAlive } from "./window.js";
 import { getWindowState, findElement } from "./ax-tree.js";
 import { click, move, drag, scroll, getCursorPosition, type as typeMethod, key } from "./input.js";
 import { clickElement, typeInElement, setElementValue, findMenuBarExtra, clickMenuBarExtra } from "./element.js";
@@ -13,7 +13,9 @@ export class MacOSPlatform {
     elementCacheMaxSize = 100;
     windowCacheTtlMs = 300;
     windowCache;
-    windowCacheInFlight = false;
+    windowCachePromise;
+    screenSizeCacheTtlMs = 5000;
+    screenSizeCache;
     activeTarget;
     savedFocus;
     constructor(options) {
@@ -58,6 +60,7 @@ export class MacOSPlatform {
         if (this.activeTarget.windowId === "tray")
             return;
         this.windowCache = undefined;
+        this.windowCachePromise = undefined;
         const windows = await this.listWindows(true);
         const match = windows.find(w => w.id === this.activeTarget.windowId);
         if (!match) {
@@ -67,6 +70,10 @@ export class MacOSPlatform {
             throw new TargetStaleError(this.activeTarget.windowId);
         }
     }
+    /** @internal Test hook to clear the screen-size cache. */
+    __resetScreenSizeCache() {
+        this.screenSizeCache = undefined;
+    }
     // ── Bound methods from domain modules ────────────────────────────────────
     saveFocus = saveFocus;
     restoreFocus = restoreFocus;
@@ -78,6 +85,7 @@ export class MacOSPlatform {
     listApps = listApps;
     focusApp = focusApp;
     getActiveBrowserContext = getActiveBrowserContext;
+    keepTargetAxAlive = keepTargetAxAlive;
     listWindows = listWindows;
     getWindowState = getWindowState;
     findElement = findElement;

package/dist/src/platform/macos/element.d.ts

@@ -14,6 +14,8 @@ export interface MenuBarExtraItem {
     height: number;
     /** Which process hosts this status item. "self" = app's own menu bar; "systemuiserver" = third-party tray hosted by SystemUIServer. */
     host: "self" | "systemuiserver";
+    /** The hosting process pid — app's own pid for host:"self", SystemUIServer's pid for host:"systemuiserver". Enables per-process event posting. */
+    pid: number;
 }
 export interface MenuBarExtraSelector {
     description?: string;