aiden-runtime 3.16.0

package/dist/core/voice/tts.js

@@ -0,0 +1,310 @@
+"use strict";
+// ============================================================
+// DevOS — Autonomous AI Execution System
+// Copyright (c) 2026 Shiva Deore. All rights reserved.
+// ============================================================
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.cleanForTTS = cleanForTTS;
+exports.synthesize = synthesize;
+exports.getTtsProviders = getTtsProviders;
+// core/voice/tts.ts — Text-to-Speech with four-provider fallback chain.
+//
+// Priority order (auto-selected at runtime):
+//   0. VoxCPM2       (USE_VOXCPM=1, Python subprocess, Apache-2.0) — voice clone/design
+//   1. Edge TTS      (edge-tts Python pkg, free)  — best quality, offline after install
+//   2. ElevenLabs    (ELEVENLABS_API_KEY)          — premium voices, REST API
+//   3. Windows SAPI  (System.Speech assembly)     — always available on Windows
+//
+// VoxCPM2 is opt-in via USE_VOXCPM=1 env var and is always tried first when enabled.
+// Never throws — returns TtsResult; callers check result.error.
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const child_process_1 = require("child_process");
+const util_1 = require("util");
+const axios_1 = __importDefault(require("axios"));
+const execAsync = (0, util_1.promisify)(child_process_1.exec);
+// ── Constants ─────────────────────────────────────────────────────────────────
+const DEFAULT_VOICE = 'en-US-AriaNeural';
+const WORKSPACE = path_1.default.join(process.cwd(), 'workspace');
+const ELEVENLABS_API_URL = 'https://api.elevenlabs.io/v1/text-to-speech';
+const VOXCPM_RUNNER_PATH = path_1.default.join(__dirname, 'voxcpm_runner.py');
+const VOXCPM_TIMEOUT_MS = 120000;
+function ensureWorkspace() {
+    if (!fs_1.default.existsSync(WORKSPACE))
+        fs_1.default.mkdirSync(WORKSPACE, { recursive: true });
+}
+// ── Text cleaner ──────────────────────────────────────────────────────────────
+function cleanForTTS(text) {
+    return text
+        .replace(/```[\s\S]*?```/g, 'code block.')
+        .replace(/`[^`]+`/g, '')
+        .replace(/\*\*([^*]+)\*\*/g, '$1')
+        .replace(/\*([^*]+)\*/g, '$1')
+        .replace(/#{1,6}\s+/g, '')
+        .replace(/\[([^\]]+)\]\([^\)]+\)/g, '$1')
+        .replace(/\n+/g, '. ')
+        .replace(/[❌✅⚡🔧📋🔍🎤🔊]/g, '')
+        .replace(/\s+/g, ' ')
+        .trim()
+        .slice(0, 500);
+}
+// ── Provider 0 — VoxCPM2 (opt-in via USE_VOXCPM=1) ───────────────────────────
+async function synthesizeVoxCPM(text, opts) {
+    const t0 = Date.now();
+    const timeout = opts.timeoutMs ?? VOXCPM_TIMEOUT_MS;
+    ensureWorkspace();
+    const outputPath = path_1.default.join(WORKSPACE, `tts_voxcpm_${Date.now()}.wav`);
+    const outputFwd = outputPath.replace(/\\/g, '/');
+    // Detect mode: clone / design / standard
+    let mode = 'tts';
+    let voiceDescription;
+    let speechText = text;
+    if (opts.referenceAudioPath) {
+        mode = 'clone';
+    }
+    else if (opts.voiceDesignPrompt) {
+        mode = 'design';
+        voiceDescription = opts.voiceDesignPrompt;
+    }
+    else if (text.startsWith('design:')) {
+        // Inline design prefix: "design:<description>\n<text-to-speak>"
+        const newline = text.indexOf('\n');
+        if (newline !== -1) {
+            mode = 'design';
+            voiceDescription = text.slice('design:'.length, newline).trim();
+            speechText = text.slice(newline + 1).trim();
+        }
+    }
+    const payload = {
+        text: speechText,
+        output_path: outputFwd,
+        mode,
+        reference_audio: opts.referenceAudioPath?.replace(/\\/g, '/') ?? null,
+        voice_description: voiceDescription ?? null,
+        language: 'en',
+    };
+    return new Promise((resolve) => {
+        const child = (0, child_process_1.spawn)('python', [VOXCPM_RUNNER_PATH], { stdio: ['pipe', 'pipe', 'pipe'] });
+        let stdout = '';
+        let stderr = '';
+        child.stdout.on('data', (d) => { stdout += d.toString(); });
+        child.stderr.on('data', (d) => { stderr += d.toString(); });
+        const timer = setTimeout(() => {
+            child.kill();
+            resolve({ provider: 'voxcpm', durationMs: Date.now() - t0, error: `VoxCPM timed out after ${timeout}ms` });
+        }, timeout);
+        child.stdin.write(JSON.stringify(payload));
+        child.stdin.end();
+        child.on('close', () => {
+            clearTimeout(timer);
+            try {
+                const result = JSON.parse(stdout.trim());
+                if (!result.ok) {
+                    // Surface well-known errors for upstream handling
+                    resolve({ provider: 'voxcpm', durationMs: Date.now() - t0, error: result.error ?? 'VoxCPM failed' });
+                    return;
+                }
+                // Play the generated WAV
+                const escaped = outputPath.replace(/\\/g, '\\\\');
+                (0, child_process_1.exec)(`powershell -Command "Add-Type -AssemblyName presentationCore; $mp = New-Object System.Windows.Media.MediaPlayer; $mp.Open([uri]'${escaped}'); $mp.Play(); Start-Sleep -Seconds 10; $mp.Stop(); $mp.Close()"`, { timeout: 15000 }, (err) => {
+                    if (err)
+                        (0, child_process_1.exec)(`powershell -Command "Start-Process '${escaped}'"`);
+                });
+                setTimeout(() => { try {
+                    fs_1.default.unlinkSync(outputPath);
+                }
+                catch { /* ignore */ } }, 15000);
+                resolve({ provider: 'voxcpm', durationMs: Date.now() - t0 });
+            }
+            catch {
+                resolve({ provider: 'voxcpm', durationMs: Date.now() - t0, error: `VoxCPM invalid output: ${stdout} | stderr: ${stderr}` });
+            }
+        });
+        child.on('error', (err) => {
+            clearTimeout(timer);
+            resolve({ provider: 'voxcpm', durationMs: Date.now() - t0, error: `VoxCPM spawn error: ${err.message}` });
+        });
+    });
+}
+// ── Provider 1 — Edge TTS ─────────────────────────────────────────────────────
+async function synthesizeEdge(text, opts) {
+    ensureWorkspace();
+    const t0 = Date.now();
+    const voice = opts.voice ?? DEFAULT_VOICE;
+    const audioPath = path_1.default.join(WORKSPACE, `tts_edge_${Date.now()}.mp3`);
+    const audioFwd = audioPath.replace(/\\/g, '/');
+    const escaped = text.replace(/"/g, '\\"').replace(/'/g, "\\'");
+    const timeout = opts.timeoutMs ?? 20000;
+    const script = `
+import asyncio, sys
+sys.stderr = open('nul', 'w')
+import edge_tts
+async def main():
+    communicate = edge_tts.Communicate("${escaped}", "${voice}")
+    await communicate.save("${audioFwd}")
+asyncio.run(main())
+`.trim();
+    const tmpPy = path_1.default.join(WORKSPACE, `tts_edge_gen_${Date.now()}.py`);
+    fs_1.default.writeFileSync(tmpPy, script);
+    try {
+        await execAsync(`python "${tmpPy}"`, { timeout });
+        if (!fs_1.default.existsSync(audioPath))
+            throw new Error('edge-tts produced no audio file');
+        // Play via Windows Media Player (fire-and-forget)
+        const escaped_path = audioPath.replace(/\\/g, '\\\\');
+        execAsync(`powershell -Command "Add-Type -AssemblyName presentationCore; $mp = New-Object System.Windows.Media.MediaPlayer; $mp.Open([uri]'${escaped_path}'); $mp.Play(); Start-Sleep -Seconds 8; $mp.Stop(); $mp.Close()"`, { timeout: 15000 }).catch(() => {
+            execAsync(`powershell -Command "Start-Process '${escaped_path}'"`)
+                .catch(() => { });
+        });
+        setTimeout(() => { try {
+            fs_1.default.unlinkSync(audioPath);
+        }
+        catch { /* ignore */ } }, 15000);
+        return { provider: 'edge', durationMs: Date.now() - t0 };
+    }
+    finally {
+        try {
+            fs_1.default.unlinkSync(tmpPy);
+        }
+        catch { /* ignore */ }
+    }
+}
+// ── Provider 2 — ElevenLabs ───────────────────────────────────────────────────
+async function synthesizeElevenLabs(text, opts) {
+    const apiKey = process.env.ELEVENLABS_API_KEY;
+    if (!apiKey)
+        throw new Error('ELEVENLABS_API_KEY not set');
+    ensureWorkspace();
+    const t0 = Date.now();
+    const voiceId = opts.voice ?? 'EXAVITQu4vr4xnSDxMaL'; // Sarah (default public voice)
+    const timeout = opts.timeoutMs ?? 20000;
+    const res = await axios_1.default.post(`${ELEVENLABS_API_URL}/${voiceId}`, {
+        text,
+        model_id: 'eleven_monolingual_v1',
+        voice_settings: { stability: 0.5, similarity_boost: 0.75 },
+    }, {
+        headers: {
+            'xi-api-key': apiKey,
+            'Content-Type': 'application/json',
+            Accept: 'audio/mpeg',
+        },
+        responseType: 'arraybuffer',
+        timeout,
+    });
+    const audioPath = path_1.default.join(WORKSPACE, `tts_eleven_${Date.now()}.mp3`);
+    const escaped_path = audioPath.replace(/\\/g, '\\\\');
+    fs_1.default.writeFileSync(audioPath, Buffer.from(res.data));
+    execAsync(`powershell -Command "Add-Type -AssemblyName presentationCore; $mp = New-Object System.Windows.Media.MediaPlayer; $mp.Open([uri]'${escaped_path}'); $mp.Play(); Start-Sleep -Seconds 8; $mp.Stop(); $mp.Close()"`, { timeout: 15000 }).catch(() => {
+        execAsync(`powershell -Command "Start-Process '${escaped_path}'"`)
+            .catch(() => { });
+    });
+    setTimeout(() => { try {
+        fs_1.default.unlinkSync(audioPath);
+    }
+    catch { /* ignore */ } }, 15000);
+    return { provider: 'elevenlabs', durationMs: Date.now() - t0 };
+}
+// ── Provider 3 — Windows SAPI ─────────────────────────────────────────────────
+async function synthesizeSAPI(text, opts) {
+    const t0 = Date.now();
+    const rate = Math.round(((opts.rate ?? 1.0) - 1.0) * 5); // map 0.5–2.0 → -3..5
+    const volume = opts.volume ?? 100;
+    const safe = text.replace(/'/g, "''").replace(/"/g, '');
+    const timeout = opts.timeoutMs ?? 30000;
+    await execAsync(`powershell -Command "Add-Type -AssemblyName System.Speech; $s = New-Object System.Speech.Synthesis.SpeechSynthesizer; $s.Rate = ${rate}; $s.Volume = ${volume}; $s.Speak('${safe}')"`, { timeout });
+    return { provider: 'sapi', durationMs: Date.now() - t0 };
+}
+// ── Main exported function ────────────────────────────────────────────────────
+/**
+ * Synthesize text using the first available provider.
+ * Never throws — always returns a TtsResult; check result.error on failure.
+ */
+async function synthesize(options) {
+    const t0 = Date.now();
+    const text = cleanForTTS(options.text);
+    if (!text)
+        return { provider: 'none', durationMs: 0 };
+    const errors = [];
+    // Explicit provider override
+    if (options.provider) {
+        try {
+            if (options.provider === 'voxcpm')
+                return await synthesizeVoxCPM(text, options);
+            if (options.provider === 'edge')
+                return await synthesizeEdge(text, options);
+            if (options.provider === 'elevenlabs')
+                return await synthesizeElevenLabs(text, options);
+            if (options.provider === 'sapi')
+                return await synthesizeSAPI(text, options);
+        }
+        catch (e) {
+            return { provider: options.provider, durationMs: Date.now() - t0, error: e.message };
+        }
+    }
+    // Provider 0 — VoxCPM2 (opt-in via USE_VOXCPM=1)
+    const voxCpmEnabled = process.env.USE_VOXCPM === '1';
+    if (voxCpmEnabled || options.referenceAudioPath || options.voiceDesignPrompt) {
+        const r = await synthesizeVoxCPM(text, options);
+        if (!r.error) {
+            console.log(`[TTS] VoxCPM2: ${r.durationMs}ms`);
+            return r;
+        }
+        const isNotInstalled = r.error?.includes('No module named voxcpm');
+        const isOOM = r.error?.includes('CUDA out of memory');
+        if (isOOM) {
+            console.warn(`[TTS] VoxCPM OOM — falling through to next provider`);
+        }
+        else if (isNotInstalled && !voxCpmEnabled) {
+            // clone/design requested but VoxCPM not installed — surface error immediately
+            return r;
+        }
+        errors.push(`voxcpm: ${r.error}`);
+    }
+    // Provider 1 — Edge TTS
+    try {
+        const r = await synthesizeEdge(text, options);
+        console.log(`[TTS] Edge TTS: ${r.durationMs}ms`);
+        return r;
+    }
+    catch (e) {
+        errors.push(`edge: ${e.message}`);
+    }
+    // Provider 2 — ElevenLabs
+    try {
+        const r = await synthesizeElevenLabs(text, options);
+        console.log(`[TTS] ElevenLabs: ${r.durationMs}ms`);
+        return r;
+    }
+    catch (e) {
+        errors.push(`elevenlabs: ${e.message}`);
+    }
+    // Provider 3 — Windows SAPI
+    try {
+        const r = await synthesizeSAPI(text, options);
+        console.log(`[TTS] SAPI: ${r.durationMs}ms`);
+        return r;
+    }
+    catch (e) {
+        errors.push(`sapi: ${e.message}`);
+    }
+    // All failed
+    const errorMsg = errors.join(' | ');
+    console.warn(`[TTS] All providers failed: ${errorMsg}`);
+    return { provider: 'none', durationMs: Date.now() - t0, error: errorMsg };
+}
+/** Returns which TTS providers are likely available (env / platform check). */
+function getTtsProviders() {
+    return [
+        {
+            name: 'voxcpm',
+            available: process.env.USE_VOXCPM === '1',
+            note: process.env.USE_VOXCPM === '1' ? 'enabled (USE_VOXCPM=1)' : 'set USE_VOXCPM=1 to enable',
+        },
+        { name: 'edge', available: true }, // checked at runtime via Python import
+        { name: 'elevenlabs', available: !!process.env.ELEVENLABS_API_KEY },
+        { name: 'sapi', available: process.platform === 'win32' },
+    ];
+}

package/dist/core/voiceInput.js

@@ -0,0 +1,118 @@
+"use strict";
+// ============================================================
+// DevOS — Autonomous AI Execution System
+// Copyright (c) 2026 Shiva Deore. All rights reserved.
+// ============================================================
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.checkVoiceAvailable = checkVoiceAvailable;
+exports.transcribeAudio = transcribeAudio;
+exports.recordAudio = recordAudio;
+// core/voiceInput.ts — Voice input via faster-whisper (Python)
+//
+// Prerequisites (user installs once):
+//   pip install faster-whisper
+//
+// Fallback: if faster-whisper is not available, returns error message
+// so the UI can hide the voice button gracefully.
+const child_process_1 = require("child_process");
+const util_1 = require("util");
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const execAsync = (0, util_1.promisify)(child_process_1.exec);
+const WORKSPACE = path_1.default.join(process.cwd(), 'workspace');
+function ensureWorkspace() {
+    if (!fs_1.default.existsSync(WORKSPACE))
+        fs_1.default.mkdirSync(WORKSPACE, { recursive: true });
+}
+// ── Availability check ────────────────────────────────────────
+async function checkVoiceAvailable() {
+    try {
+        const { stdout } = await execAsync('python -c "import faster_whisper; print(\'ok\')"', { timeout: 5000 });
+        return stdout.trim() === 'ok';
+    }
+    catch {
+        return false;
+    }
+}
+// ── Transcribe audio file ─────────────────────────────────────
+// Uses faster-whisper tiny model (CPU, int8) — fast enough for real-time
+async function transcribeAudio(audioPath) {
+    ensureWorkspace();
+    const normalizedPath = audioPath.replace(/\\/g, '/');
+    const pythonScript = `
+from faster_whisper import WhisperModel
+model = WhisperModel("tiny", device="cpu", compute_type="int8")
+segments, info = model.transcribe("${normalizedPath}", beam_size=5)
+text = " ".join([segment.text for segment in segments])
+print(text.strip())
+`.trim();
+    const tmpScript = path_1.default.join(WORKSPACE, `whisper_${Date.now()}.py`);
+    fs_1.default.writeFileSync(tmpScript, pythonScript);
+    try {
+        const { stdout } = await execAsync(`python "${tmpScript}"`, { timeout: 30000 });
+        return stdout.trim();
+    }
+    catch (e) {
+        throw new Error(`Transcription failed: ${e.message}`);
+    }
+    finally {
+        try {
+            fs_1.default.unlinkSync(tmpScript);
+        }
+        catch { }
+    }
+}
+// ── Record audio from microphone ──────────────────────────────
+// Uses Windows MCI (mciSendString) via P/Invoke — no third-party dep
+async function recordAudio(durationMs = 5000) {
+    ensureWorkspace();
+    const outputPath = path_1.default.join(WORKSPACE, `recording_${Date.now()}.wav`);
+    const outputPathFwd = outputPath.replace(/\\/g, '\\\\');
+    const psScript = `
+Add-Type -TypeDefinition @"
+using System;
+using System.Threading;
+using System.Runtime.InteropServices;
+
+public class AudioRecorder {
+  [DllImport("winmm.dll")]
+  private static extern int mciSendString(
+    string command,
+    System.Text.StringBuilder returnValue,
+    int returnLength,
+    IntPtr winHandle
+  );
+
+  public static void Record(string outputPath, int durationMs) {
+    mciSendString("open new Type waveaudio Alias recsound", null, 0, IntPtr.Zero);
+    mciSendString("set recsound channels 1 bitspersample 16 samplespersec 16000", null, 0, IntPtr.Zero);
+    mciSendString("record recsound", null, 0, IntPtr.Zero);
+    Thread.Sleep(durationMs);
+    mciSendString("stop recsound", null, 0, IntPtr.Zero);
+    mciSendString("save recsound " + outputPath, null, 0, IntPtr.Zero);
+    mciSendString("close recsound", null, 0, IntPtr.Zero);
+  }
+}
+"@
+[AudioRecorder]::Record("${outputPathFwd}", ${durationMs})
+Write-Output "${outputPath}"
+`.trim();
+    const psFile = path_1.default.join(WORKSPACE, `record_${Date.now()}.ps1`);
+    fs_1.default.writeFileSync(psFile, psScript);
+    try {
+        await execAsync(`powershell.exe -ExecutionPolicy Bypass -File "${psFile}"`, { timeout: durationMs + 8000 });
+        return outputPath;
+    }
+    catch (e) {
+        throw new Error(`Recording failed: ${e.message}`);
+    }
+    finally {
+        try {
+            fs_1.default.unlinkSync(psFile);
+        }
+        catch { }
+    }
+}

package/dist/core/voiceOutput.js

@@ -0,0 +1,130 @@
+"use strict";
+// ============================================================
+// DevOS — Autonomous AI Execution System
+// Copyright (c) 2026 Shiva Deore. All rights reserved.
+// ============================================================
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.checkTTSAvailable = checkTTSAvailable;
+exports.speak = speak;
+// core/voiceOutput.ts — Voice output via edge-tts (Python) with SAPI fallback
+//
+// Prerequisites for best quality (user installs once):
+//   pip install edge-tts
+//
+// Fallback: Windows SAPI (System.Speech) — always available on Windows,
+// no install required but lower quality than edge-tts/Aria.
+const child_process_1 = require("child_process");
+const util_1 = require("util");
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const execAsync = (0, util_1.promisify)(child_process_1.exec);
+const WORKSPACE = path_1.default.join(process.cwd(), 'workspace');
+const DEFAULT_VOICE = 'en-US-AriaNeural';
+function ensureWorkspace() {
+    if (!fs_1.default.existsSync(WORKSPACE))
+        fs_1.default.mkdirSync(WORKSPACE, { recursive: true });
+}
+// ── Availability check ────────────────────────────────────────
+async function checkTTSAvailable() {
+    // edge-tts Python check
+    try {
+        const { stdout } = await execAsync('python -c "import edge_tts; print(\'ok\')"', { timeout: 5000 });
+        if (stdout.trim() === 'ok')
+            return true;
+    }
+    catch { }
+    // Windows SAPI fallback check — always true on Windows
+    try {
+        await execAsync('powershell -Command "Add-Type -AssemblyName System.Speech; Write-Output ok"', { timeout: 3000 });
+        return true;
+    }
+    catch { }
+    return false;
+}
+// ── Clean text for TTS ────────────────────────────────────────
+// Strips markdown, code blocks, symbols — leaves clean spoken text
+function cleanForTTS(text) {
+    return text
+        .replace(/```[\s\S]*?```/g, 'code block.')
+        .replace(/`[^`]+`/g, '')
+        .replace(/\*\*([^*]+)\*\*/g, '$1')
+        .replace(/\*([^*]+)\*/g, '$1')
+        .replace(/#{1,6}\s+/g, '')
+        .replace(/\[([^\]]+)\]\([^\)]+\)/g, '$1') // links → text
+        .replace(/\n+/g, '. ')
+        .replace(/[❌✅⚡🔧📋🔍🎤🔊]/g, '') // strip emojis
+        .replace(/\s+/g, ' ')
+        .trim()
+        .slice(0, 500); // max 500 chars for TTS
+}
+// ── Speak via edge-tts (Python) ───────────────────────────────
+async function speakEdgeTTS(text, voice) {
+    ensureWorkspace();
+    const audioPath = path_1.default.join(WORKSPACE, `tts_${Date.now()}.mp3`);
+    const audioFwd = audioPath.replace(/\\/g, '/');
+    const escapedText = text.replace(/"/g, '\\"').replace(/'/g, "\\'");
+    const scriptContent = `
+import asyncio, sys
+sys.stderr = open('nul', 'w')
+import edge_tts
+async def main():
+    communicate = edge_tts.Communicate("${escapedText}", "${voice}")
+    await communicate.save("${audioFwd}")
+asyncio.run(main())
+`.trim();
+    const tmpScript = path_1.default.join(WORKSPACE, `tts_gen_${Date.now()}.py`);
+    fs_1.default.writeFileSync(tmpScript, scriptContent);
+    try {
+        await execAsync(`python "${tmpScript}"`, { timeout: 15000 });
+        if (!fs_1.default.existsSync(audioPath))
+            return false;
+        // Play the MP3 via Windows Media Player (async — don't block the response)
+        execAsync(`powershell -Command "Add-Type -AssemblyName presentationCore; $mp = New-Object System.Windows.Media.MediaPlayer; $mp.Open([uri]'${audioPath.replace(/\\/g, '\\\\')}'); $mp.Play(); Start-Sleep -Seconds 6; $mp.Stop(); $mp.Close()"`, { timeout: 15000 }).catch(() => {
+            // Fallback: just Start-Process (opens system default player)
+            execAsync(`powershell -Command "Start-Process '${audioPath.replace(/\\/g, '\\\\')}'"`).catch(() => { });
+        });
+        // Clean up after 12s
+        setTimeout(() => { try {
+            fs_1.default.unlinkSync(audioPath);
+        }
+        catch { } }, 12000);
+        return true;
+    }
+    catch {
+        return false;
+    }
+    finally {
+        try {
+            fs_1.default.unlinkSync(tmpScript);
+        }
+        catch { }
+    }
+}
+// ── Speak via Windows SAPI (always available) ─────────────────
+async function speakSAPI(text) {
+    // Escape single quotes for PowerShell string embedding
+    const safe = text.replace(/'/g, "''").replace(/"/g, '');
+    await execAsync(`powershell -Command "Add-Type -AssemblyName System.Speech; $s = New-Object System.Speech.Synthesis.SpeechSynthesizer; $s.Rate = 1; $s.Volume = 100; $s.Speak('${safe}')"`, { timeout: 30000 });
+}
+// ── Main exported function ────────────────────────────────────
+async function speak(text, voice = DEFAULT_VOICE) {
+    if (!text?.trim())
+        return;
+    const clean = cleanForTTS(text);
+    if (!clean)
+        return;
+    // Try edge-tts first — best quality
+    const edgeOk = await speakEdgeTTS(clean, voice);
+    if (edgeOk)
+        return;
+    // Fallback to Windows SAPI
+    try {
+        await speakSAPI(clean);
+    }
+    catch (e) {
+        console.error('[TTS] Both methods failed:', e.message);
+    }
+}