ucu-mcp 0.2.0 → 0.3.1

package/dist/src/mcp/tools.js

@@ -1,15 +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 { metrics } from "../util/metrics.js";
 import { SafetyError, PermissionError, UnsupportedParameterError, UcuError, WindowNotFoundError } from "../util/errors.js";
 const log = createLogger("tools");
 let _platform;
@@ -20,6 +21,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;
@@ -43,6 +52,8 @@ 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":
@@ -61,28 +72,63 @@ function recoveryHint(code) {
             return "Inspect the error message, observe the current UI state, and retry only if the operation is safe.";
     }
 }
-function mcpErrorResponse(error) {
+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: {
-                    name: err.name,
-                    code,
-                    retryable,
-                    message: err.message,
-                    recovery: recoveryHint(code),
-                },
+                error: errorDetails(error),
             }),
         ],
     };
 }
-async function actionResponse(result, captureAfter, captureFormat = "jpeg", captureMaxWidth = 1280) {
-    if (!captureAfter)
-        return { content: [jsonText(result)] };
+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 buf = await getPlatform().screenshot(undefined, undefined, {
             format: captureFormat,
@@ -90,7 +136,7 @@ async function actionResponse(result, captureAfter, captureFormat = "jpeg", capt
         });
         return {
             content: [
-                jsonText({ actionResult: result }),
+                jsonText(receipt),
                 {
                     type: "image",
                     data: buf.toString("base64"),
@@ -99,8 +145,9 @@ async function actionResponse(result, captureAfter, captureFormat = "jpeg", capt
             ],
         };
     }
-    catch {
-        return { content: [jsonText(result)] };
+    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([
@@ -118,7 +165,9 @@ 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) {
@@ -136,12 +185,14 @@ async function withSafety(sa) {
     const shouldManageFocus = sa.requiresAccessibility && !["screenshot", "list_windows", "list_apps", "get_window_state", "get_cursor_position", "get_screen_size", "ocr", "doctor", "wait", "wait_for_element", "find_element", "focus_app"].includes(sa.action);
     if (shouldManageFocus)
         await platform.saveFocus?.();
+    const start = Date.now();
     try {
         return retryableActions.has(sa.action)
             ? await retry(() => sa.execute())
             : await sa.execute();
     }
     finally {
+        metrics.record(sa.action, Date.now() - start);
         if (shouldManageFocus)
             await platform.restoreFocus?.();
     }
@@ -224,13 +275,15 @@ export function registerTools(server) {
         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");
     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");
@@ -242,7 +295,7 @@ 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 actionResponse({ clicked: true, x: pt.x, y: pt.y }, params.captureAfter, params.captureFormat, params.captureMaxWidth);
+        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");
     registerTool("double_click", "Double-click at screen coordinates", {
@@ -253,7 +306,7 @@ 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 actionResponse({ doubleClicked: true, x: pt.x, y: pt.y }, params.captureAfter, params.captureFormat, params.captureMaxWidth);
+        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");
     registerTool("type_text", "Type text at the current cursor position", {
@@ -264,7 +317,7 @@ 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 actionResponse({ typed: true, charCount: params.text.length }, params.captureAfter, params.captureFormat, params.captureMaxWidth);
+        return actionResponse("type_text", { typed: true, charCount: params.text.length }, {}, params.captureAfter, params.captureFormat, params.captureMaxWidth);
     });
     registry.register("type_text");
     registerTool("press_key", "Press a keyboard shortcut", {
@@ -283,7 +336,7 @@ export function registerTools(server) {
         if (keys.length === 0)
             throw new UnsupportedParameterError("press_key requires at least one key");
         await withSafety({ action: "press_key", params: { keys }, requiresAccessibility: true, execute: () => getPlatform().key(keys) });
-        return actionResponse({ pressed: true, keys }, params.captureAfter, params.captureFormat, params.captureMaxWidth);
+        return actionResponse("press_key", { pressed: true, keys }, {}, params.captureAfter, params.captureFormat, params.captureMaxWidth);
     });
     registry.register("press_key");
     registerTool("scroll", "Scroll at coordinates", {
@@ -295,7 +348,7 @@ export function registerTools(server) {
         const pt = await resolvePoint(params.x, params.y, params.windowId);
         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({ scrolled: true, x: pt.x, y: pt.y }, params.captureAfter, params.captureFormat, params.captureMaxWidth);
+        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");
     registerTool("drag", "Drag from one point to another", {
@@ -309,30 +362,100 @@ export function registerTools(server) {
         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({ dragged: true, startX: start.x, startY: start.y, endX: end.x, endY: end.y }, params.captureAfter, params.captureFormat, params.captureMaxWidth);
+        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");
-    registerTool("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.",
+            metrics: {
+                global: metrics.stats(),
+                byTool: metrics.byTool(),
             },
         };
         return { content: [{ type: "text", text: JSON.stringify(report, null, 2) }] };
@@ -343,27 +466,56 @@ export function registerTools(server) {
         return { content: [{ type: "text", text: JSON.stringify({ waited: params.ms }) }] };
     });
     registry.register("wait");
-    registerTool("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)"),
         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 ?? params.timeoutMs ?? 5000);
         const interval = params.interval ?? params.intervalMs ?? 500;
-        const query = { text: params.text, role: params.role, app: params.app, maxResults: 1 };
+        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;
+        let hasInitial = false;
         while (Date.now() < deadline) {
-            const results = await getPlatform().findElement(query);
-            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.
+                // A separate `hasInitial` flag is required because the first match's `value` may itself be
+                // undefined; using `initialValue === undefined` to mean "not yet captured" would loop
+                // forever in that case. On timeout, distinguish "element never appeared" from "value stayed
+                // the same" so the model can branch on the result.
+                if (matched) {
+                    if (!hasInitial) {
+                        initialValue = matched.value;
+                        hasInitial = true;
+                    }
+                    else if (matched.value !== initialValue) {
+                        return { content: [{ type: "text", text: JSON.stringify({ found: true, oldValue: initialValue, newValue: matched.value }, null, 2) }] };
+                    }
+                }
+            }
             await new Promise(r => setTimeout(r, interval));
         }
-        return { content: [{ type: "text", text: JSON.stringify({ found: false, reason: "timeout" }) }] };
+        const reason = until === "value_change" ? (hasInitial ? "value_unchanged" : "never_appeared") : "timeout";
+        return { content: [{ type: "text", text: JSON.stringify({ found: false, reason }, null, 2) }] };
     });
     registry.register("wait_for_element");
     registerTool("get_cursor_position", "Get current cursor position", {}, async () => {
@@ -392,40 +544,61 @@ export function registerTools(server) {
     }, 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 actionResponse({ moved: true, x: pt.x, y: pt.y }, params.captureAfter, params.captureFormat, params.captureMaxWidth);
+        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");
     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");
     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 actionResponse({ clicked: true, elementId: params.elementId }, params.captureAfter, params.captureFormat, params.captureMaxWidth);
+        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");
     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 actionResponse({ setValue: true, elementId: params.elementId }, params.captureAfter, params.captureFormat, params.captureMaxWidth);
+        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");
     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 actionResponse({ typed: true, elementId: params.elementId, charCount: params.text.length }, params.captureAfter, params.captureFormat, params.captureMaxWidth);
+        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 {

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

@@ -38,10 +38,12 @@ export interface AppInfo {
     windowCount: number;
 }
 export interface AppTarget {
+    targetId: string;
     appName: string;
     pid: number;
     windowId?: string;
     title?: string;
+    capturedAt: string;
 }
 export interface BrowserContext {
     appName: string;
@@ -81,6 +83,17 @@ export interface FindElementOptions {
     depth?: number;
     includeBounds?: boolean;
     maxResults?: number;
+    textMode?: "contains" | "exact" | "regex";
+    visibleOnly?: boolean;
+    /** Match against the AX element's current value attribute (respects textMode). */
+    value?: string;
+    /** Return only the Nth match (0-based) after all other filtering and sorting. */
+    index?: number;
+    /** Sort results by ascending distance to this point and return closest first. */
+    near?: {
+        x: number;
+        y: number;
+    };
 }
 export interface FindElementResult {
     id: string;
@@ -95,6 +108,16 @@ export interface FindElementResult {
     };
     description?: string;
 }
+export interface FindElementMetrics {
+    scannedCount: number;
+    matchedCount: number;
+    durationMs: number;
+    truncated: boolean;
+}
+export interface FindElementResponse {
+    results: FindElementResult[];
+    metrics: FindElementMetrics;
+}
 export interface WindowState {
     window: WindowInfo;
     focusedElement?: ElementInfo;
@@ -117,11 +140,13 @@ export interface Platform {
     ocr(display?: number, region?: ScreenRegion): Promise<OcrResult>;
     type(text: string, delay?: number): Promise<void>;
     key(keys: string[]): Promise<void>;
-    findElement(options: FindElementOptions): Promise<FindElementResult[]>;
+    findElement(options: FindElementOptions): Promise<FindElementResponse>;
     clickElement(elementId: string, app?: string): Promise<void>;
     typeInElement(elementId: string, text: string, app?: string, clearFirst?: boolean): Promise<void>;
     setElementValue?(elementId: string, value: string, app?: string): Promise<void>;
     isScreenLocked?(): boolean;
     saveFocus?(): Promise<void>;
     restoreFocus?(): Promise<void>;
+    readClipboard(): Promise<string>;
+    writeClipboard(text: string): Promise<void>;
 }

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

@@ -1,4 +1,4 @@
-import type { Platform, ScreenRegion, ScreenSize, CursorPosition, WindowInfo, WindowState, OcrResult, FindElementOptions, FindElementResult } from "./base.js";
+import type { Platform, ScreenRegion, ScreenSize, CursorPosition, WindowInfo, WindowState, OcrResult, FindElementOptions, FindElementResponse } from "./base.js";
 /**
  * Linux platform adapter (AT-SPI2 + xdotool fallback)
  * TODO: Implement with D-Bus AT-SPI2 bindings
@@ -16,7 +16,9 @@ export declare class LinuxPlatform implements Platform {
     type(text: string, delay?: number): Promise<void>;
     key(keys: string[]): Promise<void>;
     ocr(_display?: number, _region?: ScreenRegion): Promise<OcrResult>;
-    findElement(_options: FindElementOptions): Promise<FindElementResult[]>;
+    findElement(_options: FindElementOptions): Promise<FindElementResponse>;
     clickElement(_elementId: string, _app?: string): Promise<void>;
     typeInElement(_elementId: string, _text: string, _app?: string, _clearFirst?: boolean): Promise<void>;
+    readClipboard(): Promise<string>;
+    writeClipboard(text: string): Promise<void>;
 }

package/dist/src/platform/linux.js

@@ -1,3 +1,27 @@
+import { execFileSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { PlatformError } from "../util/errors.js";
+/** Pick the first available clipboard utility, preferring xclip. */
+function pickClipboardTool() {
+    for (const bin of ["/usr/bin/xclip", "/usr/local/bin/xclip", "xclip"]) {
+        if (bin.startsWith("/") ? existsSync(bin) : which(bin))
+            return "xclip";
+    }
+    for (const bin of ["/usr/bin/xsel", "/usr/local/bin/xsel", "xsel"]) {
+        if (bin.startsWith("/") ? existsSync(bin) : which(bin))
+            return "xsel";
+    }
+    return undefined;
+}
+function which(bin) {
+    try {
+        execFileSync("which", [bin], { encoding: "utf-8", timeout: 2000, stdio: "ignore" });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 /**
  * Linux platform adapter (AT-SPI2 + xdotool fallback)
  * TODO: Implement with D-Bus AT-SPI2 bindings
@@ -59,4 +83,31 @@ export class LinuxPlatform {
     async typeInElement(_elementId, _text, _app, _clearFirst) {
         throw new Error("Not implemented: Linux typeInElement");
     }
+    async readClipboard() {
+        const tool = pickClipboardTool();
+        if (!tool) {
+            throw new PlatformError("readClipboard requires xclip or xsel on PATH", false);
+        }
+        try {
+            const args = tool === "xclip" ? ["-selection", "clipboard", "-o"] : ["--clipboard", "--output"];
+            const out = execFileSync(tool, args, { encoding: "utf-8", timeout: 5000 });
+            return out;
+        }
+        catch (error) {
+            throw new PlatformError(`read_clipboard failed: ${error.message}`);
+        }
+    }
+    async writeClipboard(text) {
+        const tool = pickClipboardTool();
+        if (!tool) {
+            throw new PlatformError("writeClipboard requires xclip or xsel on PATH", false);
+        }
+        try {
+            const args = tool === "xclip" ? ["-selection", "clipboard"] : ["--clipboard", "--input"];
+            execFileSync(tool, args, { input: text, encoding: "utf-8", timeout: 5000 });
+        }
+        catch (error) {
+            throw new PlatformError(`write_clipboard failed: ${error.message}`);
+        }
+    }
 }

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

@@ -1,4 +1,4 @@
-import type { Platform, ScreenRegion, ScreenSize, CursorPosition, WindowInfo, WindowState, OcrResult, FindElementOptions, FindElementResult, AppInfo, AppTarget, BrowserContext, ScreenshotOptions } from "./base.js";
+import type { Platform, ScreenRegion, ScreenSize, CursorPosition, WindowInfo, WindowState, OcrResult, FindElementOptions, FindElementResponse, AppInfo, AppTarget, BrowserContext, ScreenshotOptions } from "./base.js";
 export declare class MacOSPlatform implements Platform {
     private readonly elementCache;
     private readonly elementCacheTtlMs;
@@ -13,6 +13,8 @@ export declare class MacOSPlatform implements Platform {
     private evictOverflowCacheEntries;
     /** Check whether a cached element descriptor has expired. */
     private isCacheEntryExpired;
+    /** Validate that the active target window still exists. */
+    validateActiveTarget(): Promise<void>;
     /** Save the current frontmost app/window so we can restore after an action. */
     saveFocus(): Promise<void>;
     /** Restore the previously saved frontmost app/window. */
@@ -36,8 +38,10 @@ export declare class MacOSPlatform implements Platform {
     private ocrJxa;
     type(text: string, delay?: number): Promise<void>;
     key(keys: string[]): Promise<void>;
-    findElement(options: FindElementOptions): Promise<FindElementResult[]>;
+    findElement(options: FindElementOptions): Promise<FindElementResponse>;
     clickElement(elementId: string, app?: string): Promise<void>;
     typeInElement(elementId: string, text: string, app?: string, clearFirst?: boolean): Promise<void>;
+    readClipboard(): Promise<string>;
+    writeClipboard(text: string): Promise<void>;
     setElementValue(elementId: string, value: string, app?: string): Promise<void>;
 }