@tritard/waterbrother 0.9.2 → 0.9.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tritard/waterbrother",
-  "version": "0.9.2",
+  "version": "0.9.4",
   "description": "Waterbrother: Grok-powered coding CLI with local tools, sessions, operator modes, and approval controls",
   "type": "module",
   "bin": {

package/src/agent.js

@@ -74,7 +74,8 @@ When you use tools:
   - avoid hype such as "premium", "luxurious", "studio-grade", or "improved!"
 - Explain what you changed and why.
 - Never claim you ran commands you did not run.
-- If a tool fails, show the failure and recover.`;
+- If a tool fails, show the failure and recover.
+- You are a coding tool for real software engineering work. If a request is clearly a joke, hypothetical, non-technical, or not related to actual software development, respond conversationally WITHOUT using any tools. Do not create files, write scripts, or make edits for non-engineering requests. Examples of things you should NOT build: personality generators, dating advice scripts, joke apps, horoscope generators, or any request that is clearly not serious engineering work.`;
 
 const COMPACTION_SYSTEM_PROMPT = `You summarize coding assistant transcripts for context compaction.
 Output concise markdown with these sections:

package/src/cli.js

@@ -167,7 +167,8 @@ const INTERACTIVE_COMMANDS = [
   { name: "/models", description: "Select model from list" },
   { name: "/feedback", description: "Report a bug or share feedback" },
   { name: "/cost", description: "Show session token usage and cost breakdown" },
-  { name: "/diff", description: "Show git changes in the current repo" }
+  { name: "/diff", description: "Show git changes in the current repo" },
+  { name: "/voice", description: "Toggle voice dictation (press space to record)" }
 ];
 
 const AGENT_PROFILES = ["coder", "designer", "reviewer", "planner"];
@@ -4459,6 +4460,8 @@ async function readInteractiveLine(options = {}) {
   const output = process.stdout;
   const initialRaw = Boolean(input.isRaw);
   const getFooterText = typeof options.getFooterText === "function" ? options.getFooterText : null;
+  const voiceSession = options.voiceSession || null;
+  const grokConfig = options.grokConfig || null;
 
   return new Promise((resolve, reject) => {
     let buffer = "";
@@ -4468,6 +4471,10 @@ async function readInteractiveLine(options = {}) {
     let ignoredPasteEnters = 0;
     let pasteSuppressUntil = 0;
 
+    // Voice recording state
+    let voiceRecording = false;
+    let voiceIndicator = "";
+
     function finish(nextValue) {
       if (settled) return;
       settled = true;
@@ -4490,8 +4497,9 @@ async function readInteractiveLine(options = {}) {
         selectedIndex = 0;
       }
 
+      const displayBuffer = voiceIndicator ? `${buffer} ${voiceIndicator}` : buffer;
       const writePrompt = () => {
-        output.write(formatPromptRow(buffer, columns));
+        output.write(formatPromptRow(displayBuffer, columns));
       };
 
       output.write("\r\x1b[2K");
@@ -4625,6 +4633,60 @@ async function readInteractiveLine(options = {}) {
         return;
       }
 
+      // Voice: spacebar on empty/trailing-space triggers a 5-second recording.
+      // Uses fixed duration with clean sox exit — same code path as test-capture.mjs.
+      if (voiceSession && !voiceRecording && str === " " && (buffer.length === 0 || buffer.endsWith(" "))) {
+        voiceRecording = true;
+        voiceIndicator = "\x1b[31m[recording 5s — speak now]\x1b[0m";
+        render();
+
+        (async () => {
+          try {
+            const result = await voiceSession.recordAndTranscribe(5);
+            voiceRecording = false;
+
+            if (result && typeof result === "object" && result.error) {
+              voiceIndicator = `\x1b[31m[${result.error}]\x1b[0m`;
+              render();
+              setTimeout(() => { voiceIndicator = ""; render(); }, 6000);
+              return;
+            }
+
+            const rawText = typeof result === "string" ? result : "";
+            voiceIndicator = "";
+            if (!rawText) {
+              render();
+              return;
+            }
+
+            const insertPoint = buffer.length;
+            buffer += rawText;
+            render();
+
+            if (grokConfig && grokConfig.apiKey) {
+              voiceIndicator = "\x1b[36m[correcting...]\x1b[0m";
+              render();
+              voiceSession.correctTranscript(rawText, grokConfig).then((corrected) => {
+                voiceIndicator = "";
+                if (settled) return;
+                if (corrected && corrected !== rawText) {
+                  const before = buffer.slice(0, insertPoint);
+                  const after = buffer.slice(insertPoint + rawText.length);
+                  buffer = before + corrected + after;
+                }
+                render();
+              });
+            }
+          } catch (err) {
+            voiceIndicator = `\x1b[31m[voice error: ${err.message || err}]\x1b[0m`;
+            voiceRecording = false;
+            render();
+            setTimeout(() => { voiceIndicator = ""; render(); }, 6000);
+          }
+        })();
+        return;
+      }
+
       if (isPrintableKey(str, key)) {
         buffer += str;
         selectedIndex = 0;
@@ -5015,7 +5077,7 @@ async function promptLoop(agent, session, context) {
     let line = normalizeInteractiveInput(
       await readInteractiveLine({
         getFooterText(inputBuffer) {
-          return buildInteractiveFooter({
+          const footer = buildInteractiveFooter({
             agent,
             cwd: context.cwd,
             sessionId: currentSession.id,
@@ -5023,7 +5085,17 @@ async function promptLoop(agent, session, context) {
             lastUsage: context.lastUsage,
             costTracker: context.costTracker
           });
-        }
+          if (context.voiceModeEnabled) {
+            return "Voice ON — space to record, space to stop | " + footer;
+          }
+          return footer;
+        },
+        voiceSession: context.voiceModeEnabled ? context.voiceSession : null,
+        grokConfig: context.voiceModeEnabled ? {
+          apiKey: context.runtime.apiKey,
+          baseUrl: context.runtime.baseUrl,
+          model: context.runtime.model
+        } : null
       })
     );
     if (!line) continue;
@@ -6680,6 +6752,30 @@ async function promptLoop(agent, session, context) {
       continue;
     }
 
+    if (line === "/voice") {
+      if (!context.voiceModeEnabled) {
+        try {
+          if (!context.voiceSession) {
+            const { setupVoice } = await import("./voice.js");
+            context.voiceSession = await setupVoice((msg) => console.log(msg));
+          }
+          context.voiceModeEnabled = true;
+          console.log("Voice mode ON. Press spacebar to record (5 seconds).");
+          console.log(dim("Tip: Grok will auto-correct technical terms after transcription."));
+        } catch (error) {
+          console.log(`Voice mode failed: ${error instanceof Error ? error.message : String(error)}`);
+        }
+      } else {
+        context.voiceModeEnabled = false;
+        if (context.voiceSession) {
+          context.voiceSession.destroy();
+          context.voiceSession = null;
+        }
+        console.log("Voice mode OFF.");
+      }
+      continue;
+    }
+
     if (line.startsWith("/")) {
       console.log("Unknown slash command. Use /help.");
       continue;

package/src/voice.js

@@ -0,0 +1,511 @@
+import { execFile, spawn } from "node:child_process";
+import fs from "node:fs/promises";
+import { createRequire } from "node:module";
+import path from "node:path";
+import process from "node:process";
+import { pathToFileURL } from "node:url";
+import { promisify } from "node:util";
+import { createChatCompletion } from "./grok-client.js";
+
+const execFileAsync = promisify(execFile);
+
+// ---------------------------------------------------------------------------
+// Paths
+// ---------------------------------------------------------------------------
+
+const MODEL_DIR_NAME = "sherpa-onnx-moonshine-base-en-int8";
+const MODEL_FILES = [
+  "preprocess.onnx",
+  "encode.int8.onnx",
+  "uncached_decode.int8.onnx",
+  "cached_decode.int8.onnx",
+  "tokens.txt"
+];
+
+function getWaterbrotherHome() {
+  const home = process.env.HOME || process.env.USERPROFILE || "";
+  return path.join(home, ".waterbrother");
+}
+
+function getModelsDir() {
+  return path.join(getWaterbrotherHome(), "models", MODEL_DIR_NAME);
+}
+
+function getVoiceRuntimeDir() {
+  return path.join(getWaterbrotherHome(), "voice-runtime");
+}
+
+// ---------------------------------------------------------------------------
+// System checks
+// ---------------------------------------------------------------------------
+
+async function hasBin(name) {
+  const cmd = process.platform === "win32" ? "where" : "which";
+  try {
+    await execFileAsync(cmd, [name]);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function checkSox() {
+  const cmd = process.platform === "win32" ? "where" : "which";
+  try {
+    const { stdout } = await execFileAsync(cmd, ["sox"]);
+    return { ok: true, path: String(stdout || "").trim().split("\n")[0] || null };
+  } catch {}
+
+  // On Windows, winget portable installs don't add to PATH — search known locations
+  if (process.platform === "win32") {
+    const localAppData = process.env.LOCALAPPDATA;
+    if (localAppData) {
+      const packagesDir = path.join(localAppData, "Microsoft", "WinGet", "Packages");
+      try {
+        const entries = await fs.readdir(packagesDir);
+        for (const entry of entries) {
+          if (!entry.toLowerCase().includes("sox")) continue;
+          const entryPath = path.join(packagesDir, entry);
+          const subEntries = await fs.readdir(entryPath, { recursive: true });
+          for (const sub of subEntries) {
+            if (path.basename(sub).toLowerCase() === "sox.exe") {
+              const fullPath = path.join(entryPath, sub);
+              const soxDir = path.dirname(fullPath);
+              process.env.PATH = `${soxDir};${process.env.PATH}`;
+              return { ok: true, path: fullPath };
+            }
+          }
+        }
+      } catch {}
+    }
+  }
+
+  return { ok: false, path: null };
+}
+
+async function checkSherpaOnnx() {
+  const runtimeDir = getVoiceRuntimeDir();
+  const markerPath = path.join(runtimeDir, "node_modules", "sherpa-onnx-node", "package.json");
+  try {
+    await fs.access(markerPath);
+    return { ok: true };
+  } catch {
+    return { ok: false };
+  }
+}
+
+async function checkModel() {
+  const dir = getModelsDir();
+  try {
+    const entries = await fs.readdir(dir);
+    const missing = MODEL_FILES.filter((f) => !entries.includes(f));
+    return { ok: missing.length === 0, dir, missing };
+  } catch {
+    return { ok: false, dir, missing: MODEL_FILES };
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Model download
+// ---------------------------------------------------------------------------
+
+const MODEL_ARCHIVE_URL =
+  `https://github.com/k2-fsa/sherpa-onnx/releases/download/asr-models/${MODEL_DIR_NAME}.tar.bz2`;
+
+async function downloadModel(onProgress) {
+  const modelsRoot = path.dirname(getModelsDir());
+  await fs.mkdir(modelsRoot, { recursive: true });
+
+  if (onProgress) onProgress({ status: "downloading" });
+
+  const response = await fetch(MODEL_ARCHIVE_URL, { redirect: "follow" });
+  if (!response.ok) {
+    throw new Error(`Failed to download model archive: HTTP ${response.status}`);
+  }
+
+  const contentLength = Number(response.headers.get("content-length")) || 0;
+  const reader = response.body.getReader();
+  const chunks = [];
+  let downloaded = 0;
+
+  while (true) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    chunks.push(value);
+    downloaded += value.length;
+    if (onProgress && contentLength > 0) {
+      onProgress({ status: "progress", downloaded, total: contentLength });
+    }
+  }
+
+  // Write archive to temp file, then extract
+  const archivePath = path.join(modelsRoot, `${MODEL_DIR_NAME}.tar.bz2`);
+  const archiveBuffer = Buffer.concat(chunks);
+  await fs.writeFile(archivePath, archiveBuffer);
+  if (onProgress) onProgress({ status: "extracting" });
+
+  await execFileAsync("tar", ["xjf", archivePath, "-C", modelsRoot], {
+    timeout: 120_000
+  });
+
+  // Clean up archive
+  await fs.unlink(archivePath).catch(() => {});
+  if (onProgress) onProgress({ status: "done", size: archiveBuffer.length });
+}
+
+// ---------------------------------------------------------------------------
+// Recognizer lifecycle
+// ---------------------------------------------------------------------------
+
+let _sherpaOnnx = null;
+
+async function loadSherpaOnnx() {
+  if (_sherpaOnnx) return _sherpaOnnx;
+
+  // Load from the local voice-runtime install via createRequire
+  const runtimeDir = getVoiceRuntimeDir();
+  const fakePath = path.join(runtimeDir, "loader.cjs");
+  const require = createRequire(fakePath);
+  _sherpaOnnx = require("sherpa-onnx-node");
+  return _sherpaOnnx;
+}
+
+function createRecognizer() {
+  const sherpa = _sherpaOnnx;
+  if (!sherpa) throw new Error("sherpa-onnx-node not loaded");
+
+  const dir = getModelsDir();
+  const config = {
+    modelConfig: {
+      moonshine: {
+        preprocessor: path.join(dir, "preprocess.onnx"),
+        encoder: path.join(dir, "encode.int8.onnx"),
+        uncachedDecoder: path.join(dir, "uncached_decode.int8.onnx"),
+        cachedDecoder: path.join(dir, "cached_decode.int8.onnx")
+      },
+      tokens: path.join(dir, "tokens.txt"),
+      provider: "cpu",
+      numThreads: 2,
+      debug: 0
+    }
+  };
+
+  return new sherpa.OfflineRecognizer(config);
+}
+
+// ---------------------------------------------------------------------------
+// Audio device detection (Windows)
+// ---------------------------------------------------------------------------
+
+const WAVEIN_ENUM_SCRIPT = `
+Add-Type -TypeDefinition @"
+using System;
+using System.Runtime.InteropServices;
+public class WaveInHelper {
+    [DllImport("winmm.dll")]
+    public static extern uint waveInGetNumDevs();
+    [DllImport("winmm.dll", CharSet = CharSet.Auto)]
+    public static extern uint waveInGetDevCapsW(uint id, ref WAVEINCAPS caps, uint size);
+    [StructLayout(LayoutKind.Sequential, CharSet = CharSet.Auto)]
+    public struct WAVEINCAPS {
+        public ushort wMid;
+        public ushort wPid;
+        public uint vDriverVersion;
+        [MarshalAs(UnmanagedType.ByValTStr, SizeConst = 32)]
+        public string szPname;
+        public uint dwFormats;
+        public ushort wChannels;
+        public ushort wReserved1;
+    }
+}
+"@
+$$n = [WaveInHelper]::waveInGetNumDevs()
+for ($$i = 0; $$i -lt $$n; $$i++) {
+    $$c = New-Object WaveInHelper+WAVEINCAPS
+    [WaveInHelper]::waveInGetDevCapsW($$i, [ref]$$c, [Runtime.InteropServices.Marshal]::SizeOf($$c)) | Out-Null
+    Write-Output "$$i|$$($$c.szPname)"
+}
+`.replace(/\$\$/g, "$");
+
+async function detectAudioDevice(soxPath, log) {
+  if (process.platform !== "win32") return null;
+
+  try {
+    const { stdout } = await execFileAsync("powershell.exe", [
+      "-NoProfile", "-ExecutionPolicy", "Bypass", "-Command", WAVEIN_ENUM_SCRIPT
+    ], { timeout: 10000 });
+
+    const devices = String(stdout).trim().split("\n")
+      .map((line) => line.trim())
+      .filter(Boolean)
+      .map((line) => {
+        const sep = line.indexOf("|");
+        return { index: line.slice(0, sep), name: line.slice(sep + 1) };
+      });
+
+    if (devices.length === 0) return "default";
+
+    // Score each device: prefer hardware mics, deprioritize virtual/mixer devices
+    const scored = devices.map((d) => {
+      const lower = d.name.toLowerCase();
+      let score = 0;
+      if (lower.startsWith("headset microphone")) score += 100;
+      else if (lower.startsWith("microphone (")) score += 50;
+      else if (lower.startsWith("microphone")) score += 30;
+      else if (lower.startsWith("line in")) score += 20;
+      if (/sonar|virtual|nahimic|nvidia/i.test(d.name)) score -= 200;
+      return { ...d, score };
+    });
+
+    scored.sort((a, b) => b.score - a.score);
+    const best = scored[0];
+    log(`  audio device: ${best.name} (device ${best.index})`);
+    return best.index;
+  } catch {
+    return "default";
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Audio capture via sox
+// ---------------------------------------------------------------------------
+
+// Record for a fixed duration, sox exits cleanly. This is the exact same
+// approach as test-capture.mjs which is the only code path proven to work.
+async function captureAudio(soxPath, audioDevice, durationSec) {
+  const isWin = process.platform === "win32";
+  const inputArgs = isWin
+    ? ["-t", "waveaudio", audioDevice || "default"]
+    : ["-d"];
+
+  const args = [
+    ...inputArgs,
+    "-t", "raw", "-r", "16000", "-c", "1", "-b", "16", "-e", "signed-integer",
+    "-", "trim", "0", String(durationSec)
+  ];
+
+  const { stdout } = await execFileAsync(soxPath, args, {
+    timeout: (durationSec + 5) * 1000,
+    maxBuffer: durationSec * 32000 + 1024,
+    encoding: "buffer"
+  });
+
+  const samples = new Float32Array(Math.floor(stdout.length / 2));
+  for (let i = 0; i < samples.length; i++) {
+    samples[i] = stdout.readInt16LE(i * 2) / 32768.0;
+  }
+  return samples;
+}
+
+// ---------------------------------------------------------------------------
+// Transcription
+// ---------------------------------------------------------------------------
+
+function transcribe(recognizer, audioSamples) {
+  if (!audioSamples || audioSamples.length < 1600) {
+    return "";
+  }
+
+  const stream = recognizer.createStream();
+  stream.acceptWaveform({ sampleRate: 16000, samples: audioSamples });
+  recognizer.decode(stream);
+  return recognizer.getResult(stream).text.trim();
+}
+
+// ---------------------------------------------------------------------------
+// Grok correction pass
+// ---------------------------------------------------------------------------
+
+const CORRECTION_SYSTEM_PROMPT =
+  "You are a transcription corrector for a coding CLI. Fix speech-to-text errors. " +
+  "Properly format technical terms (camelCase, snake_case, file paths, CLI flags, function names). " +
+  "Return ONLY the corrected text, nothing else. If the text is already correct, return it unchanged.";
+
+async function correctTranscript(rawText, { apiKey, baseUrl, model }) {
+  if (!rawText || !apiKey) return rawText;
+
+  try {
+    const completion = await createChatCompletion({
+      apiKey,
+      baseUrl,
+      model: model || "grok-3-mini",
+      messages: [
+        { role: "system", content: CORRECTION_SYSTEM_PROMPT },
+        { role: "user", content: rawText }
+      ],
+      temperature: 0
+    });
+
+    const corrected = (completion?.message?.content || "").trim();
+    return corrected || rawText;
+  } catch {
+    return rawText;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Auto-install helpers
+// ---------------------------------------------------------------------------
+
+async function runShell(command, args, { label, log, timeout = 300_000 } = {}) {
+  if (log && label) log(`  Installing ${label}...`);
+  const { stdout, stderr } = await execFileAsync(command, args, {
+    timeout,
+    env: process.env,
+    shell: process.platform === "win32"
+  });
+  return { stdout, stderr };
+}
+
+async function installSox(log) {
+  const platform = process.platform;
+  if (platform === "darwin") {
+    if (!await hasBin("brew")) throw new Error("Cannot auto-install sox: Homebrew not found.");
+    await runShell("brew", ["install", "sox"], { label: "sox via Homebrew", log });
+  } else if (platform === "win32") {
+    if (await hasBin("winget")) {
+      await runShell("winget", ["install", "--id", "ChrisBagwell.SoX", "-e", "--accept-source-agreements", "--accept-package-agreements"], { label: "sox via winget", log });
+    } else if (await hasBin("choco")) {
+      await runShell("choco", ["install", "sox", "-y"], { label: "sox via Chocolatey", log });
+    } else {
+      throw new Error("Cannot auto-install sox: neither winget nor choco found.");
+    }
+  } else {
+    if (await hasBin("apt-get")) {
+      await runShell("sudo", ["apt-get", "install", "-y", "sox"], { label: "sox via apt", log });
+    } else if (await hasBin("dnf")) {
+      await runShell("sudo", ["dnf", "install", "-y", "sox"], { label: "sox via dnf", log });
+    } else {
+      throw new Error("Cannot auto-install sox: neither apt-get nor dnf found.");
+    }
+  }
+}
+
+function getNativeAddonPackage() {
+  const { platform, arch } = process;
+  if (platform === "win32" && arch === "x64") return "sherpa-onnx-win-x64";
+  if (platform === "win32" && arch === "ia32") return "sherpa-onnx-win-ia32";
+  if (platform === "darwin" && arch === "arm64") return "sherpa-onnx-darwin-arm64";
+  if (platform === "darwin" && arch === "x64") return "sherpa-onnx-darwin-x64";
+  if (platform === "linux" && arch === "x64") return "sherpa-onnx-linux-x64";
+  if (platform === "linux" && arch === "arm64") return "sherpa-onnx-linux-arm64";
+  return null;
+}
+
+async function installSherpaOnnx(log) {
+  const runtimeDir = getVoiceRuntimeDir();
+  await fs.mkdir(runtimeDir, { recursive: true });
+
+  const nativePkg = getNativeAddonPackage();
+  if (!nativePkg) {
+    throw new Error(`Unsupported platform: ${process.platform}-${process.arch}`);
+  }
+
+  // Include the platform-specific native addon as a direct dependency
+  const pkgPath = path.join(runtimeDir, "package.json");
+  await fs.writeFile(pkgPath, JSON.stringify({
+    name: "waterbrother-voice-runtime",
+    version: "1.0.0",
+    private: true,
+    dependencies: {
+      "sherpa-onnx-node": "^1.12.0",
+      [nativePkg]: "^1.12.0"
+    }
+  }, null, 2));
+
+  log("  Installing sherpa-onnx-node (this may take a minute)...");
+  const npmCmd = process.platform === "win32" ? "npm.cmd" : "npm";
+  await execFileAsync(npmCmd, ["install", "--no-audit", "--no-fund"], {
+    cwd: runtimeDir,
+    timeout: 300_000,
+    env: process.env,
+    shell: process.platform === "win32"
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Setup orchestrator
+// ---------------------------------------------------------------------------
+
+export async function setupVoice(onStatus) {
+  const log = onStatus || (() => {});
+
+  log("Setting up voice mode...");
+
+  // 1. sox — check, auto-install if missing
+  let sox = await checkSox();
+  if (!sox.ok) {
+    await installSox(log);
+    sox = await checkSox();
+    if (!sox.ok) throw new Error("sox installed but not found. Restart your terminal and try again.");
+  }
+  log(`  sox: ${sox.path}`);
+
+  // 2. sherpa-onnx — install into ~/.waterbrother/voice-runtime/ if missing
+  let sherpa = await checkSherpaOnnx();
+  if (!sherpa.ok) {
+    await installSherpaOnnx(log);
+    sherpa = await checkSherpaOnnx();
+    if (!sherpa.ok) throw new Error("sherpa-onnx-node install failed. Check ~/.waterbrother/voice-runtime/ for errors.");
+  }
+  log("  sherpa-onnx: ready");
+
+  // 3. Model — auto-download if missing
+  const model = await checkModel();
+  if (!model.ok) {
+    log("  Downloading Moonshine Base model (~250 MB)...");
+    await downloadModel(({ status, downloaded, total, size }) => {
+      if (status === "progress" && total > 0) {
+        const pct = Math.round((downloaded / total) * 100);
+        process.stdout.write(`\r    ${pct}% (${formatBytes(downloaded)}/${formatBytes(total)})`);
+      } else if (status === "extracting") {
+        process.stdout.write(`\r    Extracting...                              \n`);
+      } else if (status === "done") {
+        log(`    Done (${formatBytes(size)})`);
+      }
+    });
+    log("  Model ready.");
+  } else {
+    log("  Moonshine Base: ready");
+  }
+
+  // 4. Detect audio device (Windows)
+  const soxPath = sox.path;
+  const audioDevice = await detectAudioDevice(soxPath, log);
+
+  // 5. Initialize recognizer
+  await loadSherpaOnnx();
+  const recognizer = createRecognizer();
+
+  return {
+    // Record for a fixed duration (sox exits cleanly, no kill).
+    // Returns transcribed text or { error: "..." }.
+    async recordAndTranscribe(durationSec = 5) {
+      const samples = await captureAudio(soxPath, audioDevice, durationSec);
+      const durationMs = Math.round((samples.length / 16000) * 1000);
+      let maxAmp = 0;
+      for (const v of samples) { const a = Math.abs(v); if (a > maxAmp) maxAmp = a; }
+      const text = transcribe(recognizer, samples);
+      if (text) return text;
+      if (samples.length < 1600) return { error: `Recording too short (${durationMs}ms)` };
+      if (maxAmp < 0.01) return { error: `Silence (${durationMs}ms, amp=${maxAmp.toFixed(4)}) — mic not active` };
+      return { error: `No speech detected (${durationMs}ms, amp=${maxAmp.toFixed(4)})` };
+    },
+
+    async correctTranscript(rawText, grokConfig) {
+      return correctTranscript(rawText, grokConfig);
+    },
+
+    destroy() {}
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function formatBytes(bytes) {
+  if (bytes < 1024) return `${bytes} B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+  return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}