agentix-cli 0.35.0 → 0.36.0

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

@@ -4,7 +4,7 @@ import AppKit
 ///
 /// 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 window
+/// 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.
 ///
@@ -14,9 +14,19 @@ import AppKit
 ///   {"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`. EOF fades everything out.
+/// 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
@@ -35,73 +45,37 @@ enum Presence {
 
     // MARK: Windows
 
-    private static func panel(_ rect: NSRect) -> NSPanel {
+    /// 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 = .screenSaver
+        p.level = .floating
         p.isOpaque = false
         p.backgroundColor = .clear
         p.hasShadow = false
-        // Click-through: the person's clicks land on the app underneath.
-        p.ignoresMouseEvents = true
+        // 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, the initial badge, the name, and the speech bubble.
-    private final class AvatarView: NSView {
+    /// The arrow alone: the system cursor's silhouette, in the agent's colour.
+    private final class ArrowView: 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()
-        /// Wide on both sides of the tip, so the bubble can sit to the left
-        /// when the target is near the right edge of the screen.
-        static let size = NSSize(width: 720, height: 170)
+        static let size = NSSize(width: 30, height: 40)
         /// The arrow tip, in view coordinates (bottom-left origin).
-        static let tip = NSPoint(x: 360, y: size.height - 6)
-        var bubbleLeft = false { didSet { if bubbleLeft != oldValue { layoutBubble() } } }
+        static let tip = NSPoint(x: 4, y: size.height - 4)
 
-        init(color: NSColor, initial: String, name: String) {
-            self.color = color; self.initial = initial; self.name = name
-            super.init(frame: NSRect(origin: .zero, size: AvatarView.size))
-            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)
+        init(color: NSColor) {
+            self.color = color
+            super.init(frame: NSRect(origin: .zero, size: ArrowView.size))
         }
         required init?(coder: NSCoder) { fatalError() }
 
-        /// Under the badge and name, never over them.
-        func setBubble(_ text: String) {
-            box.isHidden = text.isEmpty
-            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.setFrameSize(NSSize(width: w + 20, height: h + 12))
-            layoutBubble()
-        }
-
-        func layoutBubble() {
-            let t = AvatarView.tip, s = box.frame.size
-            box.setFrameOrigin(NSPoint(x: bubbleLeft ? t.x - s.width - 4 : t.x + 16, y: t.y - 58 - s.height))
-        }
-
         override func draw(_ dirtyRect: NSRect) {
-            let t = AvatarView.tip
-            // The arrow: the system cursor's silhouette, in the agent's colour.
+            let t = ArrowView.tip
             let arrow = NSBezierPath()
             arrow.move(to: t)
             arrow.line(to: NSPoint(x: t.x, y: t.y - 26))
@@ -120,43 +94,58 @@ enum Presence {
             color.setFill(); arrow.fill()
             NSGraphicsContext.current?.restoreGraphicsState()
             NSColor.white.setStroke(); arrow.lineWidth = 1.5; arrow.stroke()
+        }
+    }
 
-            // The badge with the initial, and the name pill beside it.
-            let badge = NSRect(x: t.x + 16, y: t.y - 50, 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, color: .white)
+    // MARK: Pinned position
 
-            let attrs: [NSAttributedString.Key: Any] = [.font: NSFont.systemFont(ofSize: 11, weight: .semibold)]
-            let nameW = (name as NSString).size(withAttributes: attrs).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, color: .white)
-        }
+    /// 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
+    }
 
-        private func draw(_ s: String, in r: NSRect, size: CGFloat, weight: NSFont.Weight, color: NSColor) {
-            let a: [NSAttributedString.Key: Any] = [.font: NSFont.systemFont(ofSize: size, weight: weight), .foregroundColor: color]
-            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)
+    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 avatar: NSPanel
-        let view: AvatarView
+        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) {
+        init(color: NSColor, initial: String, name: String, posFile: String?) {
             self.color = color
-            view = AvatarView(color: color, initial: initial, name: name)
-            avatar = Presence.panel(NSRect(origin: .zero, size: AvatarView.size))
-            avatar.contentView = view
+            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
@@ -165,11 +154,25 @@ enum Presence {
             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)
-            avatar.alphaValue = 0
-            avatar.orderFrontRegardless()
-            NSAnimationContext.runAnimationGroup { $0.duration = 0.2; avatar.animator().alphaValue = 1 }
+            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 {
@@ -178,9 +181,16 @@ enum Presence {
         }
 
         func place(_ tip: CGPoint) {
-            avatar.setFrameOrigin(NSPoint(x: tip.x - AvatarView.tip.x, y: tip.y - AvatarView.tip.y))
-            let screen = NSScreen.screens.first(where: { $0.frame.contains(tip) }) ?? NSScreen.main
-            view.bubbleLeft = (screen?.visibleFrame.maxX ?? .greatestFiniteMagnitude) - tip.x < 360
+            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
@@ -205,7 +215,8 @@ enum Presence {
             guard let rect else { ring.orderOut(nil); return }
             ring.setFrame(Presence.toAppKit(rect).insetBy(dx: -6, dy: -6), display: true)
             ring.orderFrontRegardless()
-            avatar.orderFrontRegardless()
+            arrow.orderFrontRegardless()
+            tagPanel.orderFrontRegardless()
         }
 
         func handle(_ obj: [String: Any]) {
@@ -220,7 +231,8 @@ enum Presence {
                 glide(to: Presence.toAppKit(aim))
                 highlight((obj["highlight"] as? Bool ?? false) && w > 0 && h > 0 ? rect : nil)
             case "say":
-                view.setBubble(obj["text"] as? String ?? "")
+                tag.setBubble(obj["text"] as? String ?? "")
+                place(at)
             case "clear":
                 highlight(nil)
             case "park":
@@ -235,7 +247,8 @@ enum Presence {
             ring.orderOut(nil)
             NSAnimationContext.runAnimationGroup { ctx in
                 ctx.duration = 0.25
-                avatar.animator().alphaValue = 0
+                arrow.animator().alphaValue = 0
+                tagPanel.animator().alphaValue = 0
             } completionHandler: { done() }
         }
     }
@@ -248,18 +261,33 @@ enum Presence {
                        blue: CGFloat(v & 0xff) / 255, alpha: 1)
     }
 
-    /// Read commands until stdin closes.
-    static func run(name: String, initial: String, colorHex: String?) {
+    /// 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)
+        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 { ctl.handle(obj) }
+                DispatchQueue.main.async { lastCommand = Date(); ctl.handle(obj) }
             }
-            DispatchQueue.main.async { ctl.fadeOut { app.terminate(nil) } }
+            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

@@ -260,7 +260,9 @@ 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"))
+                 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]

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

@@ -54,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) {

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.