agentix-cli 0.26.0 → 0.28.0

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

@@ -0,0 +1,275 @@
+import AppKit
+
+/// The floating widget itself.
+///
+/// NSPanel with .nonactivatingPanel so pressing the hotkey never pulls
+/// 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.
+final class Panel: NSPanel {
+    private let label = NSTextField(labelWithString: "")
+    private let orb = NSView()
+
+    /// Scrolls text too long for the pill instead of truncating it.
+    ///
+    /// Step text is routinely wider than 180 points, and an ellipsis hides
+    /// exactly the part that makes it reassuring.
+    ///
+    /// The first version rotated the STRING by one character every 0.18s.
+    /// That flickers, and unavoidably: every tick re-lays out the whole
+    /// text, and the motion is quantised to a character width, so it jumps
+    /// rather than slides. Instead the label now moves inside a clipping
+    /// view, animated by Core Animation — continuous, sub-pixel, composited
+    /// off the main thread, and it never touches the text once set.
+    private var clip: NSView?
+    private var marqueeText = ""
+
+    private var pressedAt: NSPoint?
+
+    /// A click acts on mouse UP, and only when the pointer has not moved.
+    ///
+    /// The panel is draggable by its background, so acting on mouse DOWN
+    /// would fire every time someone repositioned it — you could not move
+    /// the widget without talking to it.
+    override func mouseDown(with event: NSEvent) {
+        pressedAt = NSEvent.mouseLocation
+        super.mouseDown(with: event)
+    }
+
+    /// Right-click opens the only menu the widget has.
+    ///
+    /// A hold has to be reversible in one gesture from wherever you are,
+    /// and it has to SHOW — a switch that silences your notifications
+    /// without saying so is how people miss things for a day and blame the
+    /// software.
+    override func rightMouseDown(with event: NSEvent) {
+        let menu = NSMenu()
+        let holding = Hold.isOn
+        let item = NSMenuItem(
+            title: holding ? "Delivering notifications" : "Hold notifications",
+            action: #selector(toggleHold), keyEquivalent: "")
+        item.target = self
+        item.state = holding ? .on : .off
+        menu.addItem(item)
+        menu.addItem(.separator())
+        let quit = NSMenuItem(title: "Quit AgentX Voice",
+                              action: #selector(NSApplication.terminate(_:)), keyEquivalent: "q")
+        menu.addItem(quit)
+        NSMenu.popUpContextMenu(menu, with: event, for: contentView ?? NSView())
+    }
+
+    @objc private func toggleHold() {
+        let nowOn = Hold.toggle()
+        onHoldChanged?(nowOn)
+    }
+
+    /// Told when the hold flips, so the app can redraw and flush.
+    var onHoldChanged: ((Bool) -> Void)?
+
+    override func mouseUp(with event: NSEvent) {
+        defer { pressedAt = nil }
+        if let start = pressedAt {
+            let now = NSEvent.mouseLocation
+            let moved = hypot(now.x - start.x, now.y - start.y)
+            if moved < 4 { onClick?() }
+        }
+        super.mouseUp(with: event)
+    }
+
+    enum State {
+        case idle, listening, thinking, speaking
+        /// Live activity from the daemon, with seconds elapsed — the
+        /// difference between "it's working" and "it's hung".
+        case working(String, Int)
+        /// What is being said right now, scrolled in full.
+        ///
+        /// "Speaking" told you the state and not the content, which is the
+        /// wrong half: you already know it is speaking, you can hear it.
+        /// What you cannot do is re-read a sentence that has gone past, or
+        /// follow it at all in a noisy room.
+        case saying(String)
+        case error(String)
+
+        var text: String {
+            switch self {
+            case .idle: return Hold.isOn ? "notifications held" : "hold ⌥space"
+            case .listening: return "Listening"
+            case .thinking: return "Thinking"
+            case .speaking: return "Speaking"
+            case .saying(let text): return text
+            // "·" is the system's own separator glyph.
+            case .working(let what, let secs): return "\(what)  ·  \(secs)s"
+            case .error(let m): return m
+            }
+        }
+        var color: NSColor {
+            switch self {
+            // Teal carries every ACTIVE state, so the widget reads as one
+            // thing doing work rather than a traffic light. System reds
+            // and greens were macOS's voice, not the product's, and they
+            // shift with the user's accent-colour setting.
+            case .idle: return Hold.isOn ? Brand.warn : .tertiaryLabelColor
+            case .listening: return Brand.accent
+            case .thinking, .working: return Brand.primaryBright
+            case .speaking, .saying: return Brand.accentDeep
+            case .error: return Brand.alert
+            }
+        }
+
+        /// Idle is an invitation and belongs in meta type; everything else
+        /// is a running commentary and belongs in body type.
+        var isMeta: Bool { if case .idle = self { return true }; return false }
+    }
+
+    /// Called when the pill is clicked. Set by the app.
+    ///
+    /// The hotkey is faster once you know it, and invisible until then.
+    /// A widget whose only affordance is a chord you have to be told about
+    /// is a widget most people never use — "HOLD ⌥SPACE" is printed on it
+    /// precisely because there was nothing to click.
+    var onClick: (() -> Void)?
+
+    init() {
+        super.init(contentRect: NSRect(x: 0, y: 0, width: 230, height: 54),
+                   styleMask: [.borderless, .nonactivatingPanel],
+                   backing: .buffered, defer: false)
+        isFloatingPanel = true
+        level = .floating
+        collectionBehavior = [.canJoinAllSpaces, .fullScreenAuxiliary, .stationary]
+        isOpaque = false
+        backgroundColor = .clear
+        hasShadow = true
+        isMovableByWindowBackground = true
+        hidesOnDeactivate = false
+
+        let blur = NSVisualEffectView(frame: NSRect(origin: .zero, size: NSSize(width: 230, height: 54)))
+        blur.material = .hudWindow
+        blur.blendingMode = .behindWindow
+        blur.state = .active
+        blur.wantsLayer = true
+        blur.layer?.cornerRadius = Brand.Radius.lg
+        blur.layer?.masksToBounds = true
+        blur.autoresizingMask = [.width, .height]
+        contentView = blur
+
+        // An opaque tint over the blur, and it is not a style preference.
+        //
+        // `blendingMode = .behindWindow` composites whatever is behind the
+        // pill, so the editor's own panel dividers were coming through it
+        // as a faint rectangle around the widget — it read as a border the
+        // widget was drawing, when it was the window behind. Translucency
+        // is pleasant over wallpaper and actively confusing over ruled UI.
+        //
+        // This keeps enough blur to feel native while making the pill read
+        // as one solid object wherever it is parked.
+        let tint = NSView(frame: blur.bounds)
+        tint.wantsLayer = true
+        tint.layer?.backgroundColor = NSColor.windowBackgroundColor
+            .withAlphaComponent(0.72).cgColor
+        tint.layer?.cornerRadius = Brand.Radius.lg
+        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)
+        blur.addSubview(orb)
+
+        // A clipping window the label slides behind.
+        let clipView = NSView(frame: NSRect(x: 38, y: 17, width: 180, height: 20))
+        clipView.wantsLayer = true
+        clipView.layer?.masksToBounds = true
+        label.frame = NSRect(x: 0, y: 0, width: 180, height: 20)
+        label.font = Brand.body(size: 12)
+        label.lineBreakMode = .byClipping
+        label.wantsLayer = true
+        clipView.addSubview(label)
+        blur.addSubview(clipView)
+        clip = clipView
+
+        render(.idle)
+        positionBottomRight()
+    }
+
+    /// 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))
+    }
+
+    /// AppKit is not thread-safe. Marking this explicitly means a stray
+    /// call from a delegate queue is a compile error rather than heap
+    /// 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
+
+        if state.isMeta {
+            stopMarquee()
+            label.attributedStringValue = Brand.metaString(state.text, color: state.color)
+            label.frame.origin.x = 0
+        } else {
+            label.textColor = state.color
+            setText(state.text)
+        }
+    }
+
+    /// Fits, or scrolls. Identical text is left alone so a per-second tick
+    /// cannot restart the animation and make it stutter in place.
+    @MainActor
+    private func setText(_ text: String) {
+        guard let clipView = clip else { label.stringValue = text; return }
+        let font = label.font ?? NSFont.systemFont(ofSize: 12)
+        let width = (text as NSString).size(withAttributes: [.font: font]).width
+
+        if width <= clipView.bounds.width {
+            stopMarquee()
+            label.stringValue = text
+            label.frame.size.width = clipView.bounds.width
+            label.frame.origin.x = 0
+            return
+        }
+        if text == marqueeText { return }
+        marqueeText = text
+        startMarquee(text: text, textWidth: width, in: clipView)
+    }
+
+    @MainActor
+    private func startMarquee(text: String, textWidth: CGFloat, in clipView: NSView) {
+        label.layer?.removeAnimation(forKey: "marquee")
+
+        // Gap so the loop point reads as a pause rather than words colliding.
+        let gap: CGFloat = 40
+        let travel = textWidth + gap
+        label.stringValue = text
+        label.frame = NSRect(x: 0, y: 0, width: textWidth + gap, height: clipView.bounds.height)
+
+        let slide = CABasicAnimation(keyPath: "position.x")
+        slide.fromValue = label.layer?.position.x ?? 0
+        slide.byValue = -travel
+        // Speed proportional to length, so a long step is not punishingly
+        // slow and a short one is not a blur. ~40 points a second reads at
+        // a glance without demanding attention.
+        slide.duration = CFTimeInterval(travel / 40)
+        slide.repeatCount = .infinity
+        slide.isRemovedOnCompletion = false
+        label.layer?.add(slide, forKey: "marquee")
+    }
+
+    @MainActor
+    private func stopMarquee() {
+        label.layer?.removeAnimation(forKey: "marquee")
+        marqueeText = ""
+    }
+
+    // Borderless panels refuse key status unless told otherwise; without
+    // this the widget cannot show a caret or take any future text input.
+    override var canBecomeKey: Bool { true }
+}

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

@@ -0,0 +1,147 @@
+import Foundation
+
+/// Live activity from the daemon while a turn runs.
+///
+/// A voice assistant that goes silent for ten seconds reads as broken, and
+/// the honest fix is not a spinner — it is saying what is actually
+/// happening. The daemon already publishes `task:step` on its /events SSE
+/// with a step name, action and input summary, so the widget can narrate
+/// real work instead of inventing reassurance.
+///
+/// Deliberately best-effort: if the stream drops or the shape changes, the
+/// turn still completes and the answer is still spoken. Progress is
+/// decoration over a working path, never a dependency of it.
+final class Progress: NSObject, URLSessionDataDelegate {
+    private var task: URLSessionDataTask?
+    private var session: URLSession?
+    private var buffer = Data()
+    private let agentID: String
+    private let onStep: (String) -> Void
+
+    /// Every touch of `buffer`, `task` and `session` happens here.
+    ///
+    /// URLSession delivers on its own queue while stop() is called from the
+    /// main thread at the end of a turn, and both mutated `buffer`. Two
+    /// threads mutating a Data value is not a race you get to lose
+    /// gracefully — it corrupts the heap, and the process traps later in
+    /// unrelated code (a CATransaction flush, in the crash that prompted
+    /// this). Serialising is the fix; a lock around only removeAll() would
+    /// not be, because the append path mutates it too.
+    private let queue = DispatchQueue(label: "tn.acme.agentx.voice.progress")
+    private var stopped = false
+
+    init(agentID: String, onStep: @escaping (String) -> Void) {
+        self.agentID = agentID
+        self.onStep = onStep
+    }
+
+    func start() {
+        queue.async { [weak self] in self?.startLocked() }
+    }
+
+    private func startLocked() {
+        guard !stopped else { return }
+        guard let url = URL(string: "\(Config.daemonURL)/events?type=task") else { return }
+        var req = URLRequest(url: url)
+        req.setValue("text/event-stream", forHTTPHeaderField: "Accept")
+        req.timeoutInterval = 3600
+        let cfg = URLSessionConfiguration.default
+        cfg.timeoutIntervalForRequest = 3600
+        // Deliver on our own serial queue rather than an arbitrary one, so
+        // didReceive and stop() cannot interleave.
+        let opQueue = OperationQueue()
+        opQueue.maxConcurrentOperationCount = 1
+        opQueue.underlyingQueue = queue
+        let s = URLSession(configuration: cfg, delegate: self, delegateQueue: opQueue)
+        session = s
+        task = s.dataTask(with: req)
+        task?.resume()
+    }
+
+    func stop() {
+        queue.async { [weak self] in
+            guard let self, !self.stopped else { return }
+            self.stopped = true
+            self.task?.cancel(); self.task = nil
+            // invalidateAndCancel breaks the session's strong reference to
+            // this delegate; without it the object leaks for the life of
+            // the app and keeps receiving events after the turn ended.
+            self.session?.invalidateAndCancel(); self.session = nil
+            self.buffer.removeAll()
+        }
+    }
+
+    deinit { task?.cancel(); session?.invalidateAndCancel() }
+
+    // Already on `queue` — see the delegateQueue wiring in startLocked().
+    func urlSession(_ s: URLSession, dataTask: URLSessionDataTask, didReceive data: Data) {
+        guard !stopped else { return }
+        buffer.append(data)
+        // SSE frames are separated by a blank line. Anything not yet
+        // terminated stays buffered for the next packet.
+        while let range = buffer.range(of: Data("\n\n".utf8)) {
+            let frame = buffer.subdata(in: buffer.startIndex..<range.lowerBound)
+            buffer.removeSubrange(buffer.startIndex..<range.upperBound)
+            handle(String(data: frame, encoding: .utf8) ?? "")
+        }
+    }
+
+    private func handle(_ frame: String) {
+        var event = "message", payload = ""
+        for line in frame.split(separator: "\n", omittingEmptySubsequences: false) {
+            if line.hasPrefix("event:") { event = line.dropFirst(6).trimmingCharacters(in: .whitespaces) }
+            if line.hasPrefix("data:") { payload += line.dropFirst(5).trimmingCharacters(in: .whitespaces) }
+        }
+        guard event.contains("task"), !payload.isEmpty,
+              let data = payload.data(using: .utf8),
+              let outer = try? JSONSerialization.jsonObject(with: data) as? [String: Any]
+        else { return }
+
+        // broadcastSSE wraps every frame as {time, message}, where
+        // `message` is the payload re-encoded as a STRING. So the step is
+        // one JSON level deeper than the frame appears to be — unwrap it,
+        // while still accepting a flat frame in case that ever changes.
+        var obj = outer
+        if let inner = outer["message"] as? String,
+           let innerData = inner.data(using: .utf8),
+           let parsed = try? JSONSerialization.jsonObject(with: innerData) as? [String: Any] {
+            obj = parsed
+        }
+
+        // Only this widget's agent. Other agents are busy on their own work
+        // and narrating theirs would be both confusing and a privacy leak.
+        guard (obj["agentId"] as? String) == agentID else { return }
+        guard let label = summarise(obj) else { return }
+        DispatchQueue.main.async { self.onStep(label) }
+    }
+
+    /// Turn a step event into something worth showing in 180 points of
+    /// label. Prefers the human-facing action over the internal step name.
+    private func summarise(_ obj: [String: Any]) -> String? {
+        // Only the start of a step is worth announcing. A tool_result
+        // arrives a beat later and would just repeat what was said.
+        if (obj["name"] as? String) == "tool_result" { return nil }
+
+        let tool = (obj["action"] as? String) ?? (obj["name"] as? String) ?? ""
+        guard !tool.isEmpty, tool != "tool_use" else { return nil }
+
+        // inputSummary is the tool's raw arguments as JSON. The useful
+        // part is one field — a command, a path, a query — and showing the
+        // braces instead would waste the whole label.
+        var detail = ""
+        if let input = obj["inputSummary"] as? String,
+           let d = input.data(using: .utf8),
+           let args = try? JSONSerialization.jsonObject(with: d) as? [String: Any] {
+            for key in ["command", "file_path", "path", "query", "pattern", "url", "description"] {
+                if let v = args[key] as? String, !v.isEmpty { detail = v; break }
+            }
+        }
+        // Raw tool names never reach the screen. The marquee used to show
+        // things like "mcp__agentx__agentx_task", which is unreadable to
+        // anyone outside this codebase and appears during exactly the long
+        // waits the widget exists to explain.
+        guard let text = StepLabel.describe(tool: tool, detail: detail) else { return nil }
+        // Long text is fine — the panel marquees it rather than truncating.
+        return text.count > 90 ? String(text.prefix(88)) + "…" : text
+    }
+}

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

@@ -0,0 +1,139 @@
+import AVFoundation
+
+/// Microphone capture that yields exactly what a speech API wants: 16 kHz
+/// mono 16-bit PCM in a RIFF container.
+///
+/// The hardware input is whatever the device feels like (commonly 48 kHz
+/// float32, and on some Macs the format is only valid AFTER the engine
+/// starts), so the tap installs with the input node's own format and an
+/// AVAudioConverter does the rest. Converting in the tap rather than at
+/// the end keeps memory flat for long utterances.
+final class Recorder {
+    private let engine = AVAudioEngine()
+    private var converter: AVAudioConverter?
+    private var pcm = Data()
+    private let lock = NSLock()
+    private(set) var isRecording = false
+
+    /// Loudness of the most recent buffer, 0…1, smoothed.
+    ///
+    /// Exists so the widget can tell talking from silence without a second
+    /// audio tap. Hands-free listening needs to know when you have
+    /// FINISHED a sentence, and the only honest signal for that is the
+    /// microphone going quiet — a fixed timeout either cuts people off
+    /// mid-thought or leaves the mic open staring at them.
+    ///
+    /// Read from the main thread while the audio thread writes it. A
+    /// Float write is atomic on every platform this runs on, and a reader
+    /// that occasionally sees the previous buffer's value is choosing
+    /// between two adjacent 100ms windows — which changes nothing.
+    private(set) var level: Float = 0
+
+    /// 16 kHz mono int16 — the format both ElevenLabs and whisper prefer,
+    /// and small enough that a 30-second utterance is under 1 MB.
+    private let target = AVAudioFormat(
+        commonFormat: .pcmFormatInt16, sampleRate: 16_000, channels: 1, interleaved: true)!
+
+    enum RecorderError: LocalizedError {
+        case micDenied
+        case tooShort
+        var errorDescription: String? {
+            switch self {
+            case .micDenied: return "Microphone access denied. Grant it in System Settings › Privacy & Security › Microphone."
+            case .tooShort: return "Didn't catch that — hold the hotkey while you speak."
+            }
+        }
+    }
+
+    func requestPermission(_ done: @escaping (Bool) -> Void) {
+        switch AVCaptureDevice.authorizationStatus(for: .audio) {
+        case .authorized: done(true)
+        case .notDetermined: AVCaptureDevice.requestAccess(for: .audio) { ok in
+            DispatchQueue.main.async { done(ok) } }
+        default: done(false)
+        }
+    }
+
+    func start() throws {
+        level = 0
+        guard !isRecording else { return }
+        lock.lock(); pcm.removeAll(keepingCapacity: true); lock.unlock()
+
+        let input = engine.inputNode
+        let inputFormat = input.inputFormat(forBus: 0)
+        guard inputFormat.sampleRate > 0 else { throw RecorderError.micDenied }
+        converter = AVAudioConverter(from: inputFormat, to: target)
+
+        input.installTap(onBus: 0, bufferSize: 4096, format: inputFormat) { [weak self] buf, _ in
+            self?.append(buf)
+        }
+        engine.prepare()
+        try engine.start()
+        isRecording = true
+    }
+
+    /// Stops and returns a WAV, or nil when nothing usable was captured.
+    func stop() -> Data? {
+        guard isRecording else { return nil }
+        engine.inputNode.removeTap(onBus: 0)
+        engine.stop()
+        isRecording = false
+
+        lock.lock(); let body = pcm; lock.unlock()
+        // 16 kHz * 2 bytes = 32 kB/s; under a quarter second is a misfire,
+        // not speech, and sending it just wastes an API call.
+        guard body.count > 8_000 else { return nil }
+        return wav(body)
+    }
+
+    private func append(_ buffer: AVAudioPCMBuffer) {
+        guard let converter else { return }
+        let ratio = target.sampleRate / buffer.format.sampleRate
+        let capacity = AVAudioFrameCount(Double(buffer.frameLength) * ratio) + 1024
+        guard let out = AVAudioPCMBuffer(pcmFormat: target, frameCapacity: capacity) else { return }
+
+        var supplied = false
+        var error: NSError?
+        converter.convert(to: out, error: &error) { _, status in
+            if supplied { status.pointee = .noDataNow; return nil }
+            supplied = true
+            status.pointee = .haveData
+            return buffer
+        }
+        guard error == nil, out.frameLength > 0,
+              let channel = out.int16ChannelData?[0] else { return }
+
+        // RMS over the buffer, in the same pass that copies it.
+        var sum: Float = 0
+        for i in 0..<Int(out.frameLength) {
+            let sample = Float(channel[i]) / 32768.0
+            sum += sample * sample
+        }
+        let rms = (sum / Float(max(Int(out.frameLength), 1))).squareRoot()
+        // Attack fast, release slow: a level that drops instantly makes a
+        // pause between words look like the end of a sentence.
+        level = rms > level ? rms : level * 0.82 + rms * 0.18
+
+        let bytes = Int(out.frameLength) * MemoryLayout<Int16>.size
+        lock.lock()
+        pcm.append(UnsafeBufferPointer(start: channel, count: Int(out.frameLength)).withMemoryRebound(to: UInt8.self) {
+            Data(bytes: $0.baseAddress!, count: bytes)
+        })
+        lock.unlock()
+    }
+
+    /// Minimal RIFF/WAVE header for 16-bit mono PCM.
+    private func wav(_ body: Data) -> Data {
+        let rate = UInt32(target.sampleRate), channels: UInt16 = 1, bits: UInt16 = 16
+        let byteRate = rate * UInt32(channels) * UInt32(bits / 8)
+        var d = Data()
+        func str(_ s: String) { d.append(s.data(using: .ascii)!) }
+        func u32(_ v: UInt32) { withUnsafeBytes(of: v.littleEndian) { d.append(contentsOf: $0) } }
+        func u16(_ v: UInt16) { withUnsafeBytes(of: v.littleEndian) { d.append(contentsOf: $0) } }
+        str("RIFF"); u32(UInt32(36 + body.count)); str("WAVE")
+        str("fmt "); u32(16); u16(1); u16(channels); u32(rate); u32(byteRate)
+        u16(channels * bits / 8); u16(bits)
+        str("data"); u32(UInt32(body.count)); d.append(body)
+        return d
+    }
+}