agentix-cli 0.58.0 → 0.60.0

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

@@ -213,7 +213,11 @@ enum AgentClient {
         /// "#RRGGBB": presence.color, else derived from the id. Older
         /// daemons send none, and the app derives it the same way.
         let color: String?
+        /// The orb's nature palette. Older daemons send none, and the orb
+        /// uses shades of `color`.
+        let palette: Palette?
         var label: String { name ?? id }
+        struct Palette: Decodable { let id: String; let colors: [String] }
     }
 
     /// The daemon's agents, or nil when the daemon cannot be reached.

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

@@ -0,0 +1,228 @@
+import AppKit
+import WebKit
+
+/// What the agent said, in a form you can read, select and copy, inside
+/// the pill.
+///
+/// Speech is lossy in one specific way that matters: a URL cannot be
+/// spoken usefully, an image cannot be spoken at all, and a name you have
+/// not seen written is a name you cannot act on. The spoken answer is
+/// deliberately short and stripped of exactly those things, so without a
+/// visual surface everything worth keeping from a turn is the part that
+/// gets thrown away.
+///
+/// Rich content arrives through the same `agentx:ui` directive Telegram
+/// and WhatsApp already use, parsed server-side, so an agent has one way to
+/// attach a link or a picture regardless of where it is speaking.
+final class AnswerView: NSView {
+    // A web view, because agents write markdown: headings, bullets, fenced
+    // code, tables. An NSTextView shows that as a mess of asterisks and
+    // hashes, which defeats the answer's only purpose: being MORE readable
+    // than the spoken answer, not less. Text in it is selectable, and it
+    // scrolls once the answer is taller than the pill lets it grow.
+    private let web = WKWebView()
+    private let links = NSStackView()
+    private let thumb = NSImageView()
+    private let actions = NSStackView()
+    private var source = ""
+
+    /// The answer's natural height, measured after it renders. The pill
+    /// grows to it, up to its maximum.
+    var onHeight: ((CGFloat) -> Void)?
+    /// "Open in chat". Set by the app.
+    var onOpenChat: (() -> Void)?
+
+    private static let linkRow: CGFloat = 34
+    private static let imageHeight: CGFloat = 120
+
+    override init(frame: NSRect) {
+        super.init(frame: frame)
+        web.setValue(false, forKey: "drawsBackground")
+        web.navigationDelegate = self
+        addSubview(web)
+
+        thumb.imageScaling = .scaleProportionallyUpOrDown
+        thumb.isHidden = true
+        addSubview(thumb)
+
+        links.orientation = .horizontal
+        links.spacing = 8
+        links.edgeInsets = NSEdgeInsets(top: 4, left: 12, bottom: 8, right: 12)
+        addSubview(links)
+
+        // Copy and Open in chat, shown while the pointer is over the answer.
+        actions.orientation = .horizontal
+        actions.spacing = 2
+        actions.addArrangedSubview(actionButton("doc.on.doc", "Copy the answer", #selector(copyAnswer)))
+        actions.addArrangedSubview(actionButton("bubble.left.and.bubble.right", "Open in chat", #selector(openChat)))
+        actions.isHidden = true
+        actions.edgeInsets = NSEdgeInsets(top: 1, left: 3, bottom: 1, right: 3)
+        // A backing of its own, so the buttons read over the text below.
+        actions.wantsLayer = true
+        actions.layer?.cornerRadius = 7
+        actions.layer?.cornerCurve = .continuous
+        addSubview(actions)
+
+        addTrackingArea(NSTrackingArea(rect: .zero, options: [.mouseEnteredAndExited, .activeAlways, .inVisibleRect],
+                                       owner: self, userInfo: nil))
+    }
+
+    @available(*, unavailable)
+    required init?(coder: NSCoder) { fatalError("not from a nib") }
+
+    private func actionButton(_ symbol: String, _ label: String, _ action: Selector) -> NSButton {
+        let b = NSButton()
+        b.isBordered = false
+        b.bezelStyle = .regularSquare
+        b.imagePosition = .imageOnly
+        b.image = NSImage(systemSymbolName: symbol, accessibilityDescription: label)
+        b.contentTintColor = .secondaryLabelColor
+        b.toolTip = label
+        b.setAccessibilityLabel(label)
+        b.target = self
+        b.action = action
+        b.widthAnchor.constraint(equalToConstant: 24).isActive = true
+        b.heightAnchor.constraint(equalToConstant: 22).isActive = true
+        return b
+    }
+
+    override func resizeSubviews(withOldSize oldSize: NSSize) {
+        let w = bounds.width, h = bounds.height
+        let linkH: CGFloat = links.arrangedSubviews.isEmpty ? 0 : Self.linkRow
+        let imgH: CGFloat = thumb.isHidden ? 0 : Self.imageHeight
+        thumb.frame = NSRect(x: 12, y: h - imgH - 10, width: w - 24, height: imgH)
+        web.frame = NSRect(x: 0, y: linkH, width: w, height: max(0, h - linkH - imgH - (imgH > 0 ? 16 : 0)))
+        links.frame = NSRect(x: 0, y: 0, width: w, height: linkH)
+        actions.frame = NSRect(x: w - 64, y: h - 32, width: 56, height: 26)
+    }
+
+    /// Does this turn have anything the spoken answer did not already
+    /// deliver?
+    ///
+    /// Opening on every turn, including "Ok.", shows one word you have
+    /// already heard. A surface that adds nothing trains you to ignore it,
+    /// so the turn where it DOES carry a link gets ignored too.
+    ///
+    /// Worth showing when there is rich content, a URL you could click, or
+    /// materially more written than was spoken. Otherwise the speech was
+    /// the whole answer.
+    static func isWorthShowing(spoken: String, written: String?, buttons: [(String, String)], imageURL: String?) -> Bool {
+        if !buttons.isEmpty || imageURL != nil { return true }
+        let text = (written?.isEmpty == false ? written! : spoken)
+        if text.range(of: #"https?://"#, options: .regularExpression) != nil { return true }
+        // Speech drops formatting, so written is often a little longer for
+        // the same content. Only a real difference counts.
+        let spokenLen = spoken.trimmingCharacters(in: .whitespacesAndNewlines).count
+        let writtenLen = text.trimmingCharacters(in: .whitespacesAndNewlines).count
+        if writtenLen > spokenLen + 80 { return true }
+        // Long enough that re-reading it beats re-hearing it.
+        return writtenLen > 280
+    }
+
+    /// `spoken` is what was said; `written` is the fuller answer with the
+    /// URLs and formatting the spoken form had to drop. `onHeight` follows
+    /// once it has rendered.
+    @MainActor
+    func show(spoken: String, written: String?, buttons: [(String, String)], imageURL: String?) {
+        source = (written?.isEmpty == false ? written! : spoken)
+        web.loadHTMLString(Markdown.page(Markdown.toHTML(source), css: Brand.cardCSS), baseURL: nil)
+
+        links.arrangedSubviews.forEach { links.removeArrangedSubview($0); $0.removeFromSuperview() }
+        for (label, url) in buttons.prefix(4) {
+            let b = NSButton(title: label, target: self, action: #selector(openLink(_:)))
+            b.bezelStyle = .push
+            b.controlSize = .small
+            b.toolTip = url
+            b.identifier = NSUserInterfaceItemIdentifier(url)
+            links.addArrangedSubview(b)
+        }
+
+        thumb.isHidden = true
+        thumb.image = nil
+        if let s = imageURL, let u = URL(string: s) {
+            // Off the main thread: a slow image must never stall the UI,
+            // and the answer is useful without it.
+            URLSession.shared.dataTask(with: u) { [weak self] data, _, _ in
+                guard let data, let img = NSImage(data: data) else { return }
+                Task { @MainActor in
+                    guard let self, self.source.isEmpty == false else { return }
+                    self.thumb.image = img
+                    self.thumb.isHidden = false
+                    self.measure()
+                }
+            }.resume()
+        }
+        resizeSubviews(withOldSize: bounds.size)
+    }
+
+    /// Empty again, once the pill has collapsed.
+    @MainActor
+    func clear() {
+        source = ""
+        web.loadHTMLString("", baseURL: nil)
+        thumb.isHidden = true
+        links.arrangedSubviews.forEach { links.removeArrangedSubview($0); $0.removeFromSuperview() }
+    }
+
+    /// The rendered text's height plus the image and links around it.
+    @MainActor
+    private func measure() {
+        let js = "(() => { const b = document.body, s = getComputedStyle(b);"
+            + " return b.scrollHeight + parseFloat(s.marginTop) + parseFloat(s.marginBottom) })()"
+        web.evaluateJavaScript(js) { [weak self] value, _ in
+            MainActor.assumeIsolated {
+                guard let self, !self.source.isEmpty else { return }
+                let text = CGFloat((value as? NSNumber)?.doubleValue ?? 120)
+                let extra = (self.links.arrangedSubviews.isEmpty ? 0 : Self.linkRow)
+                    + (self.thumb.isHidden ? 0 : Self.imageHeight + 16)
+                self.resizeSubviews(withOldSize: self.bounds.size)
+                self.onHeight?(ceil(text + extra))
+            }
+        }
+    }
+
+    override func mouseEntered(with event: NSEvent) {
+        effectiveAppearance.performAsCurrentDrawingAppearance {
+            actions.layer?.backgroundColor = NSColor.windowBackgroundColor.cgColor
+            actions.layer?.borderColor = NSColor.separatorColor.cgColor
+            actions.layer?.borderWidth = 1 / (window?.backingScaleFactor ?? 2)
+        }
+        actions.isHidden = source.isEmpty
+    }
+    override func mouseExited(with event: NSEvent) { actions.isHidden = true }
+
+    @objc private func copyAnswer() {
+        NSPasteboard.general.clearContents()
+        NSPasteboard.general.setString(source, forType: .string)
+    }
+
+    @objc private func openChat() { onOpenChat?() }
+
+    /// Select-and-⌘C: the pill has no Edit menu to route the shortcut.
+    func copySelection() { NSApp.sendAction(#selector(NSText.copy(_:)), to: web, from: nil) }
+
+    @objc private func openLink(_ sender: NSButton) {
+        guard let s = sender.identifier?.rawValue, let u = URL(string: s) else { return }
+        NSWorkspace.shared.open(u)
+    }
+}
+
+extension AnswerView: WKNavigationDelegate {
+    func webView(_ webView: WKWebView, didFinish navigation: WKNavigation!) {
+        MainActor.assumeIsolated { if !source.isEmpty { measure() } }
+    }
+
+    /// Links open in the real browser. A pill is not a place to read a web
+    /// page, and navigating away would replace the answer it exists to hold.
+    func webView(_ webView: WKWebView,
+                 decidePolicyFor navigationAction: WKNavigationAction,
+                 decisionHandler: @escaping (WKNavigationActionPolicy) -> Void) {
+        if navigationAction.navigationType == .linkActivated,
+           let url = navigationAction.request.url {
+            NSWorkspace.shared.open(url)
+            decisionHandler(.cancel)
+            return
+        }
+        decisionHandler(.allow)
+    }
+}

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

@@ -0,0 +1,55 @@
+import Foundation
+
+/// The daemon's voice history (src/daemon/voice-history-api.ts).
+///
+/// The list is summaries only; an answer in full is fetched when one is
+/// opened. A replay is queued by the daemon in the agent's voice, at the
+/// back of the speaking queue, so it never talks over what is playing.
+/// Loopback needs no token, as for the rest of AgentClient.
+enum HistoryClient {
+    /// One page, newest first; `before` is the previous page's `next`.
+    static func page(agent: String?, limit: Int, before: String? = nil) async -> Result<VoiceHistoryPage, HistoryFailure> {
+        let q = HistoryLogic.query(agent: agent, limit: limit, before: before)
+        guard let url = URL(string: "\(Config.daemonURL)/voice/history?\(q)") else { return .failure(.init(message: "Bad daemon address.")) }
+        var req = URLRequest(url: url)
+        req.timeoutInterval = 5
+        do {
+            let (data, response) = try await URLSession.shared.data(for: req)
+            let status = (response as? HTTPURLResponse)?.statusCode ?? 0
+            if status == 200, let page = try? JSONDecoder().decode(VoiceHistoryPage.self, from: data) { return .success(page) }
+            return .failure(.init(message: errorText(data) ?? "The daemon answered \(status)."))
+        } catch {
+            return .failure(.init(message: "The AgentX daemon isn't reachable."))
+        }
+    }
+
+    /// One exchange in full, or nil when it cannot be loaded.
+    static func detail(_ id: String) async -> VoiceExchangeDetail? {
+        guard let url = URL(string: "\(Config.daemonURL)/voice/history/\(id)") else { return nil }
+        var req = URLRequest(url: url)
+        req.timeoutInterval = 5
+        guard let (data, response) = try? await URLSession.shared.data(for: req),
+              (response as? HTTPURLResponse)?.statusCode == 200 else { return nil }
+        return try? JSONDecoder().decode(VoiceExchangeDetail.self, from: data)
+    }
+
+    /// Say the answer again. Nil when queued, else why not.
+    static func replay(_ id: String) async -> String? {
+        guard let url = URL(string: "\(Config.daemonURL)/voice/history/\(id)/replay") else { return "Bad daemon address." }
+        var req = URLRequest(url: url)
+        req.httpMethod = "POST"
+        req.timeoutInterval = 5
+        guard let (data, response) = try? await URLSession.shared.data(for: req) else {
+            return "The AgentX daemon isn't reachable."
+        }
+        if (response as? HTTPURLResponse)?.statusCode == 202 { return nil }
+        return errorText(data) ?? "The answer wasn't queued."
+    }
+
+    struct HistoryFailure: Error { let message: String }
+
+    private static func errorText(_ data: Data) -> String? {
+        struct Reply: Decodable { let error: String? }
+        return (try? JSONDecoder().decode(Reply.self, from: data))?.error
+    }
+}

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

@@ -0,0 +1,153 @@
+import Foundation
+
+/// Past voice exchanges as the daemon serves them (GET /voice/history),
+/// and the small decisions the History window and the menu make about
+/// them. Foundation only, so Tests/History can run it without a window.
+
+/// One row of the list: a bounded summary, never the whole answer.
+struct VoiceExchange: Decodable, Identifiable, Equatable {
+    let id: String
+    let agentId: String
+    /// When it was asked, ms since the epoch.
+    let at: Double
+    let durationMs: Int?
+    /// "ok", "error", "in-flight", "canceled" or "timeout".
+    let status: String
+    let question: String
+    let answerPreview: String
+    let answerChars: Int
+    let error: String?
+
+    var date: Date { Date(timeIntervalSince1970: at / 1000) }
+    var failed: Bool { status == "error" || status == "timeout" || status == "canceled" }
+    /// Something to say again.
+    var canReplay: Bool { answerChars > 0 && !failed }
+}
+
+struct VoiceHistoryPage: Decodable {
+    let exchanges: [VoiceExchange]
+    let next: String?
+}
+
+/// One exchange in full (GET /voice/history/:id), loaded when opened.
+struct VoiceExchangeDetail: Decodable {
+    struct Button: Decodable, Equatable { let label: String; let url: String }
+    struct Media: Decodable, Equatable { let type: String; let url: String; let caption: String? }
+    struct UI: Decodable, Equatable { let buttons: [Button]?; let media: Media? }
+
+    let id: String
+    let agentId: String
+    let at: Double
+    let durationMs: Int?
+    let status: String
+    let question: String
+    let answer: String?
+    let truncated: Bool
+    let ui: UI?
+    let error: String?
+    /// The task page, relative to the dashboard's address.
+    let taskPath: String
+
+    /// Buttons and a non-image media link, as (label, url).
+    var links: [(String, String)] {
+        var out = (ui?.buttons ?? []).map { ($0.label, $0.url) }
+        if let m = ui?.media { out.append((m.caption ?? m.type.capitalized, m.url)) }
+        return out
+    }
+}
+
+/// A day's exchanges under one heading.
+struct HistoryDay: Equatable {
+    let title: String
+    let exchanges: [VoiceExchange]
+}
+
+enum HistoryLogic {
+    /// Newest day first, each day newest first; "Today", "Yesterday", then
+    /// the date. Input order does not matter.
+    static func groupByDay(_ items: [VoiceExchange], now: Date = Date(),
+                           calendar: Calendar = .current, locale: Locale = .current) -> [HistoryDay] {
+        let sorted = items.sorted { $0.at != $1.at ? $0.at > $1.at : $0.id > $1.id }
+        var days: [HistoryDay] = []
+        var current: (Date, [VoiceExchange])?
+        for e in sorted {
+            let day = calendar.startOfDay(for: e.date)
+            if let c = current, c.0 == day {
+                current = (day, c.1 + [e])
+            } else {
+                if let c = current { days.append(HistoryDay(title: dayTitle(c.0, now: now, calendar: calendar, locale: locale), exchanges: c.1)) }
+                current = (day, [e])
+            }
+        }
+        if let c = current { days.append(HistoryDay(title: dayTitle(c.0, now: now, calendar: calendar, locale: locale), exchanges: c.1)) }
+        return days
+    }
+
+    static func dayTitle(_ day: Date, now: Date, calendar: Calendar = .current, locale: Locale = .current) -> String {
+        if calendar.isDate(day, inSameDayAs: now) { return "Today" }
+        if let y = calendar.date(byAdding: .day, value: -1, to: now), calendar.isDate(day, inSameDayAs: y) { return "Yesterday" }
+        let f = DateFormatter()
+        f.locale = locale
+        f.calendar = calendar
+        f.timeZone = calendar.timeZone
+        let sameYear = calendar.component(.year, from: day) == calendar.component(.year, from: now)
+        f.setLocalizedDateFormatFromTemplate(sameYear ? "EEEEdMMMM" : "EEEEdMMMMyyyy")
+        return f.string(from: day)
+    }
+
+    /// How long the answer took: "0.8 s", "12 s", "2 min 5 s"; "—" unknown.
+    static func duration(_ ms: Int?) -> String {
+        guard let ms, ms >= 0 else { return "—" }
+        if ms < 10_000 { return String(format: "%.1f s", Double(ms) / 1000) }
+        let s = Int((Double(ms) / 1000).rounded())
+        if s < 60 { return "\(s) s" }
+        let m = s / 60, r = s % 60
+        return r == 0 ? "\(m) min" : "\(m) min \(r) s"
+    }
+
+    /// A menu row: the question, clipped, and who answered.
+    static func menuTitle(_ e: VoiceExchange, agentName: String, max: Int = 44) -> String {
+        let q = e.question.split(whereSeparator: \.isWhitespace).joined(separator: " ")
+        let clipped = q.count > max ? String(q.prefix(max - 1)).trimmingCharacters(in: .whitespaces) + "…" : q
+        return "\u{201C}\(clipped)\u{201D} · \(agentName)"
+    }
+
+    /// Add a page to what is shown: no duplicates, newest first.
+    static func merge(_ shown: [VoiceExchange], _ page: [VoiceExchange]) -> [VoiceExchange] {
+        var seen = Set(shown.map(\.id))
+        var out = shown
+        for e in page where seen.insert(e.id).inserted { out.append(e) }
+        return out.sorted { $0.at != $1.at ? $0.at > $1.at : $0.id > $1.id }
+    }
+
+    /// Bare http(s) URLs as markdown links, so the written answer shows
+    /// them as links. URLs already inside a markdown link or <…> are left.
+    static func linkify(_ text: String) -> String {
+        guard let re = try? NSRegularExpression(pattern: #"(?<![\(\[<])\bhttps?://[^\s<>()\[\]]+"#) else { return text }
+        let ns = text as NSString
+        var out = ""
+        var last = 0
+        for m in re.matches(in: text, range: NSRange(location: 0, length: ns.length)) {
+            var url = ns.substring(with: m.range)
+            // A sentence's full stop or comma is not part of the link.
+            var tail = ""
+            while let c = url.last, ".,;:!?\"'".contains(c) { tail = String(c) + tail; url.removeLast() }
+            out += ns.substring(with: NSRange(location: last, length: m.range.location - last))
+            out += "[\(url)](\(url))"
+            out += tail
+            last = m.range.location + m.range.length
+        }
+        out += ns.substring(from: last)
+        return out
+    }
+
+    /// The query string for a page of history.
+    static func query(agent: String?, limit: Int, before: String?) -> String {
+        var items = [URLQueryItem(name: "limit", value: String(limit))]
+        if let agent, !agent.isEmpty { items.append(URLQueryItem(name: "agent", value: agent)) }
+        if let before, !before.isEmpty { items.append(URLQueryItem(name: "before", value: before)) }
+        var c = URLComponents()
+        c.queryItems = items
+        return c.percentEncodedQuery ?? ""
+    }
+}