ucu-mcp 0.6.0 → 0.6.2

package/CHANGELOG.md

@@ -5,6 +5,44 @@ 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 版只前台）。

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/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/macos/base.d.ts

@@ -1,4 +1,4 @@
-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";
@@ -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;

package/dist/src/platform/macos/base.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;

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
@@ -104,7 +115,7 @@ export async function clickElement(elementId, app) {
         var c1 = boundsCenter(elem);
         _result = {success: true, needCoordinateClick: true, cx: c1.x, cy: c1.y};
       } else {
-        spinMs(80);
+        spinMs(${getAxPressSpinMs()});
         var sigAfter = stateSignature(elem);
         if (sigBefore !== '' && sigAfter !== sigBefore) {
           _result = {success: true, method: "axpress", verified: true};
@@ -523,7 +534,7 @@ export async function clickMenuBarExtra(app, selector = {}) {
             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};

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

@@ -178,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 {

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ucu-mcp",
-  "version": "0.6.0",
+  "version": "0.6.2",
   "description": "MCP server for Universal Computer Use — desktop automation for AI agents via Model Context Protocol",
   "type": "module",
   "bin": {