agentix-cli 0.34.0 → 0.36.0

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

@@ -0,0 +1,294 @@
+import AppKit
+
+/// An agent's own cursor on screen: its colour, its initial, its name.
+///
+/// Drawn, never driven. `point` moves the person's real mouse, which is
+/// right for a lesson the person watches and wrong for one they take part
+/// in — their hand is on that mouse. This cursor is a click-through arrow
+/// that glides to what the agent means, highlights it, and says a line in
+/// a bubble, while the real pointer stays exactly where the person left it.
+///
+/// Driven over stdin, one JSON object per line, like the HUD:
+///
+///   {"cmd":"move","x":120,"y":80,"w":90,"h":24,"highlight":true}
+///   {"cmd":"say","text":"The export button is top right."}
+///   {"cmd":"clear"}   drop the highlight
+///   {"cmd":"park"}    rest in the bottom-right corner, no highlight
+///   {"cmd":"ping"}    nothing; keeps an idle overlay alive
+///
+/// Coordinates are accessibility coordinates (top-left origin, global),
+/// the same as `read`, `ocr` and `point`.
+///
+/// Only the arrow and highlight are click-through. The name tag and bubble
+/// (PresenceTag) can be dragged out of the way; with `--pos-file` the spot
+/// is remembered for this agent and the tag stays there on later turns.
+///
+/// It never outlives its owner: EOF, the owner's death (`--parent`, or
+/// being re-parented to launchd) or `--idle` seconds without a command
+/// fade everything out and exit. One process draws one cursor, on one
+/// screen; it follows across Spaces but is never duplicated per display.
+enum Presence {
+
+    // MARK: Geometry
+
+    /// Accessibility → AppKit. Global AX coordinates are measured from the
+    /// top of the PRIMARY display, whichever screen the point is on.
+    static func toAppKit(_ p: CGPoint) -> CGPoint {
+        let h = NSScreen.screens.first?.frame.maxY ?? 0
+        return CGPoint(x: p.x, y: h - p.y)
+    }
+
+    static func toAppKit(_ r: CGRect) -> CGRect {
+        let o = toAppKit(CGPoint(x: r.minX, y: r.maxY))
+        return CGRect(x: o.x, y: o.y, width: r.width, height: r.height)
+    }
+
+    // MARK: Windows
+
+    /// Floating, not screen-saver level: above the windows the person works
+    /// in, below menus, alerts and Spotlight.
+    fileprivate static func panel(_ rect: NSRect, clickThrough: Bool = true) -> NSPanel {
+        let p = NSPanel(contentRect: rect, styleMask: [.borderless, .nonactivatingPanel],
+                        backing: .buffered, defer: false)
+        p.level = .floating
+        p.isOpaque = false
+        p.backgroundColor = .clear
+        p.hasShadow = false
+        // The arrow and the highlight are click-through: the person's clicks
+        // land on the app underneath. Only the name tag takes the mouse.
+        p.ignoresMouseEvents = clickThrough
+        p.collectionBehavior = [.canJoinAllSpaces, .fullScreenAuxiliary, .stationary]
+        return p
+    }
+
+    /// The arrow alone: the system cursor's silhouette, in the agent's colour.
+    private final class ArrowView: NSView {
+        let color: NSColor
+        static let size = NSSize(width: 30, height: 40)
+        /// The arrow tip, in view coordinates (bottom-left origin).
+        static let tip = NSPoint(x: 4, y: size.height - 4)
+
+        init(color: NSColor) {
+            self.color = color
+            super.init(frame: NSRect(origin: .zero, size: ArrowView.size))
+        }
+        required init?(coder: NSCoder) { fatalError() }
+
+        override func draw(_ dirtyRect: NSRect) {
+            let t = ArrowView.tip
+            let arrow = NSBezierPath()
+            arrow.move(to: t)
+            arrow.line(to: NSPoint(x: t.x, y: t.y - 26))
+            arrow.line(to: NSPoint(x: t.x + 7, y: t.y - 20))
+            arrow.line(to: NSPoint(x: t.x + 12, y: t.y - 30))
+            arrow.line(to: NSPoint(x: t.x + 16, y: t.y - 28))
+            arrow.line(to: NSPoint(x: t.x + 11, y: t.y - 18))
+            arrow.line(to: NSPoint(x: t.x + 20, y: t.y - 18))
+            arrow.close()
+            NSGraphicsContext.current?.saveGraphicsState()
+            let shadow = NSShadow()
+            shadow.shadowBlurRadius = 4
+            shadow.shadowOffset = NSSize(width: 0, height: -1)
+            shadow.shadowColor = NSColor.black.withAlphaComponent(0.35)
+            shadow.set()
+            color.setFill(); arrow.fill()
+            NSGraphicsContext.current?.restoreGraphicsState()
+            NSColor.white.setStroke(); arrow.lineWidth = 1.5; arrow.stroke()
+        }
+    }
+
+    // MARK: Pinned position
+
+    /// Where the person dragged this agent's tag: its top-left, AppKit
+    /// coordinates, as {"x":…,"y":…}. Ignored if no screen shows it any more.
+    static func loadPin(_ file: String?) -> NSPoint? {
+        guard let file, let data = FileManager.default.contents(atPath: file),
+              let o = try? JSONSerialization.jsonObject(with: data) as? [String: Any],
+              let x = o["x"] as? Double, let y = o["y"] as? Double else { return nil }
+        let p = NSPoint(x: x, y: y)
+        // The badge row hangs below the top-left; it must be on a screen.
+        let row = NSPoint(x: x + 12, y: y - 12)
+        return NSScreen.screens.contains(where: { $0.frame.contains(row) }) ? p : nil
+    }
+
+    static func savePin(_ p: NSPoint?, to file: String?) {
+        guard let file else { return }
+        guard let p else { try? FileManager.default.removeItem(atPath: file); return }
+        let url = URL(fileURLWithPath: file)
+        do {
+            try FileManager.default.createDirectory(at: url.deletingLastPathComponent(), withIntermediateDirectories: true)
+            let data = try JSONSerialization.data(withJSONObject: ["x": Double(p.x), "y": Double(p.y)])
+            try data.write(to: url, options: .atomic)
+        } catch {
+            FileHandle.standardError.write("presence: could not save position: \(error)\n".data(using: .utf8)!)
+        }
+    }
+
+    // MARK: Behaviour
+
+    private final class Controller {
+        let arrow: NSPanel
+        let tagPanel: NSPanel
+        let tag: PresenceTag
+        let ring: NSPanel
+        let color: NSColor
+        let posFile: String?
+        var at: CGPoint          // tip position, AppKit coordinates
+        /// The tag's top-left once the person has dragged it; nil rides with the arrow.
+        var pinned: NSPoint?
+        var timer: Timer?
+
+        init(color: NSColor, initial: String, name: String, posFile: String?) {
+            self.color = color
+            self.posFile = posFile
+            arrow = Presence.panel(NSRect(origin: .zero, size: ArrowView.size))
+            arrow.contentView = ArrowView(color: color)
+            tag = PresenceTag(color: color, initial: initial, name: name)
+            tagPanel = Presence.panel(NSRect(origin: .zero, size: tag.frame.size), clickThrough: false)
+            tagPanel.contentView = tag
+            ring = Presence.panel(.zero)
+            let ringView = NSView()
+            ringView.wantsLayer = true
+            ringView.layer?.borderWidth = 3
+            ringView.layer?.borderColor = color.cgColor
+            ringView.layer?.cornerRadius = 8
+            ringView.layer?.backgroundColor = color.withAlphaComponent(0.10).cgColor
+            ring.contentView = ringView
+            pinned = Presence.loadPin(posFile)
+            at = Controller.parking()
+            tag.onPin = { [weak self] p in self?.pinned = p; Presence.savePin(p, to: posFile) }
+            tag.onUnpin = { [weak self] in
+                guard let self else { return }
+                self.pinned = nil
+                Presence.savePin(nil, to: posFile)
+                self.place(self.at)
+            }
+            place(at)
+            for p in [arrow, tagPanel] {
+                p.alphaValue = 0
+                p.orderFrontRegardless()
+            }
+            NSAnimationContext.runAnimationGroup { ctx in
+                ctx.duration = 0.2
+                arrow.animator().alphaValue = 1
+                tagPanel.animator().alphaValue = 1
+            }
+        }
+
+        static func parking() -> CGPoint {
+            let v = NSScreen.main?.visibleFrame ?? NSRect(x: 0, y: 0, width: 1440, height: 900)
+            return CGPoint(x: v.maxX - 380, y: v.minY + 170)
+        }
+
+        func place(_ tip: CGPoint) {
+            arrow.setFrameOrigin(NSPoint(x: tip.x - ArrowView.tip.x, y: tip.y - ArrowView.tip.y))
+            if tag.dragged { return }
+            let size = tagPanel.frame.size
+            var top = pinned ?? NSPoint(x: tip.x + 20, y: tip.y - 26)
+            if pinned == nil {
+                // Near the right edge the tag sits to the left of the arrow.
+                let screen = NSScreen.screens.first(where: { $0.frame.contains(tip) }) ?? NSScreen.main
+                if let edge = screen?.visibleFrame.maxX, top.x + size.width > edge { top.x = tip.x - 4 - size.width }
+            }
+            tagPanel.setFrameOrigin(NSPoint(x: top.x, y: top.y - size.height))
+        }
+
+        /// Glide with minimum-jerk easing; duration follows distance, as in
+        /// Pointer, so a long move reads as a reach and a short one as a nudge.
+        func glide(to target: CGPoint) {
+            timer?.invalidate()
+            let from = at
+            let d = hypot(target.x - from.x, target.y - from.y)
+            let duration = min(0.9, max(0.2, 0.12 + d / 2200))
+            let start = Date()
+            timer = Timer.scheduledTimer(withTimeInterval: 1.0 / 60, repeats: true) { [weak self] t in
+                guard let self else { t.invalidate(); return }
+                let u = min(1, Date().timeIntervalSince(start) / duration)
+                let e = 10 * pow(u, 3) - 15 * pow(u, 4) + 6 * pow(u, 5)
+                self.at = CGPoint(x: from.x + (target.x - from.x) * e, y: from.y + (target.y - from.y) * e)
+                self.place(self.at)
+                if u >= 1 { t.invalidate() }
+            }
+        }
+
+        func highlight(_ rect: CGRect?) {
+            guard let rect else { ring.orderOut(nil); return }
+            ring.setFrame(Presence.toAppKit(rect).insetBy(dx: -6, dy: -6), display: true)
+            ring.orderFrontRegardless()
+            arrow.orderFrontRegardless()
+            tagPanel.orderFrontRegardless()
+        }
+
+        func handle(_ obj: [String: Any]) {
+            switch obj["cmd"] as? String {
+            case "move":
+                guard let x = obj["x"] as? Double, let y = obj["y"] as? Double else { return }
+                let w = obj["w"] as? Double ?? 0, h = obj["h"] as? Double ?? 0
+                let rect = CGRect(x: x, y: y, width: w, height: h)
+                // Aim just inside the control's lower-left third, so the
+                // arrow points AT it rather than covering its label.
+                let aim = CGPoint(x: x + min(w * 0.5, 24), y: y + h * 0.7)
+                glide(to: Presence.toAppKit(aim))
+                highlight((obj["highlight"] as? Bool ?? false) && w > 0 && h > 0 ? rect : nil)
+            case "say":
+                tag.setBubble(obj["text"] as? String ?? "")
+                place(at)
+            case "clear":
+                highlight(nil)
+            case "park":
+                highlight(nil)
+                glide(to: Controller.parking())
+            default:
+                break
+            }
+        }
+
+        func fadeOut(_ done: @escaping () -> Void) {
+            ring.orderOut(nil)
+            NSAnimationContext.runAnimationGroup { ctx in
+                ctx.duration = 0.25
+                arrow.animator().alphaValue = 0
+                tagPanel.animator().alphaValue = 0
+            } completionHandler: { done() }
+        }
+    }
+
+    static func color(hex: String?) -> NSColor {
+        guard let hex, hex.count == 7, hex.hasPrefix("#"), let v = UInt32(hex.dropFirst(), radix: 16) else {
+            return Brand.primaryBright
+        }
+        return NSColor(srgbRed: CGFloat((v >> 16) & 0xff) / 255, green: CGFloat((v >> 8) & 0xff) / 255,
+                       blue: CGFloat(v & 0xff) / 255, alpha: 1)
+    }
+
+    /// Read commands until stdin closes, the owner dies, or it goes idle.
+    static func run(name: String, initial: String, colorHex: String?, parent: pid_t?, idle: TimeInterval,
+                    posFile: String? = nil) {
+        let app = NSApplication.shared
+        app.setActivationPolicy(.accessory)
+        let ctl = Controller(color: color(hex: colorHex), initial: initial, name: name, posFile: posFile)
+        var lastCommand = Date()
+        var quitting = false
+        // Main thread only. The fade is a courtesy: exit follows regardless.
+        func quit() {
+            if quitting { return }
+            quitting = true
+            ctl.fadeOut { exit(0) }
+            DispatchQueue.main.asyncAfter(deadline: .now() + 1) { exit(0) }
+        }
+        DispatchQueue(label: "tn.acme.agentx.presence.stdin").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 { lastCommand = Date(); ctl.handle(obj) }
+            }
+            DispatchQueue.main.async { quit() }
+        }
+        Timer.scheduledTimer(withTimeInterval: 2, repeats: true) { _ in
+            let orphaned = getppid() == 1 || (parent.map { kill($0, 0) != 0 && errno == ESRCH } ?? false)
+            let idled = idle > 0 && Date().timeIntervalSince(lastCommand) > idle
+            if orphaned || idled { quit() }
+        }
+        app.run()
+    }
+}

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

@@ -0,0 +1,147 @@
+import AppKit
+
+/// The part of an agent's presence the person can touch: the initial
+/// badge, the name, and the speech bubble under them.
+///
+/// It sits in its own panel, apart from the click-through arrow, so it can
+/// take the mouse without the arrow ever stealing a click:
+///
+///   drag anywhere        move it; it stays there (pinned) for this agent
+///   double-click bubble  dismiss the bubble for the rest of this overlay
+///   double-click name    unpin; it rides next to the arrow again
+///
+/// The view is top-anchored: the badge row stays put as the bubble comes
+/// and goes, and the window grows or shrinks underneath it.
+final class PresenceTag: NSView {
+    let color: NSColor
+    let initial: String
+    let name: String
+    let bubble = NSTextField(wrappingLabelWithString: "")
+    /// The bubble's background, so the text gets padding.
+    let box = NSView()
+
+    static let rowHeight: CGFloat = 24
+    static let gap: CGFloat = 8
+
+    /// Called with the window's new top-left once a drag ends.
+    var onPin: ((NSPoint) -> Void)?
+    var onUnpin: (() -> Void)?
+    /// A double-click on the bubble hides it; later lines stay hidden too.
+    private(set) var dismissed = false
+
+    private var dragFrom: NSPoint?
+    private var windowFrom: NSPoint = .zero
+    /// True mid-drag, so a glide doesn't pull the tag out of the hand.
+    private(set) var dragged = false
+
+    init(color: NSColor, initial: String, name: String) {
+        self.color = color; self.initial = initial; self.name = name
+        super.init(frame: .zero)
+        wantsLayer = true
+        bubble.font = Brand.body(size: 13)
+        bubble.textColor = Brand.ink
+        bubble.maximumNumberOfLines = 4
+        box.wantsLayer = true
+        box.layer?.backgroundColor = Brand.paper.cgColor
+        box.layer?.cornerRadius = Brand.Radius.md
+        box.layer?.borderWidth = 2
+        box.layer?.borderColor = color.cgColor
+        box.isHidden = true
+        box.addSubview(bubble)
+        addSubview(box)
+        setFrameSize(fittingSize)
+    }
+    required init?(coder: NSCoder) { fatalError() }
+
+    private static let nameAttrs: [NSAttributedString.Key: Any] = [.font: NSFont.systemFont(ofSize: 11, weight: .semibold)]
+    private var rowWidth: CGFloat { 24 + 4 + (name as NSString).size(withAttributes: PresenceTag.nameAttrs).width + 14 }
+
+    override var fittingSize: NSSize {
+        guard !box.isHidden else { return NSSize(width: rowWidth, height: PresenceTag.rowHeight) }
+        return NSSize(width: max(rowWidth, box.frame.width),
+                      height: PresenceTag.rowHeight + PresenceTag.gap + box.frame.height)
+    }
+
+    func setBubble(_ text: String) {
+        box.isHidden = text.isEmpty || dismissed
+        bubble.stringValue = text
+        let textW: CGFloat = 300
+        bubble.preferredMaxLayoutWidth = textW
+        let fit = bubble.sizeThatFits(NSSize(width: textW, height: 90))
+        let w = min(textW, ceil(fit.width)), h = min(90, ceil(fit.height))
+        bubble.frame = NSRect(x: 10, y: 6, width: w, height: h)
+        box.frame = NSRect(x: 0, y: 0, width: w + 20, height: h + 12)
+        refit()
+    }
+
+    /// Resize the window to the content, keeping its top-left where it is.
+    private func refit() {
+        let size = fittingSize
+        setFrameSize(size)
+        needsDisplay = true
+        guard let w = window else { return }
+        let top = NSPoint(x: w.frame.minX, y: w.frame.maxY)
+        w.setFrame(NSRect(x: top.x, y: top.y - size.height, width: size.width, height: size.height), display: true)
+    }
+
+    override func draw(_ dirtyRect: NSRect) {
+        let badge = NSRect(x: 0, y: bounds.maxY - 24, width: 24, height: 24)
+        color.setFill(); NSBezierPath(ovalIn: badge).fill()
+        NSColor.white.setStroke()
+        let ring = NSBezierPath(ovalIn: badge.insetBy(dx: 0.75, dy: 0.75)); ring.lineWidth = 1.5; ring.stroke()
+        draw(initial, in: badge, size: 11, weight: .bold)
+
+        let nameW = (name as NSString).size(withAttributes: PresenceTag.nameAttrs).width + 14
+        let pill = NSRect(x: badge.maxX + 4, y: badge.minY + 3, width: nameW, height: 18)
+        color.setFill(); NSBezierPath(roundedRect: pill, xRadius: 9, yRadius: 9).fill()
+        draw(name, in: pill, size: 11, weight: .semibold)
+    }
+
+    private func draw(_ s: String, in r: NSRect, size: CGFloat, weight: NSFont.Weight) {
+        let a: [NSAttributedString.Key: Any] = [.font: NSFont.systemFont(ofSize: size, weight: weight), .foregroundColor: NSColor.white]
+        let sz = (s as NSString).size(withAttributes: a)
+        (s as NSString).draw(at: NSPoint(x: r.midX - sz.width / 2, y: r.midY - sz.height / 2), withAttributes: a)
+    }
+
+    // MARK: Mouse
+
+    /// The label would swallow clicks meant for the drag.
+    override func hitTest(_ point: NSPoint) -> NSView? {
+        frame.contains(point) ? self : nil
+    }
+    /// The panel never activates this app, so the first click must count.
+    override func acceptsFirstMouse(for event: NSEvent?) -> Bool { true }
+
+    override func mouseDown(with event: NSEvent) {
+        if event.clickCount == 2 {
+            let p = convert(event.locationInWindow, from: nil)
+            if !box.isHidden && box.frame.contains(p) {
+                dismissed = true
+                box.isHidden = true
+                refit()
+            } else if p.y >= bounds.maxY - PresenceTag.rowHeight {
+                onUnpin?()
+            }
+            dragFrom = nil
+            return
+        }
+        dragFrom = NSEvent.mouseLocation
+        windowFrom = window?.frame.origin ?? .zero
+        dragged = false
+    }
+
+    override func mouseDragged(with event: NSEvent) {
+        guard let from = dragFrom, let w = window else { return }
+        let now = NSEvent.mouseLocation
+        let dx = now.x - from.x, dy = now.y - from.y
+        if !dragged && hypot(dx, dy) < 3 { return }
+        dragged = true
+        w.setFrameOrigin(NSPoint(x: windowFrom.x + dx, y: windowFrom.y + dy))
+    }
+
+    override func mouseUp(with event: NSEvent) {
+        defer { dragFrom = nil; dragged = false }
+        guard dragged, let w = window else { return }
+        onPin?(NSPoint(x: w.frame.minX, y: w.frame.maxY))
+    }
+}

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

@@ -256,10 +256,18 @@ case "hud":
     // Long-lived: reads update lines on stdin until EOF.
     HUD.run()
 
+case "presence":
+    // Long-lived: the agent's own drawn cursor. Never moves the real mouse.
+    let name = flag("name") ?? "Agent"
+    Presence.run(name: name, initial: flag("initial") ?? String(name.prefix(1)).uppercased(),
+                 colorHex: flag("color"), parent: flag("parent").flatMap { pid_t($0) },
+                 idle: flag("idle").flatMap { TimeInterval($0) } ?? 60,
+                 posFile: flag("pos-file"))
+
 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")
+    fail("unknown verb \"\(verb)\" — expected read, screens, point, click, type, key, scroll, drag, ocr, capture, hittest, focused, hud, presence or trusted")
 }

package/apps/mac-voice/Sources/AgentXVoice/AgentClient.swift

@@ -25,6 +25,8 @@ enum AgentClient {
         /// The agent that answered and its ElevenLabs voice, when it has one.
         let agentID: String?
         let voiceID: String?
+        /// Presence mode the daemon chose for this turn (talk, teach, …).
+        var presenceMode: String? = nil
     }
 
     /// What, if anything, to say about the step now running.
@@ -52,28 +54,37 @@ enum AgentClient {
         return (try? JSONDecoder().decode(Reply.self, from: data))?.say
     }
 
-    // MARK: Talk mode
+    // MARK: The door
     //
-    // While two agents talk out loud (`agentx talk`), Option-Space is the
-    // door: pressing it hushes them at once, and what is said goes to the
-    // talk instead of /ask. See src/daemon/voice-talk-api.ts.
+    // Option-Space is one door for everything spoken: a talk, a live
+    // lesson, task narration, an agent's bubble. Pressing it hushes all of
+    // them at once; what is then said goes to the activity that was
+    // speaking, which answers it first. See src/daemon/voice-talk-api.ts.
 
-    /// Silence a running talk. Returns whether one is running, so the
-    /// caller knows where the words about to be spoken should go. Never
-    /// throws: no daemon means no talk.
-    static func talkHush() async -> Bool {
-        guard let (data, _) = try? await post("/talk/hush", [:], timeout: 2) else { return false }
-        struct Reply: Decodable { let active: Bool? }
-        return (try? JSONDecoder().decode(Reply.self, from: data))?.active ?? false
+    /// What was speaking when the door opened.
+    struct Hushed {
+        /// "talk", "lesson" or "narration"; nil when nothing was.
+        let kind: String?
+        let agentID: String?
+        static let nothing = Hushed(kind: nil, agentID: nil)
     }
 
-    /// Hand the listener's words to the talk; "stop" ends it.
-    static func talkDoor(_ text: String) async throws {
-        let (_, response) = try await post("/talk/door", ["text": text], timeout: 5)
-        if let http = response as? HTTPURLResponse, !(200..<300).contains(http.statusCode) {
-            throw NSError(domain: "AgentXVoice", code: http.statusCode,
-                          userInfo: [NSLocalizedDescriptionKey: "The talk has ended"])
-        }
+    /// Silence everything the daemon is saying. Never throws: no daemon
+    /// means nothing was speaking.
+    static func hush() async -> Hushed {
+        guard let (data, _) = try? await post("/voice/hush", [:], timeout: 2) else { return .nothing }
+        struct Reply: Decodable { let kind: String?; let agentId: String? }
+        let r = try? JSONDecoder().decode(Reply.self, from: data)
+        return Hushed(kind: r?.kind, agentID: r?.agentId)
+    }
+
+    /// Hand the listener's words through the door. True when an activity
+    /// took them (a talk or lesson answers; "stop" ends it); false means
+    /// nothing did, and they are an ordinary question.
+    static func door(_ text: String) async -> Bool {
+        guard let (_, response) = try? await post("/voice/door", ["text": text], timeout: 5),
+              let http = response as? HTTPURLResponse else { return false }
+        return (200..<300).contains(http.statusCode)
     }
 
     private static func post(_ path: String, _ body: [String: Any], timeout: TimeInterval) async throws -> (Data, URLResponse) {
@@ -103,9 +114,11 @@ enum AgentClient {
         struct UiMedia: Decodable { let type: String; let url: String; let caption: String? }
         struct Ui: Decodable { let buttons: [UiButton]?; let media: UiMedia? }
         struct Voice: Decodable { let elevenlabsVoiceId: String? }
+        struct Presence: Decodable { let mode: String? }
         struct Reply: Decodable {
             let agentId: String?
             let voice: Voice?
+            let presence: Presence?
             let text: String?
             let full: String?
             let ui: Ui?
@@ -144,6 +157,7 @@ enum AgentClient {
 
         return Answer(text: text, written: reply?.full,
                       buttons: buttons + extra, imageURL: image,
-                      durationMs: reply?.duration, agentID: reply?.agentId, voiceID: voiceID)
+                      durationMs: reply?.duration, agentID: reply?.agentId, voiceID: voiceID,
+                      presenceMode: reply?.presence?.mode)
     }
 }

package/apps/mac-voice/Sources/AgentXVoice/Speech.swift

@@ -72,6 +72,9 @@ enum Speech {
 
     // MARK: Text to speech
 
+    /// Silence whatever this app is saying (an answer or a step line).
+    static func stop() { Player.shared.stop() }
+
     /// `voiceID` is the answering agent's voice; nil means the global default.
     static func speak(_ text: String, voiceID: String? = nil) async {
         guard !text.isEmpty else { return }
@@ -154,6 +157,12 @@ final class Player: NSObject, AVAudioPlayerDelegate {
     func audioPlayerDidFinishPlaying(_ player: AVAudioPlayer, successfully flag: Bool) {
         finished?.resume(); finished = nil; self.player = nil
     }
+
+    /// Cut the line off now; the `play` awaiting it returns.
+    func stop() {
+        player?.stop()
+        finished?.resume(); finished = nil; player = nil
+    }
 }
 
 /// Logs to stderr AND to a file.