ucu-mcp 0.5.2 → 0.6.2

package/dist/src/utils/input.js

@@ -18,33 +18,93 @@ const execFileAsync = promisify(execFile);
 // ── Native CGEvent helper (macOS) ──────────────────────────────────────
 // JXA (osascript -l JavaScript) cannot call CGEventPost without segfault.
 // We ship a small Swift binary that does native CGEvent injection instead.
+//
+// v0.6.0: two helpers. `skylight-helper` posts events per-process via
+// SLEventPostToPid (private SkyLight SPI) so the global cursor does NOT move
+// and the foreground is NOT stolen — matching Codex computer-use. `cgevent-helper`
+// (legacy) posts to the HID event tap, which moves the cursor. We prefer
+// skylight when a target pid is available; fall back to cgevent otherwise.
 const __dirname = dirname(fileURLToPath(import.meta.url));
 // In dev: src/utils/input.ts → native/cgevent/cgevent-helper
 // In prod: dist/src/utils/input.js → dist/native/cgevent/cgevent-helper
-const nativeHelperPath = join(__dirname, "..", "..", "..", "native", "cgevent", "cgevent-helper");
-// Fallback: try from project root (dev mode)
-const nativeHelperPathAlt = join(__dirname, "..", "..", "native", "cgevent", "cgevent-helper");
+const cgeventHelperPath = join(__dirname, "..", "..", "..", "native", "cgevent", "cgevent-helper");
+const cgeventHelperPathAlt = join(__dirname, "..", "..", "native", "cgevent", "cgevent-helper");
+const skylightHelperPath = join(__dirname, "..", "..", "..", "native", "skylight", "skylight-helper");
+const skylightHelperPathAlt = join(__dirname, "..", "..", "native", "skylight", "skylight-helper");
 import { existsSync } from "node:fs";
-const resolvedNativePath = existsSync(nativeHelperPath) ? nativeHelperPath : nativeHelperPathAlt;
-let _nativeAvailable;
-function isNativeAvailable() {
-    if (_nativeAvailable !== undefined)
-        return _nativeAvailable;
+const resolvedCgeventPath = existsSync(cgeventHelperPath) ? cgeventHelperPath : cgeventHelperPathAlt;
+const resolvedSkylightPath = existsSync(skylightHelperPath) ? skylightHelperPath : skylightHelperPathAlt;
+let _cgeventAvailable;
+let _skylightAvailable;
+function isCgeventAvailable() {
+    if (_cgeventAvailable !== undefined)
+        return _cgeventAvailable;
     try {
-        const stdout = execFileSync(resolvedNativePath, [], {
+        const stdout = execFileSync(resolvedCgeventPath, [], {
             input: '{"command":"ping"}',
             encoding: "utf8",
             timeout: 3000,
         });
-        _nativeAvailable = stdout.includes('"ok"');
+        _cgeventAvailable = stdout.includes('"ok"');
     }
     catch {
-        _nativeAvailable = false;
+        _cgeventAvailable = false;
     }
-    return _nativeAvailable;
+    return _cgeventAvailable;
 }
-function runNativeChecked(payload) {
-    const raw = execFileSync(resolvedNativePath, [], {
+function isSkylightAvailable() {
+    if (_skylightAvailable !== undefined)
+        return _skylightAvailable;
+    if (!existsSync(resolvedSkylightPath)) {
+        _skylightAvailable = false;
+        return false;
+    }
+    try {
+        const stdout = execFileSync(resolvedSkylightPath, [], {
+            input: '{"command":"ping"}',
+            encoding: "utf8",
+            timeout: 3000,
+        });
+        _skylightAvailable = stdout.includes('"ok"');
+    }
+    catch {
+        _skylightAvailable = false;
+    }
+    return _skylightAvailable;
+}
+/** @deprecated use isCgeventAvailable — kept for external callers/tests. */
+function isNativeAvailable() {
+    return isCgeventAvailable();
+}
+/**
+ * Run an input command via the best available helper.
+ * - target.pid > 0 AND skylight available → skylight-helper (per-process, no cursor move). Returns "per-pid".
+ * - otherwise → cgevent-helper (HID tap, moves cursor). Returns "hid-tap".
+ * If skylight is chosen but errors at runtime, falls back to cgevent (HID-tap) rather than throwing.
+ * Throws only if BOTH helpers fail.
+ */
+function runInputChecked(payload, target) {
+    const useSkylight = !!target?.pid && target.pid > 0 && isSkylightAvailable();
+    if (useSkylight) {
+        const fullPayload = { ...payload, pid: target.pid, windowNumber: target.windowNumber };
+        try {
+            const raw = execFileSync(resolvedSkylightPath, [], {
+                input: JSON.stringify(fullPayload),
+                encoding: "utf8",
+                timeout: 10000,
+            }).trim();
+            const resp = JSON.parse(raw);
+            if (!resp.error) {
+                return (resp.method === "per-pid") ? "per-pid" : "hid-tap";
+            }
+            // skylight errored at runtime (SPI filtered / event build failed) → fall through to cgevent.
+        }
+        catch {
+            // skylight crashed/timed out → fall through to cgevent.
+        }
+    }
+    // cgevent path (HID-tap) — the reliable fallback.
+    const raw = execFileSync(resolvedCgeventPath, [], {
         input: JSON.stringify(payload),
         encoding: "utf8",
         timeout: 10000,
@@ -53,6 +113,11 @@ function runNativeChecked(payload) {
     if (resp.error) {
         throw new Error(`native helper error: ${resp.error}`);
     }
+    return "hid-tap";
+}
+/** @deprecated use runInputChecked — kept for external callers/tests. */
+function runNativeChecked(payload) {
+    runInputChecked(payload);
 }
 // ── Dry-run mode ──────────────────────────────────────────────────────────
 const isDryRun = () => process.env.UCU_DRY_RUN === "true";
@@ -112,15 +177,14 @@ async function runJXA(script, timeout = 5000) {
     return stdout.trim();
 }
 // ── Mouse operations (CGEvent — background, no focus steal) ───────────────
-export async function click(x, y, button = "left", _platform = process.platform) {
+export async function click(x, y, button = "left", _platform = process.platform, target) {
     if (isDryRun()) {
         logDryRun("click", { x, y, button });
         return;
     }
     if (_platform === "darwin") {
-        if (isNativeAvailable()) {
-            runNativeChecked({ command: "click", x, y, button });
-            return;
+        if (isCgeventAvailable() || isSkylightAvailable()) {
+            return runInputChecked({ command: "click", x, y, button }, target);
         }
         const btnType = { left: 0, right: 1, middle: 2 }[button];
         await runJXA(`
@@ -144,15 +208,14 @@ export async function click(x, y, button = "left", _platform = process.platform)
     // Windows
     throw new Error("click not implemented for Windows");
 }
-export async function doubleClick(x, y, button = "left", _platform = process.platform) {
+export async function doubleClick(x, y, button = "left", _platform = process.platform, target) {
     if (isDryRun()) {
         logDryRun("doubleClick", { x, y, button });
         return;
     }
     if (_platform === "darwin") {
-        if (isNativeAvailable()) {
-            runNativeChecked({ command: "doubleClick", x, y, button });
-            return;
+        if (isCgeventAvailable() || isSkylightAvailable()) {
+            return runInputChecked({ command: "doubleClick", x, y, button }, target);
         }
         const btnType = { left: 0, right: 1, middle: 2 }[button];
         await runJXA(`
@@ -182,15 +245,14 @@ export async function doubleClick(x, y, button = "left", _platform = process.pla
     await new Promise(r => setTimeout(r, 50));
     await click(x, y, button, _platform);
 }
-export async function move(x, y, _platform = process.platform) {
+export async function move(x, y, _platform = process.platform, target) {
     if (isDryRun()) {
         logDryRun("move", { x, y });
         return;
     }
     if (_platform === "darwin") {
-        if (isNativeAvailable()) {
-            runNativeChecked({ command: "move", x, y });
-            return;
+        if (isCgeventAvailable() || isSkylightAvailable()) {
+            return runInputChecked({ command: "move", x, y }, target);
         }
         await runJXA(`
       ObjC.import('CoreGraphics');
@@ -207,15 +269,14 @@ export async function move(x, y, _platform = process.platform) {
     }
     throw new Error("move not implemented for Windows");
 }
-export async function drag(fromX, fromY, toX, toY, button = "left", duration = 300, _platform = process.platform) {
+export async function drag(fromX, fromY, toX, toY, button = "left", duration = 300, _platform = process.platform, target) {
     if (isDryRun()) {
         logDryRun("drag", { fromX, fromY, toX, toY, button, duration });
         return;
     }
     if (_platform === "darwin") {
-        if (isNativeAvailable()) {
-            runNativeChecked({ command: "drag", fromX, fromY, toX, toY, button, durationMs: duration });
-            return;
+        if (isCgeventAvailable() || isSkylightAvailable()) {
+            return runInputChecked({ command: "drag", fromX, fromY, toX, toY, button, durationMs: duration }, target);
         }
         const btnType = { left: 0, right: 1, middle: 2 }[button];
         const steps = Math.max(2, Math.min(60, Math.ceil(duration / 16)));
@@ -257,15 +318,14 @@ export async function drag(fromX, fromY, toX, toY, button = "left", duration = 3
     }
     throw new Error("drag not implemented for Windows");
 }
-export async function scroll(x, y, deltaX, deltaY, _platform = process.platform) {
+export async function scroll(x, y, deltaX, deltaY, _platform = process.platform, target) {
     if (isDryRun()) {
         logDryRun("scroll", { x, y, deltaX, deltaY });
         return;
     }
     if (_platform === "darwin") {
-        if (isNativeAvailable()) {
-            runNativeChecked({ command: "scroll", x, y, deltaX, deltaY });
-            return;
+        if (isCgeventAvailable() || isSkylightAvailable()) {
+            return runInputChecked({ command: "scroll", x, y, deltaX, deltaY }, target);
         }
         const verticalDelta = -deltaY;
         const horizontalDelta = deltaX;
@@ -292,7 +352,7 @@ export async function scroll(x, y, deltaX, deltaY, _platform = process.platform)
     throw new Error("scroll not implemented for Windows");
 }
 // ── Keyboard operations (CGEvent — background) ────────────────────────────
-export async function typeText(text, delay = 20, _platform = process.platform) {
+export async function typeText(text, delay = 20, _platform = process.platform, target) {
     if (isDryRun()) {
         logDryRun("typeText", { text: text.slice(0, 50), delay });
         return;
@@ -377,8 +437,8 @@ export async function typeText(text, delay = 20, _platform = process.platform) {
         // Process each batch
         for (const batch of batches) {
             if (batch.cgEvent && Array.isArray(batch.chars)) {
-                if (isNativeAvailable()) {
-                    runNativeChecked({ command: "typeBatch", keys: batch.chars });
+                if (isCgeventAvailable() || isSkylightAvailable()) {
+                    runInputChecked({ command: "typeBatch", keys: batch.chars }, target);
                 }
                 else {
                     // Build a single JXA script that types all chars in this CGEvent batch
@@ -418,7 +478,7 @@ export async function typeText(text, delay = 20, _platform = process.platform) {
     }
     throw new Error("typeText not implemented for Windows");
 }
-export async function pressKey(key, modifiers = [], _platform = process.platform) {
+export async function pressKey(key, modifiers = [], _platform = process.platform, target) {
     if (isDryRun()) {
         logDryRun("pressKey", { key, modifiers });
         return;
@@ -443,9 +503,8 @@ export async function pressKey(key, modifiers = [], _platform = process.platform
             }
             flags |= flag;
         }
-        if (isNativeAvailable()) {
-            runNativeChecked({ command: "pressKey", keyCode, flags });
-            return;
+        if (isCgeventAvailable() || isSkylightAvailable()) {
+            return runInputChecked({ command: "pressKey", keyCode, flags }, target);
         }
         await runJXA(`
       ObjC.import('CoreGraphics');
@@ -468,7 +527,7 @@ export async function pressKey(key, modifiers = [], _platform = process.platform
     }
     throw new Error("pressKey not implemented for Windows");
 }
-export async function pressShortcut(keys, _platform = process.platform) {
+export async function pressShortcut(keys, _platform = process.platform, target) {
     if (isDryRun()) {
         logDryRun("pressShortcut", { keys });
         return;
@@ -478,7 +537,7 @@ export async function pressShortcut(keys, _platform = process.platform) {
     }
     const modifiers = keys.slice(0, -1);
     const key = keys[keys.length - 1];
-    await pressKey(key, modifiers, _platform);
+    return await pressKey(key, modifiers, _platform, target);
 }
 // ── Cursor position ───────────────────────────────────────────────────────
 export async function getCursorPosition(_platform = process.platform) {

package/native/skylight/main.swift

@@ -0,0 +1,402 @@
+// skylight-helper: per-process event posting via private SkyLight SPIs.
+//
+// Posts mouse/keyboard events to a SPECIFIC process (by pid) without moving the
+// global cursor or stealing foreground — matching Codex computer-use behavior.
+// Uses SLEventPostToPid (private SkyLight) for mouse, CGEventPostToPid (public)
+// for keyboard. Falls back to HID-tap posting (which moves the cursor) when the
+// target is frontmost/canvas-app or when SPIs are unavailable.
+//
+// stdin/stdout JSON protocol mirrors cgevent-helper (line-oriented).
+
+import CoreGraphics
+import Foundation
+import AppKit
+
+// MARK: - SkyLight SPI loading
+
+private let RTLD_DEFAULT = UnsafeMutableRawPointer(bitPattern: -2)!
+
+// Force-load SkyLight so its symbols register in the global namespace.
+_ = dlopen("/System/Library/PrivateFrameworks/SkyLight.framework/SkyLight", RTLD_LAZY)
+
+private func sym<T>(_ name: String, as _: T.Type) -> T? {
+    guard let p = dlsym(RTLD_DEFAULT, name) else { return nil }
+    return unsafeBitCast(p, to: T.self)
+}
+
+// void SLEventPostToPid(pid_t, CGEventRef)
+private typealias SLEventPostToPidFn = @convention(c) (pid_t, CGEvent) -> Void
+private let slPostToPid: SLEventPostToPidFn? = sym("SLEventPostToPid", as: SLEventPostToPidFn.self)
+
+// void CGEventSetWindowLocation(CGEventRef, CGPoint)  — private
+private typealias SetWindowLocFn = @convention(c) (CGEvent, CGPoint) -> Void
+private let setWindowLoc: SetWindowLocFn? = sym("CGEventSetWindowLocation", as: SetWindowLocFn.self)
+
+// void SLEventSetIntegerValueField(CGEventRef, uint32_t, int64_t)  — private
+private typealias SetIntFieldFn = @convention(c) (CGEvent, UInt32, Int64) -> Void
+private let setIntField: SetIntFieldFn? = sym("SLEventSetIntegerValueField", as: SetIntFieldFn.self)
+
+// CGSConnectionID CGSMainConnectionID(void)
+private typealias ConnIDFn = @convention(c) () -> UInt32
+private let mainConnID: ConnIDFn? = sym("CGSMainConnectionID", as: ConnIDFn.self)
+
+// CGError SLSGetWindowOwner(CGSConnectionID, CGWindowID, CGSConnectionID*)
+private typealias GetWindowOwnerFn = @convention(c) (UInt32, UInt32, UnsafeMutablePointer<UInt32>) -> Int32
+private let getWindowOwner: GetWindowOwnerFn? = sym("SLSGetWindowOwner", as: GetWindowOwnerFn.self)
+
+// OSStatus SLSGetConnectionPSN(CGSConnectionID, ProcessSerialNumber*)
+private typealias GetConnPSNFn = @convention(c) (UInt32, UnsafeMutableRawPointer) -> Int32
+private let getConnPSN: GetConnPSNFn? = sym("SLSGetConnectionPSN", as: GetConnPSNFn.self)
+
+// OSStatus _SLPSGetFrontProcess(ProcessSerialNumber*)
+private typealias GetFrontPSNFn = @convention(c) (UnsafeMutableRawPointer) -> Int32
+private let getFrontPSN: GetFrontPSNFn? = sym("_SLPSGetFrontProcess", as: GetFrontPSNFn.self)
+
+// OSStatus SLPSPostEventRecordTo(ProcessSerialNumber*, uint8_t*)
+private typealias PostEventRecFn = @convention(c) (UnsafeRawPointer, UnsafePointer<UInt8>) -> Int32
+private let postEventRec: PostEventRecFn? = sym("SLPSPostEventRecordTo", as: PostEventRecFn.self)
+
+/// True if all SPIs needed for per-process mouse posting are present.
+private let skylightMouseAvailable: Bool = (slPostToPid != nil)
+
+// MARK: - I/O helpers
+
+struct Input: Decodable {
+    let command: String
+    let pid: Int32?
+    let windowNumber: Int?
+    let x: Double?
+    let y: Double?
+    let fromX: Double?
+    let fromY: Double?
+    let toX: Double?
+    let toY: Double?
+    let button: String?
+    let durationMs: Int?
+    let deltaX: Int?
+    let deltaY: Int?
+    let keyCode: Int?
+    let flags: Int64?
+    let keys: [KeyEntry]?
+    struct KeyEntry: Decodable { let code: Int; let shift: Bool? }
+}
+
+func out(_ json: String) {
+    FileHandle.standardOutput.write((json + "\n").data(using: .utf8)!)
+    fflush(stdout)
+}
+
+func btn(_ s: String?) -> CGMouseButton {
+    switch s { case "right": return .right; case "middle": return .center; default: return .left }
+}
+func downT(_ b: CGMouseButton) -> CGEventType {
+    switch b { case .right: return .rightMouseDown; case .center: return .otherMouseDown; default: return .leftMouseDown }
+}
+func upT(_ b: CGMouseButton) -> CGEventType {
+    switch b { case .right: return .rightMouseUp; case .center: return .otherMouseUp; default: return .leftMouseUp }
+}
+func dragT(_ b: CGMouseButton) -> CGEventType {
+    switch b { case .right: return .rightMouseDragged; case .center: return .otherMouseDragged; default: return .leftMouseDragged }
+}
+
+// MARK: - Event construction & posting
+
+/// Build a mouse CGEvent via the NSEvent bridge (raw CGEventCreateMouseEvent events are
+/// filtered by Chromium's renderer IPC). Returns nil on failure.
+func makeMouseEvent(_ type: CGEventType, at point: CGPoint, button: CGMouseButton,
+                    clickCount: Int = 1, windowNumber: Int = 0) -> CGEvent? {
+    let nsType: NSEvent.EventType
+    switch type {
+    case .leftMouseDown: nsType = .leftMouseDown
+    case .leftMouseUp: nsType = .leftMouseUp
+    case .rightMouseDown: nsType = .rightMouseDown
+    case .rightMouseUp: nsType = .rightMouseUp
+    case .otherMouseDown: nsType = .otherMouseDown
+    case .otherMouseUp: nsType = .otherMouseUp
+    case .leftMouseDragged: nsType = .leftMouseDragged
+    case .rightMouseDragged: nsType = .rightMouseDragged
+    case .otherMouseDragged: nsType = .otherMouseDragged
+    case .mouseMoved: nsType = .mouseMoved
+    default: return nil
+    }
+    guard let ns = NSEvent.mouseEvent(
+        with: nsType, location: point, modifierFlags: [],
+        timestamp: 0, windowNumber: windowNumber, context: nil,
+        eventNumber: 0, clickCount: clickCount, pressure: (type == .mouseMoved) ? 0 : 1.0
+    ), let cg = ns.cgEvent else { return nil }
+    return cg
+}
+
+/// Stamp a mouse event with the fields Chromium's synthetic-event filter requires,
+/// then post it to the target pid via SLEventPostToPid (no global cursor move).
+func postPerPid(_ event: CGEvent, pid: Int32, at point: CGPoint, windowNumber: Int, button: CGMouseButton = .left) {
+    event.location = point
+    // Stamp the correct button number (0=left, 1=right, 2=center) — NOT hardcoded 0.
+    event.setIntegerValueField(.mouseEventButtonNumber, value: Int64(button.rawValue))
+    event.setIntegerValueField(.mouseEventSubtype, value: 3)
+    if windowNumber > 0 {
+        event.setIntegerValueField(.mouseEventWindowUnderMousePointer, value: Int64(windowNumber))
+        event.setIntegerValueField(.mouseEventWindowUnderMousePointerThatCanHandleThisEvent, value: Int64(windowNumber))
+    }
+    // Private SPIs: window-local point + Chromium pid latch (field 40).
+    setWindowLoc?(event, point)
+    setIntField?(event, 40, Int64(pid))
+    event.timestamp = clock_gettime_nsec_np(CLOCK_UPTIME_RAW)
+    slPostToPid?(pid, event)
+}
+
+/// HID-tap fallback (moves the cursor). Used for frontmost/canvas apps where
+/// per-pid posting is filtered.
+func postHidTap(_ event: CGEvent) {
+    event.post(tap: CGEventTapLocation.cghidEventTap)
+}
+
+/// True if the target pid is the frontmost app (canvas/GPU apps filter per-pid
+/// routes — must use HID-tap there).
+func isFrontmost(_ pid: Int32) -> Bool {
+    return NSRunningApplication(processIdentifier: pid)?.isActive == true
+}
+
+// MARK: - Focus-without-raise (SLPSPostEventRecordTo)
+
+/// Flip the target's AppKit-active state without raising its window (no Space switch).
+func focusWithoutRaise(pid: Int32, windowID: Int) {
+    guard let postRec = postEventRec, let frontFn = getFrontPSN else { return }
+    // Resolve target PSN via window owner.
+    guard let connFn = mainConnID, let ownerFn = getWindowOwner, let psnFn = getConnPSN,
+          windowID > 0 else { return }
+    var prevPSN = [UInt32](repeating: 0, count: 2)
+    var targetPSN = [UInt32](repeating: 0, count: 2)
+    let prevOk = prevPSN.withUnsafeMutableBytes { raw in frontFn(raw.baseAddress!) != 0 }
+    if prevOk {
+        let cid = connFn()
+        var ownerCid: UInt32 = 0
+        guard ownerFn(cid, UInt32(windowID), &ownerCid) == 0 else { return }
+        guard psnFn(ownerCid, &targetPSN) == 0 else { return }
+    } else {
+        return
+    }
+    var buf = [UInt8](repeating: 0, count: 0xF8) // 248 bytes
+    buf[0x04] = 0xF8
+    buf[0x08] = 0x0D
+    let wid = UInt32(windowID)
+    buf[0x3C] = UInt8(wid & 0xFF); buf[0x3D] = UInt8((wid >> 8) & 0xFF)
+    buf[0x3E] = UInt8((wid >> 16) & 0xFF); buf[0x3F] = UInt8((wid >> 24) & 0xFF)
+    // Defocus previous front.
+    buf[0x8A] = 0x02
+    _ = prevPSN.withUnsafeBytes { psnRaw in buf.withUnsafeBufferPointer { bp in postRec(psnRaw.baseAddress!, bp.baseAddress!) } }
+    // Focus target.
+    buf[0x8A] = 0x01
+    _ = targetPSN.withUnsafeBytes { psnRaw in buf.withUnsafeBufferPointer { bp in postRec(psnRaw.baseAddress!, bp.baseAddress!) } }
+}
+
+// MARK: - AX keepalive (root-cause fix for Electron/Tauri AXPress silent failure)
+
+/// Keep the target app's AX tree alive when occluded/background.
+///
+/// Writes the AXManualAccessibility attribute (persists for the app's lifetime,
+/// independent of this helper process). AXEnhancedUserInterface is NOT set
+/// unconditionally — it's known to slow/break some apps (Xcode, Slack, Office);
+/// gate it behind the UCU_AX_ENHANCED env var if needed.
+///
+/// The observer-based remote-aware keepalive (_AXObserverAddNotificationAndCheckRemote)
+/// requires a long-lived process to hold the subscription; this helper is one-shot
+/// (readLine → exit), so the observer would be dropped on exit. We therefore rely on
+/// the persistent attribute writes, which cover non-Chromium occluded apps. Full
+/// Chromium keepalive would require a daemon helper (future work).
+func doKeepAlive(_ p: Input) -> String {
+    guard let pid = p.pid, pid > 0 else { return "{\"error\":\"no pid\"}" }
+    let app = AXUIElementCreateApplication(pid)
+    // AXManualAccessibility: safe, persistent, tells the app to expose its AX tree.
+    let manualStatus = AXUIElementSetAttributeValue(app, "AXManualAccessibility" as CFString, kCFBooleanTrue!)
+    // AXEnhancedUserInterface: opt-in only (breaks some apps when unconditional).
+    var enhancedStatus: AXError = .cannotComplete
+    if ProcessInfo.processInfo.environment["UCU_AX_ENHANCED"] != nil {
+        enhancedStatus = AXUIElementSetAttributeValue(app, "AXEnhancedUserInterface" as CFString, kCFBooleanTrue!)
+    }
+    let ok = (manualStatus == .success)
+    return "{\"ok\":\(ok),\"method\":\"ax-keepalive\",\"manual\":\(manualStatus == .success),\"enhanced\":\(enhancedStatus == .success)}"
+}
+
+// MARK: - Commands
+
+func doClick(_ p: Input) -> String {
+    guard let pid = p.pid, pid > 0 else { return "{\"error\":\"no pid\"}" }
+    let loc = CGPoint(x: p.x ?? 0, y: p.y ?? 0)
+    let b = btn(p.button)
+    let winNum = p.windowNumber ?? 0
+    // Canvas/frontmost apps filter per-pid routes → HID-tap fallback.
+    if !skylightMouseAvailable || isFrontmost(pid) {
+        guard let dn = CGEvent(mouseEventSource: nil, mouseType: downT(b), mouseCursorPosition: loc, mouseButton: b),
+              let up = CGEvent(mouseEventSource: nil, mouseType: upT(b), mouseCursorPosition: loc, mouseButton: b)
+        else { return "{\"error\":\"fail\"}" }
+        postHidTap(dn); postHidTap(up)
+        return "{\"ok\":true,\"method\":\"hid-tap\"}"
+    }
+    focusWithoutRaise(pid: pid, windowID: winNum)
+    // Leading mouseMoved at target (cursor-state primer).
+    if let mv = makeMouseEvent(.mouseMoved, at: loc, button: b, windowNumber: winNum) {
+        postPerPid(mv, pid: pid, at: loc, windowNumber: winNum, button: b); usleep(15_000)
+    }
+    // Off-screen primer click @ (-1,-1) — satisfies Chromium user-activation gate.
+    let off = CGPoint(x: -1, y: -1)
+    if let pd = makeMouseEvent(.leftMouseDown, at: off, button: .left, windowNumber: winNum),
+       let pu = makeMouseEvent(.leftMouseUp, at: off, button: .left, windowNumber: winNum) {
+        postPerPid(pd, pid: pid, at: off, windowNumber: winNum); usleep(1_000)
+        postPerPid(pu, pid: pid, at: off, windowNumber: winNum); usleep(100_000)
+    }
+    // Target click.
+    guard let dn = makeMouseEvent(downT(b), at: loc, button: b, windowNumber: winNum),
+          let up = makeMouseEvent(upT(b), at: loc, button: b, windowNumber: winNum)
+    else { return "{\"error\":\"fail\"}" }
+    postPerPid(dn, pid: pid, at: loc, windowNumber: winNum, button: b); usleep(1_000)
+    postPerPid(up, pid: pid, at: loc, windowNumber: winNum, button: b)
+    return "{\"ok\":true,\"method\":\"per-pid\"}"
+}
+
+func doDoubleClick(_ p: Input) -> String {
+    guard let pid = p.pid, pid > 0 else { return "{\"error\":\"no pid\"}" }
+    let loc = CGPoint(x: p.x ?? 0, y: p.y ?? 0)
+    let b = btn(p.button)
+    let winNum = p.windowNumber ?? 0
+    if !skylightMouseAvailable || isFrontmost(pid) {
+        return hidTapDouble(loc: loc, b: b)
+    }
+    focusWithoutRaise(pid: pid, windowID: winNum)
+    for state in [1, 2] {
+        guard let dn = makeMouseEvent(downT(b), at: loc, button: b, clickCount: state, windowNumber: winNum),
+              let up = makeMouseEvent(upT(b), at: loc, button: b, clickCount: state, windowNumber: winNum)
+        else { return "{\"error\":\"fail\"}" }
+        postPerPid(dn, pid: pid, at: loc, windowNumber: winNum, button: b); usleep(1_000)
+        postPerPid(up, pid: pid, at: loc, windowNumber: winNum, button: b)
+        if state == 1 { usleep(80_000) }
+    }
+    return "{\"ok\":true,\"method\":\"per-pid\"}"
+}
+
+func hidTapDouble(loc: CGPoint, b: CGMouseButton) -> String {
+    guard let d1 = CGEvent(mouseEventSource: nil, mouseType: downT(b), mouseCursorPosition: loc, mouseButton: b),
+          let u1 = CGEvent(mouseEventSource: nil, mouseType: upT(b), mouseCursorPosition: loc, mouseButton: b),
+          let d2 = CGEvent(mouseEventSource: nil, mouseType: downT(b), mouseCursorPosition: loc, mouseButton: b),
+          let u2 = CGEvent(mouseEventSource: nil, mouseType: upT(b), mouseCursorPosition: loc, mouseButton: b)
+    else { return "{\"error\":\"fail\"}" }
+    d1.setIntegerValueField(.mouseEventClickState, value: 1); u1.setIntegerValueField(.mouseEventClickState, value: 1)
+    d2.setIntegerValueField(.mouseEventClickState, value: 2); u2.setIntegerValueField(.mouseEventClickState, value: 2)
+    postHidTap(d1); postHidTap(u1); postHidTap(d2); postHidTap(u2)
+    return "{\"ok\":true,\"method\":\"hid-tap\"}"
+}
+
+func doMove(_ p: Input) -> String {
+    guard let pid = p.pid, pid > 0, skylightMouseAvailable, !isFrontmost(pid) else {
+        let loc = CGPoint(x: p.x ?? 0, y: p.y ?? 0)
+        guard let ev = CGEvent(mouseEventSource: nil, mouseType: .mouseMoved, mouseCursorPosition: loc, mouseButton: .left)
+        else { return "{\"error\":\"fail\"}" }
+        postHidTap(ev); return "{\"ok\":true,\"method\":\"hid-tap\"}"
+    }
+    let loc = CGPoint(x: p.x ?? 0, y: p.y ?? 0)
+    let winNum = p.windowNumber ?? 0
+    if let ev = makeMouseEvent(.mouseMoved, at: loc, button: .left, windowNumber: winNum) {
+        postPerPid(ev, pid: pid, at: loc, windowNumber: winNum, button: .left)
+        return "{\"ok\":true,\"method\":\"per-pid\"}"
+    }
+    return "{\"error\":\"fail\"}"
+}
+
+func doDrag(_ p: Input) -> String {
+    guard let pid = p.pid, pid > 0 else { return "{\"error\":\"no pid\"}" }
+    let from = CGPoint(x: p.fromX ?? 0, y: p.fromY ?? 0)
+    let to = CGPoint(x: p.toX ?? 0, y: p.toY ?? 0)
+    let ms = p.durationMs ?? 300; let b = btn(p.button)
+    let winNum = p.windowNumber ?? 0
+    let steps = max(2, min(60, Int(ceil(Double(ms) / 16.0))))
+    let delay = max(0, (ms * 1000) / steps)
+    if !skylightMouseAvailable || isFrontmost(pid) {
+        guard let dn = CGEvent(mouseEventSource: nil, mouseType: downT(b), mouseCursorPosition: from, mouseButton: b)
+        else { return "{\"error\":\"fail\"}" }
+        postHidTap(dn)
+        for n in 1...steps {
+            let t = Double(n) / Double(steps)
+            let pt = CGPoint(x: from.x + (to.x - from.x) * t, y: from.y + (to.y - from.y) * t)
+            if let ev = CGEvent(mouseEventSource: nil, mouseType: dragT(b), mouseCursorPosition: pt, mouseButton: b) { postHidTap(ev) }
+            if delay > 0 && n < steps { usleep(UInt32(delay)) }
+        }
+        if let up = CGEvent(mouseEventSource: nil, mouseType: upT(b), mouseCursorPosition: to, mouseButton: b) { postHidTap(up) }
+        return "{\"ok\":true,\"method\":\"hid-tap\"}"
+    }
+    focusWithoutRaise(pid: pid, windowID: winNum)
+    guard let dn = makeMouseEvent(downT(b), at: from, button: b, windowNumber: winNum)
+    else { return "{\"error\":\"fail\"}" }
+    postPerPid(dn, pid: pid, at: from, windowNumber: winNum, button: b)
+    for n in 1...steps {
+        let t = Double(n) / Double(steps)
+        let pt = CGPoint(x: from.x + (to.x - from.x) * t, y: from.y + (to.y - from.y) * t)
+        if let ev = makeMouseEvent(dragT(b), at: pt, button: b, windowNumber: winNum) {
+            postPerPid(ev, pid: pid, at: pt, windowNumber: winNum, button: b)
+        }
+        if delay > 0 && n < steps { usleep(UInt32(delay)) }
+    }
+    if let up = makeMouseEvent(upT(b), at: to, button: b, windowNumber: winNum) {
+        postPerPid(up, pid: pid, at: to, windowNumber: winNum, button: b)
+    }
+    return "{\"ok\":true,\"method\":\"per-pid\"}"
+}
+
+func doScroll(_ p: Input) -> String {
+    // Scroll events use CGEventCreateScrollWheelEvent; per-pid scroll posting is
+    // unreliable across app types, so we route via HID-tap but still report method.
+    let dy = Int32(-(p.deltaY ?? 0)); let dx = Int32(p.deltaX ?? 0)
+    guard let ev = CGEvent(scrollWheelEvent2Source: nil, units: .pixel, wheelCount: 2, wheel1: dy, wheel2: dx, wheel3: 0)
+    else { return "{\"error\":\"fail\"}" }
+    // Best-effort per-pid if we have a pid; scroll doesn't move the cursor noticeably anyway.
+    if let pid = p.pid, pid > 0, slPostToPid != nil, !isFrontmost(pid) {
+        slPostToPid?(pid, ev)
+        return "{\"ok\":true,\"method\":\"per-pid\"}"
+    }
+    postHidTap(ev)
+    return "{\"ok\":true,\"method\":\"hid-tap\"}"
+}
+
+func doPressKey(_ p: Input) -> String {
+    guard let pid = p.pid, pid > 0 else { return "{\"error\":\"no pid\"}" }
+    let code = UInt16(p.keyCode ?? 0); let flags = CGEventFlags(rawValue: UInt64(p.flags ?? 0))
+    guard let dn = CGEvent(keyboardEventSource: nil, virtualKey: code, keyDown: true),
+          let up = CGEvent(keyboardEventSource: nil, virtualKey: code, keyDown: false)
+    else { return "{\"error\":\"fail\"}" }
+    dn.flags = flags; up.flags = flags
+    // Keyboard: public CGEventPostToPid is sufficient (no SkyLight needed).
+    dn.postToPid(pid); up.postToPid(pid)
+    return "{\"ok\":true,\"method\":\"per-pid\"}"
+}
+
+func doTypeBatch(_ p: Input) -> String {
+    guard let pid = p.pid, pid > 0 else { return "{\"error\":\"no pid\"}" }
+    guard let keys = p.keys else { return "{\"error\":\"missing keys\"}" }
+    let SHIFT = CGEventFlags(rawValue: 0x00020000)
+    for entry in keys {
+        let code = UInt16(entry.code); let flags: CGEventFlags = (entry.shift ?? false) ? SHIFT : []
+        guard let dn = CGEvent(keyboardEventSource: nil, virtualKey: code, keyDown: true),
+              let up = CGEvent(keyboardEventSource: nil, virtualKey: code, keyDown: false) else { continue }
+        dn.flags = flags; up.flags = flags
+        dn.postToPid(pid); up.postToPid(pid)
+    }
+    return "{\"ok\":true,\"method\":\"per-pid\"}"
+}
+
+// MARK: - Dispatch
+
+guard let line = readLine(), let data = line.data(using: .utf8),
+      let input = try? JSONDecoder().decode(Input.self, from: data)
+else { out("{\"error\":\"invalid JSON\"}"); exit(1) }
+
+switch input.command {
+case "click": out(doClick(input))
+case "doubleClick": out(doDoubleClick(input))
+case "move": out(doMove(input))
+case "drag": out(doDrag(input))
+case "scroll": out(doScroll(input))
+case "pressKey": out(doPressKey(input))
+case "typeBatch": out(doTypeBatch(input))
+case "keepAlive": out(doKeepAlive(input))
+case "ping": out(skylightMouseAvailable ? "{\"ok\":true,\"skylight\":true}" : "{\"ok\":true,\"skylight\":false}")
+default: out("{\"error\":\"unknown\"}")
+}