ucu-mcp 0.5.2 → 0.6.0

package/CHANGELOG.md

@@ -5,6 +5,36 @@ 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.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/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/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

@@ -2,7 +2,7 @@ import type { Platform, WindowInfo, AppTarget } 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";
@@ -39,6 +39,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";
@@ -78,6 +78,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;

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

@@ -44,23 +44,16 @@ const JXA_STATE_SIGNATURE = `
   function spinMs(ms) { var t = Date.now(); while (Date.now() - t < ms) {} }
 `;
 /**
- * Shared JXA snippet: perform a coordinate click at the element's bounds center.
- * Returns the {x, y} used, or null if bounds could not be read.
+ * Shared JXA snippet: compute the element's bounds center (for coordinate fallback).
+ * Does NOT post any event — the actual click is performed by the TS input layer
+ * (this.click) so it routes through per-process posting (skylight-helper) when a
+ * pid is available, instead of the JXA HID-tap that would move the global cursor.
  */
-const JXA_COORDINATE_CLICK = `
-  function coordinateClick(elem) {
+const JXA_BOUNDS_CENTER = `
+  function boundsCenter(elem) {
     var pos = elem.position();
     var sz = elem.size();
-    var cx = pos[0] + sz[0] / 2;
-    var cy = pos[1] + sz[1] / 2;
-    ObjC.import('CoreGraphics');
-    var src = $.CGEventSourceCreate($.kCGEventSourceStateHIDSystemState);
-    var pt = $.CGPointMake(cx, cy);
-    var down = $.CGEventCreateMouseEvent(src, $.kCGEventLeftMouseDown, pt, $.kCGMouseButtonLeft);
-    $.CGEventPost($.kCGHIDEventTap, down);
-    var up = $.CGEventCreateMouseEvent(src, $.kCGEventLeftMouseUp, pt, $.kCGMouseButtonLeft);
-    $.CGEventPost($.kCGHIDEventTap, up);
-    return {x: cx, y: cy};
+    return {x: pos[0] + sz[0] / 2, y: pos[1] + sz[1] / 2};
   }
 `;
 export async function clickElement(elementId, app) {
@@ -75,7 +68,7 @@ export async function clickElement(elementId, app) {
     var _result = null;
     ${jxaElementActionHelpers()}
     ${JXA_STATE_SIGNATURE}
-    ${JXA_COORDINATE_CLICK}
+    ${JXA_BOUNDS_CENTER}
     var elemPath = ${elementIdLiteral};
     var appName = ${appLiteral};
     // 容忍大小写/空格/连字符/下划线变体（cc-switch vs CC Switch vs cc_switch）
@@ -95,15 +88,11 @@ export async function clickElement(elementId, app) {
     if (!elem) {
       _result = {success: false, error: "Element not found: " + elemPath};
     } else if (preferCoord) {
-      // 启发式命中（Tauri 等已知静默吞 AXPress 的应用）：直接坐标点击
-      try {
-        coordinateClick(elem);
-        _result = {success: true, method: "coordinate", verified: false};
-      } catch(e) {
-        _result = {success: false, error: "Could not click element (coordinate): " + String(e.message || e)};
-      }
+      // 启发式命中（Tauri 等已知静默吞 AXPress 的应用）：请求坐标点击（TS 层执行 per-process）
+      var c = boundsCenter(elem);
+      _result = {success: true, needCoordinateClick: true, cx: c.x, cy: c.y};
     } else {
-      // AXPress + verify：采样前后状态签名，无变化则降级坐标
+      // AXPress + verify：采样前后状态签名，无变化则请求坐标点击
       var sigBefore = stateSignature(elem);
       var axpressThrew = false;
       try {
@@ -112,57 +101,50 @@ export async function clickElement(elementId, app) {
         axpressThrew = true;
       }
       if (axpressThrew) {
-        // AXPress 抛异常 → 坐标 fallback
-        try {
-          coordinateClick(elem);
-          _result = {success: true, method: "coordinate", verified: false};
-        } catch(e2) {
-          _result = {success: false, error: "Could not click element: " + String(e2.message || e2)};
-        }
+        var c1 = boundsCenter(elem);
+        _result = {success: true, needCoordinateClick: true, cx: c1.x, cy: c1.y};
       } else {
-        // AXPress 未抛异常：spin 等待异步生效，再采样签名判断是否真的生效
         spinMs(80);
         var sigAfter = stateSignature(elem);
         if (sigBefore !== '' && sigAfter !== sigBefore) {
-          // 状态变化 → AXPress 生效
           _result = {success: true, method: "axpress", verified: true};
         } else if (sigBefore === '' && sigAfter === '') {
-          // 无可观测状态（纯按钮无 value/focused/selected）：无法 verify，
-          // 保守认为 AXPress 可能成功（不降级坐标，避免对正常按钮误伤）
           _result = {success: true, method: "axpress", verified: false};
         } else {
-          // 有可观测状态但无变化 → 静默吞，降级坐标
-          try {
-            coordinateClick(elem);
-            _result = {success: true, method: "coordinate", verified: false};
-          } catch(e3) {
-            _result = {success: false, error: "Could not click element (coordinate fallback): " + String(e3.message || e3)};
-          }
+          var c2 = boundsCenter(elem);
+          _result = {success: true, needCoordinateClick: true, cx: c2.x, cy: c2.y};
         }
       }
     }
     JSON.stringify(_result);
   `;
+    let result;
     try {
         const out = execFileSync("osascript", [
             "-l", "JavaScript",
             "-e", jxaScript,
         ], { encoding: "utf-8", timeout: 15000 }).trim();
-        const result = JSON.parse(out);
-        if (!result.success) {
-            throw result.error
-                ? new Error(result.error)
-                : new ElementNotFoundError(elementId);
-        }
-        return {
-            method: result.method ?? "axpress",
-            verified: Boolean(result.verified),
-        };
+        result = JSON.parse(out);
     }
     catch (error) {
         rethrowElementActionError(error, "click_element", elementId);
         return { method: "axpress", verified: false }; // unreachable — rethrow throws
     }
+    if (!result.success) {
+        // Route through rethrowElementActionError so "element not found" / accessibility
+        // errors are converted to the proper UcuError subclasses (ElementNotFoundError etc.).
+        rethrowElementActionError(new Error(result.error || "click_element failed"), "click_element", elementId);
+    }
+    // JXA requested a coordinate click → perform it via the input layer (per-process
+    // when a pid is available, so the global cursor does not move).
+    if (result.needCoordinateClick && typeof result.cx === "number" && typeof result.cy === "number") {
+        await this.click(Math.round(result.cx), Math.round(result.cy), "left", false);
+        return { method: "coordinate", verified: false };
+    }
+    return {
+        method: result.method ?? "axpress",
+        verified: Boolean(result.verified),
+    };
 }
 export async function typeInElement(elementId, text, app, clearFirst) {
     const textLiteral = JSON.stringify(text);
@@ -324,7 +306,7 @@ export async function findMenuBarExtra(app) {
       return itemNorm === appNorm || itemNorm.indexOf(appNorm) !== -1 || appNorm.indexOf(itemNorm) !== -1;
     };
 
-    var _readItem = function(item, mb, i, host) {
+    var _readItem = function(item, mb, i, host, hostPid) {
       var desc = '', nm = '';
       try { desc = item.description(); } catch(e) {}
       try { nm = item.name(); } catch(e) {}
@@ -332,7 +314,7 @@ export async function findMenuBarExtra(app) {
       try { pos = item.position(); } catch(e) {}
       try { sz = item.size(); } catch(e) {}
       if (sz[0] === 0 && sz[1] === 0) return null;
-      return {menuBar: mb, index: i, name: nm, description: desc, x: pos[0], y: pos[1], width: sz[0], height: sz[1], host: host};
+      return {menuBar: mb, index: i, name: nm, description: desc, x: pos[0], y: pos[1], width: sz[0], height: sz[1], host: host, pid: hostPid || 0};
     };
 
     try {
@@ -346,7 +328,9 @@ export async function findMenuBarExtra(app) {
 
       var items = [];
 
-      // 阶段 1：app 自身 menuBarItems（host:"self"）
+      // 阶段 1：app 自身 menuBarItems（host:"self"，用 app 自身 pid）
+      var appPid = 0;
+      if (p) { try { appPid = p.unixId(); } catch(e) {} }
       if (p) {
         try {
           var menuBars = p.menuBars();
@@ -354,7 +338,7 @@ export async function findMenuBarExtra(app) {
             var mbItems;
             try { mbItems = menuBars[mb].menuBarItems(); } catch(e) { continue; }
             for (var i = 0; i < mbItems.length; i++) {
-              var rec = _readItem(mbItems[i], mb, i, "self");
+              var rec = _readItem(mbItems[i], mb, i, "self", appPid);
               if (rec) items.push(rec);
             }
           }
@@ -372,6 +356,8 @@ export async function findMenuBarExtra(app) {
       if (!hasNonApple) {
         try {
           var suiProcs = se.processes.byName("SystemUIServer");
+          var suiPid = 0;
+          if (suiProcs) { try { suiPid = suiProcs.unixId(); } catch(e) {} }
           if (suiProcs) {
             var suiBars = suiProcs.menuBars();
             for (var smb = 0; smb < suiBars.length; smb++) {
@@ -384,7 +370,7 @@ export async function findMenuBarExtra(app) {
                 try { sNm = sItem.name(); } catch(e) {}
                 // 按 description/name 匹配目标 app（status item 的 description 通常是 app 名）
                 if (_matchApp(_norm(sDesc)) || _matchApp(_norm(sNm))) {
-                  var sRec = _readItem(sItem, smb, si, "systemuiserver");
+                  var sRec = _readItem(sItem, smb, si, "systemuiserver", suiPid);
                   if (sRec) {
                     // 保留匹配信号，供 click 二次定位
                     sRec.name = sNm; sRec.description = sDesc;
@@ -499,7 +485,7 @@ export async function clickMenuBarExtra(app, selector = {}) {
     var tgtName = ${tgtNameLiteral};
     var tgtDesc = ${tgtDescLiteral};
     ${JXA_STATE_SIGNATURE}
-    ${JXA_COORDINATE_CLICK}
+    ${JXA_BOUNDS_CENTER}
     // 容忍大小写/空格/连字符/下划线变体（cc-switch vs CC Switch vs cc_switch）
     var _norm = function(s) { return String(s||'').toLowerCase().split(' ').join('').split('-').join('').split('_').join(''); };
     var appNorm = _norm(appName);
@@ -521,9 +507,9 @@ export async function clickMenuBarExtra(app, selector = {}) {
       ${resolveItemBlock}
       if (!_result && item) {
         if (preferCoord) {
-          // 启发式命中：直接坐标点击
-          coordinateClick(item);
-          _result = {success: true, method: "coordinate", verified: false};
+          // 启发式命中：请求坐标点击（TS 层执行 per-process）
+          var c0 = boundsCenter(item);
+          _result = {success: true, needCoordinateClick: true, cx: c0.x, cy: c0.y};
         } else {
           // AXPress + verify
           var sigBefore = stateSignature(item);
@@ -534,20 +520,18 @@ export async function clickMenuBarExtra(app, selector = {}) {
             axpressThrew = true;
           }
           if (axpressThrew) {
-            coordinateClick(item);
-            _result = {success: true, method: "coordinate", verified: false};
+            var c1 = boundsCenter(item);
+            _result = {success: true, needCoordinateClick: true, cx: c1.x, cy: c1.y};
           } else {
             spinMs(80);
             var sigAfter = stateSignature(item);
             if (sigBefore !== '' && sigAfter !== sigBefore) {
               _result = {success: true, method: "axpress", verified: true};
             } else if (sigBefore === '' && sigAfter === '') {
-              // 托盘 status item 通常无可观测状态（无 value/selected）；AXPress 开菜单的效果
-              // 难以从 item 本身验证。保守认为成功（菜单是否打开由后续 find_element 判断）。
               _result = {success: true, method: "axpress", verified: false};
             } else {
-              coordinateClick(item);
-              _result = {success: true, method: "coordinate", verified: false};
+              var c2 = boundsCenter(item);
+              _result = {success: true, needCoordinateClick: true, cx: c2.x, cy: c2.y};
             }
           }
         }
@@ -569,6 +553,10 @@ export async function clickMenuBarExtra(app, selector = {}) {
     if (!result.success) {
         throw new Error(`click_menu_bar_extra failed in ${app}: ${result.error}`);
     }
+    if (result.needCoordinateClick && typeof result.cx === "number" && typeof result.cy === "number") {
+        await this.click(Math.round(result.cx), Math.round(result.cy), "left", false);
+        return { method: "coordinate", verified: false };
+    }
     return {
         method: result.method ?? "axpress",
         verified: Boolean(result.verified),

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

@@ -1,9 +1,10 @@
 import type { MacOSPlatform } from "./base.js";
 import type { CursorPosition } from "../base.js";
-export declare function click(this: MacOSPlatform, x: number, y: number, button?: "left" | "right" | "middle", doubleClick?: boolean): Promise<void>;
-export declare function move(this: MacOSPlatform, x: number, y: number): Promise<void>;
-export declare function drag(this: MacOSPlatform, startX: number, startY: number, endX: number, endY: number, button?: "left" | "right" | "middle", duration?: number): Promise<void>;
-export declare function scroll(this: MacOSPlatform, x: number, y: number, deltaX: number, deltaY: number): Promise<void>;
+import type { DispatchMethod } from "../base.js";
+export declare function click(this: MacOSPlatform, x: number, y: number, button?: "left" | "right" | "middle", doubleClick?: boolean): Promise<DispatchMethod | void>;
+export declare function move(this: MacOSPlatform, x: number, y: number): Promise<DispatchMethod | void>;
+export declare function drag(this: MacOSPlatform, startX: number, startY: number, endX: number, endY: number, button?: "left" | "right" | "middle", duration?: number): Promise<DispatchMethod | void>;
+export declare function scroll(this: MacOSPlatform, x: number, y: number, deltaX: number, deltaY: number): Promise<DispatchMethod | void>;
 export declare function getCursorPosition(this: MacOSPlatform): CursorPosition;
-export declare function type(this: MacOSPlatform, text: string, delay?: number): Promise<void>;
-export declare function key(this: MacOSPlatform, keys: string[]): Promise<void>;
+export declare function type(this: MacOSPlatform, text: string, delay?: number): Promise<DispatchMethod | void>;
+export declare function key(this: MacOSPlatform, keys: string[]): Promise<DispatchMethod | void>;

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

@@ -2,13 +2,37 @@ import { execFileSync } from "node:child_process";
 import { click as inputClick, doubleClick as inputDoubleClick, move as inputMove, drag as inputDrag, scroll as inputScroll, typeText, pressShortcut } from "../../utils/input.js";
 import { PlatformError } from "../../util/errors.js";
 import { rethrowInputError, errorMessage } from "./helpers.js";
+/**
+ * Process names that must NEVER receive per-process input injection (security).
+ * Per-process posting bypasses the frontmost/focus requirement, so without this
+ * denylist an attacker could deliver keystrokes/clicks directly into a password
+ * manager or auth dialog. These fall back to HID-tap (which at least requires
+ * the app to be frontmost / visible to the user).
+ */
+const SENSITIVE_PROCESS_HINTS = [
+    "keychainaccess", "1password", "lastpass", "bitwarden", "securityagent",
+    "authd", "loginwindow", "applekeychain", "dashlane",
+];
+/** Resolve the per-process event target from the active focus_app target (pid + windowNumber). */
+function targetOf() {
+    const t = this.activeTarget;
+    if (!t || !t.pid || t.pid <= 0)
+        return undefined;
+    // Security: never route per-process events into sensitive apps (password managers / auth).
+    const name = (t.appName || "").toLowerCase();
+    if (SENSITIVE_PROCESS_HINTS.some((h) => name.includes(h))) {
+        return undefined; // forces HID-tap fallback (requires frontmost)
+    }
+    return { pid: t.pid, windowNumber: t.windowNumber };
+}
 export async function click(x, y, button, doubleClick) {
     try {
+        const target = targetOf.call(this);
         if (doubleClick) {
-            await inputDoubleClick(x, y, button);
+            return await inputDoubleClick(x, y, button, process.platform, target);
         }
         else {
-            await inputClick(x, y, button);
+            return await inputClick(x, y, button, process.platform, target);
         }
     }
     catch (error) {
@@ -17,7 +41,7 @@ export async function click(x, y, button, doubleClick) {
 }
 export async function move(x, y) {
     try {
-        await inputMove(x, y);
+        return await inputMove(x, y, process.platform, targetOf.call(this));
     }
     catch (error) {
         rethrowInputError(error, "move");
@@ -25,7 +49,7 @@ export async function move(x, y) {
 }
 export async function drag(startX, startY, endX, endY, button, duration) {
     try {
-        await inputDrag(startX, startY, endX, endY, button, duration);
+        return await inputDrag(startX, startY, endX, endY, button, duration, process.platform, targetOf.call(this));
     }
     catch (error) {
         rethrowInputError(error, "drag");
@@ -33,7 +57,7 @@ export async function drag(startX, startY, endX, endY, button, duration) {
 }
 export async function scroll(x, y, deltaX, deltaY) {
     try {
-        await inputScroll(x, y, deltaX, deltaY);
+        return await inputScroll(x, y, deltaX, deltaY, process.platform, targetOf.call(this));
     }
     catch (error) {
         rethrowInputError(error, "scroll");
@@ -55,8 +79,8 @@ export function getCursorPosition() {
     }
 }
 export async function type(text, delay) {
-    await typeText(text, delay);
+    return await typeText(text, delay, process.platform, targetOf.call(this));
 }
 export async function key(keys) {
-    await pressShortcut(keys);
+    return await pressShortcut(keys, process.platform, targetOf.call(this));
 }

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

@@ -2,5 +2,7 @@ import type { MacOSPlatform } from "./base.js";
 import type { AppInfo, AppTarget, WindowInfo, BrowserContext } from "../base.js";
 export declare function listApps(this: MacOSPlatform): Promise<AppInfo[]>;
 export declare function focusApp(this: MacOSPlatform, app: string): Promise<AppTarget>;
+/** Call the skylight-helper keepAlive command for a pid (best-effort, non-throwing). */
+export declare function keepTargetAxAlive(this: MacOSPlatform, pid: number): Promise<void>;
 export declare function getActiveBrowserContext(this: MacOSPlatform, app?: string): Promise<BrowserContext | undefined>;
 export declare function listWindows(this: MacOSPlatform, _includeMinimized?: boolean): Promise<WindowInfo[]>;