agentix-cli 0.58.0 → 0.59.0

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/Parakeet.swift

@@ -0,0 +1,264 @@
+import CoreML
+import Foundation
+
+/// NVIDIA Parakeet TDT 0.6B v3 on Core ML: on-device speech to text with
+/// no Python, from the model files ModelStore.parakeet fetches.
+///
+/// Four Core ML models, run in turn: the preprocessor turns 15 s of audio
+/// into a mel spectrogram, the encoder turns that into one vector per
+/// 80 ms, and the decoder (an LSTM over the words so far) and the joint
+/// network walk those vectors greedily. The joint picks a token and how
+/// many frames to skip (the "TDT" part), which is why it is fast.
+///
+/// v3 covers 25 European languages and detects which one on its own. It
+/// has NO Arabic; see the benchmark in docs/dashboard/voice.md.
+final class Parakeet: @unchecked Sendable {
+    enum ParakeetError: LocalizedError {
+        case notInstalled
+        case badOutput(String)
+        var errorDescription: String? {
+            switch self {
+            case .notInstalled: return "the Parakeet model is not downloaded yet"
+            case .badOutput(let what): return "Parakeet returned no \(what)"
+            }
+        }
+    }
+
+    static let sampleRate = 16_000
+    /// The Core ML export takes exactly 15 s.
+    static let window = 240_000
+    /// One encoder frame covers 80 ms.
+    static let samplesPerFrame = 1_280
+    static let blank = 8_192
+    static let durations = [0, 1, 2, 3, 4]
+    static let maxSymbolsPerFrame = 10
+
+    private let preprocessor: MLModel
+    private let encoder: MLModel
+    private let decoder: MLModel
+    private let joint: MLModel
+    private let vocabulary: [Int: String]
+
+    private static let lock = NSLock()
+    nonisolated(unsafe) private static var shared: Parakeet?
+
+    /// The loaded engine, kept for the life of the app: loading costs
+    /// seconds (Core ML prepares the encoder for the Neural Engine), a
+    /// transcription well under one.
+    static func loaded() throws -> Parakeet {
+        lock.lock(); defer { lock.unlock() }
+        if let shared { return shared }
+        let p = try Parakeet()
+        shared = p
+        return p
+    }
+
+    init() throws {
+        let store = ModelStore.parakeet
+        guard store.isInstalled else { throw ParakeetError.notInstalled }
+        func load(_ name: String, _ units: MLComputeUnits) throws -> MLModel {
+            let config = MLModelConfiguration()
+            config.computeUnits = units
+            return try MLModel(contentsOf: store.url(name), configuration: config)
+        }
+        // The same placement FluidAudio uses: the mel front end on the CPU,
+        // the rest wherever Core ML runs it best (the Neural Engine).
+        preprocessor = try load("Preprocessor.mlmodelc", .cpuOnly)
+        encoder = try load("Encoder.mlmodelc", .cpuAndNeuralEngine)
+        decoder = try load("Decoder.mlmodelc", .cpuAndNeuralEngine)
+        joint = try load("JointDecisionv3.mlmodelc", .cpuAndNeuralEngine)
+
+        let data = try Data(contentsOf: store.url("parakeet_vocab.json"))
+        let raw = try JSONSerialization.jsonObject(with: data) as? [String: String] ?? [:]
+        var vocab: [Int: String] = [:]
+        for (k, v) in raw { if let id = Int(k) { vocab[id] = v } }
+        vocabulary = vocab
+    }
+
+    /// A 16 kHz mono 16-bit WAV, as Recorder makes.
+    func transcribe(wav: Data) throws -> String {
+        try transcribe(samples: Self.samples(wav: wav))
+    }
+
+    func transcribe(samples: [Float]) throws -> String {
+        var tokens: [Int] = []
+        var state = try DecoderState(decoder: decoder)
+        for range in Self.windows(samples) {
+            tokens += try decode(Array(samples[range]), state: &state)
+        }
+        return Self.text(tokens, vocabulary: vocabulary)
+    }
+
+    // MARK: Pure helpers (tested)
+
+    /// Samples of a 16-bit PCM WAV as -1…1, found by its "data" chunk.
+    static func samples(wav: Data) -> [Float] {
+        let bytes = [UInt8](wav)
+        var offset = 12
+        while offset + 8 <= bytes.count {
+            let id = String(decoding: bytes[offset..<offset + 4], as: UTF8.self)
+            let size = Int(UInt32(bytes[offset + 4]) | UInt32(bytes[offset + 5]) << 8
+                | UInt32(bytes[offset + 6]) << 16 | UInt32(bytes[offset + 7]) << 24)
+            let body = offset + 8
+            if id == "data" {
+                let end = min(bytes.count, body + size)
+                var out = [Float]()
+                out.reserveCapacity((end - body) / 2)
+                var i = body
+                while i + 1 < end {
+                    out.append(Float(Int16(bitPattern: UInt16(bytes[i]) | UInt16(bytes[i + 1]) << 8)) / 32768)
+                    i += 2
+                }
+                return out
+            }
+            offset = body + size + (size & 1)
+        }
+        return []
+    }
+
+    /// Splits audio longer than the 15 s window, each cut at the quietest
+    /// 20 ms of the window's last 3 s, so a cut rarely lands in a word.
+    static func windows(_ samples: [Float], window: Int = Parakeet.window) -> [Range<Int>] {
+        var out: [Range<Int>] = []
+        var start = 0
+        let step = sampleRate / 50
+        while samples.count - start > window {
+            let searchFrom = start + window - 3 * sampleRate
+            var best = start + window, bestEnergy = Float.greatestFiniteMagnitude
+            var at = searchFrom
+            while at + step <= start + window {
+                var e: Float = 0
+                for i in at..<at + step { e += samples[i] * samples[i] }
+                if e < bestEnergy { bestEnergy = e; best = at + step / 2 }
+                at += step
+            }
+            out.append(start..<best)
+            start = best
+        }
+        if start < samples.count { out.append(start..<samples.count) }
+        return out
+    }
+
+    /// SentencePiece pieces to text: "▁" marks the start of a word.
+    static func text(_ tokens: [Int], vocabulary: [Int: String]) -> String {
+        var s = ""
+        for t in tokens {
+            guard let piece = vocabulary[t], !(piece.hasPrefix("<") && piece.hasSuffix(">")) else { continue }
+            s += piece.replacingOccurrences(of: "\u{2581}", with: " ")
+        }
+        return s.trimmingCharacters(in: .whitespacesAndNewlines)
+    }
+
+    // MARK: Inference
+
+    private struct DecoderState {
+        var hidden: MLMultiArray
+        var cell: MLMultiArray
+        /// The decoder's output for the last token emitted (blank at first).
+        var output: MLMultiArray?
+        let target: MLMultiArray
+        let targetLength: MLMultiArray
+
+        init(decoder: MLModel) throws {
+            hidden = try MLMultiArray(shape: [2, 1, 640], dataType: .float32)
+            cell = try MLMultiArray(shape: [2, 1, 640], dataType: .float32)
+            for i in 0..<hidden.count { hidden[i] = 0; cell[i] = 0 }
+            target = try MLMultiArray(shape: [1, 1], dataType: .int32)
+            targetLength = try MLMultiArray(shape: [1], dataType: .int32)
+            targetLength[0] = 1
+        }
+    }
+
+    private func step(_ token: Int, _ state: inout DecoderState) throws {
+        state.target[0] = NSNumber(value: token)
+        let out = try decoder.prediction(from: MLDictionaryFeatureProvider(dictionary: [
+            "targets": MLFeatureValue(multiArray: state.target),
+            "target_length": MLFeatureValue(multiArray: state.targetLength),
+            "h_in": MLFeatureValue(multiArray: state.hidden),
+            "c_in": MLFeatureValue(multiArray: state.cell),
+        ]))
+        guard let d = out.featureValue(for: "decoder")?.multiArrayValue,
+              let h = out.featureValue(for: "h_out")?.multiArrayValue,
+              let c = out.featureValue(for: "c_out")?.multiArrayValue else { throw ParakeetError.badOutput("decoder state") }
+        state.output = d; state.hidden = h; state.cell = c
+    }
+
+    /// One window: preprocessor, encoder, then greedy TDT decoding.
+    private func decode(_ chunk: [Float], state: inout DecoderState) throws -> [Int] {
+        guard chunk.count >= Self.samplesPerFrame else { return [] }
+        let audio = try MLMultiArray(shape: [1, NSNumber(value: Self.window)], dataType: .float32)
+        let ptr = audio.dataPointer.bindMemory(to: Float.self, capacity: Self.window)
+        ptr.initialize(repeating: 0, count: Self.window)
+        chunk.withUnsafeBufferPointer { src in ptr.update(from: src.baseAddress!, count: min(chunk.count, Self.window)) }
+        let length = try MLMultiArray(shape: [1], dataType: .int32)
+        length[0] = NSNumber(value: chunk.count)
+
+        let mel = try preprocessor.prediction(from: MLDictionaryFeatureProvider(dictionary: [
+            "audio_signal": MLFeatureValue(multiArray: audio),
+            "audio_length": MLFeatureValue(multiArray: length),
+        ]))
+        guard let melArray = mel.featureValue(for: "mel")?.multiArrayValue,
+              let melLength = mel.featureValue(for: "mel_length")?.multiArrayValue else { throw ParakeetError.badOutput("mel") }
+        let enc = try encoder.prediction(from: MLDictionaryFeatureProvider(dictionary: [
+            "mel": MLFeatureValue(multiArray: melArray),
+            "mel_length": MLFeatureValue(multiArray: melLength),
+        ]))
+        guard let frames = enc.featureValue(for: "encoder")?.multiArrayValue,
+              let encLength = enc.featureValue(for: "encoder_length")?.multiArrayValue else { throw ParakeetError.badOutput("encoder output") }
+
+        let hiddenSize = frames.shape[1].intValue
+        let available = frames.shape[2].intValue
+        let actual = (chunk.count + Self.samplesPerFrame - 1) / Self.samplesPerFrame
+        let count = min(encLength[0].intValue, available, actual)
+        let hStride = frames.strides[1].intValue, tStride = frames.strides[2].intValue
+
+        let encStep = try MLMultiArray(shape: [1, NSNumber(value: hiddenSize), 1], dataType: .float32)
+        let encStride = encStep.strides[1].intValue
+        let encDest = encStep.dataPointer.bindMemory(to: Float.self, capacity: encStep.count)
+        func load(frame t: Int) {
+            switch frames.dataType {
+            case .float16:
+                let src = frames.dataPointer.bindMemory(to: Float16.self, capacity: frames.count)
+                for h in 0..<hiddenSize { encDest[h * encStride] = Float(src[h * hStride + t * tStride]) }
+            default:
+                let src = frames.dataPointer.bindMemory(to: Float.self, capacity: frames.count)
+                for h in 0..<hiddenSize { encDest[h * encStride] = src[h * hStride + t * tStride] }
+            }
+        }
+
+        if state.output == nil { try step(Self.blank, &state) }
+        var tokens: [Int] = []
+        var t = 0
+        var symbolsHere = 0
+        var loaded = -1
+        while t < count {
+            if loaded != t { load(frame: t); loaded = t }
+            guard let decoderOut = state.output else { throw ParakeetError.badOutput("decoder output") }
+            let out = try joint.prediction(from: MLDictionaryFeatureProvider(dictionary: [
+                "encoder_step": MLFeatureValue(multiArray: encStep),
+                "decoder_step": MLFeatureValue(multiArray: decoderOut),
+            ]))
+            guard let tokenArray = out.featureValue(for: "token_id")?.multiArrayValue,
+                  let durArray = out.featureValue(for: "duration")?.multiArrayValue else { throw ParakeetError.badOutput("joint decision") }
+            let token = tokenArray[0].intValue
+            let bin = durArray[0].intValue
+            let duration = Self.durations.indices.contains(bin) ? Self.durations[bin] : 1
+
+            if token == Self.blank {
+                t += max(duration, 1)
+                symbolsHere = 0
+                continue
+            }
+            tokens.append(token)
+            try step(token, &state)
+            if duration > 0 {
+                t += duration
+                symbolsHere = 0
+            } else {
+                symbolsHere += 1
+                if symbolsHere >= Self.maxSymbolsPerFrame { t += 1; symbolsHere = 0 }
+            }
+        }
+        return tokens
+    }
+}

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

@@ -29,6 +29,28 @@ final class Recorder {
     /// between two adjacent 100ms windows — which changes nothing.
     private(set) var level: Float = 0
 
+    /// How a hands-free turn's end is heard: "vad" (Silero VAD, once its
+    /// model is downloaded; the volume threshold until then) or "volume",
+    /// from agentx.json's `voice.endOfTurn`. Push-to-talk sets "hold": its
+    /// turn ends on key release, so no detector runs. Set before `start()`.
+    var endOfTurn = "vad"
+    /// True while this recording's turn is judged by Silero VAD.
+    private(set) var usingVAD = false
+    private var vad: SileroVAD?
+    private var turn = TurnEnd(.level)
+    private let turnLock = NSLock()
+    /// Bumped by every start, so VAD work queued for an earlier recording
+    /// never lands in this one.
+    private var generation = 0
+    private let vadQueue = DispatchQueue(label: "tn.acme.agentx.voice.vad")
+
+    /// Where the hands-free turn stands: nothing said, talking (a pause
+    /// included), or over. Read from the main thread.
+    var turnState: TurnEnd.State {
+        turnLock.lock(); defer { turnLock.unlock() }
+        return turn.state
+    }
+
     /// 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(
@@ -58,6 +80,7 @@ final class Recorder {
         level = 0
         guard !isRecording else { return }
         lock.lock(); pcm.removeAll(keepingCapacity: true); lock.unlock()
+        prepareTurn()
 
         let input = engine.inputNode
         let inputFormat = input.inputFormat(forBus: 0)
@@ -110,9 +133,8 @@ final class Recorder {
             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
+        level = TurnEnd.smooth(level: level, rms: rms)
+        hearTurn(channel, count: Int(out.frameLength))
 
         let bytes = Int(out.frameLength) * MemoryLayout<Int16>.size
         lock.lock()
@@ -122,6 +144,62 @@ final class Recorder {
         lock.unlock()
     }
 
+    /// A fresh turn for a new recording, judged by Silero VAD when its
+    /// model is installed and loads; otherwise by the volume threshold,
+    /// with the model downloading in the background for next time.
+    private func prepareTurn() {
+        var detector: SileroVAD?
+        // Only a hands-free turn listens for its own end; push-to-talk ("hold")
+        // ends on key release, so it never loads or runs the model.
+        if endOfTurn == "vad" {
+            do {
+                if let model = try SileroVAD.loadModel() {
+                    detector = try SileroVAD(model: model)
+                } else {
+                    ModelStore.installInBackground(ModelStore.vad) { Log.info($0) }
+                }
+            } catch {
+                Log.warn("Silero VAD would not load (\(error.localizedDescription)); using the volume threshold")
+            }
+        }
+        turnLock.lock()
+        generation += 1
+        vad = detector
+        usingVAD = detector != nil
+        turn = TurnEnd(detector != nil ? .vad : .level)
+        turnLock.unlock()
+    }
+
+    /// One converted buffer: to the VAD off the audio thread, or straight
+    /// to the volume check.
+    private func hearTurn(_ channel: UnsafePointer<Int16>, count: Int) {
+        turnLock.lock()
+        let detector = vad, gen = generation
+        if detector == nil {
+            turn.feed(level: level, duration: Double(count) / target.sampleRate)
+        }
+        turnLock.unlock()
+        guard let detector else { return }
+        var samples = [Float](repeating: 0, count: count)
+        for i in 0..<count { samples[i] = Float(channel[i]) / 32768.0 }
+        vadQueue.async { [weak self] in
+            guard let self else { return }
+            let probabilities: [Float]
+            do { probabilities = try detector.process(samples) } catch {
+                Log.warn("Silero VAD failed (\(error.localizedDescription)); using the volume threshold")
+                self.turnLock.lock()
+                if self.generation == gen { self.vad = nil; self.usingVAD = false; self.turn = TurnEnd(.level) }
+                self.turnLock.unlock()
+                return
+            }
+            self.turnLock.lock()
+            if self.generation == gen {
+                for p in probabilities { self.turn.feed(probability: p, duration: SileroVAD.frameDuration) }
+            }
+            self.turnLock.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

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

@@ -365,7 +365,15 @@ private struct GeneralTab: View {
                     Picker("Speech to text", selection: binding(\.stt)) {
                         Text("Automatic").tag("auto")
                         Text("ElevenLabs").tag("elevenlabs")
-                        Text("On this Mac (Whisper)").tag("local")
+                        Text("On this Mac").tag("local")
+                    }
+                    Picker("On-this-Mac engine", selection: binding(\.localStt)) {
+                        Text("Whisper (mlx-whisper)").tag("mlx-whisper")
+                        Text("Parakeet (downloads 483 MB)").tag("parakeet")
+                    }
+                    Picker("End of a hands-free turn", selection: binding(\.endOfTurn)) {
+                        Text("Voice detection (Silero)").tag("vad")
+                        Text("Volume").tag("volume")
                     }
                     Picker("Default voice provider", selection: binding(\.provider)) {
                         Text("Mac voices (free)").tag("system")
@@ -374,7 +382,7 @@ private struct GeneralTab: View {
                 } 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.")
+                    Text("Automatic uses ElevenLabs when a key is set, and the engine on this Mac otherwise. Parakeet has no Arabic; until its model has downloaded, Whisper answers instead. Voice detection ends a turn when you stop talking, not when the room goes quiet. The default provider is for agents that don't choose their own. All apply to the next question.")
                         .font(.caption).foregroundStyle(.secondary)
                 }
                 Section {