ucu-mcp 0.5.2 → 0.6.2

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

@@ -2,6 +2,17 @@ import { execFileSync } from "node:child_process";
 import { ElementNotFoundError } from "../../util/errors.js";
 import { rethrowElementActionError } from "./helpers.js";
 import { jxaElementActionHelpers } from "../jxa-helpers.js";
+const DEFAULT_AXPRESS_SPIN_MS = 50;
+const MAX_AXPRESS_SPIN_MS = 80;
+function getAxPressSpinMs() {
+    const env = process.env.UCU_AXPRESS_SPIN_MS;
+    if (!env)
+        return DEFAULT_AXPRESS_SPIN_MS;
+    const parsed = parseInt(env, 10);
+    if (isNaN(parsed))
+        return DEFAULT_AXPRESS_SPIN_MS;
+    return Math.max(0, Math.min(parsed, MAX_AXPRESS_SPIN_MS));
+}
 /**
  * App-name hints for which AXPress is known to be silently swallowed
  * (Tauri custom window decorations, some Electron controls). When the target
@@ -44,23 +55,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 +79,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 +99,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 +112,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);
+        spinMs(${getAxPressSpinMs()});
         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 +317,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 +325,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 +339,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 +349,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 +367,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 +381,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 +496,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 +518,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 +531,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);
+            spinMs(${getAxPressSpinMs()});
             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 +564,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/helpers.js

@@ -35,17 +35,22 @@ export function rethrowInputError(error, operation) {
     throw new InputSynthesisError(`${operation} failed: ${errorMessage(error)}`);
 }
 export function normalizeAppName(name) {
-    return name.trim().toLowerCase();
+    // Drop all non-alphanumeric chars so app name variants match across
+    // formattings: "CC Switch" / "cc-switch" / "cc_switch" / "CC.Switch"
+    // all collapse to "ccswitch". This is what users (and LLMs) typically
+    // produce from casual memory, and it's the only way focus_app can
+    // resolve tray vs. windowed app identity reliably.
+    return name.trim().toLowerCase().replace(/[^a-z0-9]/g, "");
 }
 export function appNameMatches(processName, requestedApp) {
     const process = normalizeAppName(processName);
     const requested = normalizeAppName(requestedApp);
     if (!process || !requested)
         return false;
-    return process === requested ||
-        process.startsWith(`${requested} `) ||
-        process.startsWith(`${requested}-`) ||
-        process.includes(` ${requested} `);
+    // normalizeAppName strips all non-alphanumerics, so equality is the only
+    // meaningful comparison. (Prior startsWith/includes with spaces were dead code
+    // since normalized strings contain no spaces/hyphens.)
+    return process === requested || process.includes(requested) || requested.includes(process);
 }
 export function selectWindowForApp(windows, requestedApp) {
     const requested = normalizeAppName(requestedApp);

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/screen.js

@@ -26,8 +26,14 @@ export async function screenshotWindow(windowId, options) {
     return this.screenshot(undefined, win.bounds, options);
 }
 export function getScreenSize(display) {
+    const idx = display ?? 0;
+    const now = Date.now();
+    if (this.screenSizeCache &&
+        this.screenSizeCache.display === idx &&
+        now - this.screenSizeCache.cachedAt <= this.screenSizeCacheTtlMs) {
+        return this.screenSizeCache.size;
+    }
     try {
-        const idx = display ?? 0;
         const out = execFileSync("osascript", [
             "-l", "JavaScript",
             "-e",
@@ -40,7 +46,9 @@ export function getScreenSize(display) {
       var scaleFactor = screen.backingScaleFactor;
       JSON.stringify({width:Math.round(frame.size.width),height:Math.round(frame.size.height),scaleFactor:scaleFactor})`,
         ], { encoding: "utf-8", timeout: 5000 }).trim();
-        return JSON.parse(out);
+        const size = JSON.parse(out);
+        this.screenSizeCache = { display: idx, cachedAt: Date.now(), size };
+        return size;
     }
     catch (error) {
         logger.warn("getScreenSize failed, using fallback", { error: errorMessage(error) });

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[]>;

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

@@ -58,14 +58,20 @@ export async function focusApp(app) {
         try {
             const extras = await this.findMenuBarExtra(app);
             if (extras.length > 0) {
+                // Use the hosting process pid (SystemUIServer or app itself) so per-process
+                // event posting works for tray clicks (no global cursor move).
+                const trayPid = extras[0]?.pid || 0;
                 this.activeTarget = {
                     targetId: randomUUID(),
                     appName: app,
-                    pid: 0,
+                    pid: trayPid,
                     windowId: "tray",
                     title: "",
                     capturedAt: new Date().toISOString(),
                 };
+                if (trayPid > 0) {
+                    this.keepTargetAxAlive(trayPid).catch(() => { });
+                }
                 return this.activeTarget;
             }
         }
@@ -90,9 +96,29 @@ export async function focusApp(app) {
         windowId: target.id,
         title: target.title,
         capturedAt: new Date().toISOString(),
+        windowNumber: target.windowNumber,
     };
+    // AX keepalive: keep the target's accessibility tree live when occluded/background,
+    // so AXPress on Electron/Tauri controls doesn't silently no-op. Best-effort.
+    this.keepTargetAxAlive(target.pid).catch(() => { });
     return this.activeTarget;
 }
+/** Call the skylight-helper keepAlive command for a pid (best-effort, non-throwing). */
+export async function keepTargetAxAlive(pid) {
+    const helperPath = resolveNativeHelper.call(this, "skylight", "skylight-helper");
+    if (!helperPath)
+        return;
+    try {
+        execFileSync(helperPath, [], {
+            input: JSON.stringify({ command: "keepAlive", pid }),
+            encoding: "utf8",
+            timeout: 5000,
+        });
+    }
+    catch {
+        // keepAlive is best-effort; ignore failures (helper missing / SPI unavailable).
+    }
+}
 export async function getActiveBrowserContext(app) {
     const appName = app || this.activeTarget?.appName;
     if (!appName)
@@ -152,34 +178,30 @@ export async function listWindows(_includeMinimized) {
             bounds: { ...window.bounds },
         }));
     }
-    if (this.windowCacheInFlight) {
-        return this.windowCache?.windows.map((w) => ({ ...w, bounds: { ...w.bounds } })) ?? [];
+    if (this.windowCachePromise) {
+        return this.windowCachePromise.then((windows) => windows.map((window) => ({ ...window, bounds: { ...window.bounds } })));
     }
-    this.windowCacheInFlight = true;
-    try {
-        let windows;
-        const nativeResult = listWindowsNative.call(this);
-        if (nativeResult !== null) {
-            windows = nativeResult;
+    this.windowCachePromise = (async () => {
+        try {
+            const nativeResult = listWindowsNative.call(this);
+            const windows = nativeResult !== null ? nativeResult : await listWindowsJxa.call(this);
+            this.windowCache = {
+                cachedAt: Date.now(),
+                windows: windows.map((window) => ({
+                    ...window,
+                    bounds: { ...window.bounds },
+                })),
+            };
+            return windows;
         }
-        else {
-            windows = await listWindowsJxa.call(this);
+        catch {
+            return [];
         }
-        this.windowCache = {
-            cachedAt: Date.now(),
-            windows: windows.map((window) => ({
-                ...window,
-                bounds: { ...window.bounds },
-            })),
-        };
-        return windows;
-    }
-    catch {
-        return [];
-    }
-    finally {
-        this.windowCacheInFlight = false;
-    }
+        finally {
+            this.windowCachePromise = undefined;
+        }
+    })();
+    return this.windowCachePromise.then((windows) => windows.map((window) => ({ ...window, bounds: { ...window.bounds } })));
 }
 function listWindowsNative() {
     try {
@@ -201,6 +223,7 @@ function listWindowsNative() {
             bounds: w.bounds,
             isMinimized: !w.isOnScreen,
             isOnScreen: w.isOnScreen,
+            windowNumber: w.windowNumber,
         }));
     }
     catch {

package/dist/src/safety/permissions.d.ts

@@ -8,6 +8,8 @@ export interface PermissionDetail {
     granted: boolean;
     instructions: string;
 }
+/** @internal Test hook to reset the permission cache. */
+export declare function __resetPermissionCache(): void;
 /**
  * Get the name of the terminal app that the user needs to authorize.
  */

package/dist/src/safety/permissions.js

@@ -1,6 +1,30 @@
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
 const execFileAsync = promisify(execFile);
+// Short-lived cache for individual permission checks. Permissions rarely change
+// within a single tool sequence, but we keep TTL short so that a user granting
+// permission mid-session is picked up quickly.
+const PERMISSION_CACHE_TTL_MS = { granted: 5000, denied: 1000 };
+const permissionCache = {};
+/** @internal Test hook to reset the permission cache. */
+export function __resetPermissionCache() {
+    permissionCache.accessibility = undefined;
+    permissionCache.screenRecording = undefined;
+}
+function getCachedPermission(type) {
+    const entry = permissionCache[type];
+    if (!entry)
+        return undefined;
+    const ttl = entry.granted ? PERMISSION_CACHE_TTL_MS.granted : PERMISSION_CACHE_TTL_MS.denied;
+    if (Date.now() - entry.cachedAt > ttl) {
+        permissionCache[type] = undefined;
+        return undefined;
+    }
+    return entry.granted;
+}
+function setCachedPermission(type, granted) {
+    permissionCache[type] = { granted, cachedAt: Date.now() };
+}
 /**
  * Get the name of the terminal app that the user needs to authorize.
  */
@@ -133,7 +157,11 @@ export async function checkPermission(type) {
     }
     const appName = getTerminalAppName();
     if (type === "accessibility") {
-        const granted = await checkAccessibility();
+        const cached = getCachedPermission("accessibility");
+        const granted = cached ?? await checkAccessibility();
+        if (cached === undefined) {
+            setCachedPermission("accessibility", granted);
+        }
         if (!granted) {
             // Trigger the macOS system prompt for Accessibility
             await requestAccessibilityWithPrompt();
@@ -146,7 +174,11 @@ export async function checkPermission(type) {
         }
         return { granted: true };
     }
-    const granted = await checkScreenRecording();
+    const cached = getCachedPermission("screenRecording");
+    const granted = cached ?? await checkScreenRecording();
+    if (cached === undefined) {
+        setCachedPermission("screenRecording", granted);
+    }
     if (!granted) {
         // Open System Settings for Screen Recording
         await openPermissionSettings("screenRecording");

package/dist/src/utils/input.d.ts

@@ -9,14 +9,20 @@
  * Windows: Uses SendInput (stub).
  * Linux: Uses xdotool (stub).
  */
-export declare function click(x: number, y: number, button?: "left" | "right" | "middle", _platform?: string): Promise<void>;
-export declare function doubleClick(x: number, y: number, button?: "left" | "right" | "middle", _platform?: string): Promise<void>;
-export declare function move(x: number, y: number, _platform?: string): Promise<void>;
-export declare function drag(fromX: number, fromY: number, toX: number, toY: number, button?: "left" | "right" | "middle", duration?: number, _platform?: string): Promise<void>;
-export declare function scroll(x: number, y: number, deltaX: number, deltaY: number, _platform?: string): Promise<void>;
-export declare function typeText(text: string, delay?: number, _platform?: string): Promise<void>;
-export declare function pressKey(key: string, modifiers?: string[], _platform?: string): Promise<void>;
-export declare function pressShortcut(keys: string[], _platform?: string): Promise<void>;
+import type { DispatchMethod } from "../platform/base.js";
+/** Per-process event target. When pid > 0, input is routed via skylight-helper (no cursor move). */
+export interface InputTarget {
+    pid?: number;
+    windowNumber?: number;
+}
+export declare function click(x: number, y: number, button?: "left" | "right" | "middle", _platform?: string, target?: InputTarget): Promise<DispatchMethod | void>;
+export declare function doubleClick(x: number, y: number, button?: "left" | "right" | "middle", _platform?: string, target?: InputTarget): Promise<DispatchMethod | void>;
+export declare function move(x: number, y: number, _platform?: string, target?: InputTarget): Promise<DispatchMethod | void>;
+export declare function drag(fromX: number, fromY: number, toX: number, toY: number, button?: "left" | "right" | "middle", duration?: number, _platform?: string, target?: InputTarget): Promise<DispatchMethod | void>;
+export declare function scroll(x: number, y: number, deltaX: number, deltaY: number, _platform?: string, target?: InputTarget): Promise<DispatchMethod | void>;
+export declare function typeText(text: string, delay?: number, _platform?: string, target?: InputTarget): Promise<DispatchMethod | void>;
+export declare function pressKey(key: string, modifiers?: string[], _platform?: string, target?: InputTarget): Promise<DispatchMethod | void>;
+export declare function pressShortcut(keys: string[], _platform?: string, target?: InputTarget): Promise<DispatchMethod | void>;
 export declare function getCursorPosition(_platform?: string): Promise<{
     x: number;
     y: number;