agentix-cli 0.56.0 → 0.57.0

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

@@ -161,6 +161,49 @@ enum AgentClient {
         return try await URLSession.shared.data(for: req)
     }
 
+    // MARK: Settings
+    //
+    // The settings window reads and saves through the daemon, which checks
+    // every value and writes agentx.json. The app keeps no copy of its own.
+    // See src/daemon/voice-settings-api.ts.
+
+    /// GET /voice/settings, or nil when the daemon cannot be reached.
+    static func settings() async -> VoiceSettings? {
+        guard let url = URL(string: "\(Config.daemonURL)/voice/settings") else { return nil }
+        var req = URLRequest(url: url)
+        // The first call lists the Mac's voices, which can take a moment.
+        req.timeoutInterval = 15
+        guard let (data, response) = try? await URLSession.shared.data(for: req),
+              (response as? HTTPURLResponse)?.statusCode == 200 else { return nil }
+        return try? JSONDecoder().decode(VoiceSettings.self, from: data)
+    }
+
+    /// Save a change. The saved settings, or the daemon's reason in words.
+    static func saveSettings(_ patch: [String: Any]) async -> Result<VoiceSettings, SettingsFailure> {
+        struct Reply: Decodable { let settings: VoiceSettings?; let error: String? }
+        do {
+            let (data, response) = try await post("/voice/settings", patch, timeout: 20)
+            let reply = try? JSONDecoder().decode(Reply.self, from: data)
+            if let s = reply?.settings, (response as? HTTPURLResponse)?.statusCode == 200 { return .success(s) }
+            return .failure(SettingsFailure(message: reply?.error ?? "The daemon did not save the settings."))
+        } catch {
+            return .failure(SettingsFailure(message: "The AgentX daemon isn't reachable: \(error.localizedDescription)"))
+        }
+    }
+
+    /// Say a sample line in an agent's voice with unsaved changes. Nil on
+    /// success, else why not.
+    static func preview(agentID: String, voice: [String: Any]) async -> String? {
+        struct Reply: Decodable { let error: String? }
+        guard let (data, response) = try? await post("/voice/preview", ["agentId": agentID, "voice": voice], timeout: 10) else {
+            return "The AgentX daemon isn't reachable."
+        }
+        if (response as? HTTPURLResponse)?.statusCode == 202 { return nil }
+        return (try? JSONDecoder().decode(Reply.self, from: data))?.error ?? "The preview didn't play."
+    }
+
+    struct SettingsFailure: Error { let message: String }
+
     /// One row of GET /agents: who can answer, and whether they are busy.
     struct AgentInfo: Decodable {
         let id: String

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

@@ -28,7 +28,13 @@ final class Hotkey {
         self.onRelease = onRelease
     }
 
-    func register(keyCode: UInt32 = UInt32(kVK_Space), modifiers: UInt32 = UInt32(optionKey)) {
+    /// Register one shortcut; false when macOS refused it (another app
+    /// already holds it).
+    @discardableResult
+    func register(_ spec: HotkeySpec) -> Bool { register(keyCode: spec.keyCode, modifiers: spec.modifiers) }
+
+    @discardableResult
+    func register(keyCode: UInt32 = UInt32(kVK_Space), modifiers: UInt32 = UInt32(optionKey)) -> Bool {
         var spec = [
             EventTypeSpec(eventClass: OSType(kEventClassKeyboard), eventKind: UInt32(kEventHotKeyPressed)),
             EventTypeSpec(eventClass: OSType(kEventClassKeyboard), eventKind: UInt32(kEventHotKeyReleased)),
@@ -66,7 +72,7 @@ final class Hotkey {
         }, spec.count, &spec, context, &handler)
 
         let hotKeyID = EventHotKeyID(signature: OSType(0x41475856), id: id) // 'AGXV'
-        RegisterEventHotKey(keyCode, modifiers, hotKeyID, GetApplicationEventTarget(), 0, &ref)
+        return RegisterEventHotKey(keyCode, modifiers, hotKeyID, GetApplicationEventTarget(), 0, &ref) == noErr
     }
 
     deinit {

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

@@ -0,0 +1,80 @@
+import Carbon.HIToolbox
+
+/// A shortcut as agentx.json stores it: "opt+space", "cmd+opt+period",
+/// "ctrl+opt+1". The daemon checks and normalises the same form
+/// (src/voice/hotkey.ts); this turns it into what Carbon registers, and a
+/// pressed key back into it.
+struct HotkeySpec: Equatable {
+    let keyCode: UInt32
+    /// Carbon modifier flags (cmdKey, optionKey, …).
+    let modifiers: UInt32
+
+    static let keys: [String: Int] = {
+        var k: [String: Int] = [
+            "a": kVK_ANSI_A, "b": kVK_ANSI_B, "c": kVK_ANSI_C, "d": kVK_ANSI_D, "e": kVK_ANSI_E,
+            "f": kVK_ANSI_F, "g": kVK_ANSI_G, "h": kVK_ANSI_H, "i": kVK_ANSI_I, "j": kVK_ANSI_J,
+            "k": kVK_ANSI_K, "l": kVK_ANSI_L, "m": kVK_ANSI_M, "n": kVK_ANSI_N, "o": kVK_ANSI_O,
+            "p": kVK_ANSI_P, "q": kVK_ANSI_Q, "r": kVK_ANSI_R, "s": kVK_ANSI_S, "t": kVK_ANSI_T,
+            "u": kVK_ANSI_U, "v": kVK_ANSI_V, "w": kVK_ANSI_W, "x": kVK_ANSI_X, "y": kVK_ANSI_Y,
+            "z": kVK_ANSI_Z,
+            "0": kVK_ANSI_0, "1": kVK_ANSI_1, "2": kVK_ANSI_2, "3": kVK_ANSI_3, "4": kVK_ANSI_4,
+            "5": kVK_ANSI_5, "6": kVK_ANSI_6, "7": kVK_ANSI_7, "8": kVK_ANSI_8, "9": kVK_ANSI_9,
+            "space": kVK_Space, "period": kVK_ANSI_Period, "comma": kVK_ANSI_Comma,
+            "slash": kVK_ANSI_Slash, "semicolon": kVK_ANSI_Semicolon, "quote": kVK_ANSI_Quote,
+            "minus": kVK_ANSI_Minus, "equal": kVK_ANSI_Equal,
+            "leftbracket": kVK_ANSI_LeftBracket, "rightbracket": kVK_ANSI_RightBracket,
+            "backslash": kVK_ANSI_Backslash, "grave": kVK_ANSI_Grave,
+            "return": kVK_Return, "tab": kVK_Tab,
+        ]
+        let f = [kVK_F1, kVK_F2, kVK_F3, kVK_F4, kVK_F5, kVK_F6, kVK_F7, kVK_F8, kVK_F9, kVK_F10,
+                 kVK_F11, kVK_F12, kVK_F13, kVK_F14, kVK_F15, kVK_F16, kVK_F17, kVK_F18, kVK_F19, kVK_F20]
+        for (i, code) in f.enumerated() { k["f\(i + 1)"] = code }
+        return k
+    }()
+
+    private static let modifierFlags: [(String, UInt32)] = [
+        ("ctrl", UInt32(controlKey)), ("opt", UInt32(optionKey)),
+        ("shift", UInt32(shiftKey)), ("cmd", UInt32(cmdKey)),
+    ]
+    private static let aliases = ["control": "ctrl", "option": "opt", "alt": "opt", "command": "cmd"]
+
+    /// Nil for anything the daemon would refuse.
+    init?(_ text: String) {
+        let parts = text.lowercased().split(separator: "+", omittingEmptySubsequences: false)
+            .map { $0.trimmingCharacters(in: .whitespaces) }
+        guard let key = parts.last, let code = Self.keys[key] else { return nil }
+        var mods: UInt32 = 0
+        for p in parts.dropLast() {
+            let name = Self.aliases[p] ?? p
+            guard let flag = Self.modifierFlags.first(where: { $0.0 == name })?.1, mods & flag == 0 else { return nil }
+            mods |= flag
+        }
+        let isF = key.hasPrefix("f") && key.count > 1
+        guard isF || mods & UInt32(controlKey | optionKey | cmdKey) != 0 else { return nil }
+        keyCode = UInt32(code)
+        modifiers = mods
+    }
+
+    init(keyCode: UInt32, modifiers: UInt32) {
+        self.keyCode = keyCode
+        self.modifiers = modifiers
+    }
+
+    /// The stored form, modifiers in the Mac's order.
+    var text: String? {
+        guard let key = Self.keys.first(where: { UInt32($0.value) == keyCode })?.key else { return nil }
+        let mods = Self.modifierFlags.filter { modifiers & $0.1 != 0 }.map(\.0)
+        return (mods + [key]).joined(separator: "+")
+    }
+
+    /// "⌃⌥1", as menus show shortcuts.
+    static func display(_ text: String) -> String {
+        let symbols = ["ctrl": "⌃", "opt": "⌥", "shift": "⇧", "cmd": "⌘"]
+        let names = ["space": "Space", "period": ".", "comma": ",", "slash": "/", "semicolon": ";",
+                     "quote": "'", "minus": "-", "equal": "=", "leftbracket": "[", "rightbracket": "]",
+                     "backslash": "\\", "grave": "`", "return": "Return", "tab": "Tab"]
+        var parts = text.lowercased().split(separator: "+").map(String.init)
+        guard let key = parts.popLast() else { return text }
+        return parts.map { symbols[Self.aliases[$0] ?? $0] ?? $0 }.joined() + (names[key] ?? key.uppercased())
+    }
+}

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

@@ -0,0 +1,518 @@
+import AppKit
+import Carbon.HIToolbox
+import ServiceManagement
+import SwiftUI
+
+/// Settings: per-agent voices and the app's own shortcuts and engines.
+///
+/// Everything but launch at login lives in agentx.json and goes through
+/// the daemon, which checks each value against the config schema before
+/// writing. The window shows what the daemon has and keeps no copy: it
+/// loads fresh every time it opens and after every save.
+@MainActor
+final class SettingsModel: ObservableObject {
+    @Published var saved: VoiceSettings?
+    @Published var draft: VoiceSettings?
+    @Published var selected: String?
+    @Published var loading = false
+    @Published var saving = false
+    @Published var error = ""
+    @Published var notice = ""
+    @Published var launchAtLogin = LoginItem.isOn
+    /// "agents" or "general".
+    @Published var tab = "agents"
+    /// A shortcut field is waiting for keys: the app's own shortcuts are
+    /// off meanwhile, or they would fire instead of being recorded.
+    @Published var recording: String? {
+        didSet { if (recording == nil) != (oldValue == nil) { onRecording?(recording != nil) } }
+    }
+
+    var onSaved: ((VoiceSettings) -> Void)?
+    var onRecording: ((Bool) -> Void)?
+
+    var hasChanges: Bool {
+        guard let saved, let draft else { return false }
+        return !draft.patch(from: saved).isEmpty
+    }
+
+    func load() {
+        loading = true
+        error = ""
+        Task {
+            let s = await AgentClient.settings()
+            loading = false
+            guard let s else {
+                error = "The AgentX daemon isn't reachable. Start it, then open Settings again."
+                return
+            }
+            saved = s
+            draft = s
+            if selected == nil || !s.agents.contains(where: { $0.id == selected }) { selected = s.agents.first?.id }
+        }
+    }
+
+    func revert() {
+        draft = saved
+        error = ""
+        notice = ""
+    }
+
+    func save() {
+        guard let saved, let draft, hasChanges else { return }
+        saving = true
+        error = ""
+        notice = ""
+        Task {
+            let result = await AgentClient.saveSettings(draft.patch(from: saved))
+            saving = false
+            switch result {
+            case .success(let s):
+                self.saved = s
+                self.draft = s
+                notice = "Saved. The next line spoken uses it; no restart needed."
+                onSaved?(s)
+            case .failure(let f):
+                error = f.message
+            }
+        }
+    }
+
+    func preview(_ id: String) {
+        guard let draft else { return }
+        error = ""
+        notice = "Playing a sample…"
+        Task {
+            if let problem = await AgentClient.preview(agentID: id, voice: draft.previewVoice(for: id)) {
+                notice = ""
+                error = problem
+            } else {
+                notice = "Playing a sample. It is not saved until you press Save."
+            }
+        }
+    }
+
+    func setLaunchAtLogin(_ on: Bool) {
+        do {
+            try LoginItem.set(on)
+            error = ""
+        } catch {
+            self.error = "macOS didn't change the login item: \(error.localizedDescription)"
+        }
+        launchAtLogin = LoginItem.isOn
+    }
+
+    /// A binding into the draft for the agent `id`.
+    func agent(_ id: String) -> Binding<VoiceSettings.Agent>? {
+        guard let i = draft?.agents.firstIndex(where: { $0.id == id }) else { return nil }
+        return Binding(get: { self.draft!.agents[i] }, set: { self.draft!.agents[i] = $0 })
+    }
+}
+
+/// Launch at login is macOS's own setting, never agentx.json.
+enum LoginItem {
+    /// The launchd label `agentx desktop install` gives the app.
+    static let installerLabel = "tn.acme.agentx.voice"
+
+    /// Installed with `agentx desktop install`, which starts the app at
+    /// login with launchd. A second login item would start a second copy.
+    static var managedByInstaller: Bool {
+        if ProcessInfo.processInfo.environment["XPC_SERVICE_NAME"] == installerLabel { return true }
+        let plist = "\(NSHomeDirectory())/Library/LaunchAgents/\(installerLabel).plist"
+        return FileManager.default.fileExists(atPath: plist)
+    }
+
+    static var isOn: Bool { managedByInstaller || SMAppService.mainApp.status == .enabled }
+
+    static func set(_ on: Bool) throws {
+        if on { try SMAppService.mainApp.register() } else { try SMAppService.mainApp.unregister() }
+    }
+}
+
+struct SettingsView: View {
+    @ObservedObject var model: SettingsModel
+
+    var body: some View {
+        VStack(spacing: 0) {
+            if let draft = model.draft {
+                TabView(selection: $model.tab) {
+                    AgentsTab(model: model, settings: draft)
+                        .tabItem { Text("Agents") }
+                        .tag("agents")
+                    GeneralTab(model: model)
+                        .tabItem { Text("General") }
+                        .tag("general")
+                }
+                .padding([.horizontal, .top], 12)
+            } else {
+                VStack(spacing: 12) {
+                    if model.loading { ProgressView() }
+                    Text(model.loading ? "Loading settings…" : model.error)
+                        .foregroundStyle(.secondary)
+                    if !model.loading { Button("Try again") { model.load() } }
+                }
+                .frame(maxWidth: .infinity, maxHeight: .infinity)
+            }
+            if model.draft != nil { footer }
+        }
+        .frame(width: 660, height: 640)
+    }
+
+    private var footer: some View {
+        HStack(alignment: .top, spacing: 12) {
+            VStack(alignment: .leading, spacing: 2) {
+                if !model.error.isEmpty {
+                    Text(model.error)
+                        .foregroundStyle(Color(nsColor: .systemRed))
+                        .fixedSize(horizontal: false, vertical: true)
+                        .textSelection(.enabled)
+                } else if !model.notice.isEmpty {
+                    Text(model.notice).foregroundStyle(.secondary)
+                }
+            }
+            .font(.callout)
+            .frame(maxWidth: .infinity, alignment: .leading)
+            Button("Revert") { model.revert() }
+                .disabled(!model.hasChanges || model.saving)
+            Button(model.saving ? "Saving…" : "Save") { model.save() }
+                .keyboardShortcut("s", modifiers: .command)
+                .disabled(!model.hasChanges || model.saving)
+        }
+        .padding(12)
+    }
+}
+
+// MARK: Agents
+
+private struct AgentsTab: View {
+    @ObservedObject var model: SettingsModel
+    let settings: VoiceSettings
+
+    var body: some View {
+        HStack(spacing: 0) {
+            List(settings.agents, selection: $model.selected) { agent in
+                HStack(spacing: 8) {
+                    Circle().fill(Color(hex: agent.color)).frame(width: 10, height: 10)
+                    Text(agent.name)
+                }
+                .tag(agent.id)
+            }
+            .frame(width: 170)
+            Divider()
+            if let id = model.selected, let agent = model.agent(id) {
+                AgentForm(model: model, agent: agent, settings: settings)
+            } else {
+                Text("No agents in agentx.json").foregroundStyle(.secondary)
+                    .frame(maxWidth: .infinity, maxHeight: .infinity)
+            }
+        }
+    }
+}
+
+private struct AgentForm: View {
+    @ObservedObject var model: SettingsModel
+    @Binding var agent: VoiceSettings.Agent
+    let settings: VoiceSettings
+
+    private var provider: String { agent.voice.provider ?? settings.general.provider }
+
+    var body: some View {
+        Form {
+            voiceSection
+            workSection
+            shortcutSection
+        }
+        .formStyle(.grouped)
+    }
+
+    private var voiceSection: some View {
+        Section {
+            providerPicker
+            systemVoicePicker
+            elevenLabsField
+            previewRow
+            rateRow
+        } header: {
+            Text("Voice")
+        } footer: {
+            Text("Voice changes apply to the next line this agent speaks. ElevenLabs speaks at most 1.2× and at least 0.7×.")
+                .font(.caption).foregroundStyle(.secondary)
+        }
+    }
+
+    private var providerPicker: some View {
+        let fallback = settings.general.provider == "elevenlabs" ? "ElevenLabs" : "Mac voices"
+        return Picker("Voice provider", selection: $agent.voice.provider) {
+            Text("Default (\(fallback))").tag(String?.none)
+            Text("Mac voices (free)").tag(String?.some("system"))
+            Text("ElevenLabs").tag(String?.some("elevenlabs"))
+        }
+    }
+
+    /// A configured voice the Mac doesn't list (a plain name such as
+    /// "Daniel"), kept selectable so the picker can show it.
+    private var unlistedVoice: String? {
+        guard let s = agent.voice.system, s != "system",
+              !settings.systemVoices.contains(where: { $0.id == s }) else { return nil }
+        return s
+    }
+
+    @ViewBuilder private var systemVoicePicker: some View {
+        if agent.voice.systemPerLanguage {
+            LabeledContent("Mac voice", value: "One voice per language, set in agentx.json")
+        } else {
+            Picker("Mac voice", selection: $agent.voice.system) {
+                Text("Assigned automatically").tag(String?.none)
+                Text("The Mac's default voice").tag(String?.some("system"))
+                if let s = unlistedVoice { Text(s).tag(String?.some(s)) }
+                ForEach(settings.systemVoices) { v in
+                    Text(v.label).tag(String?.some(v.id))
+                }
+            }
+        }
+    }
+
+    private var elevenLabsField: some View {
+        let text = Binding<String>(
+            get: { agent.voice.elevenlabsVoiceId ?? "" },
+            set: { agent.voice.elevenlabsVoiceId = $0.isEmpty ? nil : $0 })
+        return TextField("ElevenLabs voice ID", text: text, prompt: Text("Default voice"))
+            .disabled(provider != "elevenlabs")
+    }
+
+    private var previewRow: some View {
+        let now: String = agent.speaks.provider == "elevenlabs" ? "ElevenLabs" : (agent.speaks.systemVoice ?? "the Mac's default voice")
+        return HStack {
+            Text("Saved voice: \(now)").font(.caption).foregroundStyle(.secondary)
+            Spacer()
+            Button("Preview") { model.preview(agent.id) }
+        }
+    }
+
+    private var rateRow: some View {
+        let rate = Binding<Double>(
+            get: { agent.voice.rate ?? 1 },
+            set: { v in
+                let snapped = (v * 20).rounded() / 20
+                agent.voice.rate = abs(snapped - 1) < 0.001 ? nil : snapped
+            })
+        return HStack {
+            Slider(value: rate, in: 0.75...1.5, step: 0.05) { Text("Speaking speed") }
+            Text(String(format: "%.2f×", agent.voice.rate ?? 1)).monospacedDigit().frame(width: 48)
+            Button("Normal") { agent.voice.rate = nil }.disabled(agent.voice.rate == nil)
+        }
+    }
+
+    private var workSection: some View {
+        // "off" written out and unset mean the same: both show as Off.
+        let narrate = Binding<String?>(
+            get: { agent.voice.narrate == "off" ? nil : agent.voice.narrate },
+            set: { agent.voice.narrate = $0 })
+        return Section("While it works") {
+            Picker("Narration", selection: narrate) {
+                Text("Off").tag(String?.none)
+                Text("On, except scheduled jobs").tag(String?.some("on"))
+                Text("On, scheduled jobs too").tag(String?.some("all"))
+            }
+            Picker("Queue priority", selection: $agent.voice.priority) {
+                Text("Normal").tag(String?.none)
+                Text("High: ahead of waiting lines").tag(String?.some("high"))
+                Text("Low: after waiting lines").tag(String?.some("low"))
+            }
+        }
+    }
+
+    private var shortcutSection: some View {
+        let color = Binding<Color>(
+            get: { Color(hex: agent.color) },
+            set: { agent.color = $0.hex; agent.colorSet = true })
+        let footer = agent.colorSet
+            ? "Hold the shortcut and speak to ask this agent without changing who is ticked in the menu. The colour also paints this agent's pointer."
+            : "Hold the shortcut and speak to ask this agent without changing who is ticked in the menu. The colour comes from the agent's id until you pick one."
+        return Section {
+            HotkeyField(title: "Ask with shortcut", value: $agent.voice.hotkey, optional: true, model: model, id: "agent.\(agent.id)")
+            HStack {
+                ColorPicker("Orb colour", selection: color, supportsOpacity: false)
+                Button("Use default") { agent.colorSet = false }.disabled(!agent.colorSet)
+            }
+        } header: {
+            Text("Shortcut and colour")
+        } footer: {
+            Text(footer).font(.caption).foregroundStyle(.secondary)
+        }
+    }
+}
+
+// MARK: General
+
+private struct GeneralTab: View {
+    @ObservedObject var model: SettingsModel
+
+    var body: some View {
+        Form {
+            if let draft = model.draft {
+                Section {
+                    HotkeyField(title: "Talk (hold)", value: nonOptional(\.talk, draft.general.hotkeys.talk), optional: false, model: model, id: "talk")
+                    HotkeyField(title: "Stop every voice", value: nonOptional(\.stop, draft.general.hotkeys.stop), optional: false, model: model, id: "stop")
+                    HotkeyField(title: "Smart paste", value: nonOptional(\.paste, draft.general.hotkeys.paste), optional: false, model: model, id: "paste")
+                    LabeledContent("Open the menu", value: HotkeySpec.display(draft.menuHotkey))
+                } header: {
+                    Text("Shortcuts")
+                } footer: {
+                    Text("Shortcuts change as soon as you save. If one does nothing, another app already uses it.")
+                        .font(.caption).foregroundStyle(.secondary)
+                }
+                Section {
+                    Picker("Speech to text", selection: binding(\.stt)) {
+                        Text("Automatic").tag("auto")
+                        Text("ElevenLabs").tag("elevenlabs")
+                        Text("On this Mac (Whisper)").tag("local")
+                    }
+                    Picker("Default voice provider", selection: binding(\.provider)) {
+                        Text("Mac voices (free)").tag("system")
+                        Text("ElevenLabs").tag("elevenlabs")
+                    }
+                } header: {
+                    Text("Speech")
+                } footer: {
+                    Text("Automatic uses ElevenLabs when a key is set, and Whisper on this Mac otherwise. The default provider is for agents that don't choose their own. Both apply to the next question.")
+                        .font(.caption).foregroundStyle(.secondary)
+                }
+                Section {
+                    Toggle("Launch at login", isOn: Binding(get: { model.launchAtLogin }, set: { model.setLaunchAtLogin($0) }))
+                        .disabled(LoginItem.managedByInstaller)
+                } footer: {
+                    Text(LoginItem.managedByInstaller
+                         ? "Started at login by `agentx desktop install`. To stop that, run `agentx desktop stop` in Terminal."
+                         : "Saved by macOS as a login item, not in agentx.json. Changes right away.")
+                        .font(.caption).foregroundStyle(.secondary)
+                }
+            }
+        }
+        .formStyle(.grouped)
+    }
+
+    private func binding(_ path: WritableKeyPath<VoiceSettings.General, String>) -> Binding<String> {
+        Binding(get: { model.draft?.general[keyPath: path] ?? "" },
+                set: { model.draft?.general[keyPath: path] = $0 })
+    }
+
+    private func nonOptional(_ path: WritableKeyPath<VoiceSettings.Hotkeys, String>, _ now: String) -> Binding<String?> {
+        Binding(get: { now }, set: { if let v = $0 { model.draft?.general.hotkeys[keyPath: path] = v } })
+    }
+}
+
+// MARK: Shortcut field
+
+/// Click, then press the keys. Escape cancels; Delete clears an optional one.
+private struct HotkeyField: View {
+    let title: String
+    @Binding var value: String?
+    let optional: Bool
+    @ObservedObject var model: SettingsModel
+    let id: String
+    @State private var monitor: Any?
+    @State private var hint = ""
+
+    private var recording: Bool { model.recording == id }
+
+    var body: some View {
+        LabeledContent(title) {
+            HStack(spacing: 6) {
+                if !hint.isEmpty { Text(hint).font(.caption).foregroundStyle(.secondary) }
+                Button(recording ? "Type the shortcut…" : value.map(HotkeySpec.display) ?? "None") {
+                    recording ? stop() : start()
+                }
+                .frame(minWidth: 110)
+                if optional && value != nil && !recording {
+                    Button { value = nil } label: { Image(systemName: "xmark.circle.fill") }
+                        .buttonStyle(.borderless)
+                        .accessibilityLabel("Clear \(title)")
+                }
+            }
+        }
+        .onDisappear { stop() }
+    }
+
+    private func start() {
+        model.recording = id
+        hint = "Esc to cancel"
+        monitor = NSEvent.addLocalMonitorForEvents(matching: .keyDown) { event in
+            let flags = event.modifierFlags.intersection([.control, .option, .shift, .command])
+            if event.keyCode == 53 && flags.isEmpty { stop(); return nil }  // Escape
+            if (event.keyCode == 51 || event.keyCode == 117) && flags.isEmpty && optional {  // Delete
+                value = nil; stop(); return nil
+            }
+            var mods: UInt32 = 0
+            if flags.contains(.control) { mods |= UInt32(controlKey) }
+            if flags.contains(.option) { mods |= UInt32(optionKey) }
+            if flags.contains(.shift) { mods |= UInt32(shiftKey) }
+            if flags.contains(.command) { mods |= UInt32(cmdKey) }
+            let spec = HotkeySpec(keyCode: UInt32(event.keyCode), modifiers: mods)
+            guard let text = spec.text, HotkeySpec(text) != nil else {
+                hint = "Add ⌃, ⌥ or ⌘"
+                return nil
+            }
+            value = text
+            stop()
+            return nil
+        }
+    }
+
+    private func stop() {
+        if let monitor { NSEvent.removeMonitor(monitor) }
+        monitor = nil
+        hint = ""
+        if model.recording == id { model.recording = nil }
+    }
+}
+
+// MARK: Window
+
+@MainActor
+final class SettingsWindow: NSObject, NSWindowDelegate {
+    let model = SettingsModel()
+    private var window: NSWindow?
+
+    func show() {
+        if window == nil {
+            let w = NSWindow(contentRect: NSRect(x: 0, y: 0, width: 660, height: 640),
+                             styleMask: [.titled, .closable, .miniaturizable],
+                             backing: .buffered, defer: false)
+            w.title = "AgentX Voice Settings"
+            w.isReleasedWhenClosed = false
+            w.contentView = NSHostingView(rootView: SettingsView(model: model))
+            w.delegate = self
+            w.center()
+            window = w
+        }
+        model.launchAtLogin = LoginItem.isOn
+        model.load()
+        // An accessory app has to ask to come forward before its window can
+        // take typing; the window was opened on purpose, so that is fine.
+        NSApp.activate(ignoringOtherApps: true)
+        window?.makeKeyAndOrderFront(nil)
+    }
+
+    func windowWillClose(_ notification: Notification) {
+        model.recording = nil
+    }
+}
+
+extension Color {
+    /// "#RRGGBB"; the brand teal when it isn't one.
+    init(hex: String) {
+        if let c = OrbMath.parseHex(hex) { self.init(.sRGB, red: c.r, green: c.g, blue: c.b) }
+        else { self.init(nsColor: Brand.accent) }
+    }
+
+    /// "#RRGGBB" in sRGB.
+    var hex: String {
+        let c = NSColor(self).usingColorSpace(.sRGB) ?? .black
+        let v = [c.redComponent, c.greenComponent, c.blueComponent].map { Int(($0 * 255).rounded()).clamped(0, 255) }
+        return String(format: "#%02X%02X%02X", v[0], v[1], v[2])
+    }
+}
+
+private extension Int {
+    func clamped(_ lo: Int, _ hi: Int) -> Int { Swift.min(hi, Swift.max(lo, self)) }
+}