agentix-cli 0.57.0 → 0.58.0

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

@@ -28,11 +28,25 @@ enum Config {
         set { UserDefaults.standard.set(newValue, forKey: "showPill") }
     }
 
-    /// The orb overlay while listening, thinking and speaking. On by
-    /// default; off brings back the pill for those states.
-    static var showOrb: Bool {
-        get { UserDefaults.standard.object(forKey: "showOrb") as? Bool ?? true }
-        set { UserDefaults.standard.set(newValue, forKey: "showOrb") }
+    /// The pill's orb moves with the voice. On by default; off keeps it
+    /// still in every state, as Reduce Motion does.
+    static var animatedOrb: Bool {
+        get { UserDefaults.standard.object(forKey: "animatedOrb") as? Bool ?? true }
+        set { UserDefaults.standard.set(newValue, forKey: "animatedOrb") }
+    }
+
+    /// Where the pill was last dragged to (its bottom-left corner, in
+    /// screen points). Nil: the default corner.
+    static var pillOrigin: CGPoint? {
+        get {
+            guard let xy = UserDefaults.standard.array(forKey: "pillOrigin") as? [Double], xy.count == 2
+            else { return nil }
+            return CGPoint(x: xy[0], y: xy[1])
+        }
+        set {
+            if let p = newValue { UserDefaults.standard.set([Double(p.x), Double(p.y)], forKey: "pillOrigin") }
+            else { UserDefaults.standard.removeObject(forKey: "pillOrigin") }
+        }
     }
 
     /// The agent actually answering: `agentID`, else `chosenAgentID`, else

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

@@ -1,90 +1,61 @@
 import AppKit
 import SwiftUI
 
-/// The Siri-style overlay: an orb in the agent's colour that listens,
-/// thinks and speaks, with a line of words under it.
+/// The Siri-style orb at the head of the pill: the agent's colour, and it
+/// listens, thinks and speaks.
 ///
-/// Built from SwiftUI's own gradients, no animation library. The orb only
-/// moves while it is on screen: hidden, its timeline is paused and the
-/// microphone level is no longer read, so an idle assistant costs nothing.
-/// With Reduce Motion on it is a still picture that changes between
-/// states, never a loop.
+/// Built from SwiftUI's own gradients, no animation library. It only moves
+/// while it has something to show and is on screen: idle or hidden, its
+/// timeline is paused and the microphone level is no longer read, so an
+/// idle assistant costs nothing. With Reduce Motion on, or "Animated orb"
+/// off in the menu, it is a still picture that changes between states,
+/// never a loop.
 @MainActor
 final class OrbModel: ObservableObject {
-    enum Phase: Equatable { case hidden, listening, thinking, speaking }
+    enum Phase: Equatable { case idle, listening, thinking, speaking }
 
-    @Published var phase: Phase = .hidden
+    @Published var phase: Phase = .idle
     /// 0…1: the microphone while listening.
     @Published var level: Double = 0
     @Published var tint = NSColor(srgbRed: 0.078, green: 0.722, blue: 0.651, alpha: 1)
-    @Published var name = ""
-    /// What was heard, or what is being said.
-    @Published var line = ""
-    /// The step the agent is on, and for how long.
-    @Published var status = ""
+    /// The pill is on screen. Off, nothing moves.
+    @Published var onScreen = false
     @Published var reduceMotion = NSWorkspace.shared.accessibilityDisplayShouldReduceMotion
+    /// "Animated orb" in the menu. Off: a still orb, as with Reduce Motion.
+    @Published var animated = true
+
+    var still: Bool { reduceMotion || !animated }
+    /// The timeline runs only while there is motion to draw.
+    var paused: Bool { still || phase == .idle || !onScreen }
 }
 
-struct OrbView: View {
+/// The orb as the pill draws it: `OrbBody` at its design size, scaled down
+/// to `diameter`, in a frame with room around it for the glow.
+struct PillOrbView: View {
     @ObservedObject var model: OrbModel
-    @Environment(\.colorScheme) private var scheme
+    let diameter: CGFloat
+    let frameSize: CGFloat
 
-    /// The agent's colour, lifted in dark mode so the name stays readable.
-    private var nameColor: Color {
-        guard scheme == .dark, let c = model.tint.usingColorSpace(.sRGB) else { return Color(nsColor: model.tint) }
-        var h: CGFloat = 0, s: CGFloat = 0, b: CGFloat = 0, a: CGFloat = 0
-        c.getHue(&h, saturation: &s, brightness: &b, alpha: &a)
-        return Color(nsColor: NSColor(hue: h, saturation: s * 0.55, brightness: min(1, b + 0.35), alpha: 1))
-    }
+    /// The size OrbBody's blur, ring and gradients were drawn for.
+    private static let designSize: CGFloat = 96
 
     var body: some View {
-        VStack(spacing: 8) {
-            orb.frame(width: 96, height: 96).padding(.top, 4)
-            if !model.name.isEmpty {
-                Text(model.name.uppercased())
-                    .font(.system(size: 10.5, weight: .semibold, design: .monospaced))
-                    .tracking(0.8)
-                    .foregroundStyle(nameColor)
-            }
-            if !model.line.isEmpty {
-                Text(model.line)
-                    .font(.system(size: 13, weight: .medium))
-                    .foregroundStyle(.primary)
-                    .multilineTextAlignment(.center)
-                    .lineLimit(3)
-                    .truncationMode(.head)
-                    .fixedSize(horizontal: false, vertical: true)
-            }
-            if !model.status.isEmpty {
-                Text(model.status)
-                    .font(.system(size: 11))
-                    .foregroundStyle(.secondary)
-                    .lineLimit(1)
-                    .truncationMode(.middle)
-            }
-        }
-        .padding(.horizontal, 18)
-        .padding(.vertical, 14)
-        .frame(width: OrbOverlay.width)
-        .background(.regularMaterial, in: RoundedRectangle(cornerRadius: 22, style: .continuous))
-        .overlay(RoundedRectangle(cornerRadius: 22, style: .continuous)
-            .strokeBorder(Color.primary.opacity(0.08), lineWidth: 1))
-        .frame(maxHeight: .infinity, alignment: .top)
-    }
-
-    private var orb: some View {
-        let still = model.reduceMotion
-        let paused = still || model.phase == .hidden
-        return TimelineView(.animation(minimumInterval: 1.0 / 30, paused: paused)) { context in
+        let paused = model.paused
+        TimelineView(.animation(minimumInterval: 1.0 / 30, paused: paused)) { context in
             OrbBody(t: paused ? 0 : context.date.timeIntervalSinceReferenceDate,
-                    phase: model.phase, level: model.level, tint: model.tint, still: still)
+                    phase: model.phase, level: model.level, tint: model.tint, still: model.still,
+                    ringWidth: 5)
+                .frame(width: Self.designSize, height: Self.designSize)
+                .scaleEffect(diameter / Self.designSize)
         }
+        .frame(width: frameSize, height: frameSize)
+        .accessibilityElement()
         .accessibilityLabel(Text(accessibilityText))
     }
 
     private var accessibilityText: String {
         switch model.phase {
-        case .hidden: return ""
+        case .idle: return "Idle"
         case .listening: return "Listening"
         case .thinking: return "Thinking"
         case .speaking: return "Speaking"
@@ -92,6 +63,97 @@ struct OrbView: View {
     }
 }
 
+/// The orb's view in the pill. Clicks go through it to the pill, so
+/// pressing on the orb drags the pill like anywhere else on it.
+@MainActor
+final class PillOrb: NSHostingView<PillOrbView> {
+    private let driver: OrbDriver
+    var model: OrbModel { driver.model }
+
+    /// The microphone's RMS level, read while listening. Set by the app.
+    var levelSource: (() -> Float)? {
+        get { driver.levelSource }
+        set { driver.levelSource = newValue; driver.watchLevel() }
+    }
+
+    init(diameter: CGFloat, frameSize: CGFloat) {
+        driver = OrbDriver()
+        super.init(rootView: PillOrbView(model: driver.model, diameter: diameter, frameSize: frameSize))
+    }
+
+    @available(*, unavailable)
+    required init(rootView: PillOrbView) { fatalError("use init(diameter:frameSize:)") }
+
+    @available(*, unavailable)
+    required init?(coder: NSCoder) { fatalError("not from a nib") }
+
+    override func hitTest(_ point: NSPoint) -> NSView? { nil }
+
+    /// Show `phase` in `tint`. Cheap to call on every render: SwiftUI only
+    /// redraws what changed.
+    func show(_ phase: OrbModel.Phase, tint: NSColor) {
+        let model = driver.model
+        if model.tint != tint { model.tint = tint }
+        if model.phase != phase {
+            model.phase = phase
+            if phase != .listening { model.level = 0 }
+        }
+        driver.watchLevel()
+    }
+
+    /// The pill came on screen or went off it.
+    func setOnScreen(_ on: Bool) {
+        let model = driver.model
+        guard model.onScreen != on else { return }
+        model.onScreen = on
+        if !on { model.level = 0 }
+        driver.watchLevel()
+    }
+
+    /// "Animated orb" in the menu.
+    func setAnimated(_ on: Bool) {
+        guard driver.model.animated != on else { return }
+        driver.model.animated = on
+        driver.watchLevel()
+    }
+}
+
+/// Reads the microphone into the model while listening, and follows the
+/// Reduce Motion setting.
+@MainActor
+private final class OrbDriver {
+    let model = OrbModel()
+    var levelSource: (() -> Float)?
+    private var levelTimer: Timer?
+    private var motionObserver: NSObjectProtocol?
+
+    init() {
+        motionObserver = NSWorkspace.shared.notificationCenter.addObserver(
+            forName: NSWorkspace.accessibilityDisplayOptionsDidChangeNotification,
+            object: nil, queue: .main) { [weak self] _ in
+            MainActor.assumeIsolated {
+                guard let self else { return }
+                self.model.reduceMotion = NSWorkspace.shared.accessibilityDisplayShouldReduceMotion
+                self.watchLevel()
+            }
+        }
+    }
+
+    /// The microphone is read only while listening, on screen, with
+    /// motion allowed.
+    func watchLevel() {
+        let wanted = model.phase == .listening && model.onScreen && !model.still && levelSource != nil
+        if !wanted { levelTimer?.invalidate(); levelTimer = nil; return }
+        guard levelTimer == nil else { return }
+        levelTimer = Timer.scheduledTimer(withTimeInterval: 1.0 / 20, repeats: true) { [weak self] _ in
+            MainActor.assumeIsolated {
+                guard let self, let read = self.levelSource else { return }
+                self.model.level = OrbMath.smooth(self.model.level, toward: OrbMath.level(fromRMS: read()))
+            }
+        }
+    }
+}
+
 /// One frame of the orb at time `t`.
 struct OrbBody: View {
     let t: Double
@@ -100,11 +162,14 @@ struct OrbBody: View {
     let tint: NSColor
     /// Reduce Motion: a still orb, sized and shaded by state alone.
     let still: Bool
+    /// The thinking ring's stroke at the 96-point design size. The pill
+    /// draws the orb small, so it passes a thicker one that still reads.
+    var ringWidth: CGFloat = 2.2
 
     /// How much the orb swells and glows, 0…1.
     private var energy: Double {
         switch phase {
-        case .hidden: return 0
+        case .idle: return 0
         case .listening: return still ? 0.45 : 0.12 + 0.88 * level
         case .thinking: return still ? 0.2 : 0.22 + 0.08 * sin(t * 2.2)
         case .speaking: return still ? 0.7 : OrbMath.speakingEnvelope(at: t)
@@ -114,7 +179,7 @@ struct OrbBody: View {
     /// How fast the colours drift.
     private var speed: Double {
         switch phase {
-        case .hidden: return 0
+        case .idle: return 0
         case .listening: return 0.5 + level * 1.5
         case .thinking: return 1.3
         case .speaking: return 0.9
@@ -136,7 +201,7 @@ struct OrbBody: View {
             if phase == .thinking {
                 Circle()
                     .trim(from: 0, to: 0.28)
-                    .stroke(Color.white.opacity(0.75), style: StrokeStyle(lineWidth: 2.2, lineCap: .round))
+                    .stroke(Color.white.opacity(0.75), style: StrokeStyle(lineWidth: ringWidth, lineCap: .round))
                     .rotationEffect(.radians(still ? -.pi / 2 : t * 3.1))
                     .scaleEffect(scale * 0.86)
             } else {
@@ -206,106 +271,3 @@ struct OrbBody: View {
         ]
     }
 }
-
-/// The window the orb lives in: floating, on every Space, click-through
-/// and never key, so the app in front keeps the keyboard.
-private final class OrbPanel: NSPanel {
-    override var canBecomeKey: Bool { false }
-    override var canBecomeMain: Bool { false }
-}
-
-@MainActor
-final class OrbOverlay {
-    static let width: CGFloat = 300
-    private static let height: CGFloat = 250
-
-    let model = OrbModel()
-    private let panel: NSPanel
-    private let host: NSHostingView<OrbView>
-    private var levelTimer: Timer?
-    private var motionObserver: NSObjectProtocol?
-
-    /// The microphone's RMS level, read while listening. Set by the app.
-    var levelSource: (() -> Float)?
-
-    init() {
-        panel = OrbPanel(contentRect: NSRect(x: 0, y: 0, width: Self.width, height: Self.height),
-                         styleMask: [.borderless, .nonactivatingPanel],
-                         backing: .buffered, defer: true)
-        panel.isFloatingPanel = true
-        panel.level = .floating
-        panel.collectionBehavior = [.canJoinAllSpaces, .fullScreenAuxiliary, .stationary, .ignoresCycle]
-        panel.isOpaque = false
-        panel.backgroundColor = .clear
-        panel.hasShadow = false
-        panel.ignoresMouseEvents = true
-        panel.hidesOnDeactivate = false
-        host = NSHostingView(rootView: OrbView(model: model))
-        host.frame = NSRect(x: 0, y: 0, width: Self.width, height: Self.height)
-        panel.contentView = host
-
-        let model = self.model
-        motionObserver = NSWorkspace.shared.notificationCenter.addObserver(
-            forName: NSWorkspace.accessibilityDisplayOptionsDidChangeNotification,
-            object: nil, queue: .main) { _ in
-            MainActor.assumeIsolated {
-                model.reduceMotion = NSWorkspace.shared.accessibilityDisplayShouldReduceMotion
-            }
-        }
-    }
-
-    var isVisible: Bool { panel.isVisible }
-
-    /// Where the orb's card ends on screen, for the answer card to sit
-    /// under. Nil while hidden.
-    var contentFrame: NSRect? {
-        guard panel.isVisible else { return nil }
-        let h = min(Self.height, host.fittingSize.height)
-        return NSRect(x: panel.frame.minX, y: panel.frame.maxY - h, width: Self.width, height: h)
-    }
-
-    func show(_ phase: OrbModel.Phase, name: String, tint: NSColor, line: String, status: String) {
-        guard phase != .hidden else { hide(); return }
-        model.name = name
-        model.tint = tint
-        model.line = line
-        model.status = status
-        if model.phase != phase {
-            model.phase = phase
-            if phase != .listening { model.level = 0 }
-        }
-        watchLevel()
-        if !panel.isVisible {
-            position()
-            panel.orderFrontRegardless()
-        }
-    }
-
-    func hide() {
-        model.phase = .hidden
-        model.level = 0
-        watchLevel()
-        panel.orderOut(nil)
-    }
-
-    /// Top right, under the menu bar, where macOS puts Siri.
-    private func position() {
-        guard let screen = NSScreen.main else { return }
-        let v = screen.visibleFrame
-        panel.setFrameOrigin(NSPoint(x: v.maxX - Self.width - 16, y: v.maxY - Self.height - 10))
-    }
-
-    /// The microphone is read only while listening, on screen, with
-    /// motion allowed.
-    private func watchLevel() {
-        let wanted = model.phase == .listening && !model.reduceMotion && levelSource != nil
-        if !wanted { levelTimer?.invalidate(); levelTimer = nil; return }
-        guard levelTimer == nil else { return }
-        levelTimer = Timer.scheduledTimer(withTimeInterval: 1.0 / 20, repeats: true) { [weak self] _ in
-            MainActor.assumeIsolated {
-                guard let self, let read = self.levelSource else { return }
-                self.model.level = OrbMath.smooth(self.model.level, toward: OrbMath.level(fromRMS: read()))
-            }
-        }
-    }
-}

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

@@ -6,9 +6,24 @@ import AppKit
 /// focus out of whatever you were doing — the entire point of a voice
 /// assistant is that you don't stop working to use it. It floats above
 /// normal windows, joins every Space, and is deliberately small.
+///
+/// It is the one floating widget: a small live orb at its head (Orb.swift)
+/// in the answering agent's colour, the state or the words beside it, and
+/// a close button that shows on hover. Drag it anywhere; the place is
+/// remembered across launches.
 final class Panel: NSPanel {
+    static let size = NSSize(width: 284, height: 54)
+    /// The orb's diameter, and the square it draws in with room for its glow.
+    private static let orbDiameter: CGFloat = 36
+    private static let orbFrame: CGFloat = 52
+
     private let label = NSTextField(labelWithString: "")
-    private let orb = NSView()
+    let orb = PillOrb(diameter: Panel.orbDiameter, frameSize: Panel.orbFrame)
+    private let closeButton = NSButton()
+    /// Hidden by close, Esc or the menu until the next talk key.
+    private(set) var dismissed = false
+    /// Set while the app moves the pill, so only a drag is remembered.
+    private var placing = false
 
     /// Scrolls text too long for the pill instead of truncating it.
     ///
@@ -48,16 +63,24 @@ final class Panel: NSPanel {
     /// The target agent's name, shown while listening or answering.
     var agentName: () -> String = { "" }
 
+    /// The colour of the agent shown, for the orb.
+    var agentTint: () -> NSColor = { Brand.accent }
+
     /// Stay on screen when idle. Off: the pill shows only while active.
     var alwaysVisible = false
 
-    /// The orb overlay shows listening, thinking and speaking, so the
-    /// pill stays out of the way then; it still shows idle and errors.
-    var yieldsActiveStates = false
-
     /// Told of every state rendered, so the menu-bar icon can follow.
     var onRender: ((State) -> Void)?
 
+    /// Close button or Esc. The app stops speech and calls `dismiss()`.
+    var onDismiss: (() -> Void)?
+
+    /// The pill moved, by a drag or a reset. The answer card follows.
+    var onMove: (() -> Void)?
+
+    /// The last state rendered, to draw again after a dismiss or a move.
+    private var current = State.idle
+
     override func mouseUp(with event: NSEvent) {
         defer { pressedAt = nil }
         if let start = pressedAt {
@@ -112,11 +135,14 @@ final class Panel: NSPanel {
         /// is a running commentary and belongs in body type.
         var isMeta: Bool { if case .idle = self { return true }; return false }
 
-        /// Listening, thinking or speaking: what the orb shows.
-        var isActive: Bool {
+        /// What the orb does: follows the voice, turns a ring, or pulses.
+        /// Idle and errors hold it still.
+        var orbPhase: OrbModel.Phase {
             switch self {
-            case .idle, .error: return false
-            default: return true
+            case .idle, .error: return .idle
+            case .listening: return .listening
+            case .thinking, .working: return .thinking
+            case .speaking, .saying: return .speaking
             }
         }
     }
@@ -130,7 +156,7 @@ final class Panel: NSPanel {
     var onClick: (() -> Void)?
 
     init() {
-        super.init(contentRect: NSRect(x: 0, y: 0, width: 230, height: 54),
+        super.init(contentRect: NSRect(origin: .zero, size: Self.size),
                    styleMask: [.borderless, .nonactivatingPanel],
                    backing: .buffered, defer: false)
         isFloatingPanel = true
@@ -142,7 +168,7 @@ final class Panel: NSPanel {
         isMovableByWindowBackground = true
         hidesOnDeactivate = false
 
-        let blur = NSVisualEffectView(frame: NSRect(origin: .zero, size: NSSize(width: 230, height: 54)))
+        let blur = NSVisualEffectView(frame: NSRect(origin: .zero, size: Self.size))
         blur.material = .hudWindow
         blur.blendingMode = .behindWindow
         blur.state = .active
@@ -170,16 +196,19 @@ final class Panel: NSPanel {
         tint.autoresizingMask = [.width, .height]
         blur.addSubview(tint)
 
-        orb.wantsLayer = true
-        orb.layer?.cornerRadius = 4
-        orb.frame = NSRect(x: 18, y: 22, width: 8, height: 8)
+        // The orb, centred 28 points from the left edge; its square is
+        // larger than the orb so the glow is not cut off.
+        let h = Self.size.height
+        orb.frame = NSRect(x: 28 - Self.orbFrame / 2, y: (h - Self.orbFrame) / 2,
+                           width: Self.orbFrame, height: Self.orbFrame)
         blur.addSubview(orb)
 
-        // A clipping window the label slides behind.
-        let clipView = NSView(frame: NSRect(x: 38, y: 17, width: 180, height: 20))
+        // A clipping window the label slides behind. Clicks pass through
+        // it, so pressing on the words drags the pill too.
+        let clipView = PassThroughView(frame: NSRect(x: 54, y: 17, width: 196, height: 20))
         clipView.wantsLayer = true
         clipView.layer?.masksToBounds = true
-        label.frame = NSRect(x: 0, y: 0, width: 180, height: 20)
+        label.frame = NSRect(x: 0, y: 0, width: 196, height: 20)
         label.font = Brand.body(size: 12)
         label.lineBreakMode = .byClipping
         label.wantsLayer = true
@@ -187,15 +216,115 @@ final class Panel: NSPanel {
         blur.addSubview(clipView)
         clip = clipView
 
+        // Close, shown while the pointer is over the pill. Its space is
+        // kept when hidden, so the words never jump under it.
+        closeButton.frame = NSRect(x: Self.size.width - 28, y: (h - 18) / 2, width: 18, height: 18)
+        closeButton.isBordered = false
+        closeButton.bezelStyle = .regularSquare
+        closeButton.imagePosition = .imageOnly
+        closeButton.image = NSImage(systemSymbolName: "xmark.circle.fill", accessibilityDescription: "Hide")
+        closeButton.contentTintColor = .secondaryLabelColor
+        closeButton.toolTip = "Hide (Esc)"
+        closeButton.setAccessibilityLabel("Hide the pill")
+        closeButton.target = self
+        closeButton.action = #selector(closeClicked)
+        closeButton.isHidden = true
+        blur.addSubview(closeButton)
+        blur.addTrackingArea(NSTrackingArea(rect: .zero,
+                                            options: [.mouseEnteredAndExited, .activeAlways, .inVisibleRect],
+                                            owner: self, userInfo: nil))
+
         render(.idle)
-        positionBottomRight()
+        restorePosition()
+
+        NotificationCenter.default.addObserver(self, selector: #selector(moved),
+                                               name: NSWindow.didMoveNotification, object: self)
+        // A monitor unplugged or rearranged: bring the pill back on screen.
+        NotificationCenter.default.addObserver(self, selector: #selector(screensChanged),
+                                               name: NSApplication.didChangeScreenParametersNotification, object: nil)
+    }
+
+    // MARK: Place
+
+    /// Where it was left, kept on a screen that still exists; the
+    /// bottom-right corner the first time.
+    @MainActor
+    func restorePosition() {
+        let screens = NSScreen.screens.map(\.visibleFrame)
+        let fallback = (NSScreen.main ?? NSScreen.screens.first)?.visibleFrame ?? .zero
+        place(PillPlacement.clamp(saved: Config.pillOrigin, size: frame.size, screens: screens, fallback: fallback))
+    }
+
+    /// Back to the bottom-right corner, forgetting where it was dragged.
+    @MainActor
+    func resetPosition() {
+        Config.pillOrigin = nil
+        restorePosition()
+    }
+
+    @MainActor
+    private func place(_ origin: NSPoint) {
+        placing = true
+        setFrameOrigin(origin)
+        placing = false
+        onMove?()
+    }
+
+    /// Remember a drag. Moves the app makes itself are not saved, so a
+    /// reset or a clamp never overwrites where the user put it.
+    @objc private func moved() {
+        MainActor.assumeIsolated {
+            guard !placing else { return }
+            Config.pillOrigin = frame.origin
+            onMove?()
+        }
     }
 
-    /// Bottom-right, clear of the Dock — out of the way but visible.
-    private func positionBottomRight() {
-        guard let screen = NSScreen.main else { return }
-        let v = screen.visibleFrame
-        setFrameOrigin(NSPoint(x: v.maxX - frame.width - 24, y: v.minY + 24))
+    @objc private func screensChanged() {
+        MainActor.assumeIsolated { restorePosition() }
+    }
+
+    // MARK: Show and hide
+
+    /// Close, Esc or the menu: hidden until `summon()`, whatever is
+    /// rendered meanwhile.
+    @MainActor
+    func dismiss() {
+        dismissed = true
+        hide()
+    }
+
+    /// The talk key: allowed on screen again.
+    @MainActor
+    func summon() {
+        guard dismissed else { return }
+        dismissed = false
+        render(current)
+    }
+
+    @MainActor
+    private func show() {
+        orb.setOnScreen(true)
+        if !isVisible { orderFrontRegardless() }
+    }
+
+    @MainActor
+    private func hide() {
+        closeButton.isHidden = true
+        orb.setOnScreen(false)
+        if isVisible { orderOut(nil) }
+    }
+
+    @objc private func closeClicked() { onDismiss?() }
+
+    override func mouseEntered(with event: NSEvent) { closeButton.isHidden = false }
+    override func mouseExited(with event: NSEvent) { closeButton.isHidden = true }
+
+    /// Esc, once the pill has been clicked and so holds the keyboard.
+    override func cancelOperation(_ sender: Any?) { onDismiss?() }
+
+    override func keyDown(with event: NSEvent) {
+        if event.keyCode == 53 { onDismiss?() } else { super.keyDown(with: event) }
     }
 
     /// AppKit is not thread-safe. Marking this explicitly means a stray
@@ -203,25 +332,29 @@ final class Panel: NSPanel {
     /// corruption that traps somewhere unrelated an hour later.
     @MainActor
     func render(_ state: State) {
-        orb.layer?.backgroundColor = state.color.cgColor
-        // A soft halo on the dot while active: the same --nq-ring-accent
-        // idea, and the only ornament on the pill.
-        orb.layer?.shadowColor = state.color.cgColor
-        orb.layer?.shadowOpacity = state.isMeta ? 0 : 0.55
-        orb.layer?.shadowRadius = 5
-        orb.layer?.shadowOffset = .zero
+        current = state
+        // The agent's colour, except where the state is the message: an
+        // error, or notifications held.
+        let tint: NSColor
+        switch state {
+        case .error: tint = Brand.alert
+        case .idle where Hold.isOn: tint = Brand.warn
+        default: tint = agentTint()
+        }
+        orb.show(state.orbPhase, tint: tint)
 
         if state.isMeta {
             stopMarquee()
             label.attributedStringValue = Brand.metaString(state.text, color: state.color)
             label.frame.origin.x = 0
         } else {
-            label.textColor = state.color
+            // The orb carries the state now, so the words are plain text
+            // that reads in both themes. Errors keep their colour.
+            if case .error = state { label.textColor = state.color } else { label.textColor = .labelColor }
             setText(named(state))
         }
 
-        let yield = yieldsActiveStates && state.isActive
-        if (state.isMeta && !alwaysVisible) || yield { orderOut(nil) } else { orderFrontRegardless() }
+        if dismissed || (state.isMeta && !alwaysVisible) { hide() } else { show() }
         onRender?(state)
     }
 
@@ -283,7 +416,13 @@ final class Panel: NSPanel {
         marqueeText = ""
     }
 
-    // Borderless panels refuse key status unless told otherwise; without
-    // this the widget cannot show a caret or take any future text input.
+    // Borderless panels refuse key status unless told otherwise. The pill
+    // takes it only when clicked (showing it never does: that is
+    // orderFrontRegardless, not makeKey), so Esc can reach it then.
     override var canBecomeKey: Bool { true }
 }
+
+/// A view clicks go through, to the pill behind it.
+private final class PassThroughView: NSView {
+    override func hitTest(_ point: NSPoint) -> NSView? { nil }
+}

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

@@ -0,0 +1,70 @@
+import CoreGraphics
+
+/// Where the pill and its answer card go on screen, kept free of AppKit so
+/// the tests can check it without a window. Frames are in screen
+/// coordinates, origin bottom-left, as AppKit uses them.
+enum PillPlacement {
+    /// Distance from the screen's edges for the default corner.
+    static let inset: CGFloat = 24
+    /// Space between the pill and the answer card.
+    static let cardGap: CGFloat = 8
+
+    /// Bottom-right of `visible` (a screen's frame minus the menu bar and
+    /// Dock), clear of both.
+    static func defaultOrigin(size: CGSize, visible: CGRect) -> CGPoint {
+        CGPoint(x: visible.maxX - size.width - inset, y: visible.minY + inset)
+    }
+
+    /// A saved position made safe: the pill lands fully on the screen it
+    /// overlaps most. When it overlaps none (the monitor it was on has been
+    /// unplugged, or the saved value is nonsense) it goes back to the
+    /// default corner of `fallback`. Nil `saved`: the default corner.
+    static func clamp(saved: CGPoint?, size: CGSize, screens: [CGRect], fallback: CGRect) -> CGPoint {
+        guard let saved, saved.x.isFinite, saved.y.isFinite else {
+            return defaultOrigin(size: size, visible: fallback)
+        }
+        let frame = CGRect(origin: saved, size: size)
+        var best: CGRect?
+        var bestArea: CGFloat = 0
+        for screen in screens {
+            let overlap = screen.intersection(frame)
+            guard !overlap.isNull else { continue }
+            let area = overlap.width * overlap.height
+            if area > bestArea { bestArea = area; best = screen }
+        }
+        guard let screen = best, bestArea > 0 else {
+            return defaultOrigin(size: size, visible: fallback)
+        }
+        return inside(frame, screen).origin
+    }
+
+    /// Which side of the pill the answer card opens on, and where.
+    struct Card: Equatable {
+        let origin: CGPoint
+        /// True: above the pill. False: below it.
+        let above: Bool
+    }
+
+    /// Above the pill when there is at least as much room above it as
+    /// below, else below. Right edges line up with the pill's, and the
+    /// card is kept on the screen.
+    static func card(size: CGSize, pill: CGRect, visible: CGRect) -> Card {
+        let roomAbove = visible.maxY - pill.maxY
+        let roomBelow = pill.minY - visible.minY
+        let above = roomAbove >= roomBelow
+        let y = above ? pill.maxY + cardGap : pill.minY - cardGap - size.height
+        let frame = CGRect(x: pill.maxX - size.width, y: y, width: size.width, height: size.height)
+        return Card(origin: inside(frame, visible).origin, above: above)
+    }
+
+    /// `frame` moved the least distance that puts it inside `bounds`. A
+    /// frame larger than `bounds` keeps its top-left corner in view.
+    static func inside(_ frame: CGRect, _ bounds: CGRect) -> CGRect {
+        var f = frame
+        if f.maxX > bounds.maxX { f.origin.x = bounds.maxX - f.width }
+        if f.minX < bounds.minX { f.origin.x = bounds.minX }
+        if f.minY < bounds.minY { f.origin.y = bounds.minY }
+        if f.maxY > bounds.maxY { f.origin.y = bounds.maxY - f.height }
+        return f
+    }
+}

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

@@ -22,9 +22,8 @@ final class ResultCard: NSPanel {
     private let links = NSStackView()
     private let thumb = NSImageView()
 
-    /// The orb's frame on screen while it shows, for the card to slide in
-    /// under it. Nil: the card sits above the pill. Set by the app.
-    var anchor: (() -> NSRect?)?
+    /// The pill's frame on screen, which the card attaches to. Set by the app.
+    var anchor: (() -> NSRect)?
 
     init() {
         super.init(contentRect: NSRect(x: 0, y: 0, width: 380, height: 260),
@@ -129,19 +128,32 @@ final class ResultCard: NSPanel {
         }
 
         if let c = contentView { layout(c) }
-        if let orb = anchor?() {
-            slideIn(under: orb)
-        } else {
-            positionAboveWidget()
-            orderFrontRegardless()
-        }
+        slideIn()
+    }
+
+    /// Where the card goes against the pill: above it when there is at
+    /// least as much room above as below, else below; right edges aligned.
+    @MainActor
+    private func placement() -> PillPlacement.Card? {
+        guard let pill = anchor?() else { return nil }
+        let screen = NSScreen.screens.first { $0.frame.intersects(pill) } ?? NSScreen.main
+        guard let visible = screen?.visibleFrame else { return nil }
+        return PillPlacement.card(size: frame.size, pill: pill, visible: visible)
     }
 
-    /// Under the orb, right edges aligned, sliding down into place. With
-    /// Reduce Motion it simply appears there.
+    /// The pill moved: the open card moves with it, without animation.
     @MainActor
-    private func slideIn(under orb: NSRect) {
-        let target = NSPoint(x: orb.maxX - frame.width, y: orb.minY - frame.height - 8)
+    func follow() {
+        guard isVisible, let spot = placement() else { return }
+        setFrameOrigin(spot.origin)
+    }
+
+    /// Slides out of the pill into place: up when it opens above, down
+    /// when below. With Reduce Motion it simply appears there.
+    @MainActor
+    private func slideIn() {
+        guard let spot = placement() else { alphaValue = 1; orderFrontRegardless(); return }
+        let target = spot.origin
         let wasVisible = isVisible
         guard !wasVisible, !NSWorkspace.shared.accessibilityDisplayShouldReduceMotion else {
             setFrameOrigin(target)
@@ -149,7 +161,7 @@ final class ResultCard: NSPanel {
             orderFrontRegardless()
             return
         }
-        setFrameOrigin(NSPoint(x: target.x, y: target.y + 18))
+        setFrameOrigin(NSPoint(x: target.x, y: target.y + (spot.above ? -18 : 18)))
         alphaValue = 0
         orderFrontRegardless()
         NSAnimationContext.runAnimationGroup { ctx in
@@ -165,14 +177,6 @@ final class ResultCard: NSPanel {
         NSWorkspace.shared.open(u)
     }
 
-    /// Sits just above the pill so the two read as one thing.
-    private func positionAboveWidget() {
-        guard let screen = NSScreen.main else { return }
-        let v = screen.visibleFrame
-        setFrameOrigin(NSPoint(x: v.maxX - frame.width - 24, y: v.minY + 24 + 54 + 10))
-        alphaValue = 1
-    }
-
     override var canBecomeKey: Bool { true }
 }
 

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

@@ -34,7 +34,13 @@ final class StatusMenu: NSObject, NSMenuDelegate {
     var onHoldChanged: ((Bool) -> Void)?
     var onTargetChanged: ((String) -> Void)?
     var onPillChanged: ((Bool) -> Void)?
-    var onOrbChanged: ((Bool) -> Void)?
+    var onAnimatedOrbChanged: ((Bool) -> Void)?
+    /// Hide the pill and stop speech, as its close button does.
+    var onHidePill: (() -> Void)?
+    /// Put the pill back in the bottom-right corner.
+    var onResetPosition: (() -> Void)?
+    /// Whether the pill is on screen, for "Hide pill".
+    var pillVisible: () -> Bool = { false }
     var onSettings: (() -> Void)?
 
     override init() {
@@ -178,9 +184,13 @@ final class StatusMenu: NSObject, NSMenuDelegate {
         let pill = action("Show floating pill", #selector(togglePill), key: "")
         pill.state = Config.showPill ? .on : .off
         menu.addItem(pill)
-        let orb = action("Show orb", #selector(toggleOrb), key: "")
-        orb.state = Config.showOrb ? .on : .off
+        let orb = action("Animated orb", #selector(toggleOrb), key: "")
+        orb.state = Config.animatedOrb ? .on : .off
         menu.addItem(orb)
+        let hide = action("Hide pill", #selector(hidePill), key: "")
+        hide.isEnabled = pillVisible()
+        menu.addItem(hide)
+        menu.addItem(action("Reset position", #selector(resetPosition), key: ""))
 
         menu.addItem(.separator())
         menu.addItem(action("Settings…", #selector(openSettings), key: ","))
@@ -232,10 +242,13 @@ final class StatusMenu: NSObject, NSMenuDelegate {
     }
 
     @objc private func toggleOrb() {
-        Config.showOrb.toggle()
-        onOrbChanged?(Config.showOrb)
+        Config.animatedOrb.toggle()
+        onAnimatedOrbChanged?(Config.animatedOrb)
     }
 
+    @objc private func hidePill() { onHidePill?() }
+    @objc private func resetPosition() { onResetPosition?() }
+
     @objc private func openSettings() { onSettings?() }
     @objc private func openDashboardHome() { openDashboard("/admin") }
     @objc private func openHistory() { openDashboard("/activity") }

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

@@ -19,9 +19,6 @@ final class App: NSObject, NSApplicationDelegate {
     private let panel = Panel()
     private let statusMenu = StatusMenu()
     private let card = ResultCard()
-    private let orb = OrbOverlay()
-    /// What the listener said this turn, shown under the orb.
-    private var heardLine = ""
     /// The agent whose by-name answer is on screen now, while no turn runs.
     private var asideSpeaker: String?
     private let recorder = Recorder()
@@ -164,37 +161,28 @@ final class App: NSObject, NSApplicationDelegate {
         Log.info("settings: talk \(saved.general.hotkeys.talk), speech to text \(saved.general.stt)")
     }
 
-    /// Who the panel and orb name: the agent a shortcut is asking, a
-    /// by-name answer being spoken, else the agent our turn is asking,
-    /// else the target.
+    /// Who the pill names and whose colour its orb wears: the agent a
+    /// shortcut is asking, a by-name answer being spoken, else the agent
+    /// our turn is asking, else the target.
     private var shownAgent: String {
         if let forcedAgent, recorder.isRecording { return forcedAgent }
         if let asideSpeaker { return asideSpeaker }
         return busy && !turnAgent.isEmpty ? turnAgent : Config.effectiveAgentID
     }
 
-    /// The orb follows the pill's state: listening, thinking or speaking
-    /// show it; idle and errors hide it.
-    private func renderOrb(_ state: Panel.State) {
-        guard Config.showOrb else { orb.hide(); return }
-        let who = shownAgent
-        let name = who.isEmpty ? "" : statusMenu.name(of: who)
-        let tint = statusMenu.color(of: who)
-        switch state {
-        case .idle, .error:
-            orb.hide()
-        case .listening:
-            heardLine = ""
-            orb.show(.listening, name: name, tint: tint, line: "Listening…", status: "")
-        case .thinking:
-            orb.show(.thinking, name: name, tint: tint, line: heardLine, status: "Thinking…")
-        case .working(let step, let secs):
-            orb.show(.thinking, name: name, tint: tint, line: heardLine, status: "\(step) · \(secs)s")
-        case .speaking:
-            orb.show(.speaking, name: name, tint: tint, line: heardLine, status: "")
-        case .saying(let text):
-            orb.show(.speaking, name: name, tint: tint, line: text, status: "")
+    /// Close, Esc or "Hide pill": the pill goes and the voice stops, the
+    /// same stop as ⌘⌥. An open microphone closes without sending. The
+    /// next talk key brings the pill back.
+    private func dismissPill() {
+        Log.info("pill: dismissed")
+        panel.dismiss()
+        if recorder.isRecording {
+            stopPolling()
+            _ = recorder.stop()
+            forcedAgent = nil
+            talkCheck = nil
         }
+        stopSpeaking()
     }
 
     /// ⌘⌥V. Everything except the hotkey lives in `agentx paste`.
@@ -243,30 +231,33 @@ final class App: NSObject, NSApplicationDelegate {
     func applicationDidFinishLaunching(_ note: Notification) {
         NSApp.setActivationPolicy(.accessory)
         retireOlderInstances()
-        panel.onRender = { [weak self] state in
-            self?.statusMenu.show(state)
-            self?.renderOrb(state)
-        }
+        panel.onRender = { [weak self] state in self?.statusMenu.show(state) }
         panel.contextMenu = { [weak self] in self?.statusMenu.menu ?? NSMenu() }
         panel.agentName = { [weak self] in
             guard let self else { return "" }
             let who = self.shownAgent
             return who.isEmpty ? "" : self.statusMenu.name(of: who)
         }
-        panel.alwaysVisible = Config.showPill
-        panel.yieldsActiveStates = Config.showOrb
-        orb.levelSource = { [weak self] in self?.recorder.level ?? 0 }
-        card.anchor = { [weak self] in self?.orb.contentFrame }
-        statusMenu.onOrbChanged = { [weak self] on in
-            guard let self else { return }
-            self.panel.yieldsActiveStates = on
-            if !on { self.orb.hide() }
-            if !self.busy && !self.recorder.isRecording { self.panel.render(.idle) }
+        panel.agentTint = { [weak self] in
+            guard let self else { return Brand.accent }
+            return self.statusMenu.color(of: self.shownAgent)
         }
+        panel.alwaysVisible = Config.showPill
+        panel.orb.setAnimated(Config.animatedOrb)
+        panel.orb.levelSource = { [weak self] in self?.recorder.level ?? 0 }
+        panel.onDismiss = { [weak self] in self?.dismissPill() }
+        panel.onMove = { [weak self] in self?.card.follow() }
+        card.anchor = { [weak self] in self?.panel.frame ?? .zero }
+        statusMenu.pillVisible = { [weak self] in self?.panel.isVisible ?? false }
+        statusMenu.onHidePill = { [weak self] in self?.dismissPill() }
+        statusMenu.onResetPosition = { [weak self] in self?.panel.resetPosition() }
+        statusMenu.onAnimatedOrbChanged = { [weak self] on in self?.panel.orb.setAnimated(on) }
         panel.render(.idle)
         statusMenu.onPillChanged = { [weak self] on in
             guard let self else { return }
             self.panel.alwaysVisible = on
+            // Asking for the pill brings back one that was dismissed.
+            if on { self.panel.summon() }
             if !self.busy && !self.recorder.isRecording { self.panel.render(.idle) }
         }
         statusMenu.onTargetChanged = { [weak self] id in
@@ -440,6 +431,8 @@ final class App: NSObject, NSApplicationDelegate {
         // two ways of talking never fight over the microphone.
         stopPolling()
         guard !recorder.isRecording else { return }
+        // A dismissed pill comes back with the talk key.
+        panel.summon()
         // Option-Space is the door to everything spoken, always: our own
         // answer or step line stops now, and the daemon hushes any talk,
         // lesson or narration, remembering which it was. Even mid-turn —
@@ -495,8 +488,6 @@ final class App: NSObject, NSApplicationDelegate {
                 return
             }
             Log.info("heard: \(heard)")
-            heardLine = heard
-            if orb.isVisible { orb.model.line = heard }
             let hushed = await door.value
             // Always through the door, even with nothing hushed: the
             // listener's turn is over, so the daemon's queue plays on.
@@ -580,8 +571,8 @@ final class App: NSObject, NSApplicationDelegate {
                     card.show(spoken: answer.text, written: answer.written,
                               buttons: answer.buttons, imageURL: answer.imageURL)
                 }
-                // Nothing else on screen: the orb shows this answer, in
-                // this agent's colour, while it is spoken.
+                // Nothing else on screen: the pill shows this answer, its
+                // orb in this agent's colour, while it is spoken.
                 let onScreen = !busy && !recorder.isRecording
                 if onScreen { asideSpeaker = agent; panel.render(.saying(answer.text)) }
                 await Speech.say(answer.text, agentID: answer.agentID ?? agent, kind: "answer", voice: answer.voice)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentix-cli",
-  "version": "0.57.0",
+  "version": "0.58.0",
   "description": "AI operations layer for small and medium businesses. Routes Telegram, WhatsApp, GitLab, GitHub, crons, webhooks, and mesh tasks to AI agents. Web wizard for operators, CLI for engineers. Self-hosted.",
   "license": "MIT",
   "author": {