aiden-runtime 4.0.2 → 4.1.0

package/dist/core/visionAnalyze.js

@@ -6,12 +6,27 @@
 //
 // core/visionAnalyze.ts — Image analysis via vision-capable providers.
 //
-// Provider chain (first available wins):
-//   1. Anthropic claude-3-5-sonnet  (ANTHROPIC_API_KEY)
-//   2. OpenAI gpt-4o                (OPENAI_API_KEY)
-//   3. Ollama llava                 (local, no key needed)
+// Provider chain (first available wins). Free providers first so
+// the bot doesn't burn paid budget on every inbound photo:
+//
+//   1. Gemini       gemini-2.5-flash                 (GEMINI_API_KEY)
+//   2. Groq         llama-4-maverick-17b vision      (GROQ_API_KEY)
+//   3. OpenRouter   llama-3.2-11b-vision:free        (OPENROUTER_API_KEY)
+//   4. Together     Llama-Vision-Free                (TOGETHER_API_KEY)
+//   5. Anthropic    claude-3-5-sonnet                (ANTHROPIC_API_KEY)
+//   6. OpenAI       gpt-4o                           (OPENAI_API_KEY)
+//   7. Ollama       llava                            (local, no key)
 //
 // Accepts local file paths (→ base64) or HTTP/HTTPS URLs.
+//
+// Phase v4.1-4 — added optional `Logger` parameter so the channel
+// adapter (Telegram, etc.) can route diagnostics through the unified
+// `core/v4/logger` contract instead of stdout.
+//
+// Phase v4.1-4.1 — extended chain to cover the providers Aiden
+// already authenticates against, optional httpClient test seam, and
+// shared OpenAI-compatible helper for Groq / OpenRouter / Together
+// (which all serve the same wire format).
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
     var desc = Object.getOwnPropertyDescriptor(m, k);
@@ -53,6 +68,18 @@ exports.analyzeImage = analyzeImage;
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 const axios_1 = __importDefault(require("axios"));
+const logger_1 = require("./v4/logger");
+/** Default client wraps axios so production stays unchanged. */
+const defaultHttpClient = {
+    post: (url, body, opts) => axios_1.default.post(url, body, {
+        headers: opts?.headers,
+        timeout: opts?.timeout,
+    }),
+    get: (url, opts) => axios_1.default.get(url, {
+        responseType: opts?.responseType,
+        timeout: opts?.timeout,
+    }),
+};
 // ── Media type resolver ───────────────────────────────────────────────────────
 function extToMediaType(ext) {
     const map = {
@@ -61,101 +88,275 @@ function extToMediaType(ext) {
     };
     return map[ext.toLowerCase().replace(/^\./, '')] ?? 'image/jpeg';
 }
-// ── Core function ─────────────────────────────────────────────────────────────
+function resolveLocalImage(imageSource) {
+    const isUrl = imageSource.startsWith('http://') || imageSource.startsWith('https://');
+    if (isUrl) {
+        return { isUrl: true, sourceUrl: imageSource, base64: '', mediaType: 'image/jpeg' };
+    }
+    const absPath = path.isAbsolute(imageSource)
+        ? imageSource
+        : path.resolve(process.cwd(), imageSource);
+    const buf = fs.readFileSync(absPath);
+    return {
+        isUrl: false,
+        sourceUrl: '',
+        base64: buf.toString('base64'),
+        mediaType: extToMediaType(path.extname(absPath)),
+    };
+}
+/** Build a `data:<media>;base64,<...>` URL for OpenAI-compat consumers. */
+function asDataUrl(img) {
+    if (img.isUrl)
+        return img.sourceUrl;
+    return `data:${img.mediaType};base64,${img.base64}`;
+}
 /**
- * Analyze an image using the first available vision-capable provider.
- *
- * @param imageSource  File path (absolute or relative) or HTTP(S) URL.
- * @param prompt       Instruction prompt (default: describe the image).
- * @returns            VisionResult with description, provider, model, timing.
+ * For URL sources we sometimes need raw bytes (Gemini's inline_data
+ * is base64; Ollama's images[] is base64). Download and base64 the
+ * remote URL on demand. Returns null on download failure so the caller
+ * can fall through to the next provider.
  */
-async function analyzeImage(imageSource, prompt = 'Describe this image in detail.') {
-    const start = Date.now();
-    // Resolve image data
-    const isUrl = imageSource.startsWith('http://') || imageSource.startsWith('https://');
-    let base64Data = '';
-    let mediaType = 'image/jpeg';
-    if (!isUrl) {
-        const absPath = path.isAbsolute(imageSource)
-            ? imageSource
-            : path.resolve(process.cwd(), imageSource);
-        const buf = fs.readFileSync(absPath);
-        base64Data = buf.toString('base64');
-        mediaType = extToMediaType(path.extname(absPath));
+async function ensureBase64(img, http, log) {
+    if (!img.isUrl)
+        return { base64: img.base64, mediaType: img.mediaType };
+    try {
+        const res = await http.get(img.sourceUrl, { responseType: 'arraybuffer', timeout: 15000 });
+        const base64 = Buffer.from(res.data).toString('base64');
+        const mediaType = extToMediaType(path.extname(img.sourceUrl)) || 'image/jpeg';
+        return { base64, mediaType };
     }
-    // ── Provider 1: Anthropic ─────────────────────────────────────────────────
-    const anthropicKey = process.env.ANTHROPIC_API_KEY;
-    if (anthropicKey) {
-        try {
-            const imageBlock = isUrl
-                ? { type: 'image', source: { type: 'url', url: imageSource } }
-                : { type: 'image', source: { type: 'base64', media_type: mediaType, data: base64Data } };
-            const res = await axios_1.default.post('https://api.anthropic.com/v1/messages', {
-                model: 'claude-3-5-sonnet-20241022',
-                max_tokens: 1024,
-                messages: [{ role: 'user', content: [imageBlock, { type: 'text', text: prompt }] }],
-            }, {
-                headers: {
-                    'x-api-key': anthropicKey,
-                    'anthropic-version': '2023-06-01',
-                    'content-type': 'application/json',
-                },
-                timeout: 30000,
-            });
-            const description = (res.data?.content?.[0]?.text ?? '').trim();
-            if (description) {
-                return { description, provider: 'anthropic', modelUsed: 'claude-3-5-sonnet-20241022', durationMs: Date.now() - start };
-            }
-        }
-        catch { /* fall through */ }
+    catch (e) {
+        log.warn('failed to download image url for base64-only providers', { url: img.sourceUrl, error: e?.message });
+        return null;
     }
-    // ── Provider 2: OpenAI ────────────────────────────────────────────────────
-    const openaiKey = process.env.OPENAI_API_KEY;
-    if (openaiKey) {
-        try {
-            const imageUrl = isUrl
-                ? imageSource
-                : `data:${mediaType};base64,${base64Data}`;
-            const res = await axios_1.default.post('https://api.openai.com/v1/chat/completions', {
-                model: 'gpt-4o',
-                max_tokens: 1024,
-                messages: [{
-                        role: 'user',
-                        content: [
-                            { type: 'image_url', image_url: { url: imageUrl } },
-                            { type: 'text', text: prompt },
-                        ],
-                    }],
-            }, {
-                headers: { Authorization: `Bearer ${openaiKey}`, 'content-type': 'application/json' },
-                timeout: 30000,
-            });
-            const description = (res.data?.choices?.[0]?.message?.content ?? '').trim();
-            if (description) {
-                return { description, provider: 'openai', modelUsed: 'gpt-4o', durationMs: Date.now() - start };
-            }
-        }
-        catch { /* fall through */ }
+}
+// ── Provider 1: Gemini ────────────────────────────────────────────────────────
+const GEMINI_MODEL = 'gemini-2.5-flash';
+const GEMINI_ENDPOINT = `https://generativelanguage.googleapis.com/v1beta/models/${GEMINI_MODEL}:generateContent`;
+async function tryGemini(img, prompt, log, http) {
+    const key = process.env.GEMINI_API_KEY;
+    if (!key)
+        return null;
+    const t0 = Date.now();
+    try {
+        const inline = await ensureBase64(img, http, log);
+        if (!inline)
+            return null;
+        const body = {
+            contents: [{
+                    parts: [
+                        { inline_data: { mime_type: inline.mediaType, data: inline.base64 } },
+                        { text: prompt },
+                    ],
+                }],
+            generationConfig: { maxOutputTokens: 1024 },
+        };
+        const res = await http.post(`${GEMINI_ENDPOINT}?key=${key}`, body, {
+            headers: { 'content-type': 'application/json' },
+            timeout: 30000,
+        });
+        const description = (res.data?.candidates?.[0]?.content?.parts?.[0]?.text ?? '').trim();
+        if (!description)
+            return null;
+        const result = { description, provider: 'gemini', modelUsed: GEMINI_MODEL, durationMs: Date.now() - t0 };
+        log.info('image analyzed', { provider: 'gemini', modelUsed: GEMINI_MODEL, durationMs: result.durationMs, descChars: description.length });
+        return result;
     }
-    // ── Provider 3: Ollama llava ──────────────────────────────────────────────
-    const ollamaBase = (process.env.OLLAMA_BASE_URL ?? 'http://127.0.0.1:11434').replace(/\/$/, '');
-    // For URLs we need to download first so Ollama can receive base64
-    let ollamaBase64 = base64Data;
-    if (isUrl) {
-        try {
-            const imgRes = await axios_1.default.get(imageSource, { responseType: 'arraybuffer', timeout: 15000 });
-            ollamaBase64 = Buffer.from(imgRes.data).toString('base64');
-        }
-        catch (e) {
-            throw new Error(`vision_analyze: all providers failed (could not download URL for Ollama). ${e.message}`);
-        }
+    catch (e) {
+        log.warn('gemini vision failed', { error: e?.message ?? String(e) });
+        return null;
+    }
+}
+const GROQ_TARGET = {
+    provider: 'groq',
+    baseUrl: 'https://api.groq.com/openai/v1',
+    model: 'meta-llama/llama-4-maverick-17b-128e-instruct',
+    envKey: 'GROQ_API_KEY',
+};
+const OPENROUTER_TARGET = {
+    provider: 'openrouter',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    model: 'meta-llama/llama-3.2-11b-vision-instruct:free',
+    envKey: 'OPENROUTER_API_KEY',
+};
+const TOGETHER_TARGET = {
+    provider: 'together',
+    baseUrl: 'https://api.together.xyz/v1',
+    model: 'meta-llama/Llama-Vision-Free',
+    envKey: 'TOGETHER_API_KEY',
+};
+async function tryOpenAICompat(target, img, prompt, log, http) {
+    const key = process.env[target.envKey];
+    if (!key)
+        return null;
+    const t0 = Date.now();
+    try {
+        const dataUrl = asDataUrl(img);
+        const body = {
+            model: target.model,
+            max_tokens: 1024,
+            messages: [{
+                    role: 'user',
+                    content: [
+                        { type: 'image_url', image_url: { url: dataUrl } },
+                        { type: 'text', text: prompt },
+                    ],
+                }],
+        };
+        const res = await http.post(`${target.baseUrl}/chat/completions`, body, {
+            headers: {
+                Authorization: `Bearer ${key}`,
+                'content-type': 'application/json',
+            },
+            timeout: 30000,
+        });
+        const description = (res.data?.choices?.[0]?.message?.content ?? '').trim();
+        if (!description)
+            return null;
+        const result = {
+            description,
+            provider: target.provider,
+            modelUsed: target.model,
+            durationMs: Date.now() - t0,
+        };
+        log.info('image analyzed', {
+            provider: target.provider,
+            modelUsed: target.model,
+            durationMs: result.durationMs,
+            descChars: description.length,
+        });
+        return result;
+    }
+    catch (e) {
+        log.warn(`${target.provider} vision failed`, { error: e?.message ?? String(e) });
+        return null;
+    }
+}
+// ── Provider 5: Anthropic ─────────────────────────────────────────────────────
+const ANTHROPIC_MODEL = 'claude-3-5-sonnet-20241022';
+async function tryAnthropic(img, prompt, log, http) {
+    const key = process.env.ANTHROPIC_API_KEY;
+    if (!key)
+        return null;
+    const t0 = Date.now();
+    try {
+        const imageBlock = img.isUrl
+            ? { type: 'image', source: { type: 'url', url: img.sourceUrl } }
+            : { type: 'image', source: { type: 'base64', media_type: img.mediaType, data: img.base64 } };
+        const body = {
+            model: ANTHROPIC_MODEL,
+            max_tokens: 1024,
+            messages: [{ role: 'user', content: [imageBlock, { type: 'text', text: prompt }] }],
+        };
+        const res = await http.post('https://api.anthropic.com/v1/messages', body, {
+            headers: {
+                'x-api-key': key,
+                'anthropic-version': '2023-06-01',
+                'content-type': 'application/json',
+            },
+            timeout: 30000,
+        });
+        const description = (res.data?.content?.[0]?.text ?? '').trim();
+        if (!description)
+            return null;
+        const result = { description, provider: 'anthropic', modelUsed: ANTHROPIC_MODEL, durationMs: Date.now() - t0 };
+        log.info('image analyzed', { provider: 'anthropic', modelUsed: ANTHROPIC_MODEL, durationMs: result.durationMs, descChars: description.length });
+        return result;
+    }
+    catch (e) {
+        log.warn('anthropic vision failed', { error: e?.message ?? String(e) });
+        return null;
     }
+}
+// ── Provider 6: OpenAI ────────────────────────────────────────────────────────
+const OPENAI_MODEL = 'gpt-4o';
+async function tryOpenAI(img, prompt, log, http) {
+    const key = process.env.OPENAI_API_KEY;
+    if (!key)
+        return null;
+    const t0 = Date.now();
     try {
-        const res = await axios_1.default.post(`${ollamaBase}/api/generate`, { model: 'llava', prompt, images: [ollamaBase64], stream: false }, { timeout: 60000 });
+        const body = {
+            model: OPENAI_MODEL,
+            max_tokens: 1024,
+            messages: [{
+                    role: 'user',
+                    content: [
+                        { type: 'image_url', image_url: { url: asDataUrl(img) } },
+                        { type: 'text', text: prompt },
+                    ],
+                }],
+        };
+        const res = await http.post('https://api.openai.com/v1/chat/completions', body, {
+            headers: { Authorization: `Bearer ${key}`, 'content-type': 'application/json' },
+            timeout: 30000,
+        });
+        const description = (res.data?.choices?.[0]?.message?.content ?? '').trim();
+        if (!description)
+            return null;
+        const result = { description, provider: 'openai', modelUsed: OPENAI_MODEL, durationMs: Date.now() - t0 };
+        log.info('image analyzed', { provider: 'openai', modelUsed: OPENAI_MODEL, durationMs: result.durationMs, descChars: description.length });
+        return result;
+    }
+    catch (e) {
+        log.warn('openai vision failed', { error: e?.message ?? String(e) });
+        return null;
+    }
+}
+// ── Provider 7: Ollama llava ──────────────────────────────────────────────────
+async function tryOllama(img, prompt, log, http) {
+    const ollamaBase = (process.env.OLLAMA_BASE_URL ?? 'http://127.0.0.1:11434').replace(/\/$/, '');
+    const t0 = Date.now();
+    try {
+        const inline = await ensureBase64(img, http, log);
+        if (!inline)
+            return null;
+        const res = await http.post(`${ollamaBase}/api/generate`, { model: 'llava', prompt, images: [inline.base64], stream: false }, { timeout: 60000 });
         const description = (res.data?.response ?? '').trim();
-        return { description, provider: 'ollama', modelUsed: 'llava', durationMs: Date.now() - start };
+        if (!description)
+            return null;
+        const result = { description, provider: 'ollama', modelUsed: 'llava', durationMs: Date.now() - t0 };
+        log.info('image analyzed', { provider: 'ollama', modelUsed: 'llava', durationMs: result.durationMs, descChars: description.length });
+        return result;
     }
     catch (e) {
-        throw new Error(`vision_analyze: all providers exhausted. ${e.message}`);
+        log.warn('ollama vision failed', { error: e?.message ?? String(e) });
+        return null;
+    }
+}
+// ── Main ─────────────────────────────────────────────────────────────────────
+/**
+ * Analyze an image using the first available vision-capable provider.
+ *
+ * @param imageSource  File path (absolute or relative) or HTTP(S) URL.
+ * @param prompt       Instruction prompt (default: describe the image).
+ * @param logger       Optional Logger from `core/v4/logger`; defaults
+ *                     to a noop sink for legacy callers.
+ * @param httpClient   Phase v4.1-4.1 — optional HTTP client (test seam).
+ *                     Production leaves this unset; smokes inject a fake.
+ * @returns            VisionResult with description, provider, model, timing.
+ */
+async function analyzeImage(imageSource, prompt = 'Describe this image in detail.', logger = (0, logger_1.noopLogger)(), httpClient = defaultHttpClient) {
+    const img = resolveLocalImage(imageSource);
+    // Phase v4.1-4.1 — provider chain. Free providers first so the
+    // bot doesn't burn paid budget on every inbound photo. Each
+    // attempt returns null (key missing OR call failed) on which
+    // we fall through to the next; the first one that produces a
+    // non-empty description wins.
+    const providers = [
+        tryGemini,
+        (i, p, l, h) => tryOpenAICompat(GROQ_TARGET, i, p, l, h),
+        (i, p, l, h) => tryOpenAICompat(OPENROUTER_TARGET, i, p, l, h),
+        (i, p, l, h) => tryOpenAICompat(TOGETHER_TARGET, i, p, l, h),
+        tryAnthropic,
+        tryOpenAI,
+        tryOllama,
+    ];
+    for (const tryProvider of providers) {
+        const result = await tryProvider(img, prompt, logger, httpClient);
+        if (result)
+            return result;
     }
+    logger.warn('all vision providers exhausted');
+    throw new Error('vision_analyze: all providers exhausted (no API key found, or every provider call failed). Configure GEMINI_API_KEY / GROQ_API_KEY / OPENROUTER_API_KEY / TOGETHER_API_KEY / ANTHROPIC_API_KEY / OPENAI_API_KEY, or run a local Ollama with `llava` pulled.');
 }

package/dist/core/voice/audio.js

@@ -95,12 +95,26 @@ Write-Output "${outputPath}"
 }
 async function _recordUnix(outputPath, durationMs) {
     const seconds = Math.ceil(durationMs / 1000);
+    // Phase v4.1-cross-platform: detect available backend up-front so
+    // a missing sox/arecord surfaces a friendly install hint instead of
+    // a raw spawn-failure stack trace.
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    const { detectBackend, missingBackendMessage } = require('./audioBackend');
+    const backend = detectBackend('record');
+    if (!backend) {
+        throw new Error(`[Audio] ${missingBackendMessage('record')}`);
+    }
     // Try sox first, then arecord
     try {
         await execAsync(`sox -d -t wav "${outputPath}" trim 0 ${seconds}`, { timeout: durationMs + 5000 });
     }
     catch {
-        await execAsync(`arecord -d ${seconds} -f S16_LE -r 16000 -c 1 "${outputPath}"`, { timeout: durationMs + 5000 });
+        try {
+            await execAsync(`arecord -d ${seconds} -f S16_LE -r 16000 -c 1 "${outputPath}"`, { timeout: durationMs + 5000 });
+        }
+        catch {
+            throw new Error(`[Audio] ${missingBackendMessage('record')}`);
+        }
     }
     return outputPath;
 }
@@ -144,23 +158,65 @@ async function playAudio(audioSource) {
     }
 }
 async function _playWindows(filePath) {
+    // Phase v4.1-voice-cli (Piece 0) — replaced the hard-coded
+    // `Start-Sleep -Seconds 10` with a NaturalDuration poll loop. The
+    // old code cut off any TTS reply longer than 10s mid-sentence;
+    // voice-mode replies of meaningful length need actual completion
+    // tracking. MediaPlayer.Open is async — we wait up to 5s for
+    // NaturalDuration to populate, then sleep the actual duration
+    // (capped at 5min as a runaway guard). The 10s fallback is
+    // preserved when NaturalDuration never resolves (codec issues,
+    // streaming sources).
     const escaped = filePath.replace(/\\/g, '\\\\');
-    await execAsync(`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: 30000 }).catch(async () => {
-        // Fallback: system default media player
+    const psBody = [
+        'Add-Type -AssemblyName presentationCore',
+        '$mp = New-Object System.Windows.Media.MediaPlayer',
+        `$mp.Open([uri]'${escaped}')`,
+        '$wait = 0',
+        'while (-not $mp.NaturalDuration.HasTimeSpan -and $wait -lt 50) { Start-Sleep -Milliseconds 100; $wait++ }',
+        '$mp.Play()',
+        'if ($mp.NaturalDuration.HasTimeSpan) {',
+        '  $secs = [Math]::Min(300, [Math]::Ceiling($mp.NaturalDuration.TimeSpan.TotalSeconds + 0.5))',
+        '  Start-Sleep -Seconds ([int]$secs)',
+        '} else { Start-Sleep -Seconds 10 }',
+        '$mp.Stop()',
+        '$mp.Close()',
+    ].join('; ');
+    await execAsync(`powershell -Command "${psBody}"`, 
+    // 5 min cap on the duration poll + a generous teardown margin.
+    { timeout: 320000 }).catch(async () => {
+        // Fallback: system default media player (fire-and-forget — caller
+        // doesn't wait for completion, but at least audio plays).
         await execAsync(`powershell -Command "Start-Process '${escaped}'"`, { timeout: 5000 })
             .catch(() => { });
     });
 }
 async function _playUnix(filePath) {
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    const { detectBackend, missingBackendMessage } = require('./audioBackend');
     if (process.platform === 'darwin') {
-        await execAsync(`afplay "${filePath}"`, { timeout: 30000 });
+        try {
+            await execAsync(`afplay "${filePath}"`, { timeout: 30000 });
+        }
+        catch {
+            throw new Error(`[Audio] ${missingBackendMessage('playback')}`);
+        }
     }
     else {
+        // Linux — try paplay then aplay, surface friendly error if both fail.
+        const backend = detectBackend('playback');
+        if (!backend)
+            throw new Error(`[Audio] ${missingBackendMessage('playback')}`);
         try {
             await execAsync(`paplay "${filePath}"`, { timeout: 30000 });
         }
         catch {
-            await execAsync(`aplay "${filePath}"`, { timeout: 30000 });
+            try {
+                await execAsync(`aplay "${filePath}"`, { timeout: 30000 });
+            }
+            catch {
+                throw new Error(`[Audio] ${missingBackendMessage('playback')}`);
+            }
         }
     }
 }

package/dist/core/voice/audioBackend.js

@@ -0,0 +1,134 @@
+"use strict";
+/**
+ * Copyright (c) 2026 Shiva Deore (Taracod). Licensed under AGPL-3.0.
+ *
+ * Aiden — local-first agent.
+ */
+/**
+ * core/voice/audioBackend.ts — Phase v4.1-cross-platform
+ *
+ * Detects which audio playback / recording backend is available on
+ * the current platform and surfaces friendly install hints when the
+ * stack is missing. Used by `audio.ts` and `tts.ts` instead of
+ * blowing up with a raw spawn-failure stack trace.
+ *
+ *   Windows : winmm.dll MCI via PowerShell (always available)
+ *   macOS   : afplay (playback, system) + sox (record)
+ *   Linux   : aplay/paplay (playback) + arecord/sox (record)
+ *
+ * The detection probe runs `<bin> --version` (or `which`) with a
+ * 1.5s timeout; total cost on first call is bounded under 2s.
+ * Results are cached for the process lifetime so repeated checks
+ * are free.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.detectBackend = detectBackend;
+exports.missingBackendMessage = missingBackendMessage;
+exports._resetBackendCacheForTests = _resetBackendCacheForTests;
+exports.listKnownBackends = listKnownBackends;
+const node_child_process_1 = require("node:child_process");
+const BACKENDS = {
+    win32: {
+        playback: [
+            { bin: 'powershell', label: 'PowerShell + winmm.dll', installHint: 'PowerShell ships with Windows.', builtin: true },
+        ],
+        record: [
+            { bin: 'powershell', label: 'PowerShell + winmm.dll', installHint: 'PowerShell ships with Windows.', builtin: true },
+        ],
+    },
+    darwin: {
+        playback: [
+            { bin: 'afplay', label: 'afplay', installHint: 'afplay ships with macOS.', builtin: true },
+            { bin: 'sox', label: 'sox', installHint: 'brew install sox', builtin: false },
+        ],
+        record: [
+            { bin: 'sox', label: 'sox', installHint: 'brew install sox', builtin: false },
+        ],
+    },
+    linux: {
+        playback: [
+            { bin: 'paplay', label: 'paplay (PulseAudio)', installHint: 'sudo apt install pulseaudio-utils  (or use ALSA: sudo apt install alsa-utils)', builtin: false },
+            { bin: 'aplay', label: 'aplay (ALSA)', installHint: 'sudo apt install alsa-utils', builtin: false },
+            { bin: 'sox', label: 'sox', installHint: 'sudo apt install sox', builtin: false },
+        ],
+        record: [
+            { bin: 'arecord', label: 'arecord (ALSA)', installHint: 'sudo apt install alsa-utils', builtin: false },
+            { bin: 'sox', label: 'sox', installHint: 'sudo apt install sox', builtin: false },
+        ],
+    },
+    // Catch-all for unknown platforms — no backends, friendly error.
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    fallback: { playback: [], record: [] },
+    // Other Node.js platforms get the empty fallback via lookup.
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    aix: { playback: [], record: [] },
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    freebsd: { playback: [], record: [] },
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    openbsd: { playback: [], record: [] },
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    sunos: { playback: [], record: [] },
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    android: { playback: [], record: [] },
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    cygwin: { playback: [], record: [] },
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    haiku: { playback: [], record: [] },
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    netbsd: { playback: [], record: [] },
+};
+const cache = new Map();
+/** Probe whether `bin` is on PATH. Cross-platform via `which` / `where`. */
+function probe(bin) {
+    if (cache.has(bin))
+        return cache.get(bin);
+    const cmd = process.platform === 'win32' ? `where ${bin}` : `which ${bin}`;
+    try {
+        (0, node_child_process_1.execSync)(cmd, { stdio: 'ignore', timeout: 1500, windowsHide: true });
+        cache.set(bin, true);
+        return true;
+    }
+    catch {
+        cache.set(bin, false);
+        return false;
+    }
+}
+/** Return the first available backend for `purpose` on the current platform, or null. */
+function detectBackend(purpose) {
+    const platformKey = process.platform;
+    const slot = BACKENDS[platformKey] ?? BACKENDS.fallback;
+    const candidates = slot[purpose] ?? [];
+    for (const b of candidates) {
+        if (b.builtin || probe(b.bin))
+            return b;
+    }
+    return null;
+}
+/**
+ * Build a friendly multi-line message describing the missing backend
+ * and how to install it. Used by audio.ts / tts.ts when the chosen
+ * spawn fails OR detectBackend returns null up front.
+ */
+function missingBackendMessage(purpose) {
+    const platformKey = process.platform;
+    const slot = BACKENDS[platformKey] ?? BACKENDS.fallback;
+    const candidates = slot[purpose] ?? [];
+    if (candidates.length === 0) {
+        return `Audio ${purpose} unavailable on ${process.platform}. Aiden does not yet ship a backend for this platform.`;
+    }
+    const labels = candidates.map((c) => c.label).join(' / ');
+    const installs = candidates.map((c) => `  - ${c.installHint}`).join('\n');
+    return `Audio ${purpose} backend not found. Aiden looked for: ${labels}\nInstall one of:\n${installs}`;
+}
+/**
+ * Reset the probe cache. Test-only; not exposed via the barrel.
+ */
+function _resetBackendCacheForTests() {
+    cache.clear();
+}
+/** Public read-only view for diagnostics (used by `aiden doctor`). */
+function listKnownBackends(purpose) {
+    const platformKey = process.platform;
+    const slot = BACKENDS[platformKey] ?? BACKENDS.fallback;
+    return slot[purpose] ?? [];
+}