agentix-cli 0.26.0 → 0.28.0

package/apps/mac-helper/Sources/AgentXHelper/Typer.swift

@@ -0,0 +1,185 @@
+import AppKit
+
+/// Synthetic typing and key presses.
+///
+/// This is the first verb here that CHANGES something rather than pointing
+/// at it, so it is worth being explicit about what that means: these
+/// events are indistinguishable from the keyboard to every application,
+/// they go wherever focus happens to be, and nothing downstream can tell
+/// them from a person. There is no undo.
+///
+/// Two consequences are built in rather than left to callers. Typing is
+/// paced like a hand, so a field with its own debouncing or autocomplete
+/// behaves the way it would for a person instead of receiving a paste-like
+/// burst it never sees in production. And `submit` is a separate verb from
+/// `type`, so committing a form is always its own deliberate call — never
+/// a trailing newline that slipped into some text.
+enum Typer {
+
+    /// Type text at human cadence.
+    ///
+    /// CGEventKeyboardSetUnicodeString rather than keycodes: keycodes are
+    /// layout-dependent, so the same call produces different characters on
+    /// an AZERTY machine, and this host is French.
+    static func type(_ text: String, wpm: Double = 260) {
+        // A character every ~46ms at 260wpm — brisk but visibly typed, so
+        // someone watching a lesson can read along.
+        let base = 60.0 / (wpm * 5.0)
+        let source = CGEventSource(stateID: .combinedSessionState)
+
+        for ch in text {
+            guard let down = CGEvent(keyboardEventSource: source, virtualKey: 0, keyDown: true),
+                  let up = CGEvent(keyboardEventSource: source, virtualKey: 0, keyDown: false)
+            else { continue }
+            var utf16 = Array(String(ch).utf16)
+            down.keyboardSetUnicodeString(stringLength: utf16.count, unicodeString: &utf16)
+            up.keyboardSetUnicodeString(stringLength: utf16.count, unicodeString: &utf16)
+            down.post(tap: .cghidEventTap)
+            up.post(tap: .cghidEventTap)
+
+            // Jitter, and a longer pause after a space — real typing is
+            // bursty at word boundaries, and a metronome is the tell.
+            var delay = base * Double.random(in: 0.65...1.45)
+            if ch == " " { delay += base * 0.9 }
+            Thread.sleep(forTimeInterval: delay)
+        }
+    }
+
+    /// Named keys, for the things typing cannot express.
+    private static let keyCodes: [String: CGKeyCode] = [
+        "return": 36, "enter": 36, "tab": 48, "space": 49,
+        "delete": 51, "escape": 53, "esc": 53,
+        "left": 123, "right": 124, "down": 125, "up": 126,
+    ]
+
+    static func press(_ name: String) -> Bool {
+        guard let code = keyCodes[name.lowercased()] else { return false }
+        let source = CGEventSource(stateID: .combinedSessionState)
+        CGEvent(keyboardEventSource: source, virtualKey: code, keyDown: true)?.post(tap: .cghidEventTap)
+        Thread.sleep(forTimeInterval: 0.035)
+        CGEvent(keyboardEventSource: source, virtualKey: code, keyDown: false)?.post(tap: .cghidEventTap)
+        return true
+    }
+
+    /// Modifier names accepted by `key` and the click verbs.
+    static let modifierFlags: [String: CGEventFlags] = [
+        "cmd": .maskCommand, "command": .maskCommand,
+        "shift": .maskShift,
+        "opt": .maskAlternate, "option": .maskAlternate, "alt": .maskAlternate,
+        "ctrl": .maskControl, "control": .maskControl,
+        "fn": .maskSecondaryFn,
+    ]
+
+    static func flags(from names: [String]) -> CGEventFlags {
+        var f = CGEventFlags()
+        for n in names { if let m = modifierFlags[n.lowercased()] { f.insert(m) } }
+        return f
+    }
+
+    /// Press a named key with optional modifiers, e.g. cmd+a.
+    static func press(_ name: String, modifiers: [String] = []) -> Bool {
+        guard let code = keyCodes[name.lowercased()] ?? letterCode(name) else { return false }
+        let source = CGEventSource(stateID: .combinedSessionState)
+        let mods = flags(from: modifiers)
+        let down = CGEvent(keyboardEventSource: source, virtualKey: code, keyDown: true)
+        let up = CGEvent(keyboardEventSource: source, virtualKey: code, keyDown: false)
+        down?.flags = mods
+        up?.flags = mods
+        down?.post(tap: .cghidEventTap)
+        Thread.sleep(forTimeInterval: 0.035)
+        up?.post(tap: .cghidEventTap)
+        return true
+    }
+
+    /// Single letters and digits, so `key --name a --mod cmd` works.
+    private static func letterCode(_ name: String) -> CGKeyCode? {
+        let map: [Character: CGKeyCode] = [
+            "a": 0, "s": 1, "d": 2, "f": 3, "h": 4, "g": 5, "z": 6, "x": 7, "c": 8, "v": 9,
+            "b": 11, "q": 12, "w": 13, "e": 14, "r": 15, "y": 16, "t": 17,
+            "1": 18, "2": 19, "3": 20, "4": 21, "6": 22, "5": 23, "9": 25, "7": 26, "8": 28, "0": 29,
+            "o": 31, "u": 32, "i": 34, "p": 35, "l": 37, "j": 38, "k": 40, "n": 45, "m": 46,
+        ]
+        guard name.count == 1, let ch = name.lowercased().first else { return nil }
+        return map[ch]
+    }
+
+    // MARK: Mouse
+
+    /// Click where the cursor already is.
+    ///
+    /// Separate from `point` on purpose: point is safe to run against
+    /// anything, and keeping the click a distinct call means nothing
+    /// clicks merely because it was located.
+    static func click(button: String = "left", clicks: Int = 1, modifiers: [String] = []) {
+        let p = CGEvent(source: nil)?.location ?? .zero
+        let source = CGEventSource(stateID: .combinedSessionState)
+        let right = button.lowercased() == "right"
+        let downType: CGEventType = right ? .rightMouseDown : .leftMouseDown
+        let upType: CGEventType = right ? .rightMouseUp : .leftMouseUp
+        let mouseButton: CGMouseButton = right ? .right : .left
+        let mods = flags(from: modifiers)
+
+        for i in 1...max(1, clicks) {
+            let down = CGEvent(mouseEventSource: source, mouseType: downType,
+                               mouseCursorPosition: p, mouseButton: mouseButton)
+            let up = CGEvent(mouseEventSource: source, mouseType: upType,
+                             mouseCursorPosition: p, mouseButton: mouseButton)
+            // clickState is what makes the OS read two clicks as a
+            // double-click rather than two separate ones.
+            down?.setIntegerValueField(.mouseEventClickState, value: Int64(i))
+            up?.setIntegerValueField(.mouseEventClickState, value: Int64(i))
+            down?.flags = mods
+            up?.flags = mods
+            down?.post(tap: .cghidEventTap)
+            Thread.sleep(forTimeInterval: Double.random(in: 0.05...0.09))
+            up?.post(tap: .cghidEventTap)
+            // Inside the system double-click interval, or the second click
+            // starts a new sequence.
+            if i < clicks { Thread.sleep(forTimeInterval: 0.08) }
+        }
+    }
+
+    /// Scroll by wheel units at the cursor. Negative dy scrolls down.
+    static func scroll(dx: Int32 = 0, dy: Int32 = 0, steps: Int = 10) {
+        let source = CGEventSource(stateID: .combinedSessionState)
+        // Broken into steps with easing: one large wheel event jumps, and
+        // momentum-scrolling views ignore it entirely.
+        let n = max(1, steps)
+        for i in 1...n {
+            let t = Double(i) / Double(n)
+            let ease = 1 - pow(1 - t, 2)
+            let prev = Double(i - 1) / Double(n)
+            let prevEase = 1 - pow(1 - prev, 2)
+            let stepY = Int32((Double(dy) * (ease - prevEase)).rounded())
+            let stepX = Int32((Double(dx) * (ease - prevEase)).rounded())
+            if stepX == 0 && stepY == 0 { continue }
+            CGEvent(scrollWheelEvent2Source: source, units: .pixel,
+                    wheelCount: 2, wheel1: stepY, wheel2: stepX, wheel3: 0)?
+                .post(tap: .cghidEventTap)
+            Thread.sleep(forTimeInterval: 0.016)
+        }
+    }
+
+    /// Press at the current point, move, release. Used for sliders,
+    /// reordering and selection.
+    static func drag(to target: CGPoint, durationSeconds: Double = 0.6) {
+        let from = CGEvent(source: nil)?.location ?? target
+        let source = CGEventSource(stateID: .combinedSessionState)
+        CGEvent(mouseEventSource: source, mouseType: .leftMouseDown,
+                mouseCursorPosition: from, mouseButton: .left)?.post(tap: .cghidEventTap)
+        Thread.sleep(forTimeInterval: 0.06)
+
+        let steps = max(12, Int(durationSeconds * 90))
+        for i in 1...steps {
+            let t = Double(i) / Double(steps)
+            let e = 10 * pow(t, 3) - 15 * pow(t, 4) + 6 * pow(t, 5)
+            let p = CGPoint(x: from.x + (target.x - from.x) * e,
+                            y: from.y + (target.y - from.y) * e)
+            CGEvent(mouseEventSource: source, mouseType: .leftMouseDragged,
+                    mouseCursorPosition: p, mouseButton: .left)?.post(tap: .cghidEventTap)
+            Thread.sleep(forTimeInterval: durationSeconds / Double(steps))
+        }
+        CGEvent(mouseEventSource: source, mouseType: .leftMouseUp,
+                mouseCursorPosition: target, mouseButton: .left)?.post(tap: .cghidEventTap)
+    }
+}

package/apps/mac-helper/Sources/AgentXHelper/Vision.swift

@@ -0,0 +1,201 @@
+import AppKit
+import ApplicationServices
+
+/// Eyes. Two of them, because "can I see it" and "did it work" are
+/// different questions with different right answers.
+///
+/// Everything else in this helper reads the accessibility tree, which
+/// reports what EXISTS and where, and says nothing about what is VISIBLE.
+/// Z-order, overlays, opacity, a modal on top, something scrolled out of
+/// view — all invisible to it. An element can be reported at (218, 145)
+/// with perfect confidence while something else sits on top of it.
+///
+/// That is not hypothetical. This tool's own HUD covered the search field
+/// it was pointing at, and nothing in the pipeline could tell. The
+/// obstruction was self-inflicted and still undetectable.
+///
+/// So:
+///
+///   hitTest  — is the thing I mean actually on top at that point?
+///              Uses the accessibility hit test, which is exact and costs
+///              no pixels. This is the check that catches occlusion.
+///
+///   capture  — what does this region look like right now? Used in pairs,
+///              before and after, to answer "did anything change" — which
+///              is the only honest way to claim an action landed.
+enum Vision {
+
+    // MARK: Occlusion
+
+    struct HitResult: Codable {
+        /// Role of whatever is topmost at the point.
+        let role: String
+        let label: String
+        /// The frontmost app owning it — a different app here usually means
+        /// a floating panel is in the way.
+        let app: String
+        /// True when the topmost element's frame matches the one asked
+        /// about, within a tolerance.
+        let matchesExpected: Bool?
+    }
+
+    /// What is actually on top at a screen point.
+    ///
+    /// AXUIElementCopyElementAtPosition resolves through the window server,
+    /// so it sees exactly what a click would hit — including overlays this
+    /// process put there itself.
+    static func hitTest(x: Double, y: Double, expect: CGRect? = nil) -> HitResult? {
+        let system = AXUIElementCreateSystemWide()
+        var ref: AXUIElement?
+        guard AXUIElementCopyElementAtPosition(system, Float(x), Float(y), &ref) == .success,
+              let element = ref
+        else { return nil }
+
+        let role = attr(element, kAXRoleAttribute) ?? ""
+        let label = [kAXTitleAttribute, kAXDescriptionAttribute, kAXValueAttribute]
+            .compactMap { attr(element, $0) }
+            .first(where: { !$0.isEmpty }) ?? ""
+
+        var owner = "unknown"
+        var pid: pid_t = 0
+        if AXUIElementGetPid(element, &pid) == .success,
+           let app = NSRunningApplication(processIdentifier: pid) {
+            owner = app.localizedName ?? "unknown"
+        }
+
+        var matches: Bool?
+        if let expect {
+            // Compare frames rather than identity: AXUIElement references
+            // are not stable across calls, so two handles to the same
+            // control are not equal even when they should be.
+            if let f = frame(element) {
+                let dx = abs(f.midX - expect.midX), dy = abs(f.midY - expect.midY)
+                // Generous, because a hit inside the intended control is a
+                // hit even if the tree reports a child of it.
+                matches = dx <= max(expect.width, 24) && dy <= max(expect.height, 24)
+            } else {
+                matches = false
+            }
+        }
+        return HitResult(role: role, label: label, app: owner, matchesExpected: matches)
+    }
+
+    // MARK: Capture
+
+    /// Grab a screen region to a PNG.
+    ///
+    /// CGWindowListCreateImage rather than ScreenCaptureKit: this is a
+    /// one-shot CLI, and SCK's async setup costs more than the capture. It
+    /// needs Screen Recording permission; without it macOS returns a
+    /// desktop-only image rather than failing, which is why the caller is
+    /// told to check for an all-uniform result.
+    ///
+    /// `maxPixels` caps the TOTAL area before writing, and `maxWidth` the
+    /// long edge. Prefer the area budget.
+    ///
+    /// Cost tracks pixel count, not width, and capping width alone throws
+    /// away detail on small regions while saving nothing. A menu bar strip
+    /// is 2880x52 on this display — 150k pixels, a couple of hundred
+    /// tokens — and scaling it to 1400 wide halves the resolution of the
+    /// only thing in it worth seeing. A full screen is 5.2M pixels and
+    /// genuinely does need cutting. One rule covers both: leave it alone
+    /// unless it is actually big.
+    ///
+    /// Resolution here is not a cost knob, it is the difference between a
+    /// legible indicator and a grey smudge. macOS draws the screen-
+    /// recording dot at about six points.
+    @discardableResult
+    static func capture(_ rect: CGRect, to path: String,
+                        maxWidth: Int? = nil, maxPixels: Int? = nil) -> Bool {
+        guard let image = CGWindowListCreateImage(
+            rect, .optionOnScreenOnly, kCGNullWindowID, [.bestResolution])
+        else { return false }
+        var target = maxWidth
+        if let budget = maxPixels, budget > 0 {
+            let area = image.width * image.height
+            if area > budget {
+                // Preserve aspect: width * (width / aspect) = budget.
+                let scale = (Double(budget) / Double(area)).squareRoot()
+                let fit = max(1, Int(Double(image.width) * scale))
+                target = min(target ?? fit, fit)
+            }
+        }
+        let out = target.flatMap { downscale(image, maxWidth: $0) } ?? image
+        let rep = NSBitmapImageRep(cgImage: out)
+        guard let png = rep.representation(using: .png, properties: [:]) else { return false }
+        return (try? png.write(to: URL(fileURLWithPath: path))) != nil
+    }
+
+    /// Returns nil when the image is already narrow enough, so the caller
+    /// falls back to the original rather than paying for a pointless redraw.
+    private static func downscale(_ image: CGImage, maxWidth: Int) -> CGImage? {
+        guard maxWidth > 0, image.width > maxWidth else { return nil }
+        let height = max(1, Int(Double(image.height) * Double(maxWidth) / Double(image.width)))
+        guard let ctx = CGContext(
+            data: nil, width: maxWidth, height: height,
+            bitsPerComponent: 8, bytesPerRow: 0,
+            space: CGColorSpaceCreateDeviceRGB(),
+            bitmapInfo: CGImageAlphaInfo.noneSkipLast.rawValue)
+        else { return nil }
+        // High, not low: this image exists to be READ. Cheap interpolation
+        // turns small text into grey mush and the model then reports an
+        // empty menu bar with complete confidence.
+        ctx.interpolationQuality = .high
+        ctx.draw(image, in: CGRect(x: 0, y: 0, width: maxWidth, height: height))
+        return ctx.makeImage()
+    }
+
+    /// Mean absolute difference between two regions, 0…1.
+    ///
+    /// Downsamples hard before comparing: the question is "did this change
+    /// meaningfully", not "is a single antialiased pixel different", and a
+    /// small grid also makes the comparison immune to a one-pixel shift.
+    static func difference(_ a: CGRect, _ b: CGImage?) -> Double? {
+        guard let now = CGWindowListCreateImage(a, .optionOnScreenOnly, kCGNullWindowID, [.bestResolution]),
+              let before = b
+        else { return nil }
+        guard let g1 = grid(before), let g2 = grid(now), g1.count == g2.count, !g1.isEmpty
+        else { return nil }
+        var total = 0.0
+        for i in 0..<g1.count { total += abs(Double(g1[i]) - Double(g2[i])) / 255.0 }
+        return total / Double(g1.count)
+    }
+
+    static func snapshot(_ rect: CGRect) -> CGImage? {
+        CGWindowListCreateImage(rect, .optionOnScreenOnly, kCGNullWindowID, [.bestResolution])
+    }
+
+    /// 16×16 greyscale, which is plenty to notice a page changing and
+    /// cheap enough to run between every action.
+    private static func grid(_ image: CGImage, side: Int = 16) -> [UInt8]? {
+        let space = CGColorSpaceCreateDeviceGray()
+        var pixels = [UInt8](repeating: 0, count: side * side)
+        guard let ctx = CGContext(data: &pixels, width: side, height: side,
+                                  bitsPerComponent: 8, bytesPerRow: side,
+                                  space: space, bitmapInfo: 0)
+        else { return nil }
+        ctx.interpolationQuality = .low
+        ctx.draw(image, in: CGRect(x: 0, y: 0, width: side, height: side))
+        return pixels
+    }
+
+    // MARK: Helpers
+
+    private static func attr(_ node: AXUIElement, _ name: String) -> String? {
+        var ref: CFTypeRef?
+        guard AXUIElementCopyAttributeValue(node, name as CFString, &ref) == .success else { return nil }
+        if let s = ref as? String { return s.trimmingCharacters(in: .whitespacesAndNewlines) }
+        return nil
+    }
+
+    private static func frame(_ node: AXUIElement) -> CGRect? {
+        var posRef: CFTypeRef?, sizeRef: CFTypeRef?
+        guard AXUIElementCopyAttributeValue(node, kAXPositionAttribute as CFString, &posRef) == .success,
+              AXUIElementCopyAttributeValue(node, kAXSizeAttribute as CFString, &sizeRef) == .success
+        else { return nil }
+        var p = CGPoint.zero, s = CGSize.zero
+        AXValueGetValue(posRef as! AXValue, .cgPoint, &p)
+        AXValueGetValue(sizeRef as! AXValue, .cgSize, &s)
+        return CGRect(origin: p, size: s)
+    }
+}

package/apps/mac-helper/Sources/AgentXHelper/main.swift

@@ -0,0 +1,265 @@
+import AppKit
+
+// agentx-mac-helper — the native half of computer use.
+//
+// Swift owns only what Node cannot reach: the Accessibility API and the
+// window server. Everything else — which element to choose, whether the
+// operation is allowed, what to do next — stays in agentx, so the
+// capability belongs to every agent rather than to one app.
+//
+// Two verbs in this cut, and deliberately no third:
+//
+//   read   dump the focused window's accessibility tree as JSON
+//   point  move the cursor to an element and highlight it
+//
+// There is no `click`. The point tier makes a model's choice visible and
+// reviewable before anything irreversible happens, which is worth having
+// on its own and is the only tier that is safe while the guard is still
+// soaking.
+
+func fail(_ message: String, code: Int32 = 1) -> Never {
+    let payload = ["ok": false, "error": message] as [String: Any]
+    if let d = try? JSONSerialization.data(withJSONObject: payload) {
+        FileHandle.standardOutput.write(d)
+    }
+    exit(code)
+}
+
+let args = Array(CommandLine.arguments.dropFirst())
+guard let verb = args.first else {
+    fail("usage: agentx-mac-helper read | point --x N --y N --w N --h N [--label TEXT] [--hold SECONDS] [--instant] | trusted")
+}
+
+func flag(_ name: String) -> String? {
+    guard let i = args.firstIndex(of: "--\(name)"), i + 1 < args.count else { return nil }
+    return args[i + 1]
+}
+
+switch verb {
+case "read":
+    guard AXTree.trusted() else {
+        fail("accessibility permission not granted — System Settings › Privacy & Security › Accessibility, then add this binary")
+    }
+    let snap = AXTree.snapshot(maxElements: Int(flag("max") ?? "400") ?? 400)
+    let encoder = JSONEncoder()
+    encoder.outputFormatting = [.withoutEscapingSlashes]
+    guard let data = try? encoder.encode(snap) else { fail("failed to encode tree") }
+    FileHandle.standardOutput.write(data)
+
+case "point":
+    guard let x = Double(flag("x") ?? ""), let y = Double(flag("y") ?? ""),
+          let w = Double(flag("w") ?? ""), let h = Double(flag("h") ?? "") else {
+        fail("point needs --x --y --w --h")
+    }
+    Pointer.point(x: x, y: y, width: w, height: h,
+                  label: flag("label") ?? "",
+                  // Hold long enough to be seen, short enough not to be an
+                  // obstruction. 0 is useful for scripted sequences where
+                  // the next point follows immediately.
+                  holdSeconds: Double(flag("hold") ?? "") ?? 2.5,
+                  // Skip the human-speed move when something is stepping
+                  // through many targets and the motion would just be slow.
+                  instant: args.contains("--instant"))
+    FileHandle.standardOutput.write(#"{"ok":true,"pointed":true}"#.data(using: .utf8)!)
+
+case "hittest":
+    // What is actually on top at this point. The occlusion check.
+    guard let x = Double(flag("x") ?? ""), let y = Double(flag("y") ?? "") else {
+        fail("hittest needs --x --y")
+    }
+    var expect: CGRect?
+    if let ex = Double(flag("ex") ?? ""), let ey = Double(flag("ey") ?? ""),
+       let ew = Double(flag("ew") ?? ""), let eh = Double(flag("eh") ?? "") {
+        expect = CGRect(x: ex, y: ey, width: ew, height: eh)
+    }
+    guard let hit = Vision.hitTest(x: x, y: y, expect: expect) else {
+        fail("nothing at (\(Int(x)), \(Int(y)))")
+    }
+    guard let hd = try? JSONEncoder().encode(hit) else { fail("failed to encode hit") }
+    FileHandle.standardOutput.write(hd)
+
+case "ocr":
+    // Reads the focused window unless a rect is given. Coordinates come
+    // back in the SAME convention as `read`, so a caller can point at an
+    // OCR hit without converting anything.
+    let region: CGRect
+    if let x = Double(flag("x") ?? ""), let y = Double(flag("y") ?? ""),
+       let w = Double(flag("w") ?? ""), let h = Double(flag("h") ?? "") {
+        region = CGRect(x: x, y: y, width: w, height: h)
+    } else if let win = OCR.focusedWindowFrame() {
+        region = win
+    } else {
+        fail("no focused window and no --x/--y/--w/--h given")
+    }
+    let langs = (flag("lang") ?? "fr-FR,en-US").split(separator: ",").map(String.init)
+    let hits = OCR.read(rect: region, languages: langs)
+    let payload: [String: Any] = [
+        "ok": true,
+        "region": ["x": region.minX, "y": region.minY, "w": region.width, "h": region.height],
+        "count": hits.count,
+        "hits": hits.map { ["text": $0.text, "x": $0.x, "y": $0.y,
+                            "width": $0.width, "height": $0.height,
+                            "confidence": $0.confidence] },
+    ]
+    FileHandle.standardOutput.write(
+        (try? JSONSerialization.data(withJSONObject: payload)) ?? Data())
+
+case "capture":
+    // Region precedence: an explicit rect, else a named region of a
+    // screen, else the focused window. "Whole screen" has to be reachable
+    // without the caller knowing the display's size, because the state
+    // worth checking — a recording indicator, a capture pill — lives in
+    // the menu bar, which belongs to no window at all.
+    guard let out = flag("out") else { fail("capture needs --out") }
+    let screen = Screens.list().first(where: { $0.index == Int(flag("screen") ?? "") })
+        ?? Screens.active()
+    let region: CGRect
+    if let x = Double(flag("x") ?? ""), let y = Double(flag("y") ?? ""),
+       let w = Double(flag("w") ?? ""), let h = Double(flag("h") ?? "") {
+        region = CGRect(x: x, y: y, width: w, height: h)
+    } else if args.contains("--menubar") {
+        guard let s = screen else { fail("no screen found") }
+        region = Screens.menuBar(s)
+    } else if args.contains("--screen-full") {
+        guard let s = screen else { fail("no screen found") }
+        region = Screens.rect(s)
+    } else if let win = OCR.focusedWindowFrame() {
+        region = win
+    } else {
+        fail("no focused window — pass --x/--y/--w/--h, --menubar or --screen-full")
+    }
+    guard Vision.capture(region, to: out,
+                         maxWidth: Int(flag("max-width") ?? ""),
+                         maxPixels: Int(flag("max-pixels") ?? "")) else {
+        fail("capture failed — check Screen Recording permission")
+    }
+    let shot: [String: Any] = [
+        "ok": true, "captured": true, "path": out,
+        "region": ["x": region.minX, "y": region.minY,
+                   "w": region.width, "h": region.height],
+    ]
+    FileHandle.standardOutput.write(
+        (try? JSONSerialization.data(withJSONObject: shot)) ?? Data())
+
+case "screens":
+    // Display geometry in top-left coordinates, so a caller can aim at a
+    // second monitor without redoing AppKit's origin flip.
+    guard let d = try? JSONEncoder().encode(Screens.list()) else { fail("failed to encode screens") }
+    FileHandle.standardOutput.write(d)
+
+case "focused":
+    // What has keyboard focus right now. The safety check before typing.
+    guard let f = Focus.current() else { fail("nothing focused") }
+    let enc = JSONEncoder()
+    guard let d = try? enc.encode(f) else { fail("failed to encode focus") }
+    FileHandle.standardOutput.write(d)
+
+case "type":
+    // Typing goes wherever focus is, and cannot tell a search box from a
+    // post composer. Refuses by default when focus looks publishable —
+    // this exists because a lesson once got one keystroke from posting a
+    // search query to a public timeline.
+    guard let text = flag("text") else { fail("type needs --text") }
+    if !args.contains("--force") {
+        guard let f = Focus.current() else {
+            fail("refusing to type: nothing has keyboard focus")
+        }
+        if !f.editable {
+            fail("refusing to type: focus is \(f.role) \"\(f.label)\", which does not accept text")
+        }
+        if f.publishRisk {
+            fail("refusing to type: focus looks like a compose or send field (\(f.role) \"\(f.label)\") — pass --force only if publishing is intended")
+        }
+    }
+    Typer.type(text, wpm: Double(flag("wpm") ?? "") ?? 260)
+    FileHandle.standardOutput.write(#"{"ok":true,"typed":true}"#.data(using: .utf8)!)
+
+case "key":
+    guard let name = flag("name") else { fail("key needs --name (return, tab, escape, a…z, 0…9)") }
+    // Return is the commit key. Pressing it into a composer publishes.
+    if !args.contains("--force"), ["return", "enter"].contains(name.lowercased()),
+       let f = Focus.current(), f.publishRisk {
+        fail("refusing to press \(name): focus looks like a compose or send field (\(f.role) \"\(f.label)\")")
+    }
+    let mods = (flag("mod") ?? "").split(separator: "+").map(String.init)
+    guard Typer.press(name, modifiers: mods) else { fail("unknown key \"\(name)\"") }
+    FileHandle.standardOutput.write(#"{"ok":true,"pressed":true}"#.data(using: .utf8)!)
+
+case "click":
+    // Clicks where the cursor already is, so a caller must point first.
+    // Deliberately not folded into `point`: locating something should
+    // never be the same act as pressing it.
+    //
+    // Before pressing, LOOK. The accessibility tree reports what exists,
+    // not what is visible, so a control can be reported exactly where an
+    // overlay is covering it — this tool's own HUD did precisely that.
+    // The hit test resolves through the window server and sees what a
+    // click would really land on.
+    if !args.contains("--force"), let p = CGEvent(source: nil)?.location {
+        if let hit = Vision.hitTest(x: p.x, y: p.y),
+           let expected = flag("expect"), !expected.isEmpty {
+            let seen = "\(hit.role) \(hit.label)".lowercased()
+            if !seen.contains(expected.lowercased()) {
+                fail("refusing to click: \(hit.app) shows \(hit.role) \"\(hit.label)\" at the cursor, not \"\(expected)\" — something is covering it")
+            }
+        }
+    }
+    // Visual first: a press people can see leads the reaction slightly,
+    // the way a real one does.
+    if !args.contains("--quiet") { Pointer.clickFlourish() }
+
+    // Snapshot a patch around the cursor so the caller can be told whether
+    // anything actually happened, rather than inferring it from a
+    // successful call.
+    var beforeShot: CGImage?
+    var patch = CGRect.zero
+    if let p = CGEvent(source: nil)?.location {
+        patch = CGRect(x: p.x - 90, y: p.y - 60, width: 180, height: 120)
+        beforeShot = Vision.snapshot(patch)
+    }
+
+    Typer.click(button: flag("button") ?? "left",
+                clicks: Int(flag("clicks") ?? "1") ?? 1,
+                modifiers: (flag("mod") ?? "").split(separator: "+").map(String.init))
+
+    // A UI needs a frame or two to react.
+    Thread.sleep(forTimeInterval: Double(flag("settle") ?? "") ?? 0.45)
+    var changed: Bool?
+    if beforeShot != nil, let diff = Vision.difference(patch, beforeShot) {
+        // 1.5% mean absolute difference over a 16x16 grid: enough to catch
+        // a button state or a menu opening, high enough to ignore a
+        // blinking caret.
+        changed = diff > 0.015
+    }
+    let payload: [String: Any] = [
+        "ok": true, "clicked": true,
+        "changed": changed as Any,
+    ]
+    FileHandle.standardOutput.write(
+        (try? JSONSerialization.data(withJSONObject: payload)) ?? Data())
+
+case "scroll":
+    Typer.scroll(dx: Int32(flag("dx") ?? "0") ?? 0,
+                 dy: Int32(flag("dy") ?? "0") ?? 0,
+                 steps: Int(flag("steps") ?? "10") ?? 10)
+    FileHandle.standardOutput.write(#"{"ok":true,"scrolled":true}"#.data(using: .utf8)!)
+
+case "drag":
+    guard let tx = Double(flag("to-x") ?? ""), let ty = Double(flag("to-y") ?? "") else {
+        fail("drag needs --to-x --to-y (press starts wherever the cursor is)")
+    }
+    Typer.drag(to: CGPoint(x: tx, y: ty),
+               durationSeconds: Double(flag("duration") ?? "") ?? 0.6)
+    FileHandle.standardOutput.write(#"{"ok":true,"dragged":true}"#.data(using: .utf8)!)
+
+case "hud":
+    // Long-lived: reads update lines on stdin until EOF.
+    HUD.run()
+
+case "trusted":
+    let payload = ["ok": true, "trusted": AXTree.trusted()] as [String: Any]
+    FileHandle.standardOutput.write(try! JSONSerialization.data(withJSONObject: payload))
+
+default:
+    fail("unknown verb \"\(verb)\" — expected read, screens, point, click, type, key, scroll, drag, ocr, capture, hittest, focused, hud or trusted")
+}