agentix-cli 0.26.0 → 0.28.0

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

@@ -0,0 +1,179 @@
+import AppKit
+
+/// A callout that stays on screen and updates while the agent talks.
+///
+/// The pointer's label vanishes with its highlight, which is fine for
+/// "here is the button" and useless for "here is what we are doing and
+/// why". A lesson needs somewhere the current instruction persists —
+/// something you can glance back at after listening, and that still says
+/// what is happening when the speech has moved on.
+///
+/// Driven over stdin rather than as one-shot calls, because the point is
+/// that it UPDATES: a fresh window per step would flash, lose its
+/// position, and steal focus. One window, many lines, closed on EOF.
+///
+///   {"title":"Step 2 of 9","body":"Type from:naval","state":"typing",
+///    "avoid":{"x":218,"y":145,"w":420,"h":40}}
+///
+/// `avoid` is the rectangle the lesson is about to point at. The callout
+/// moves out of its way.
+///
+/// This is not the same problem as click occlusion, and a hit test does
+/// not catch it: the panel sets ignoresMouseEvents, so a click passes
+/// straight through and the window server correctly reports whatever is
+/// underneath. It is invisible to a click and very visible to a person —
+/// which is exactly how this window ended up sitting on top of the search
+/// field a lesson was pointing at, with nothing able to notice.
+///
+/// Anything unparseable is ignored rather than fatal — a malformed line
+/// from a caller should not take down the display mid-lesson.
+enum HUD {
+
+    private final class Window: NSPanel {
+        let titleField = NSTextField(labelWithString: "")
+        let bodyField = NSTextField(wrappingLabelWithString: "")
+        let dot = NSView()
+
+        init() {
+            super.init(contentRect: NSRect(x: 0, y: 0, width: 460, height: 96),
+                       styleMask: [.borderless, .nonactivatingPanel],
+                       backing: .buffered, defer: false)
+            level = .screenSaver
+            isOpaque = false
+            backgroundColor = .clear
+            hasShadow = true
+            ignoresMouseEvents = true
+            collectionBehavior = [.canJoinAllSpaces, .fullScreenAuxiliary, .stationary]
+
+            let blur = NSVisualEffectView(frame: NSRect(x: 0, y: 0, width: 460, height: 96))
+            blur.material = .hudWindow
+            blur.blendingMode = .behindWindow
+            blur.state = .active
+            blur.wantsLayer = true
+            blur.layer?.cornerRadius = Brand.Radius.lg
+            blur.layer?.masksToBounds = true
+            blur.autoresizingMask = [.width, .height]
+            contentView = blur
+
+            dot.wantsLayer = true
+            dot.layer?.cornerRadius = 4
+            dot.frame = NSRect(x: 20, y: 63, width: 8, height: 8)
+            blur.addSubview(dot)
+
+            titleField.frame = NSRect(x: 38, y: 58, width: 400, height: 18)
+            // Eyebrow: mono, uppercase, tracked — "STEP 2 OF 9".
+            titleField.font = .monospacedSystemFont(ofSize: 10, weight: .semibold)
+            titleField.textColor = .secondaryLabelColor
+            blur.addSubview(titleField)
+
+            bodyField.frame = NSRect(x: 20, y: 14, width: 420, height: 40)
+            bodyField.font = Brand.body(size: 14)
+            bodyField.textColor = .labelColor
+            bodyField.maximumNumberOfLines = 2
+            blur.addSubview(bodyField)
+
+            moveToDefault()
+        }
+
+        /// Top centre: out of the way of most content, and where a person
+        /// already looks for system feedback.
+        func moveToDefault() {
+            guard let screen = NSScreen.main else { return }
+            let v = screen.visibleFrame
+            setFrameOrigin(NSPoint(x: v.midX - frame.width / 2, y: v.maxY - frame.height - 34))
+        }
+
+        /// Move below the target when the default position would cover it.
+        ///
+        /// `rect` arrives in accessibility coordinates (top-left origin);
+        /// windows use bottom-left, so it is flipped before comparing.
+        func avoid(_ rect: CGRect) {
+            guard let screen = NSScreen.main else { return }
+            let v = screen.visibleFrame
+            let flipped = CGRect(x: rect.origin.x,
+                                 y: screen.frame.maxY - rect.origin.y - rect.height,
+                                 width: rect.width, height: rect.height)
+            moveToDefault()
+            // A margin, so the callout does not merely touch the target's
+            // edge and still crowd it.
+            guard frame.insetBy(dx: -16, dy: -16).intersects(flipped) else { return }
+
+            // Prefer just below the target; fall back to just above when
+            // there is no room, and give up rather than push it off screen.
+            let below = flipped.minY - frame.height - 20
+            if below > v.minY {
+                setFrameOrigin(NSPoint(x: frame.origin.x, y: below))
+            } else {
+                let above = flipped.maxY + 20
+                if above + frame.height < v.maxY {
+                    setFrameOrigin(NSPoint(x: frame.origin.x, y: above))
+                }
+            }
+        }
+
+        override var canBecomeKey: Bool { false }
+    }
+
+    // Teal for the agent acting on the screen, blue while it speaks,
+    // amber when it is blocked. One accent family, not a traffic light.
+    private static let colours: [String: NSColor] = [
+        "talking": Brand.primaryBright,
+        "pointing": Brand.accent,
+        "typing": Brand.accentDeep,
+        "waiting": Brand.warn,
+        "done": Brand.accent,
+    ]
+
+    /// Read update lines until stdin closes.
+    static func run() {
+        let app = NSApplication.shared
+        app.setActivationPolicy(.accessory)
+        let window = Window()
+        window.alphaValue = 0
+        window.orderFrontRegardless()
+        NSAnimationContext.runAnimationGroup { $0.duration = 0.2; window.animator().alphaValue = 1 }
+
+        // stdin on a background thread: the main thread has to keep
+        // pumping the run loop or nothing renders and the blur never
+        // resolves.
+        let queue = DispatchQueue(label: "tn.acme.agentx.hud.stdin")
+        queue.async {
+            while let line = readLine(strippingNewline: true) {
+                guard let data = line.data(using: .utf8),
+                      let obj = try? JSONSerialization.jsonObject(with: data) as? [String: Any]
+                else { continue }
+                DispatchQueue.main.async {
+                    if let t = obj["title"] as? String {
+                        window.titleField.attributedStringValue =
+                            Brand.metaString(t, size: 10, color: .secondaryLabelColor)
+                    }
+                    if let b = obj["body"] as? String { window.bodyField.stringValue = b }
+                    if let a = obj["avoid"] as? [String: Any],
+                       let x = a["x"] as? Double, let y = a["y"] as? Double,
+                       let w = a["w"] as? Double, let h = a["h"] as? Double {
+                        window.avoid(CGRect(x: x, y: y, width: w, height: h))
+                    } else {
+                        window.moveToDefault()
+                    }
+                    let state = (obj["state"] as? String) ?? "talking"
+                    let c = colours[state] ?? Brand.primaryBright
+                    window.dot.layer?.backgroundColor = c.cgColor
+                    window.dot.layer?.shadowColor = c.cgColor
+                    window.dot.layer?.shadowOpacity = 0.6
+                    window.dot.layer?.shadowRadius = 5
+                    window.dot.layer?.shadowOffset = .zero
+                }
+            }
+            // EOF: the lesson ended.
+            DispatchQueue.main.async {
+                NSAnimationContext.runAnimationGroup { ctx in
+                    ctx.duration = 0.25
+                    window.animator().alphaValue = 0
+                } completionHandler: {
+                    app.terminate(nil)
+                }
+            }
+        }
+        app.run()
+    }
+}

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

@@ -0,0 +1,117 @@
+import AppKit
+import Vision
+
+/// Reading the screen when the accessibility tree has nothing to say.
+///
+/// Electron apps are the reason this exists. VS Code exposes three
+/// controls and labels none of them; Screen Studio's own recording picker
+/// exposes no children at all. To the tree those screens look empty, which
+/// is indistinguishable from an app with genuinely nothing on it — so a
+/// lesson or an agent asked to act there has no candidates and can only
+/// refuse.
+///
+/// Apple's Vision framework reads the pixels instead. Entirely local: the
+/// image never leaves the machine, which is the same posture third-hand
+/// takes and the opposite of shipping screenshots to a vision model.
+///
+/// What this buys and what it does not. OCR returns TEXT AND WHERE IT IS.
+/// It does not return affordances — it cannot tell a button from its own
+/// caption, or a disabled control from an enabled one. So an OCR
+/// candidate is a weaker thing than a tree element and is marked as such,
+/// rather than quietly mixed in as though the two were equivalent.
+enum OCR {
+
+    struct TextHit: Codable {
+        let text: String
+        /// Screen coordinates, top-left origin — the same convention the
+        /// accessibility tree uses, so callers need no second mapping.
+        let x: Double
+        let y: Double
+        let width: Double
+        let height: Double
+        let confidence: Double
+    }
+
+    /// Read text from a screen rectangle.
+    ///
+    /// `rect` is in screen coordinates with a TOP-LEFT origin, matching
+    /// AXTree. Everything about coordinates here is a conversion between
+    /// three conventions and it is the part most likely to be wrong, so
+    /// each step is named:
+    ///
+    ///   1. CGWindowListCreateImage takes top-left screen coords. Good.
+    ///   2. The image comes back at backing scale — 2x on Retina — so its
+    ///      pixel size is not the rect's point size.
+    ///   3. Vision reports NORMALISED coordinates (0…1) with a BOTTOM-LEFT
+    ///      origin, relative to the image.
+    ///
+    /// So a hit is un-normalised against the image, flipped vertically,
+    /// and finally offset by the rect's own origin.
+    static func read(rect: CGRect, languages: [String] = ["fr-FR", "en-US"]) -> [TextHit] {
+        guard rect.width >= 8, rect.height >= 8,
+              let image = CGWindowListCreateImage(
+                rect, .optionOnScreenOnly, kCGNullWindowID, [.bestResolution])
+        else { return [] }
+
+        let request = VNRecognizeTextRequest()
+        request.recognitionLevel = .accurate
+        // The machine under test is French and pages render in French;
+        // an English-only recogniser drops accented words entirely.
+        request.recognitionLanguages = languages
+        request.usesLanguageCorrection = true
+
+        let handler = VNImageRequestHandler(cgImage: image, options: [:])
+        guard (try? handler.perform([request])) != nil,
+              let observations = request.results
+        else { return [] }
+
+        var hits: [TextHit] = []
+        for obs in observations {
+            guard let candidate = obs.topCandidates(1).first else { continue }
+            let text = candidate.string.trimmingCharacters(in: .whitespacesAndNewlines)
+            // Single stray characters are noise from borders and icons.
+            guard text.count > 1 else { continue }
+
+            // Vision box: normalised, bottom-left origin, relative to image.
+            let b = obs.boundingBox
+            let w = b.width * rect.width
+            let h = b.height * rect.height
+            let x = rect.minX + b.minX * rect.width
+            // Flip: Vision's y grows upward from the image bottom; screen
+            // coordinates grow downward from the rect top.
+            let y = rect.minY + (1.0 - b.maxY) * rect.height
+
+            hits.append(TextHit(text: text, x: x, y: y, width: w, height: h,
+                                confidence: Double(candidate.confidence)))
+        }
+        // Reading order: top to bottom, then left to right. Matches how a
+        // person would enumerate what is on screen.
+        return hits.sorted { a, b in
+            abs(a.y - b.y) > 6 ? a.y < b.y : a.x < b.x
+        }
+    }
+
+    /// The focused window's frame, in top-left screen coordinates.
+    ///
+    /// Capturing the whole screen would work and is worse: more to read,
+    /// slower, and it pulls in every other application's content.
+    static func focusedWindowFrame() -> CGRect? {
+        guard let app = NSWorkspace.shared.frontmostApplication else { return nil }
+        let axApp = AXUIElementCreateApplication(app.processIdentifier)
+        var windowRef: CFTypeRef?
+        guard AXUIElementCopyAttributeValue(axApp, kAXFocusedWindowAttribute as CFString, &windowRef) == .success,
+              CFGetTypeID(windowRef) == AXUIElementGetTypeID()
+        else { return nil }
+        let window = unsafeBitCast(windowRef, to: AXUIElement.self)
+
+        var posRef: CFTypeRef?, sizeRef: CFTypeRef?
+        guard AXUIElementCopyAttributeValue(window, kAXPositionAttribute as CFString, &posRef) == .success,
+              AXUIElementCopyAttributeValue(window, 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)
+        guard s.width > 0, s.height > 0 else { return nil }
+        return CGRect(origin: p, size: s)
+    }
+}

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

@@ -0,0 +1,309 @@
+import AppKit
+
+/// Shows where a control is, at a speed a person can follow. Does not click.
+///
+/// The first version warped the cursor, then eased it over a flat 280ms.
+/// Both read as machine motion: a teleport is missed entirely, and a
+/// constant-duration slide is the same speed whether it crosses the screen
+/// or nudges thirty points. Neither looks like a hand.
+///
+/// Real pointing has three properties worth copying, all cheap:
+///
+///   1. Duration follows Fitts's law — far targets and small targets take
+///      longer. A fixed duration is the single biggest tell.
+///   2. Velocity is minimum-jerk: accelerate, cruise, decelerate. Linear
+///      motion reads as a glitch; abrupt stops read as a snap.
+///   3. The path bows slightly. Hands do not travel in straight lines, and
+///      a perfectly straight traverse is conspicuous on a long move.
+///
+/// There is deliberately no click here. The point tier exists so a model's
+/// choice is visible and reviewable BEFORE anything irreversible happens.
+enum Pointer {
+
+    static func point(x: Double, y: Double, width: Double, height: Double, label: String,
+                      holdSeconds: Double = 2.5, instant: Bool = false) {
+        let target = CGPoint(x: x + width / 2, y: y + height / 2)
+        if instant {
+            CGWarpMouseCursorPosition(target)
+        } else {
+            humanMove(to: target, targetSize: min(width, height))
+        }
+        CGAssociateMouseAndMouseCursorPosition(1)
+        annotate(CGRect(x: x, y: y, width: width, height: height),
+                 label: label, holdSeconds: holdSeconds)
+    }
+
+    // MARK: Movement
+
+    /// Move the way a hand would.
+    private static func humanMove(to target: CGPoint, targetSize: Double) {
+        let from = CGEvent(source: nil)?.location ?? target
+        let dx = target.x - from.x, dy = target.y - from.y
+        let distance = (dx * dx + dy * dy).squareRoot()
+        if distance < 2 { CGWarpMouseCursorPosition(target); return }
+
+        // Fitts's law: time ∝ log2(distance / width + 1). The constants put
+        // a short hop near 180ms and a full-screen traverse near 700ms,
+        // which is roughly what a person does — fast enough not to feel
+        // like waiting, slow enough to follow.
+        let width = max(targetSize, 12)
+        let difficulty = log2(distance / width + 1)
+        let duration = min(0.95, max(0.18, 0.09 + 0.13 * difficulty))
+
+        // Bow the path perpendicular to the direction of travel, scaled to
+        // distance and with a stable sign so it does not wobble.
+        let bow = min(distance * 0.08, 55.0) * (dx * dy >= 0 ? 1.0 : -1.0)
+        let nx = -dy / distance, ny = dx / distance
+        let control = CGPoint(x: from.x + dx * 0.5 + nx * bow,
+                              y: from.y + dy * 0.5 + ny * bow)
+
+        let steps = max(24, Int(duration * 110))
+        for i in 1...steps {
+            let t = Double(i) / Double(steps)
+            // Minimum-jerk: 10t³ − 15t⁴ + 6t⁵. Starts and ends at zero
+            // velocity AND zero acceleration, which is why it looks settled
+            // rather than braked.
+            let e = 10 * pow(t, 3) - 15 * pow(t, 4) + 6 * pow(t, 5)
+            let p = quadratic(from, control, target, e)
+
+            // A trace of tremor, fading to nothing as it arrives. Without
+            // it the path is mathematically perfect and reads as drawn.
+            let tremor = (1 - e) * 0.7
+            let jitter = CGPoint(x: Double.random(in: -tremor...tremor),
+                                 y: Double.random(in: -tremor...tremor))
+            CGWarpMouseCursorPosition(CGPoint(x: p.x + jitter.x, y: p.y + jitter.y))
+            Thread.sleep(forTimeInterval: duration / Double(steps))
+        }
+
+        // Long moves overshoot slightly and correct — the correction is
+        // what makes an arrival look human rather than magnetic.
+        if distance > 320 {
+            let over = CGPoint(x: target.x + dx / distance * 4,
+                               y: target.y + dy / distance * 4)
+            CGWarpMouseCursorPosition(over)
+            Thread.sleep(forTimeInterval: 0.045)
+        }
+        CGWarpMouseCursorPosition(target)
+    }
+
+    private static func quadratic(_ a: CGPoint, _ b: CGPoint, _ c: CGPoint, _ t: Double) -> CGPoint {
+        let u = 1 - t
+        return CGPoint(x: u * u * a.x + 2 * u * t * b.x + t * t * c.x,
+                       y: u * u * a.y + 2 * u * t * b.y + t * t * c.y)
+    }
+
+    /// A click, made visible.
+    ///
+    /// A synthetic click is otherwise invisible — the UI reacts, but
+    /// nothing shows that the press came from here rather than from the
+    /// person watching. In a lesson that ambiguity is the whole problem:
+    /// you cannot learn a gesture you did not see performed.
+    ///
+    /// So the cursor position gets a ring that snaps inward and rebounds,
+    /// which is how a fingertip reads — compression then release, not a
+    /// flash. Runs before the event so the visual leads the reaction by a
+    /// frame or two, the way a real press does.
+    static func clickFlourish(durationSeconds: Double = 0.42) {
+        guard let p = CGEvent(source: nil)?.location,
+              let screen = NSScreen.screens.first(where: {
+                  $0.frame.contains(CGPoint(x: p.x, y: $0.frame.maxY - p.y))
+              }) ?? NSScreen.main else { return }
+
+        let r: CGFloat = 46
+        let flipped = CGPoint(x: p.x, y: screen.frame.maxY - p.y)
+        let panel = NSPanel(contentRect: NSRect(x: flipped.x - r, y: flipped.y - r,
+                                                width: r * 2, height: r * 2),
+                            styleMask: [.borderless, .nonactivatingPanel],
+                            backing: .buffered, defer: false)
+        panel.level = .screenSaver
+        panel.isOpaque = false
+        panel.backgroundColor = .clear
+        panel.ignoresMouseEvents = true
+        panel.hasShadow = false
+        panel.collectionBehavior = [.canJoinAllSpaces, .fullScreenAuxiliary, .stationary]
+
+        let host = NSView(frame: panel.contentView!.bounds)
+        host.wantsLayer = true
+        panel.contentView = host
+
+        let ring = CAShapeLayer()
+        let box = CGRect(x: r - 17, y: r - 17, width: 34, height: 34)
+        ring.path = CGPath(ellipseIn: box, transform: nil)
+        ring.fillColor = Brand.accent.withAlphaComponent(0.22).cgColor
+        ring.strokeColor = Brand.accent.cgColor
+        ring.lineWidth = 2.5
+        ring.frame = host.bounds
+        ring.anchorPoint = CGPoint(x: 0.5, y: 0.5)
+        host.layer?.addSublayer(ring)
+
+        // Squash then rebound past rest, then settle — the shape of a
+        // press. A single scale-down reads as the UI shrinking, not as a
+        // finger landing.
+        let squash = CAKeyframeAnimation(keyPath: "transform.scale")
+        squash.values = [1.0, 0.55, 1.22, 1.0]
+        squash.keyTimes = [0, 0.28, 0.62, 1.0]
+        squash.timingFunctions = [
+            CAMediaTimingFunction(name: .easeIn),
+            CAMediaTimingFunction(name: .easeOut),
+            CAMediaTimingFunction(name: .easeOut),
+        ]
+        squash.duration = durationSeconds
+
+        let fade = CAKeyframeAnimation(keyPath: "opacity")
+        fade.values = [0.0, 1.0, 0.9, 0.0]
+        fade.keyTimes = [0, 0.18, 0.55, 1.0]
+        fade.duration = durationSeconds
+
+        let group = CAAnimationGroup()
+        group.animations = [squash, fade]
+        group.duration = durationSeconds
+        group.isRemovedOnCompletion = false
+        group.fillMode = .forwards
+        ring.add(group, forKey: "click")
+
+        panel.orderFrontRegardless()
+        let deadline = Date().addingTimeInterval(durationSeconds)
+        while Date() < deadline {
+            RunLoop.current.run(mode: .default, before: Date().addingTimeInterval(0.012))
+        }
+        panel.orderOut(nil)
+    }
+
+    // MARK: Annotation
+
+    /// A radar ping and a marching-ants border.
+    ///
+    /// Presentation tools converge on these two for the same reason: an
+    /// expanding ring draws the eye to a point without hiding what is
+    /// underneath, and a moving dash says "this one" in a way a static box
+    /// does not on a busy screen. Both are Core Animation, so they run on
+    /// the render thread and stay smooth while the process is otherwise
+    /// blocked.
+    private static func annotate(_ rect: CGRect, label: String, holdSeconds: Double) {
+        guard let screen = NSScreen.screens.first(where: { $0.frame.contains(
+            CGPoint(x: rect.midX, y: $0.frame.maxY - rect.midY)) }) ?? NSScreen.main else { return }
+
+        // Accessibility gives top-left origin; NSWindow wants bottom-left.
+        let flipped = CGRect(x: rect.origin.x,
+                             y: screen.frame.maxY - rect.origin.y - rect.height,
+                             width: rect.width, height: rect.height)
+        let pad: CGFloat = 60  // room for the ping to expand past the target
+        let panel = NSPanel(contentRect: flipped.insetBy(dx: -pad, dy: -pad),
+                            styleMask: [.borderless, .nonactivatingPanel],
+                            backing: .buffered, defer: false)
+        panel.level = .screenSaver
+        panel.isOpaque = false
+        panel.backgroundColor = .clear
+        panel.ignoresMouseEvents = true
+        panel.hasShadow = false
+        panel.collectionBehavior = [.canJoinAllSpaces, .fullScreenAuxiliary, .stationary]
+
+        let host = NSView(frame: panel.contentView!.bounds)
+        host.wantsLayer = true
+        panel.contentView = host
+
+        let box = CGRect(x: pad, y: pad, width: rect.width, height: rect.height)
+        let accent = Brand.accent
+
+        // Marching ants.
+        let border = CAShapeLayer()
+        border.path = CGPath(roundedRect: box.insetBy(dx: -3, dy: -3),
+                             cornerWidth: Brand.Radius.base, cornerHeight: Brand.Radius.base, transform: nil)
+        border.fillColor = accent.withAlphaComponent(0.10).cgColor
+        border.strokeColor = accent.cgColor
+        border.lineWidth = 2.5
+        border.lineDashPattern = [7, 4]
+        host.layer?.addSublayer(border)
+
+        let ants = CABasicAnimation(keyPath: "lineDashPhase")
+        ants.fromValue = 0; ants.toValue = 11
+        ants.duration = 0.55
+        ants.repeatCount = .infinity
+        border.add(ants, forKey: "ants")
+
+        // Radar ping, twice, offset so the second starts as the first fades.
+        for delay in [0.0, 0.5] {
+            let ping = CAShapeLayer()
+            ping.path = CGPath(roundedRect: box.insetBy(dx: -3, dy: -3),
+                               cornerWidth: Brand.Radius.base, cornerHeight: Brand.Radius.base, transform: nil)
+            ping.fillColor = NSColor.clear.cgColor
+            ping.strokeColor = accent.cgColor
+            ping.lineWidth = 2
+            ping.opacity = 0
+            host.layer?.addSublayer(ping)
+
+            let grow = CABasicAnimation(keyPath: "transform.scale")
+            grow.fromValue = 1.0; grow.toValue = 1.9
+            let fade = CABasicAnimation(keyPath: "opacity")
+            fade.fromValue = 0.85; fade.toValue = 0.0
+
+            let group = CAAnimationGroup()
+            group.animations = [grow, fade]
+            group.duration = 1.0
+            group.beginTime = CACurrentMediaTime() + delay
+            group.repeatCount = 2
+            group.timingFunction = CAMediaTimingFunction(name: .easeOut)
+            group.isRemovedOnCompletion = false
+            // Scale about the target, not the layer's corner.
+            ping.anchorPoint = CGPoint(x: 0.5, y: 0.5)
+            ping.frame = host.bounds
+            ping.add(group, forKey: "ping")
+        }
+
+        if !label.isEmpty { addLabel(label, to: host, above: box, accent: accent) }
+
+        panel.alphaValue = 0
+        panel.orderFrontRegardless()
+        NSAnimationContext.runAnimationGroup { ctx in
+            ctx.duration = 0.16
+            panel.animator().alphaValue = 1
+        }
+
+        // The process is a one-shot CLI: without pumping the run loop the
+        // window would never render before it exits.
+        let deadline = Date().addingTimeInterval(holdSeconds)
+        while Date() < deadline {
+            RunLoop.current.run(mode: .default, before: Date().addingTimeInterval(0.02))
+        }
+        NSAnimationContext.runAnimationGroup { ctx in
+            ctx.duration = 0.22
+            panel.animator().alphaValue = 0
+        }
+        let fadeEnd = Date().addingTimeInterval(0.26)
+        while Date() < fadeEnd {
+            RunLoop.current.run(mode: .default, before: Date().addingTimeInterval(0.02))
+        }
+        panel.orderOut(nil)
+    }
+
+    /// A pill above the target naming what was chosen, so a wrong pick is
+    /// obvious rather than merely mysterious.
+    private static func addLabel(_ text: String, to host: NSView, above box: CGRect, accent: NSColor) {
+        // Meta type — mono, uppercase, tracked — because this names a
+        // thing rather than saying something about it.
+        let field = NSTextField(labelWithString: "")
+        field.attributedStringValue = Brand.metaString(text, size: 10.5, color: .white)
+        field.alignment = .center
+        field.sizeToFit()
+
+        let w = field.frame.width + 18, h = field.frame.height + 8
+        // Below the target when there is no room above, so a control near
+        // the top of the screen still gets a readable label.
+        let above = box.maxY + 8 + h < host.bounds.height
+        let y = above ? box.maxY + 8 : box.minY - h - 8
+        let pill = NSView(frame: NSRect(x: box.midX - w / 2, y: y, width: w, height: h))
+        pill.wantsLayer = true
+        pill.layer?.backgroundColor = accent.cgColor
+        pill.layer?.cornerRadius = Brand.Radius.sm
+        field.frame = NSRect(x: 9, y: 4, width: field.frame.width, height: field.frame.height)
+        pill.addSubview(field)
+        host.addSubview(pill)
+
+        let rise = CABasicAnimation(keyPath: "position.y")
+        rise.fromValue = (pill.layer?.position.y ?? 0) + (above ? -6 : 6)
+        rise.toValue = pill.layer?.position.y ?? 0
+        rise.duration = 0.22
+        rise.timingFunction = CAMediaTimingFunction(name: .easeOut)
+        pill.layer?.add(rise, forKey: "rise")
+    }
+}

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

@@ -0,0 +1,67 @@
+import AppKit
+
+/// Display geometry, in the same top-left coordinate space as everything
+/// else in this helper.
+///
+/// AppKit reports screens in a global space whose origin is the PRIMARY
+/// screen's bottom-left and whose y grows upward. The accessibility tree,
+/// OCR and the pointer all use top-left origins with y growing downward.
+/// Mixing the two puts the cursor on the wrong monitor — and on a single
+/// display it looks correct, so the bug only appears on someone else's
+/// desk. Converting once, here, is cheaper than remembering not to.
+enum Screens {
+
+    struct Info: Codable {
+        let index: Int
+        let x: Double
+        let y: Double
+        let width: Double
+        let height: Double
+        /// The screen with the menu bar.
+        let primary: Bool
+        /// The screen the active window is on.
+        let active: Bool
+        /// 2.0 on Retina. A capture comes back at this multiple of the
+        /// point size, which is why anything sent to a model is scaled.
+        let scale: Double
+    }
+
+    static func list() -> [Info] {
+        let screens = NSScreen.screens
+        guard let primary = screens.first else { return [] }
+        // Every y flips about the primary screen's top edge.
+        let top = primary.frame.maxY
+        return screens.enumerated().map { index, screen in
+            Info(index: index,
+                 x: screen.frame.minX,
+                 y: top - screen.frame.maxY,
+                 width: screen.frame.width,
+                 height: screen.frame.height,
+                 primary: index == 0,
+                 active: screen == NSScreen.main,
+                 scale: screen.backingScaleFactor)
+        }
+    }
+
+    /// The screen to capture when no rectangle is given: the one holding
+    /// the active window, not blindly the primary.
+    static func active() -> Info? {
+        let all = list()
+        return all.first(where: { $0.active }) ?? all.first
+    }
+
+    /// Full bounds of one screen, in top-left coordinates.
+    static func rect(_ info: Info) -> CGRect {
+        CGRect(x: info.x, y: info.y, width: info.width, height: info.height)
+    }
+
+    /// The menu bar strip of a screen.
+    ///
+    /// Its own region because it is where macOS puts the truth about
+    /// background state: recording indicators, capture pills, sync and VPN
+    /// status. None of it is in any app's accessibility tree, and reading
+    /// a 24-point strip costs a fraction of a full screen.
+    static func menuBar(_ info: Info) -> CGRect {
+        CGRect(x: info.x, y: info.y, width: info.width, height: 26)
+    }
+}