agentix-cli 0.58.0 → 0.60.0

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

@@ -0,0 +1,301 @@
+import AppKit
+import SwiftUI
+
+/// History: past voice exchanges by day, filterable by agent.
+///
+/// The daemon keeps the records (every /ask turn is a task trace on the
+/// voice channel); the window reads them and keeps no copy. The list holds
+/// summaries only, and an answer in full is fetched when it is selected.
+/// Replay goes through the daemon's speaking queue, like any answer.
+@MainActor
+final class HistoryStore: ObservableObject {
+    static let pageSize = 30
+
+    @Published var exchanges: [VoiceExchange] = []
+    @Published var next: String?
+    /// nil shows every agent.
+    @Published var agent: String? { didSet { if agent != oldValue { reload() } } }
+    @Published var agents: [AgentClient.AgentInfo] = []
+    @Published var selected: String? { didSet { if selected != oldValue { loadDetail() } } }
+    @Published var detail: VoiceExchangeDetail?
+    @Published var loading = false
+    @Published var error = ""
+    @Published var notice = ""
+
+    /// Swapped for fixed data when rendering screenshots.
+    var fetchPage: (String?, Int, String?) async -> Result<VoiceHistoryPage, HistoryClient.HistoryFailure> = HistoryClient.page
+    var fetchDetail: (String) async -> VoiceExchangeDetail? = HistoryClient.detail
+    var fetchAgents: () async -> [AgentClient.AgentInfo]? = AgentClient.agents
+
+    var days: [HistoryDay] { HistoryLogic.groupByDay(exchanges) }
+
+    func name(of id: String) -> String { agents.first { $0.id == id }?.label ?? id }
+
+    func color(of id: String) -> Color {
+        Color(hex: OrbMath.colorHex(agentID: id, configured: agents.first { $0.id == id }?.color))
+    }
+
+    func reload() {
+        loading = true
+        error = ""
+        Task {
+            if agents.isEmpty, let a = await fetchAgents() { agents = a }
+            let result = await fetchPage(agent, Self.pageSize, nil)
+            loading = false
+            switch result {
+            case .success(let page):
+                exchanges = page.exchanges
+                next = page.next
+                if selected == nil || !exchanges.contains(where: { $0.id == selected }) { selected = exchanges.first?.id }
+            case .failure(let f):
+                exchanges = []
+                next = nil
+                error = f.message
+            }
+        }
+    }
+
+    func loadOlder() {
+        guard let before = next, !loading else { return }
+        loading = true
+        Task {
+            let result = await fetchPage(agent, Self.pageSize, before)
+            loading = false
+            switch result {
+            case .success(let page):
+                exchanges = HistoryLogic.merge(exchanges, page.exchanges)
+                next = page.next
+            case .failure(let f):
+                error = f.message
+            }
+        }
+    }
+
+    private func loadDetail() {
+        detail = nil
+        guard let id = selected else { return }
+        Task {
+            let d = await fetchDetail(id)
+            if selected == id { detail = d }
+        }
+    }
+
+    func replay(_ id: String) {
+        notice = ""
+        error = ""
+        Task {
+            if let problem = await HistoryClient.replay(id) { error = problem }
+            else { notice = "Queued. It plays after anything already speaking." }
+        }
+    }
+
+    func copy(_ d: VoiceExchangeDetail) {
+        NSPasteboard.general.clearContents()
+        NSPasteboard.general.setString(d.answer ?? "", forType: .string)
+        notice = "Answer copied."
+    }
+
+    func openTask(_ d: VoiceExchangeDetail) {
+        guard let url = URL(string: Config.dashboardURL + d.taskPath) else { return }
+        NSWorkspace.shared.open(url)
+    }
+}
+
+struct HistoryView: View {
+    @ObservedObject var store: HistoryStore
+
+    var body: some View {
+        VStack(spacing: 0) {
+            toolbar
+            Divider()
+            HStack(spacing: 0) {
+                list.frame(width: 320)
+                Divider()
+                detailPane.frame(maxWidth: .infinity, maxHeight: .infinity)
+            }
+            if !store.error.isEmpty || !store.notice.isEmpty { footer }
+        }
+        .frame(minWidth: 760, minHeight: 480)
+        .background(Color(nsColor: .windowBackgroundColor))
+    }
+
+    private var toolbar: some View {
+        HStack(spacing: 10) {
+            Picker("Agent", selection: $store.agent) {
+                Text("All agents").tag(String?.none)
+                ForEach(store.agents, id: \.id) { a in Text(a.label).tag(String?.some(a.id)) }
+            }
+            .frame(width: 220)
+            Spacer()
+            if store.loading { ProgressView().controlSize(.small) }
+            Button("Refresh") { store.reload() }
+                .keyboardShortcut("r", modifiers: .command)
+        }
+        .padding(10)
+    }
+
+    @ViewBuilder private var list: some View {
+        if store.exchanges.isEmpty {
+            Text(store.loading ? "Loading…" : store.error.isEmpty ? "No voice exchanges yet." : "Nothing to show.")
+                .foregroundStyle(.secondary)
+                .frame(maxWidth: .infinity, maxHeight: .infinity)
+        } else {
+            List(selection: $store.selected) {
+                ForEach(store.days, id: \.title) { day in
+                    Section(day.title) {
+                        ForEach(day.exchanges) { e in row(e).tag(e.id) }
+                    }
+                }
+                if store.next != nil {
+                    Button("Load older") { store.loadOlder() }
+                        .frame(maxWidth: .infinity)
+                }
+            }
+            .listStyle(.inset)
+        }
+    }
+
+    private func row(_ e: VoiceExchange) -> some View {
+        VStack(alignment: .leading, spacing: 3) {
+            HStack(spacing: 6) {
+                Circle().fill(store.color(of: e.agentId)).frame(width: 8, height: 8)
+                Text(store.name(of: e.agentId)).font(.caption.weight(.semibold))
+                Spacer()
+                Text(e.date, style: .time).font(.caption).foregroundStyle(.secondary)
+                Text(HistoryLogic.duration(e.durationMs)).font(.caption.monospacedDigit()).foregroundStyle(.secondary)
+            }
+            Text(e.question).fontWeight(.medium).lineLimit(2)
+            Text(e.failed ? (e.error ?? "No answer") : e.answerPreview)
+                .font(.callout)
+                .foregroundStyle(e.failed ? Color(nsColor: Brand.alert) : .secondary)
+                .lineLimit(2)
+        }
+        .padding(.vertical, 3)
+        .accessibilityElement(children: .combine)
+    }
+
+    @ViewBuilder private var detailPane: some View {
+        if let d = store.detail {
+            ScrollView {
+                VStack(alignment: .leading, spacing: 14) {
+                    HStack(spacing: 6) {
+                        Circle().fill(store.color(of: d.agentId)).frame(width: 10, height: 10)
+                        Text(store.name(of: d.agentId)).font(.headline)
+                        Spacer()
+                        Text("Answered in \(HistoryLogic.duration(d.durationMs))")
+                            .font(.caption).foregroundStyle(.secondary)
+                    }
+                    VStack(alignment: .leading, spacing: 4) {
+                        Text("YOU SAID").font(.caption2.monospaced()).tracking(0.8).foregroundStyle(.secondary)
+                        Text(d.question).textSelection(.enabled)
+                    }
+                    VStack(alignment: .leading, spacing: 4) {
+                        Text("ANSWER").font(.caption2.monospaced()).tracking(0.8).foregroundStyle(.secondary)
+                        if let answer = d.answer, !answer.isEmpty {
+                            Text(written(answer)).textSelection(.enabled)
+                            if d.truncated { Text("The answer is longer; open the task for all of it.").font(.caption).foregroundStyle(.secondary) }
+                        } else {
+                            Text(d.error ?? "No answer was recorded.").foregroundStyle(Color(nsColor: Brand.alert))
+                        }
+                    }
+                    if !d.links.isEmpty {
+                        HStack(spacing: 8) {
+                            ForEach(d.links, id: \.1) { link in
+                                if let url = URL(string: link.1) { Link(link.0, destination: url) }
+                            }
+                        }
+                    }
+                    Divider()
+                    HStack(spacing: 8) {
+                        Button("Replay") { store.replay(d.id) }
+                            .disabled(!(d.answer?.isEmpty == false))
+                            .keyboardShortcut(.return, modifiers: .command)
+                        Button("Copy") { store.copy(d) }
+                            .disabled(!(d.answer?.isEmpty == false))
+                            .keyboardShortcut("c", modifiers: [.command, .shift])
+                        Button("Open task in dashboard") { store.openTask(d) }
+                    }
+                }
+                .padding(16)
+                .frame(maxWidth: .infinity, alignment: .leading)
+            }
+        } else {
+            Text(store.selected == nil ? "Select an exchange." : "Loading…")
+                .foregroundStyle(.secondary)
+        }
+    }
+
+    /// The answer as written: markdown links and bare URLs as links.
+    private func written(_ answer: String) -> AttributedString {
+        let md = HistoryLogic.linkify(answer)
+        return (try? AttributedString(markdown: md, options: .init(interpretedSyntax: .inlineOnlyPreservingWhitespace)))
+            ?? AttributedString(answer)
+    }
+
+    private var footer: some View {
+        HStack {
+            Text(store.error.isEmpty ? store.notice : store.error)
+                .foregroundStyle(store.error.isEmpty ? Color.secondary : Color(nsColor: .systemRed))
+                .font(.callout)
+            Spacer()
+        }
+        .padding(10)
+    }
+}
+
+@MainActor
+final class HistoryWindow: NSObject {
+    static let shared = HistoryWindow()
+    let store = HistoryStore()
+    private var window: NSWindow?
+
+    func show() {
+        if window == nil {
+            let w = NSWindow(contentRect: NSRect(x: 0, y: 0, width: 860, height: 560),
+                             styleMask: [.titled, .closable, .miniaturizable, .resizable],
+                             backing: .buffered, defer: false)
+            w.title = "AgentX Voice History"
+            w.isReleasedWhenClosed = false
+            w.contentView = NSHostingView(rootView: HistoryView(store: store))
+            w.center()
+            window = w
+        }
+        store.agents = []
+        store.reload()
+        NSApp.activate(ignoringOtherApps: true)
+        window?.makeKeyAndOrderFront(nil)
+    }
+}
+
+/// The menu's last three exchanges, for a quick replay.
+@MainActor
+final class RecentExchanges: NSObject {
+    private(set) var items: [VoiceExchange] = []
+
+    func refresh() async {
+        if case .success(let page) = await HistoryClient.page(agent: nil, limit: 3) { items = page.exchanges }
+    }
+
+    /// A "Recent" section, or nothing when there is no history.
+    func addItems(to menu: NSMenu, name: (String) -> String) {
+        guard !items.isEmpty else { return }
+        menu.addItem(.separator())
+        menu.addItem(NSMenuItem.sectionHeader(title: "Recent · click to replay"))
+        for e in items {
+            let row = NSMenuItem(title: HistoryLogic.menuTitle(e, agentName: name(e.agentId)),
+                                 action: #selector(replay(_:)), keyEquivalent: "")
+            row.target = self
+            row.representedObject = e.id
+            row.isEnabled = e.canReplay
+            row.toolTip = e.answerPreview.isEmpty ? nil : e.answerPreview
+            menu.addItem(row)
+        }
+    }
+
+    @objc private func replay(_ sender: NSMenuItem) {
+        guard let id = sender.representedObject as? String else { return }
+        Task {
+            if let problem = await HistoryClient.replay(id) { Log.warn("history replay: \(problem)") }
+        }
+    }
+}

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

@@ -0,0 +1,79 @@
+import Foundation
+
+/// Parakeet as the app uses it: never makes a turn wait for a download or
+/// for the first model load, and answers nil whenever mlx-whisper should
+/// take this turn instead.
+///
+/// The first load of Parakeet on a Mac takes about half a minute (Core ML
+/// prepares the encoder for the Neural Engine and caches the result);
+/// later loads take about half a second. A turn waits a few seconds for
+/// the load at most, then falls back while the load carries on.
+enum LocalSTT {
+    /// How long a turn waits for Parakeet to finish loading.
+    static let loadPatience: TimeInterval = 4
+
+    private static let loader = ParakeetLoader()
+
+    static func parakeet(wav: Data) async -> String? {
+        guard ModelStore.parakeet.isInstalled else {
+            Log.warn("Parakeet is not downloaded yet; using mlx-whisper for now")
+            ModelStore.installInBackground(ModelStore.parakeet) { Log.info($0) }
+            return nil
+        }
+        guard let engine = await loader.engine(within: loadPatience) else {
+            Log.warn("Parakeet is still loading (the first load takes about 30 s); using mlx-whisper for this turn")
+            return nil
+        }
+        return await Task.detached(priority: .userInitiated) { () -> String? in
+            do {
+                let t = Date()
+                let text = try engine.transcribe(wav: wav)
+                Log.info(String(format: "parakeet: %.2f s", Date().timeIntervalSince(t)))
+                return text
+            } catch {
+                Log.warn("Parakeet failed (\(error.localizedDescription)); falling back to mlx-whisper")
+                return nil
+            }
+        }.value
+    }
+}
+
+/// Loads Parakeet once, in the background, and lets callers wait for it
+/// with a limit.
+private actor ParakeetLoader {
+    private var loading: Task<Parakeet?, Never>?
+
+    func engine(within seconds: TimeInterval) async -> Parakeet? {
+        let task = loading ?? start()
+        return await withTaskGroup(of: Parakeet?.self) { group in
+            group.addTask { await task.value }
+            group.addTask {
+                try? await Task.sleep(nanoseconds: UInt64(seconds * 1_000_000_000))
+                return nil
+            }
+            let first = await group.next() ?? nil
+            group.cancelAll()
+            return first
+        }
+    }
+
+    private func start() -> Task<Parakeet?, Never> {
+        let task = Task.detached(priority: .userInitiated) { () -> Parakeet? in
+            let t = Date()
+            do {
+                let p = try Parakeet.loaded()
+                Log.info(String(format: "parakeet: loaded in %.1f s", Date().timeIntervalSince(t)))
+                return p
+            } catch {
+                Log.warn("Parakeet would not load (\(error.localizedDescription))")
+                return nil
+            }
+        }
+        loading = task
+        Task { if await task.value == nil { self.forget() } }
+        return task
+    }
+
+    /// A failed load is tried again on the next turn.
+    private func forget() { loading = nil }
+}

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

@@ -0,0 +1,184 @@
+import CryptoKit
+import Foundation
+
+/// On-device models, fetched on first use into ~/.agentx/models and never
+/// shipped with the app or the repository.
+///
+/// Every file is pinned twice: by the Hugging Face revision it comes from
+/// and by its SHA-256. A file that does not match is deleted, so a
+/// truncated download or a changed upstream repo can never be loaded. A
+/// model counts as installed only when a `.verified` stamp sits next to
+/// it, written after every file checked out, so a half-finished download
+/// is simply "not installed" and the next attempt starts over.
+struct LocalModel: Sendable {
+    struct File: Sendable {
+        let path: String
+        let size: Int64
+        let sha256: String
+    }
+
+    /// Short name for the command line and the logs: "vad", "parakeet".
+    let name: String
+    let repo: String
+    let revision: String
+    let files: [File]
+
+    var totalBytes: Int64 { files.reduce(0) { $0 + $1.size } }
+
+    /// ~/.agentx/models/<repo name>/
+    var directory: URL {
+        ModelStore.root.appendingPathComponent(repo.split(separator: "/").last.map(String.init) ?? repo)
+    }
+
+    func url(_ path: String) -> URL { directory.appendingPathComponent(path) }
+
+    private var stamp: URL { directory.appendingPathComponent(".verified") }
+
+    /// Every file is present and was verified for this revision.
+    var isInstalled: Bool {
+        guard let s = try? String(contentsOf: stamp, encoding: .utf8) else { return false }
+        return s.trimmingCharacters(in: .whitespacesAndNewlines) == revision
+            && files.allSatisfy { FileManager.default.fileExists(atPath: url($0.path).path) }
+    }
+
+    fileprivate func markInstalled() throws {
+        try revision.write(to: stamp, atomically: true, encoding: .utf8)
+    }
+}
+
+enum ModelStore {
+    static let root: URL = {
+        if let dir = ProcessInfo.processInfo.environment["AGENTX_MODELS_DIR"], !dir.isEmpty {
+            return URL(fileURLWithPath: dir)
+        }
+        return URL(fileURLWithPath: NSHomeDirectory()).appendingPathComponent(".agentx/models")
+    }()
+
+    /// Silero VAD v6, converted to Core ML by FluidInference (MIT). 0.9 MB.
+    /// One call scores 32 ms of 16 kHz audio (512 samples plus 64 of context).
+    static let vad = LocalModel(
+        name: "vad",
+        repo: "FluidInference/silero-vad-coreml",
+        revision: "b419383c55c110e2c9271fa6ee0ea83d03c70d96",
+        files: [
+            .init(path: "silero-vad-unified-v6.0.0.mlmodelc/analytics/coremldata.bin", size: 243, sha256: "2141be60ea0adf7acb1232fbcfaffb2be308ae02e6672d3762aedf36611ea9fd"),
+            .init(path: "silero-vad-unified-v6.0.0.mlmodelc/coremldata.bin", size: 593, sha256: "f460dcdf796b19c04bc38ab6e69601831f634e5e74d499487f0c8fe17ca12f0f"),
+            .init(path: "silero-vad-unified-v6.0.0.mlmodelc/metadata.json", size: 3232, sha256: "282b1b788b5d4d66d6a70d468464a7ada71d2469a8705526b741fd9ab841295a"),
+            .init(path: "silero-vad-unified-v6.0.0.mlmodelc/model.mil", size: 25126, sha256: "79eea23c368f3e7edf85af798a953f5b0910e4b08ff48e55fff8545dd05fd047"),
+            .init(path: "silero-vad-unified-v6.0.0.mlmodelc/weights/weight.bin", size: 882304, sha256: "853cf34740d3f5061f977ebe2976f7c921b064261c9c4753b3a1196f2dba42b4"),
+        ])
+
+    /// NVIDIA Parakeet TDT 0.6B v3 (CC-BY-4.0), converted to Core ML by
+    /// FluidInference. 483 MB, almost all of it the encoder. The same build
+    /// FluidAudio loads by default: 6-bit palettized encoder, 15 s window.
+    static let parakeet = LocalModel(
+        name: "parakeet",
+        repo: "FluidInference/parakeet-tdt-0.6b-v3-coreml",
+        revision: "7dd20fe6b1797d35f5e3307e8b1732d9a178edfe",
+        files: [
+            .init(path: "Preprocessor.mlmodelc/analytics/coremldata.bin", size: 243, sha256: "c9beeb989c8d66f8be11df59bc6df277ec76cee404f6865b46243835ef562f6d"),
+            .init(path: "Preprocessor.mlmodelc/coremldata.bin", size: 486, sha256: "dbde3f2300842c1fd51ef3ff948a0bcffe65ffd2dca10707f2509f32c1d65b1d"),
+            .init(path: "Preprocessor.mlmodelc/metadata.json", size: 2841, sha256: "2a98699e22d279dd37fa1d238aeb1c6db1df0d6fad687775324157689d8f3acf"),
+            .init(path: "Preprocessor.mlmodelc/model.mil", size: 28181, sha256: "4b8518a956450fec57f06c2a21bdffc26973f7f1fa6842fb38fe917f896b6b93"),
+            .init(path: "Preprocessor.mlmodelc/weights/weight.bin", size: 491072, sha256: "129b76e3aeafa8afa3ea76d995b964b145fe83700d579f6ff42c4c38fa0968ea"),
+            .init(path: "Encoder.mlmodelc/analytics/coremldata.bin", size: 243, sha256: "42e638870d73f26b332918a3496ce36793fbb413a81cbd3d16ba01328637a105"),
+            .init(path: "Encoder.mlmodelc/coremldata.bin", size: 485, sha256: "d48034a167a82e88fc3df64f60af963ab3983538271175b8319e7d5720a0fb86"),
+            .init(path: "Encoder.mlmodelc/metadata.json", size: 2921, sha256: "da24da9cca943fb29d7fa8e376d57fca7cb3aa08ca51b956b0b0e56813f087e9"),
+            .init(path: "Encoder.mlmodelc/model.mil", size: 959769, sha256: "ed7b19156ca29fa7dfd6891deb9fda4b0e8893f68597c985d135736546a43808"),
+            .init(path: "Encoder.mlmodelc/weights/weight.bin", size: 445187200, sha256: "e2020f323703477a5b21d7c2d282c403e371afb5962e79877e3033e73ba6f421"),
+            .init(path: "Decoder.mlmodelc/analytics/coremldata.bin", size: 243, sha256: "4238c4e81ecd0dc94bd7dfbb60f7e2cc824107c1ffe0387b8607b72833dba350"),
+            .init(path: "Decoder.mlmodelc/coremldata.bin", size: 554, sha256: "18647af085d87bd8f3121c8a9b4d4564c1ede038dab63d295b4e745cf2d7fb99"),
+            .init(path: "Decoder.mlmodelc/metadata.json", size: 3427, sha256: "a39e93cd8371b8ded92635c7804fcd0590f0d1dd9415c6d19a0484be073077d9"),
+            .init(path: "Decoder.mlmodelc/model.mil", size: 13110, sha256: "ef2a0a281695398a62fde86ac269c68f73d5b578d7ed3b31f2ba91a2d1ea1f35"),
+            .init(path: "Decoder.mlmodelc/weights/weight.bin", size: 23604992, sha256: "48adf0f0d47c406c8253d4f7fef967436a39da14f5a65e66d5a4b407be355d41"),
+            .init(path: "JointDecisionv3.mlmodelc/analytics/coremldata.bin", size: 243, sha256: "26def4bf73dd56d29dee21c8ef97cb8969e62f6120ed1adc91e46828e2737b6c"),
+            .init(path: "JointDecisionv3.mlmodelc/coremldata.bin", size: 521, sha256: "f5fc08b741400f0088492c9e839418b1e18522f19cba28d361dd030c5f398342"),
+            .init(path: "JointDecisionv3.mlmodelc/metadata.json", size: 3453, sha256: "d9307211b9a37e0f0ac260c7660b1571a3de25841035cfdf9b58fd40425f890f"),
+            .init(path: "JointDecisionv3.mlmodelc/model.mil", size: 11775, sha256: "be60732943389a047175111a83f8839f3eb39d4803adafa828a0871b2f39818d"),
+            .init(path: "JointDecisionv3.mlmodelc/weights/weight.bin", size: 12642764, sha256: "4e0e63d840032f7f07ddb1d64446051166281e5491bf22da8a945c41f6eedb3e"),
+            .init(path: "parakeet_vocab.json", size: 151122, sha256: "7ec60e05f1b24480736ec0eed40900f4626bce1fa9a60fd700ec7e2a59198735"),
+        ])
+
+    static let all = [vad, parakeet]
+
+    enum StoreError: LocalizedError {
+        case http(String, Int)
+        case mismatch(String)
+        var errorDescription: String? {
+            switch self {
+            case .http(let path, let code): return "download of \(path) failed with HTTP \(code)"
+            case .mismatch(let path): return "\(path) did not match its checksum and was deleted"
+            }
+        }
+    }
+
+    /// Downloads whatever is missing or wrong, checks every file, then
+    /// stamps the model installed. `progress` gets bytes done and total.
+    static func install(_ model: LocalModel, progress: ((Int64, Int64) -> Void)? = nil) async throws {
+        if model.isInstalled { return }
+        let fm = FileManager.default
+        try fm.createDirectory(at: model.directory, withIntermediateDirectories: true)
+        var done: Int64 = 0
+        for file in model.files {
+            let dest = model.url(file.path)
+            if fm.fileExists(atPath: dest.path), (try? sha256(of: dest)) == file.sha256 {
+                done += file.size
+                progress?(done, model.totalBytes)
+                continue
+            }
+            try? fm.removeItem(at: dest)
+            try fm.createDirectory(at: dest.deletingLastPathComponent(), withIntermediateDirectories: true)
+            let source = URL(string: "https://huggingface.co/\(model.repo)/resolve/\(model.revision)/\(file.path)")!
+            let (tmp, response) = try await URLSession.shared.download(from: source)
+            if let http = response as? HTTPURLResponse, !(200..<300).contains(http.statusCode) {
+                try? fm.removeItem(at: tmp)
+                throw StoreError.http(file.path, http.statusCode)
+            }
+            guard (try? sha256(of: tmp)) == file.sha256 else {
+                try? fm.removeItem(at: tmp)
+                throw StoreError.mismatch(file.path)
+            }
+            try fm.moveItem(at: tmp, to: dest)
+            done += file.size
+            progress?(done, model.totalBytes)
+        }
+        try model.markInstalled()
+    }
+
+    /// Streams the file, so the 445 MB encoder is never held in memory.
+    static func sha256(of url: URL) throws -> String {
+        let handle = try FileHandle(forReadingFrom: url)
+        defer { try? handle.close() }
+        var hasher = SHA256()
+        while let chunk = try handle.read(upToCount: 1 << 20), !chunk.isEmpty {
+            hasher.update(data: chunk)
+        }
+        return hasher.finalize().map { String(format: "%02x", $0) }.joined()
+    }
+
+    private static let background = BackgroundInstalls()
+
+    /// Starts one download of `model` in the background unless it is
+    /// installed or already downloading. For first use: the turn that
+    /// found it missing falls back, and a later one gets the model.
+    static func installInBackground(_ model: LocalModel, log: @escaping @Sendable (String) -> Void) {
+        guard !model.isInstalled, background.begin(model.name) else { return }
+        log("downloading the \(model.name) model (\(model.totalBytes / 1_000_000) MB) into \(model.directory.path)")
+        Task.detached {
+            do {
+                try await install(model)
+                log("the \(model.name) model is installed")
+            } catch {
+                log("the \(model.name) model could not be downloaded: \(error.localizedDescription)")
+            }
+            background.end(model.name)
+        }
+    }
+}
+
+private final class BackgroundInstalls: @unchecked Sendable {
+    private let lock = NSLock()
+    private var running = Set<String>()
+    func begin(_ name: String) -> Bool { lock.lock(); defer { lock.unlock() }; return running.insert(name).inserted }
+    func end(_ name: String) { lock.lock(); running.remove(name); lock.unlock() }
+}

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

@@ -1,8 +1,8 @@
 import AppKit
 import SwiftUI
 
-/// The Siri-style orb at the head of the pill: the agent's colour, and it
-/// listens, thinks and speaks.
+/// The Siri-style orb at the head of the pill: the agent's nature palette
+/// (lagoon, forest, dusk…), and it listens, thinks and speaks.
 ///
 /// 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
@@ -18,6 +18,9 @@ final class OrbModel: ObservableObject {
     /// 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)
+    /// The agent's palette, five stops deep to light, from the daemon.
+    /// Nil: shades of `tint` (an error, held notifications, an older daemon).
+    @Published var colors: [NSColor]?
     /// The pill is on screen. Off, nothing moves.
     @Published var onScreen = false
     @Published var reduceMotion = NSWorkspace.shared.accessibilityDisplayShouldReduceMotion
@@ -43,8 +46,8 @@ struct PillOrbView: View {
         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: model.still,
-                    ringWidth: 5)
+                    phase: model.phase, level: model.level, tint: model.tint, colors: model.colors,
+                    still: model.still, ringWidth: 5)
                 .frame(width: Self.designSize, height: Self.designSize)
                 .scaleEffect(diameter / Self.designSize)
         }
@@ -89,11 +92,12 @@ final class PillOrb: NSHostingView<PillOrbView> {
 
     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) {
+    /// Show `phase` in `colors`, or in shades of `tint` without them.
+    /// Cheap to call on every render: SwiftUI only redraws what changed.
+    func show(_ phase: OrbModel.Phase, tint: NSColor, colors: [NSColor]?) {
         let model = driver.model
         if model.tint != tint { model.tint = tint }
+        if model.colors != colors { model.colors = colors }
         if model.phase != phase {
             model.phase = phase
             if phase != .listening { model.level = 0 }
@@ -160,6 +164,8 @@ struct OrbBody: View {
     let phase: OrbModel.Phase
     let level: Double
     let tint: NSColor
+    /// The agent's palette, deep to light; nil for shades of `tint`.
+    var colors: [NSColor]? = nil
     /// 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
@@ -190,12 +196,17 @@ struct OrbBody: View {
         let scale = 0.78 + 0.22 * energy
         ZStack {
             Circle()
-                .fill(Color(nsColor: tint).opacity(0.28 + 0.32 * energy))
+                .fill(glow.opacity(0.28 + 0.32 * energy))
                 .blur(radius: 10 + 12 * energy)
                 .scaleEffect(scale * 1.08)
             fill
                 .clipShape(Circle())
                 .scaleEffect(scale)
+            // Glass: a soft light from the top left, as on a marble.
+            Circle()
+                .fill(RadialGradient(colors: [.white.opacity(0.42), .white.opacity(0)],
+                                     center: UnitPoint(x: 0.34, y: 0.26), startRadius: 0, endRadius: 34))
+                .scaleEffect(scale)
             // Thinking reads as a slow ring going round; the other states
             // as a soft rim.
             if phase == .thinking {
@@ -247,9 +258,25 @@ struct OrbBody: View {
         ]
     }
 
+    /// The halo's colour: the palette's middle stop, or the tint.
+    private var glow: Color {
+        if let colors, colors.count == 5 { return Color(nsColor: colors[2]) }
+        return Color(nsColor: tint)
+    }
+
+    /// Five colours for the mesh: the agent's palette when it has one,
+    /// with its light stop brightening into a core as the voice grows.
+    private var palette: [Color] {
+        guard let colors, colors.count == 5 else { return shades }
+        let core = CGFloat(0.1 + 0.35 * energy)
+        let light = colors[4].blended(withFraction: core, of: .white) ?? colors[4]
+        // Spread so neighbouring mesh points differ: deep beside light.
+        return [colors[1], colors[3], colors[0], colors[2], light].map { Color(nsColor: $0) }
+    }
+
     /// Five shades around the agent's colour: lighter, deeper and two
     /// neighbouring hues, and a bright core that grows with the voice.
-    private var palette: [Color] {
+    private var shades: [Color] {
         let base = tint.usingColorSpace(.sRGB) ?? tint
         var h: CGFloat = 0, s: CGFloat = 0, b: CGFloat = 0, a: CGFloat = 0
         base.getHue(&h, saturation: &s, brightness: &b, alpha: &a)