ucu-mcp 0.1.3 → 0.3.0

package/dist/src/mcp/tools.js

@@ -1,16 +1,16 @@
 /**
  * Tool registry for UCU-MCP.
  *
- * Registers 22 MCP tools on the server and dispatches each call through
+ * Registers 24 MCP tools on the server and dispatches each call through
  * a shared safety/permission/retry pipeline (`withSafety`).
  */
 import { z } from "zod";
 import { MacOSPlatform } from "../platform/macos.js";
-import { SafetyGuard } from "../safety/guard.js";
+import { SafetyGuard, classifyAction } from "../safety/guard.js";
 import { checkPermission } from "../safety/permissions.js";
 import { retry } from "../util/retry.js";
 import { createLogger } from "../util/logger.js";
-import { SafetyError, PermissionError, UnsupportedParameterError } from "../util/errors.js";
+import { SafetyError, PermissionError, UnsupportedParameterError, UcuError, WindowNotFoundError } from "../util/errors.js";
 const log = createLogger("tools");
 let _platform;
 function getPlatform() {
@@ -20,6 +20,14 @@ function getPlatform() {
     return _platform;
 }
 const safety = new SafetyGuard();
+// Active target context — set by focus_app, used by AX element tools
+let activeTargetContext;
+/**
+ * Get the currently active target context (set by focus_app).
+ */
+export function getActiveTarget() {
+    return activeTargetContext;
+}
 // User activity monitor — pauses automation when user moves the cursor
 let lastCursorPos = { x: 0, y: 0 };
 let userActivityInterval;
@@ -31,21 +39,134 @@ const captureAfterFields = {
 async function resolvePoint(x, y, windowId) {
     if (!windowId)
         return { x, y };
+    const win = (await getPlatform().listWindows()).find(w => w.id === windowId);
+    if (!win)
+        throw new WindowNotFoundError(windowId);
+    return { x: win.bounds.x + x, y: win.bounds.y + y };
+}
+function jsonText(value) {
+    return { type: "text", text: JSON.stringify(value, null, 2) };
+}
+function recoveryHint(code) {
+    switch (code) {
+        case "WINDOW_NOT_FOUND":
+            return "Run list_windows again, then retry with a fresh windowId or omit windowId for screen coordinates.";
+        case "TARGET_STALE":
+            return "Run focus_app again for the target app, or run list_windows and retry with a fresh windowId.";
+        case "ELEMENT_NOT_FOUND":
+            return "Run find_element again, then retry with a fresh elementId.";
+        case "PERMISSION_DENIED":
+            return "Run doctor and grant the missing macOS permission, then restart the launching client.";
+        case "UNSUPPORTED_PARAMETER":
+            return "Remove or replace the unsupported parameter; inspect tools/list for this tool schema.";
+        case "SAFETY_BLOCKED":
+            return "Choose a less risky action or ask the user to perform it manually.";
+        case "INPUT_FAILED":
+            return "Observe current state with screenshot or get_window_state before retrying manually.";
+        case "CAPTURE_FAILED":
+            return "Run doctor to check Screen Recording permission, then retry screenshot or ocr.";
+        case "COORDINATE_OUT_OF_BOUNDS":
+            return "Run get_screen_size or list_windows, then retry with coordinates inside the active display or window bounds.";
+        default:
+            return "Inspect the error message, observe the current UI state, and retry only if the operation is safe.";
+    }
+}
+function errorDetails(error) {
+    const err = error instanceof Error ? error : new Error(String(error));
+    const code = error instanceof UcuError ? error.code : "UNKNOWN_ERROR";
+    const retryable = error instanceof UcuError ? error.retryable : false;
+    return {
+        name: err.name,
+        code,
+        retryable,
+        message: err.message,
+        recovery: recoveryHint(code),
+    };
+}
+let _actionCounter = 0;
+function nextActionId() {
+    _actionCounter = (_actionCounter + 1) % 1_000_000;
+    return `a${Date.now().toString(36)}-${_actionCounter.toString(36)}`;
+}
+function buildActionReceipt(action, status, target, result, captureRequested, captureFormat, captureMaxWidth, captureError, warnings = []) {
+    const captureStatus = captureRequested
+        ? captureError ? "error" : "ok"
+        : "skipped";
+    return {
+        actionId: nextActionId(),
+        action,
+        status,
+        target,
+        result,
+        capture: {
+            requested: captureRequested,
+            status: captureStatus,
+            ...(captureFormat && { format: captureFormat }),
+            ...(captureMaxWidth && { maxWidth: captureMaxWidth }),
+            ...(captureError && { error: captureError }),
+        },
+        warnings,
+        next: captureError
+            ? "screenshot"
+            : status === "partial"
+                ? "get_window_state"
+                : "find_element or get_window_state",
+    };
+}
+function mcpErrorResponse(error) {
+    return {
+        isError: true,
+        content: [
+            jsonText({
+                error: errorDetails(error),
+            }),
+        ],
+    };
+}
+async function actionResponse(action, result, target, captureAfter, captureFormat = "jpeg", captureMaxWidth = 1280, warnings = []) {
+    const receipt = buildActionReceipt(action, "ok", target, result, captureAfter ?? false, captureFormat, captureMaxWidth, undefined, warnings);
+    if (!captureAfter) {
+        return { content: [jsonText(receipt)] };
+    }
     try {
-        const win = (await getPlatform().listWindows()).find(w => w.id === windowId);
-        if (!win)
-            return { x, y };
-        return { x: win.bounds.x + x, y: win.bounds.y + y };
+        const buf = await getPlatform().screenshot(undefined, undefined, {
+            format: captureFormat,
+            maxWidth: captureMaxWidth,
+        });
+        return {
+            content: [
+                jsonText(receipt),
+                {
+                    type: "image",
+                    data: buf.toString("base64"),
+                    mimeType: `image/${captureFormat}`,
+                },
+            ],
+        };
     }
-    catch {
-        return { x, y };
+    catch (error) {
+        const partialReceipt = buildActionReceipt(action, "partial", target, result, true, captureFormat, captureMaxWidth, errorDetails(error), [...warnings, "Post-action screenshot capture failed"]);
+        return { content: [jsonText(partialReceipt)] };
     }
 }
+const retryableActions = new Set([
+    "screenshot",
+    "list_windows",
+    "list_apps",
+    "get_window_state",
+    "get_cursor_position",
+    "get_screen_size",
+    "ocr",
+    "doctor",
+    "find_element",
+]);
 async function withSafety(sa) {
     const platform = getPlatform();
     if (platform.isScreenLocked?.())
         throw new SafetyError("Screen is locked");
-    const check = safety.checkAction(sa.action, sa.params);
+    const check = safety.checkAction(sa.action, sa.params, {
+        skipUserActivityPause: sa.skipUserActivityPause ?? classifyAction(sa.action) === "observe",
+    });
     if (!check.allowed)
         throw new SafetyError(check.reason ?? "Action blocked by safety guard");
     if (sa.requiresAccessibility) {
@@ -64,27 +185,24 @@ async function withSafety(sa) {
     if (shouldManageFocus)
         await platform.saveFocus?.();
     try {
-        return await retry(() => sa.execute());
+        return retryableActions.has(sa.action)
+            ? await retry(() => sa.execute())
+            : await sa.execute();
     }
     finally {
         if (shouldManageFocus)
             await platform.restoreFocus?.();
     }
 }
-async function appendCaptureAfter(result, captureAfter) {
-    if (!captureAfter)
-        return result;
+export function startUserActivityMonitor() {
+    if (userActivityInterval)
+        return;
     try {
-        const buf = await getPlatform().screenshot();
-        return { actionResult: result, screenshot: { type: "image", data: buf.toString("base64"), mimeType: "image/png" } };
+        lastCursorPos = getPlatform().getCursorPosition();
     }
     catch {
-        return result;
+        // Keep the default when the cursor cannot be queried during startup.
     }
-}
-export function startUserActivityMonitor() {
-    if (userActivityInterval)
-        return;
     userActivityInterval = setInterval(() => {
         try {
             const pos = getPlatform().getCursorPosition();
@@ -95,8 +213,9 @@ export function startUserActivityMonitor() {
         }
         catch { /* can't check cursor */ }
     }, 250);
+    userActivityInterval.unref?.();
 }
-function stopUserActivityMonitor() {
+export function stopUserActivityMonitor() {
     if (userActivityInterval) {
         clearInterval(userActivityInterval);
         userActivityInterval = undefined;
@@ -104,43 +223,68 @@ function stopUserActivityMonitor() {
 }
 export function registerTools(server) {
     const registry = ToolRegistry.instance;
-    server.tool("screenshot", "Capture a screenshot of the entire screen or a region", {
+    const registerTool = (name, description, schema, handler) => {
+        server.tool(name, description, schema, async (params) => {
+            try {
+                return await handler(params);
+            }
+            catch (error) {
+                return mcpErrorResponse(error);
+            }
+        });
+    };
+    registerTool("screenshot", "Capture a screenshot of the entire screen or a region", {
         display: z.number().optional().describe("Display index (default 0)"),
+        windowId: z.string().optional().describe("Window ID from list_windows; when set, captures that window"),
         region: z.object({ x: z.number(), y: z.number(), width: z.number(), height: z.number() }).optional().describe("Region to capture"),
         format: z.enum(["png", "jpeg"]).default("png").describe("Image format"),
         maxWidth: z.number().default(1280).describe("Maximum output width in pixels. Aspect ratio is preserved."),
     }, async (params) => {
-        const buf = await withSafety({ action: "screenshot", params: {}, requiresScreenRecording: true, execute: () => getPlatform().screenshot(params.display, params.region, { format: params.format }) });
+        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({
+            action: "screenshot",
+            params,
+            requiresScreenRecording: true,
+            execute: () => params.windowId
+                ? getPlatform().screenshotWindow
+                    ? getPlatform().screenshotWindow(params.windowId, options)
+                    : Promise.reject(new UnsupportedParameterError("window screenshots are not implemented on this platform"))
+                : getPlatform().screenshot(params.display, params.region, options),
+        });
         return { content: [{ type: "image", data: buf.toString("base64"), mimeType: `image/${params.format}` }] };
     });
     registry.register("screenshot");
-    server.tool("list_windows", "List all visible windows on screen", {
+    registerTool("list_windows", "List all visible windows on screen", {
         includeMinimized: z.boolean().optional().describe("Include minimized windows"),
     }, async (params) => {
         const windows = await withSafety({ action: "list_windows", params: {}, requiresAccessibility: true, execute: () => getPlatform().listWindows(params.includeMinimized) });
         return { content: [{ type: "text", text: JSON.stringify(windows, null, 2) }] };
     });
     registry.register("list_windows");
-    server.tool("list_apps", "List all running applications", {}, async () => {
+    registerTool("list_apps", "List all running applications", {}, async () => {
         const apps = await withSafety({ action: "list_apps", params: {}, requiresAccessibility: true, execute: async () => getPlatform().listApps() });
         return { content: [{ type: "text", text: JSON.stringify(apps, null, 2) }] };
     });
     registry.register("list_apps");
-    server.tool("focus_app", "Bring an application to the foreground", {
+    registerTool("focus_app", "Select an application/window as the active target context", {
         app: z.string().describe("Application name to focus"),
     }, async (params) => {
         const target = await withSafety({ action: "focus_app", params: {}, requiresAccessibility: true, execute: () => getPlatform().focusApp(params.app) });
+        activeTargetContext = target;
         return { content: [{ type: "text", text: JSON.stringify(target, null, 2) }] };
     });
     registry.register("focus_app");
-    server.tool("get_window_state", "Get detailed state of a window including accessibility tree", {
+    registerTool("get_window_state", "Get detailed state of a window including accessibility tree", {
         windowId: z.string().optional().describe("Window ID"), depth: z.number().optional().describe("AX tree depth"), includeBounds: z.boolean().optional().describe("Include element bounds"),
     }, async (params) => {
-        const state = await withSafety({ action: "get_window_state", params: {}, requiresAccessibility: true, execute: () => getPlatform().getWindowState(params.windowId, params.depth, params.includeBounds) });
+        const effectiveWindowId = params.windowId || getActiveTarget()?.windowId;
+        const state = await withSafety({ action: "get_window_state", params: {}, requiresAccessibility: true, execute: () => getPlatform().getWindowState(effectiveWindowId, params.depth, params.includeBounds) });
         return { content: [{ type: "text", text: JSON.stringify(state, null, 2) }] };
     });
     registry.register("get_window_state");
-    server.tool("click", "Click at screen coordinates", {
+    registerTool("click", "Click at screen coordinates", {
         x: z.number().describe("X coordinate"), y: z.number().describe("Y coordinate"),
         button: z.enum(["left", "right", "middle"]).optional().describe("Mouse button"),
         windowId: z.string().optional().describe("If set, x/y are relative to this window"),
@@ -148,10 +292,10 @@ export function registerTools(server) {
     }, async (params) => {
         const pt = await resolvePoint(params.x, params.y, params.windowId);
         await withSafety({ action: "click", params: { x: pt.x, y: pt.y }, requiresAccessibility: true, execute: () => getPlatform().click(pt.x, pt.y, params.button) });
-        return { content: [{ type: "text", text: JSON.stringify(await appendCaptureAfter({ clicked: true, x: pt.x, y: pt.y }, params.captureAfter), null, 2) }] };
+        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);
     });
     registry.register("click");
-    server.tool("double_click", "Double-click at screen coordinates", {
+    registerTool("double_click", "Double-click at screen coordinates", {
         x: z.number().describe("X coordinate"), y: z.number().describe("Y coordinate"),
         button: z.enum(["left", "right", "middle"]).optional().describe("Mouse button"),
         windowId: z.string().optional().describe("If set, x/y are relative to this window"),
@@ -159,10 +303,10 @@ export function registerTools(server) {
     }, async (params) => {
         const pt = await resolvePoint(params.x, params.y, params.windowId);
         await withSafety({ action: "click", params: { x: pt.x, y: pt.y, doubleClick: true }, requiresAccessibility: true, execute: () => getPlatform().click(pt.x, pt.y, params.button, true) });
-        return { content: [{ type: "text", text: JSON.stringify(await appendCaptureAfter({ doubleClicked: true, x: pt.x, y: pt.y }, params.captureAfter), null, 2) }] };
+        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);
     });
     registry.register("double_click");
-    server.tool("type_text", "Type text at the current cursor position", {
+    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"),
         windowId: z.string().optional().describe("UNSUPPORTED: windowId-targeted keyboard typing is not implemented"),
         ...captureAfterFields,
@@ -170,107 +314,208 @@ export function registerTools(server) {
         if (params.windowId)
             throw new UnsupportedParameterError("windowId-targeted keyboard typing is not implemented");
         await withSafety({ action: "type_text", params: { text: params.text }, requiresAccessibility: true, execute: () => getPlatform().type(params.text, params.delay) });
-        return { content: [{ type: "text", text: JSON.stringify(await appendCaptureAfter({ typed: true, charCount: params.text.length }, params.captureAfter), null, 2) }] };
+        return actionResponse("type_text", { typed: true, charCount: params.text.length }, {}, params.captureAfter, params.captureFormat, params.captureMaxWidth);
     });
     registry.register("type_text");
-    server.tool("press_key", "Press a keyboard shortcut", {
+    registerTool("press_key", "Press a keyboard shortcut", {
         keys: z.array(z.string()).optional().describe("Keys to press simultaneously"),
         key: z.string().optional().describe("Single key to press (alias for keys)"),
+        modifiers: z.array(z.string()).optional().describe("Modifier keys used with key, such as cmd, shift, alt, or ctrl"),
         windowId: z.string().optional().describe("UNSUPPORTED: windowId-targeted key events are not implemented"),
         ...captureAfterFields,
     }, async (params) => {
         if (params.windowId)
             throw new UnsupportedParameterError("windowId-targeted key events are not implemented");
-        const keys = params.keys ?? (params.key ? [params.key] : []);
+        const keys = params.keys ?? [
+            ...(params.modifiers ?? []),
+            ...(params.key ? [params.key] : []),
+        ];
         if (keys.length === 0)
-            throw new Error("press_key requires at least one key");
+            throw new UnsupportedParameterError("press_key requires at least one key");
         await withSafety({ action: "press_key", params: { keys }, requiresAccessibility: true, execute: () => getPlatform().key(keys) });
-        return { content: [{ type: "text", text: JSON.stringify(await appendCaptureAfter({ pressed: true, keys: params.keys }, params.captureAfter), null, 2) }] };
+        return actionResponse("press_key", { pressed: true, keys }, {}, params.captureAfter, params.captureFormat, params.captureMaxWidth);
     });
     registry.register("press_key");
-    server.tool("scroll", "Scroll at coordinates", {
+    registerTool("scroll", "Scroll at coordinates", {
         x: z.number().describe("X coordinate"), y: z.number().describe("Y coordinate"),
-        deltaX: z.number().describe("Horizontal scroll"), deltaY: z.number().describe("Vertical scroll (negative = up)"),
+        deltaX: z.number().default(0).describe("Horizontal scroll"), deltaY: z.number().describe("Vertical scroll (negative = up)"),
         windowId: z.string().optional().describe("If set, x/y are relative to this window"),
         ...captureAfterFields,
     }, async (params) => {
         const pt = await resolvePoint(params.x, params.y, params.windowId);
-        await withSafety({ action: "scroll", params: { x: pt.x, y: pt.y }, requiresAccessibility: true, execute: () => getPlatform().scroll(pt.x, pt.y, params.deltaX, params.deltaY) });
-        return { content: [{ type: "text", text: JSON.stringify(await appendCaptureAfter({ scrolled: true, x: pt.x, y: pt.y }, params.captureAfter), null, 2) }] };
+        const deltaX = params.deltaX ?? 0;
+        await withSafety({ action: "scroll", params: { x: pt.x, y: pt.y }, 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);
     });
     registry.register("scroll");
-    server.tool("drag", "Drag from one point to another", {
+    registerTool("drag", "Drag from one point to another", {
         startX: z.number().describe("Start X"), startY: z.number().describe("Start Y"),
         endX: z.number().describe("End X"), endY: z.number().describe("End Y"),
         button: z.enum(["left", "right", "middle"]).optional().describe("Mouse button"),
+        windowId: z.string().optional().describe("If set, start/end coordinates are relative to this window"),
         duration: z.number().optional().describe("Drag duration in ms"),
         ...captureAfterFields,
     }, async (params) => {
-        await withSafety({ action: "drag", params: {}, requiresAccessibility: true, execute: () => getPlatform().drag(params.startX, params.startY, params.endX, params.endY, params.button, params.duration) });
-        return { content: [{ type: "text", text: JSON.stringify(await appendCaptureAfter({ dragged: true }, params.captureAfter), null, 2) }] };
+        const start = await resolvePoint(params.startX, params.startY, params.windowId);
+        const end = await resolvePoint(params.endX, params.endY, params.windowId);
+        await withSafety({ action: "drag", params: { startX: start.x, startY: start.y, endX: end.x, endY: end.y }, 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);
     });
     registry.register("drag");
-    server.tool("doctor", "Check system permissions and diagnose common issues", {}, async () => {
+    registerTool("doctor", "Check system permissions, native helpers, and client readiness", {}, async () => {
         const { checkPermissions } = await import("../safety/permissions.js");
         const { MacOSPlatform: MacPlat } = await import("../platform/macos.js");
+        const { existsSync } = await import("node:fs");
+        const { join, dirname } = await import("node:path");
+        const { fileURLToPath } = await import("node:url");
+        const { execFileSync } = await import("node:child_process");
         const permissions = await checkPermissions();
         const screenLocked = process.platform === "darwin" ? new MacPlat().isScreenLocked?.() ?? false : false;
+        let nativeHelpers;
+        if (process.platform === "darwin") {
+            const moduleDir = dirname(fileURLToPath(import.meta.url));
+            const checkPaths = (subdirs) => {
+                const paths = [
+                    join(process.cwd(), ...subdirs),
+                    join(moduleDir, "..", ...subdirs),
+                    join(moduleDir, "..", "..", ...subdirs),
+                ];
+                return paths.some(p => { try {
+                    return existsSync(p);
+                }
+                catch {
+                    return false;
+                } });
+            };
+            nativeHelpers = {
+                cgevent: checkPaths(["native", "cgevent", "cgevent-helper"]),
+                ocr: checkPaths(["native", "ocr", "ocr-helper"]),
+            };
+        }
+        let readiness = "ready";
+        const issues = [];
+        if (!permissions.granted) {
+            readiness = "blocked";
+            issues.push("Missing macOS permissions: " + permissions.missing.join(", "));
+        }
+        if (screenLocked) {
+            readiness = "blocked";
+            issues.push("Screen is locked");
+        }
+        if (process.platform === "darwin" && nativeHelpers) {
+            if (!nativeHelpers.cgevent) {
+                readiness = readiness === "ready" ? "degraded" : readiness;
+                issues.push("Native CGEvent helper not found (input synthesis may crash on macOS Sequoia+)");
+            }
+            if (!nativeHelpers.ocr) {
+                readiness = readiness === "ready" ? "degraded" : readiness;
+                issues.push("Native OCR helper not found (OCR may fail on macOS Sequoia+)");
+            }
+        }
+        const clients = {};
+        for (const bin of ["claude", "codex", "opencode", "npx"]) {
+            try {
+                const path = execFileSync("which", [bin], { encoding: "utf-8", timeout: 2000 }).trim();
+                clients[bin] = path || "not found";
+            }
+            catch {
+                clients[bin] = "not found";
+            }
+        }
+        const recommendations = [];
+        if (readiness === "blocked") {
+            recommendations.push("Grant missing permissions in System Settings > Privacy & Security, then restart the MCP client.");
+        }
+        else if (readiness === "degraded") {
+            if (nativeHelpers && (!nativeHelpers.cgevent || !nativeHelpers.ocr)) {
+                recommendations.push("Run 'npm run build' to compile native Swift helpers.");
+            }
+        }
+        else {
+            recommendations.push("All checks passed. MCP client can proceed with automation.");
+        }
         const report = {
-            ok: permissions.granted && !screenLocked,
+            readiness,
+            issues: issues.length > 0 ? issues : undefined,
+            recommendations,
             platform: process.platform,
             node: process.version,
             permissions,
             screenLocked,
+            nativeHelpers,
+            clients,
             safety: {
                 urlBlocklist: true,
                 lockScreenGuard: process.platform === "darwin",
                 typedTextInjectionScan: true,
             },
             stdioCommand: "ucu-mcp",
-            clients: {
-                claudeCodeCli: "Run ucu-mcp as an MCP stdio server.",
-                claudeCodeDesktop: "Configure ucu-mcp as a local MCP stdio server.",
-                openCode: "Configure ucu-mcp as a local MCP stdio server.",
-            },
         };
         return { content: [{ type: "text", text: JSON.stringify(report, null, 2) }] };
     });
     registry.register("doctor");
-    server.tool("wait", "Wait for a specified duration", { ms: z.number().describe("Duration in milliseconds") }, async (params) => {
+    registerTool("wait", "Wait for a specified duration", { ms: z.number().describe("Duration in milliseconds") }, async (params) => {
         await new Promise(r => setTimeout(r, params.ms));
         return { content: [{ type: "text", text: JSON.stringify({ waited: params.ms }) }] };
     });
     registry.register("wait");
-    server.tool("wait_for_element", "Poll until an accessibility element matching the criteria appears", {
+    registerTool("wait_for_element", "Poll until an accessibility element matching the criteria reaches the desired state", {
         text: z.string().optional().describe("Element text"), role: z.string().optional().describe("Element role"),
-        app: z.string().optional().describe("Target app"), timeout: z.number().optional().describe("Timeout ms (default 5000)"), interval: z.number().optional().describe("Poll interval ms (default 500)"),
+        app: z.string().optional().describe("Target app"),
+        timeout: z.number().optional().describe("Timeout ms (default 5000)"),
+        timeoutMs: z.number().optional().describe("Alias for timeout"),
+        interval: z.number().optional().describe("Poll interval ms (default 500)"),
+        intervalMs: z.number().optional().describe("Alias for interval"),
+        until: z.enum(["appear", "disappear", "value_change"]).default("appear").describe("Wait condition: 'appear' (default) waits for a match, 'disappear' waits until no match, 'value_change' waits until first match's value changes"),
     }, async (params) => {
-        const deadline = Date.now() + (params.timeout ?? 5000);
-        const interval = params.interval ?? 500;
+        const deadline = Date.now() + (params.timeout ?? params.timeoutMs ?? 5000);
+        const interval = params.interval ?? params.intervalMs ?? 500;
+        const until = params.until ?? "appear";
+        const effectiveApp = params.app || getActiveTarget()?.appName;
+        const query = { text: params.text, role: params.role, app: effectiveApp, maxResults: 1 };
+        const { granted } = await checkPermission("accessibility");
+        if (!granted)
+            throw new PermissionError("accessibility", process.platform);
+        let initialValue;
         while (Date.now() < deadline) {
-            try {
-                const results = await getPlatform().findElement({ text: params.text, role: params.role, app: params.app, maxResults: 1 });
-                if (results.length > 0)
-                    return { content: [{ type: "text", text: JSON.stringify({ found: true, element: results[0] }, null, 2) }] };
+            const response = await getPlatform().findElement(query);
+            const matched = response.results[0];
+            if (until === "appear") {
+                if (matched)
+                    return { content: [{ type: "text", text: JSON.stringify({ found: true, element: matched }, null, 2) }] };
+            }
+            else if (until === "disappear") {
+                if (!matched)
+                    return { content: [{ type: "text", text: JSON.stringify({ found: true, reason: "disappeared" }, null, 2) }] };
+            }
+            else {
+                // value_change: capture the initial value of the first match, then wait for it to differ
+                if (matched) {
+                    if (initialValue === undefined) {
+                        initialValue = matched.value;
+                    }
+                    else if (matched.value !== initialValue) {
+                        return { content: [{ type: "text", text: JSON.stringify({ found: true, oldValue: initialValue, newValue: matched.value }, null, 2) }] };
+                    }
+                }
             }
-            catch { /* retry */ }
             await new Promise(r => setTimeout(r, interval));
         }
-        return { content: [{ type: "text", text: JSON.stringify({ found: false, reason: "timeout" }) }] };
+        return { content: [{ type: "text", text: JSON.stringify({ found: false, reason: "timeout" }, null, 2) }] };
     });
     registry.register("wait_for_element");
-    server.tool("get_cursor_position", "Get current cursor position", {}, async () => {
+    registerTool("get_cursor_position", "Get current cursor position", {}, async () => {
         const pos = await withSafety({ action: "get_cursor_position", params: {}, execute: () => Promise.resolve(getPlatform().getCursorPosition()) });
         return { content: [{ type: "text", text: JSON.stringify(pos, null, 2) }] };
     });
     registry.register("get_cursor_position");
-    server.tool("get_screen_size", "Get screen dimensions and scale factor", {
+    registerTool("get_screen_size", "Get screen dimensions and scale factor", {
         display: z.number().optional().describe("Display index"),
     }, async (params) => {
         return { content: [{ type: "text", text: JSON.stringify(getPlatform().getScreenSize(params.display), null, 2) }] };
     });
     registry.register("get_screen_size");
-    server.tool("ocr", "Perform OCR on screen region", {
+    registerTool("ocr", "Perform OCR on screen region", {
         display: z.number().optional().describe("Display index"),
         region: z.object({ x: z.number(), y: z.number(), width: z.number(), height: z.number() }).optional().describe("Region to OCR"),
     }, async (params) => {
@@ -278,46 +523,68 @@ export function registerTools(server) {
         return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
     });
     registry.register("ocr");
-    server.tool("move", "Move cursor to coordinates", {
+    registerTool("move", "Move cursor to coordinates", {
         x: z.number().describe("X coordinate"), y: z.number().describe("Y coordinate"),
         windowId: z.string().optional().describe("If set, x/y are relative to this window"),
+        ...captureAfterFields,
     }, async (params) => {
         const pt = await resolvePoint(params.x, params.y, params.windowId);
         await withSafety({ action: "move", params: { x: pt.x, y: pt.y }, requiresAccessibility: true, execute: () => getPlatform().move(pt.x, pt.y) });
-        return { content: [{ type: "text", text: JSON.stringify({ moved: true, x: pt.x, y: pt.y }, null, 2) }] };
+        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);
     });
     registry.register("move");
-    server.tool("find_element", "Find accessibility elements by text, role, or app", {
+    registerTool("find_element", "Find accessibility elements by text, role, or app", {
         text: z.string().optional().describe("Text to search"), role: z.string().optional().describe("AX role"), app: z.string().optional().describe("Target app"),
         depth: z.number().optional().describe("AX tree depth"), includeBounds: z.boolean().default(true).describe("Include bounds"), maxResults: z.number().min(1).max(200).default(50).describe("Max results"),
+        textMode: z.enum(["contains", "exact", "regex"]).default("contains").describe("Text matching mode: contains (default), exact, or regex"),
+        visibleOnly: z.boolean().default(false).describe("Only return elements with valid on-screen bounds"),
+        value: z.string().optional().describe("Filter by AX element value (respects textMode)"),
+        index: z.number().int().nonnegative().optional().describe("Return only the Nth match (0-based) after all other filtering and sorting"),
+        near: z.object({ x: z.number(), y: z.number() }).optional().describe("Sort results by ascending distance to this point and return closest first"),
     }, async (params) => {
-        const results = await withSafety({ action: "find_element", params: {}, requiresAccessibility: true,
-            execute: () => getPlatform().findElement({ text: params.text, role: params.role, app: params.app, depth: params.depth, includeBounds: params.includeBounds, maxResults: params.maxResults }) });
-        return { content: [{ type: "text", text: JSON.stringify(results, null, 2) }] };
+        const effectiveApp = params.app || getActiveTarget()?.appName;
+        const response = await withSafety({ action: "find_element", params: {}, requiresAccessibility: true,
+            execute: () => getPlatform().findElement({ text: params.text, role: params.role, app: effectiveApp, depth: params.depth, includeBounds: params.includeBounds, maxResults: params.maxResults, textMode: params.textMode, visibleOnly: params.visibleOnly, value: params.value, index: params.index, near: params.near }) });
+        return { content: [{ type: "text", text: JSON.stringify({ results: response.results, metrics: response.metrics }, null, 2) }] };
     });
     registry.register("find_element");
-    server.tool("click_element", "Click an accessibility element by its ID", {
+    registerTool("click_element", "Click an accessibility element by its ID", {
         elementId: z.string().describe("AX element identifier"), app: z.string().optional().describe("Target app"), ...captureAfterFields,
     }, async (params) => {
-        await withSafety({ action: "click_element", params: {}, requiresAccessibility: true, execute: () => getPlatform().clickElement(params.elementId, params.app) });
-        return { content: [{ type: "text", text: JSON.stringify(await appendCaptureAfter({ clicked: true, elementId: params.elementId }, params.captureAfter), null, 2) }] };
+        const effectiveApp = params.app || getActiveTarget()?.appName;
+        await withSafety({ action: "click_element", params: {}, requiresAccessibility: true, execute: () => getPlatform().clickElement(params.elementId, effectiveApp) });
+        return actionResponse("click_element", { clicked: true, elementId: params.elementId }, { elementId: params.elementId, app: effectiveApp }, params.captureAfter, params.captureFormat, params.captureMaxWidth);
     });
     registry.register("click_element");
-    server.tool("set_value", "Set the value of an accessibility element", {
+    registerTool("set_value", "Set the value of an accessibility element", {
         elementId: z.string().describe("AX element identifier"), value: z.string().describe("Value to set"), app: z.string().optional().describe("Target app"), ...captureAfterFields,
     }, async (params) => {
-        await withSafety({ action: "set_value", params: { value: params.value }, requiresAccessibility: true, execute: () => getPlatform().setElementValue(params.elementId, params.value, params.app) });
-        return { content: [{ type: "text", text: JSON.stringify(await appendCaptureAfter({ setValue: true, elementId: params.elementId }, params.captureAfter), null, 2) }] };
+        const effectiveApp = params.app || getActiveTarget()?.appName;
+        await withSafety({ action: "set_value", params: { value: params.value }, requiresAccessibility: true, execute: () => getPlatform().setElementValue(params.elementId, params.value, effectiveApp) });
+        return actionResponse("set_value", { setValue: true, elementId: params.elementId }, { elementId: params.elementId, app: effectiveApp }, params.captureAfter, params.captureFormat, params.captureMaxWidth);
     });
     registry.register("set_value");
-    server.tool("type_in_element", "Type text into an accessibility element, optionally clearing first", {
+    registerTool("type_in_element", "Type text into an accessibility element, optionally clearing first", {
         elementId: z.string().describe("AX element identifier"), text: z.string().describe("Text to type"),
         app: z.string().optional().describe("Target app"), clearFirst: z.boolean().optional().describe("Clear existing text before typing"), ...captureAfterFields,
     }, async (params) => {
-        await withSafety({ action: "type_in_element", params: { text: params.text }, requiresAccessibility: true, execute: () => getPlatform().typeInElement(params.elementId, params.text, params.app, params.clearFirst) });
-        return { content: [{ type: "text", text: JSON.stringify(await appendCaptureAfter({ typed: true, elementId: params.elementId, charCount: params.text.length }, params.captureAfter), null, 2) }] };
+        const effectiveApp = params.app || getActiveTarget()?.appName;
+        await withSafety({ action: "type_in_element", params: { text: params.text }, requiresAccessibility: true, execute: () => getPlatform().typeInElement(params.elementId, params.text, effectiveApp, params.clearFirst) });
+        return actionResponse("type_in_element", { typed: true, elementId: params.elementId, charCount: params.text.length }, { elementId: params.elementId, app: effectiveApp }, params.captureAfter, params.captureFormat, params.captureMaxWidth);
     });
     registry.register("type_in_element");
+    registerTool("clipboard_read", "Read the current contents of the system clipboard", {}, async () => {
+        const text = await withSafety({ action: "clipboard_read", params: {}, execute: () => getPlatform().readClipboard() });
+        return { content: [{ type: "text", text: JSON.stringify({ text }, null, 2) }] };
+    });
+    registry.register("clipboard_read");
+    registerTool("clipboard_write", "Write text to the system clipboard (text injection patterns are blocked)", {
+        text: z.string().describe("Text to place on the clipboard"),
+    }, async (params) => {
+        await withSafety({ action: "clipboard_write", params: { text: params.text }, execute: () => getPlatform().writeClipboard(params.text) });
+        return { content: [{ type: "text", text: JSON.stringify({ written: true }, null, 2) }] };
+    });
+    registry.register("clipboard_write");
     log.info("Registered tools", { count: registry.tools.length, tools: registry.tools.join(", ") });
 }
 export class ToolRegistry {