@astra-code/astra-ai 0.1.4 → 0.1.6

package/src/app/App.tsx

@@ -3,7 +3,7 @@ import {Box, Text, useApp, useInput} from "ink";
 import Spinner from "ink-spinner";
 import TextInput from "ink-text-input";
 import {spawn} from "child_process";
-import {mkdirSync, unlinkSync, writeFileSync} from "fs";
+import {existsSync, mkdirSync, unlinkSync, writeFileSync} from "fs";
 import {dirname, join} from "path";
 import {BackendClient, type SessionSummary} from "../lib/backendClient.js";
 import {clearSession, loadSession, saveSession} from "../lib/sessionStore.js";
@@ -17,7 +17,7 @@ import {
 import {runTerminalCommand} from "../lib/terminalBridge.js";
 import {isWorkspaceTrusted, trustWorkspace} from "../lib/trustStore.js";
 import {scanWorkspace} from "../lib/workspaceScanner.js";
-import {startLiveTranscription, transcribeOnce, type LiveTranscriptionController} from "../lib/voice.js";
+import {startLiveTranscription, transcribeOnce, resolveAudioDevice, setAudioDevice, listAvfAudioDevices, writeAstraKey, type LiveTranscriptionController} from "../lib/voice.js";
 import type {AgentEvent, AuthSession, ChatMessage} from "../types/events.js";
 import type {WorkspaceFile} from "../lib/workspaceScanner.js";
 
@@ -76,6 +76,7 @@ const FOUNDER_WELCOME = centerLine("Welcome to Astra from Astra CEO & Founder, S
 
 const HISTORY_SETTINGS_URL = "https://astra-web-builder.vercel.app/settings";
 const VOICE_SILENCE_MS = Number(process.env.ASTRA_VOICE_SILENCE_MS ?? "3000");
+
 const VOICE_MIN_CHARS = Number(process.env.ASTRA_VOICE_MIN_CHARS ?? "4");
 const VOICE_DUPLICATE_WINDOW_MS = Number(process.env.ASTRA_VOICE_DUPLICATE_WINDOW_MS ?? "10000");
 const VOICE_NOISE_WORDS = new Set(["you", "yes", "yeah", "yep", "ok", "okay", "uh", "um", "hmm"]);
@@ -306,6 +307,25 @@ const summarizeToolResult = (toolName: string, data: Record<string, unknown>, su
   return `${toolName} completed`;
 };
 
+const isLikelyVoiceNoise = (text: string): boolean => {
+  const normalized = text.trim().toLowerCase();
+  if (!normalized) {
+    return true;
+  }
+  if (normalized.length < VOICE_MIN_CHARS) {
+    return true;
+  }
+  const tokens = normalized.split(/\s+/).filter(Boolean);
+  if (tokens.length === 0) {
+    return true;
+  }
+  const nonNoise = tokens.filter((t) => !VOICE_NOISE_WORDS.has(t));
+  if (nonNoise.length === 0) {
+    return true;
+  }
+  return false;
+};
+
 type InlineToken = {text: string; bold?: boolean; italic?: boolean; code?: boolean};
 
 const parseInline = (line: string): InlineToken[] => {
@@ -640,6 +660,7 @@ export const AstraApp = (): React.JSX.Element => {
   const [voicePreparing, setVoicePreparing] = useState(false);
   const [voiceWaitingForSilence, setVoiceWaitingForSilence] = useState(false);
   const [voiceQueuedPrompt, setVoiceQueuedPrompt] = useState<string | null>(null);
+  const [micSetupDevices, setMicSetupDevices] = useState<Array<{index: number; name: string}> | null>(null);
   const [toolFeedMode, setToolFeedMode] = useState<"compact" | "expanded">("compact");
   const [historyOpen, setHistoryOpen] = useState(false);
   const [historyMode, setHistoryMode] = useState<HistoryMode>("picker");
@@ -771,34 +792,67 @@ export const AstraApp = (): React.JSX.Element => {
     if (liveVoiceRef.current) {
       return;
     }
+    // #region agent log
+    fetch('http://127.0.0.1:7573/ingest/fdd4f018-1ba3-4303-b1bb-375443267476',{method:'POST',headers:{'Content-Type':'application/json','X-Debug-Session-Id':'17f1ea'},body:JSON.stringify({sessionId:'17f1ea',runId:'voice_run_1',hypothesisId:'H5',location:'App.tsx:startLiveVoice',message:'startLiveVoice called',data:{announce,voiceEnabled,thinking,hasController:Boolean(liveVoiceRef.current)},timestamp:Date.now()})}).catch(()=>{});
+    // #endregion
     setVoiceEnabled(true);
     setVoicePreparing(true);
     setVoiceListening(false);
     setVoiceWaitingForSilence(false);
     if (announce) {
-      pushMessage("system", "Dictation armed. Preparing microphone...");
+      pushMessage("system", "Voice input armed. Preparing microphone...");
     }
-    liveVoiceRef.current = startLiveTranscription({
+
+    // Resolve mic device before starting — triggers onboarding if not configured.
+    void resolveAudioDevice(workspaceRoot).then((device) => {
+      if (device === null) {
+        // No device configured — run onboarding inline.
+        setVoicePreparing(false);
+        const devices = listAvfAudioDevices();
+        if (!devices.length) {
+          pushMessage("error", "No audio devices found. Install ffmpeg: brew install ffmpeg");
+          setVoiceEnabled(false);
+          return;
+        }
+        setMicSetupDevices(devices);
+        const lines = [
+          "Let's set up your microphone first.",
+          ...devices.map(d => `  [${d.index}] ${d.name}`),
+          "Type the number for your mic and press Enter:"
+        ];
+        pushMessage("system", lines.join("\n"));
+        return;
+      }
+      // Device resolved — start transcription.
+      liveVoiceRef.current = startLiveTranscription({
       onPartial: (text) => {
         setVoicePreparing(false);
         setVoiceListening(true);
-        setPrompt(text);
         if (voiceSilenceTimerRef.current) {
           clearTimeout(voiceSilenceTimerRef.current);
         }
         const candidate = text.trim();
         if (!candidate) {
+          setPrompt("");
           setVoiceWaitingForSilence(false);
           return;
         }
         const normalized = candidate.toLowerCase();
-        const isLikelyNoise = normalized.length < VOICE_MIN_CHARS || VOICE_NOISE_WORDS.has(normalized);
+        const isLikelyNoise = isLikelyVoiceNoise(normalized);
+        // #region agent log
+        fetch('http://127.0.0.1:7573/ingest/fdd4f018-1ba3-4303-b1bb-375443267476',{method:'POST',headers:{'Content-Type':'application/json','X-Debug-Session-Id':'17f1ea'},body:JSON.stringify({sessionId:'17f1ea',runId:'voice_run_1',hypothesisId:'H1',location:'App.tsx:startLiveVoice.onPartial',message:'partial transcript observed',data:{textLen:text.length,candidateLen:candidate.length,normalized,isLikelyNoise,silenceMs:VOICE_SILENCE_MS},timestamp:Date.now()})}).catch(()=>{});
+        // #endregion
         if (isLikelyNoise) {
+          setPrompt("");
           setVoiceWaitingForSilence(false);
           return;
         }
+        setPrompt(text);
         setVoiceWaitingForSilence(true);
         voiceSilenceTimerRef.current = setTimeout(() => {
+          // #region agent log
+          fetch('http://127.0.0.1:7573/ingest/fdd4f018-1ba3-4303-b1bb-375443267476',{method:'POST',headers:{'Content-Type':'application/json','X-Debug-Session-Id':'17f1ea'},body:JSON.stringify({sessionId:'17f1ea',runId:'voice_run_1',hypothesisId:'H2',location:'App.tsx:startLiveVoice.silenceTimeout',message:'silence timeout fired and queueing prompt',data:{candidate,voiceWaitingForSilence:true},timestamp:Date.now()})}).catch(()=>{});
+          // #endregion
           setVoiceQueuedPrompt(candidate);
           void stopLiveVoice();
         }, VOICE_SILENCE_MS);
@@ -813,15 +867,22 @@ export const AstraApp = (): React.JSX.Element => {
         setVoicePreparing(false);
         setVoiceListening(false);
         setVoiceWaitingForSilence(false);
+        // #region agent log
+        fetch('http://127.0.0.1:7573/ingest/fdd4f018-1ba3-4303-b1bb-375443267476',{method:'POST',headers:{'Content-Type':'application/json','X-Debug-Session-Id':'17f1ea'},body:JSON.stringify({sessionId:'17f1ea',runId:'voice_run_1',hypothesisId:'H4',location:'App.tsx:startLiveVoice.onFinal',message:'final transcript emitted',data:{finalLen:text.length,finalText:text.slice(0,80)},timestamp:Date.now()})}).catch(()=>{});
+        // #endregion
       },
       onError: (error) => {
         setVoicePreparing(false);
         setVoiceListening(false);
         setVoiceWaitingForSilence(false);
         pushMessage("error", `Voice transcription error: ${error.message}`);
+        // #region agent log
+        fetch('http://127.0.0.1:7573/ingest/fdd4f018-1ba3-4303-b1bb-375443267476',{method:'POST',headers:{'Content-Type':'application/json','X-Debug-Session-Id':'17f1ea'},body:JSON.stringify({sessionId:'17f1ea',runId:'voice_run_1',hypothesisId:'H4',location:'App.tsx:startLiveVoice.onError',message:'voice transcription error',data:{error:error.message},timestamp:Date.now()})}).catch(()=>{});
+        // #endregion
       }
-    });
-  }, [pushMessage, stopLiveVoice]);
+      });
+    }); // end resolveAudioDevice.then
+  }, [pushMessage, stopLiveVoice, workspaceRoot]);
 
   useEffect(() => {
     return () => {
@@ -910,6 +971,11 @@ export const AstraApp = (): React.JSX.Element => {
       if (key.return) {
         if (trustSelection === 0) {
           trustWorkspace(workspaceRoot);
+          // Create .astra settings file at workspace root if it doesn't exist yet.
+          try {
+            const astraPath = join(workspaceRoot, ".astra");
+            if (!existsSync(astraPath)) writeFileSync(astraPath, "");
+          } catch { /* non-fatal */ }
           setTrustedWorkspace(true);
           setBooting(true);
           return;
@@ -1312,7 +1378,7 @@ export const AstraApp = (): React.JSX.Element => {
         if (voiceEnabled) {
           await stopLiveVoice();
           setVoiceEnabled(false);
-          pushMessage("system", "Dictation paused: credits exhausted. Recharge, then run /dictate on.");
+          pushMessage("system", "Voice input paused: credits exhausted. Recharge, then run /voice on.");
           pushMessage("system", "");
         }
       }
@@ -1387,10 +1453,32 @@ export const AstraApp = (): React.JSX.Element => {
         return;
       }
 
+      // Mic onboarding: intercept when waiting for device selection.
+      if (micSetupDevices !== null) {
+        const idx = parseInt(text, 10);
+        const valid = !isNaN(idx) && idx >= 0 && micSetupDevices.some(d => d.index === idx);
+        if (!valid) {
+          pushMessage("error", `Please type one of: ${micSetupDevices.map(d => d.index).join(", ")}`);
+          return;
+        }
+        const device = `:${idx}`;
+        // Write to .astra local cache
+        writeAstraKey(workspaceRoot, "ASTRA_STT_DEVICE", device);
+        // Persist to backend
+        void backend.updateCliSettings({audio_device_index: idx});
+        // Update in-process cache
+        setAudioDevice(device);
+        setMicSetupDevices(null);
+        pushMessage("system", `Mic set to [${idx}] ${micSetupDevices.find(d => d.index === idx)?.name ?? ""}. Starting voice...`);
+        pushMessage("system", "");
+        startLiveVoice(false);
+        return;
+      }
+
       if (text === "/help") {
         pushMessage(
           "system",
-          "/new  /history  /dictate  /dictate on|off|status  /tools compact|expanded  /settings  /settings model <id>  /logout  /exit"
+          "/new  /history  /voice  /dictate on|off|status  /tools compact|expanded  /settings  /settings model <id>  /logout  /exit"
         );
         pushMessage("system", "");
         return;
@@ -1410,12 +1498,12 @@ export const AstraApp = (): React.JSX.Element => {
       if (text === "/settings") {
         pushMessage(
           "system",
-          `Settings: mode=${runtimeMode} scope=${workspaceRoot} model=${activeModel} provider=${getProviderForModel(activeModel)} dictate=${voiceEnabled ? "on" : "off"} listening=${voiceListening ? "yes" : "no"} tool_feed=${toolFeedMode} silence_ms=${VOICE_SILENCE_MS} role=${user.role ?? "user"} client_id=${getDefaultClientId()} backend=${getBackendUrl()}`
+          `Settings: mode=${runtimeMode} scope=${workspaceRoot} model=${activeModel} provider=${getProviderForModel(activeModel)} voice=${voiceEnabled ? "on" : "off"} listening=${voiceListening ? "yes" : "no"} tool_feed=${toolFeedMode} silence_ms=${VOICE_SILENCE_MS} role=${user.role ?? "user"} client_id=${getDefaultClientId()} backend=${getBackendUrl()}`
         );
         pushMessage("system", "");
         return;
       }
-      if (text === "/dictate" || text === "/voice") {
+      if (text === "/voice") {
         if (!voiceEnabled) {
           setVoiceEnabled(true);
           startLiveVoice(true);
@@ -1423,7 +1511,7 @@ export const AstraApp = (): React.JSX.Element => {
         }
         pushMessage(
           "system",
-          `Dictation is on${voiceListening ? " (currently listening)" : ""}. Use /dictate off to disable.`
+          `Voice input is on${voiceListening ? " (currently listening)" : ""}. Use /voice off to disable.`
         );
         pushMessage("system", "");
         return;
@@ -1448,29 +1536,29 @@ export const AstraApp = (): React.JSX.Element => {
         await openHistory();
         return;
       }
-      if (text === "/dictate status" || text === "/voice status") {
+      if (text === "/dictate status") {
         pushMessage(
           "system",
-          `Dictation is ${voiceEnabled ? "on" : "off"}${voicePreparing ? " (preparing mic)" : ""}${voiceListening ? " (listening)" : ""}${voiceWaitingForSilence ? " (waiting for silence to auto-send)" : ""}.`
+          `Voice input is ${voiceEnabled ? "on" : "off"}${voicePreparing ? " (preparing mic)" : ""}${voiceListening ? " (listening)" : ""}${voiceWaitingForSilence ? " (waiting for silence to auto-send)" : ""}.`
         );
         pushMessage("system", "");
         return;
       }
-      if (text === "/dictate on" || text === "/voice on") {
+      if (text === "/dictate on") {
         setVoiceEnabled(true);
         startLiveVoice(true);
-        pushMessage("system", `Dictation enabled. Auto-send after ${Math.round(VOICE_SILENCE_MS / 1000)}s silence.`);
+        pushMessage("system", `Voice input enabled. Auto-send after ${Math.round(VOICE_SILENCE_MS / 1000)}s silence.`);
         pushMessage("system", "");
         return;
       }
-      if (text === "/dictate off" || text === "/voice off") {
+      if (text === "/dictate off") {
         await stopLiveVoice();
         setVoiceEnabled(false);
-        pushMessage("system", "Dictation disabled.");
+        pushMessage("system", "Voice input disabled.");
         pushMessage("system", "");
         return;
       }
-      if (text === "/dictate input" || text === "/voice input") {
+      if (text === "/dictate input") {
         const transcribed = await transcribeOnce();
         if (!transcribed) {
           pushMessage(
@@ -1583,9 +1671,11 @@ export const AstraApp = (): React.JSX.Element => {
       exit,
       handleEvent,
       localFileCache,
+      micSetupDevices,
       openHistory,
       pushMessage,
       sessionId,
+      setMicSetupDevices,
       startLiveVoice,
       stopLiveVoice,
       thinking,
@@ -1610,11 +1700,14 @@ export const AstraApp = (): React.JSX.Element => {
     }
     const normalizedQueued = queued.toLowerCase();
     const last = lastVoicePromptRef.current;
-    const isLikelyNoise = normalizedQueued.length < VOICE_MIN_CHARS || VOICE_NOISE_WORDS.has(normalizedQueued);
+    const isLikelyNoise = isLikelyVoiceNoise(normalizedQueued);
     const isFastDuplicate =
       last !== null &&
       last.text === normalizedQueued &&
       Date.now() - last.at <= VOICE_DUPLICATE_WINDOW_MS;
+    // #region agent log
+    fetch('http://127.0.0.1:7573/ingest/fdd4f018-1ba3-4303-b1bb-375443267476',{method:'POST',headers:{'Content-Type':'application/json','X-Debug-Session-Id':'17f1ea'},body:JSON.stringify({sessionId:'17f1ea',runId:'voice_run_1',hypothesisId:'H3',location:'App.tsx:voiceQueuedPromptEffect',message:'queued prompt evaluated',data:{queued,normalizedQueued,isLikelyNoise,isFastDuplicate,thinking},timestamp:Date.now()})}).catch(()=>{});
+    // #endregion
     if (isLikelyNoise || isFastDuplicate) {
       const now = Date.now();
       const lastIgnored = lastIgnoredVoiceRef.current;
@@ -1629,8 +1722,11 @@ export const AstraApp = (): React.JSX.Element => {
       return;
     }
     lastVoicePromptRef.current = {text: normalizedQueued, at: Date.now()};
-    pushMessage("system", `Dictation input: ${queued}`);
+    pushMessage("system", `Voice input: ${queued}`);
     setPrompt("");
+    // #region agent log
+    fetch('http://127.0.0.1:7573/ingest/fdd4f018-1ba3-4303-b1bb-375443267476',{method:'POST',headers:{'Content-Type':'application/json','X-Debug-Session-Id':'17f1ea'},body:JSON.stringify({sessionId:'17f1ea',runId:'voice_run_1',hypothesisId:'H3',location:'App.tsx:voiceQueuedPromptEffect',message:'queued prompt forwarded to sendPrompt',data:{queuedLen:queued.length},timestamp:Date.now()})}).catch(()=>{});
+    // #endregion
     void sendPrompt(queued);
   }, [pushMessage, sendPrompt, thinking, user, voiceQueuedPrompt]);
 
@@ -1829,7 +1925,7 @@ export const AstraApp = (): React.JSX.Element => {
       <Text color="#6c88a8">
         {`scope ${
           workspaceRoot.length > HEADER_PATH_MAX ? `…${workspaceRoot.slice(-(HEADER_PATH_MAX - 1))}` : workspaceRoot
-        } · dictate ${
+        } · voice ${
           voiceEnabled
             ? voicePreparing
               ? "on/preparing"
@@ -1842,7 +1938,7 @@ export const AstraApp = (): React.JSX.Element => {
         }`}
       </Text>
       <Text color="#2a3a50">{divider}</Text>
-      <Text color="#3a5068">/help  /new  /history  /dictate  /dictate on|off|status</Text>
+      <Text color="#3a5068">/help  /new  /history  /voice  /dictate on|off|status</Text>
       <Text color="#3a5068">/tools compact|expanded  /settings  /logout  /exit</Text>
       <Text color="#2a3a50">{divider}</Text>
       <Box flexDirection="column" marginTop={1}>
@@ -1958,7 +2054,7 @@ export const AstraApp = (): React.JSX.Element => {
       ) : null}
       {voiceEnabled && !thinking ? (
         <Box flexDirection="row" marginTop={1}>
-          <Text color="#9ad5ff">{"🎤 dictate".padEnd(LABEL_WIDTH, " ")}</Text>
+          <Text color="#9ad5ff">{"🎤 voice".padEnd(LABEL_WIDTH, " ")}</Text>
           {voicePreparing ? (
             <Text color="#f4d58a">🟡 preparing microphone...</Text>
           ) : voiceListening && !voiceWaitingForSilence ? (
@@ -1983,7 +2079,7 @@ export const AstraApp = (): React.JSX.Element => {
               setPrompt(value);
             }
           }}
-          placeholder={voiceEnabled ? "Ask Astra... (dictate on: auto listen + send on silence)" : "Ask Astra..."}
+          placeholder={voiceEnabled ? "Ask Astra... (voice on: auto listen + send on silence)" : "Ask Astra..."}
         />
       </Box>
     </Box>

package/src/lib/backendClient.ts

@@ -162,6 +162,24 @@ export class BackendClient {
     return out;
   }
 
+  public async getCliSettings(): Promise<Record<string, unknown>> {
+    try {
+      const data = await this.get("/api/user/cli-settings");
+      return (data.cli_settings as Record<string, unknown>) ?? {};
+    } catch {
+      return {};
+    }
+  }
+
+  public async updateCliSettings(settings: Record<string, unknown>): Promise<Record<string, unknown>> {
+    try {
+      const data = await this.patch("/api/user/cli-settings", settings);
+      return (data.cli_settings as Record<string, unknown>) ?? {};
+    } catch {
+      return {};
+    }
+  }
+
   public async deleteSession(sessionId: string): Promise<void> {
     await this.delete(`/api/sessions/${sessionId}`);
   }

package/src/lib/voice.ts

@@ -1,5 +1,6 @@
 import {spawn, spawnSync} from "child_process";
 import {randomUUID} from "crypto";
+import {existsSync, readFileSync, writeFileSync} from "fs";
 import {basename, join} from "path";
 import {tmpdir} from "os";
 import {readFile, rm} from "fs/promises";
@@ -10,6 +11,101 @@ const VOICE_TEXT_LIMIT = 600;
 const DEFAULT_STT_MODEL = process.env.ASTRA_STT_MODEL?.trim() || "whisper-1";
 const DEFAULT_CHUNK_SECONDS = Number(process.env.ASTRA_STT_CHUNK_SECONDS ?? "2.5");
 
+// Module-level device cache — resolved once per process lifetime.
+// undefined = not yet resolved; null = not configured; string = resolved device (e.g. ":1")
+let _cachedDevice: string | null | undefined = undefined;
+
+/** Read/write the .astra file at the workspace root. */
+const ASTRA_FILE_NAME = ".astra";
+
+const readAstraFile = (workspaceRoot: string): Record<string, string> => {
+  const filePath = join(workspaceRoot, ASTRA_FILE_NAME);
+  if (!existsSync(filePath)) return {};
+  const lines = readFileSync(filePath, "utf8").split("\n");
+  const result: Record<string, string> = {};
+  for (const line of lines) {
+    const eq = line.indexOf("=");
+    if (eq > 0) result[line.slice(0, eq).trim()] = line.slice(eq + 1).trim();
+  }
+  return result;
+};
+
+export const writeAstraKey = (workspaceRoot: string, key: string, value: string): void => {
+  const filePath = join(workspaceRoot, ASTRA_FILE_NAME);
+  const existing = existsSync(filePath) ? readFileSync(filePath, "utf8") : "";
+  const lines = existing.split("\n").filter(l => l.trim() && !l.startsWith(`${key}=`));
+  lines.push(`${key}=${value}`);
+  writeFileSync(filePath, lines.join("\n") + "\n");
+};
+
+/**
+ * Resolve the mic device string for ffmpeg (e.g. ":1").
+ * Priority: in-process cache → .astra file → backend cli_settings → null (needs onboarding).
+ * Writes the value to .astra when fetched from the backend so future runs are instant.
+ */
+export const resolveAudioDevice = async (workspaceRoot: string): Promise<string | null> => {
+  if (_cachedDevice !== undefined) return _cachedDevice;
+
+  // 1. Read local .astra cache
+  const local = readAstraFile(workspaceRoot);
+  if (local.ASTRA_STT_DEVICE) {
+    _cachedDevice = local.ASTRA_STT_DEVICE;
+    return _cachedDevice;
+  }
+
+  // 2. Fetch from backend
+  const token = loadSession()?.access_token;
+  if (token) {
+    try {
+      const resp = await fetch(`${getBackendUrl()}/api/user/cli-settings`, {
+        headers: {Authorization: `Bearer ${token}`}
+      });
+      if (resp.ok) {
+        const data = (await resp.json()) as {cli_settings?: {audio_device_index?: number}};
+        const idx = data.cli_settings?.audio_device_index;
+        if (typeof idx === "number") {
+          const device = `:${idx}`;
+          writeAstraKey(workspaceRoot, "ASTRA_STT_DEVICE", device);
+          _cachedDevice = device;
+          return _cachedDevice;
+        }
+      }
+    } catch {
+      // Silently fall through to onboarding
+    }
+  }
+
+  _cachedDevice = null;
+  return null;
+};
+
+/** Call after onboarding saves a new device so the running process uses it immediately. */
+export const setAudioDevice = (device: string): void => {
+  _cachedDevice = device;
+};
+
+/** List AVFoundation audio devices. Returns [] on non-macOS or if ffmpeg is missing. */
+export const listAvfAudioDevices = (): Array<{index: number; name: string}> => {
+  if (process.platform !== "darwin") return [];
+  const result = spawnSync(
+    "ffmpeg",
+    ["-f", "avfoundation", "-list_devices", "true", "-i", ""],
+    {encoding: "utf8", timeout: 8000}
+  );
+  const output = (result.stderr ?? "") + (result.stdout ?? "");
+  const devices: Array<{index: number; name: string}> = [];
+  let inAudio = false;
+  for (const line of output.split("\n")) {
+    if (line.includes("AVFoundation audio devices")) { inAudio = true; continue; }
+    if (inAudio) {
+      const m = line.match(/\[(\d+)\]\s+(.+)$/);
+      if (m?.[1] && m[2]) devices.push({index: parseInt(m[1], 10), name: m[2].trim()});
+      else if (devices.length) break;
+    }
+  }
+  return devices;
+};
+
 const safeText = (text: string): string => text.replace(/\s+/g, " ").trim().slice(0, VOICE_TEXT_LIMIT);
 
 const commandExists = (binary: string): boolean => {
@@ -39,7 +135,8 @@ const captureAudioChunk = async (seconds: number): Promise<string> => {
     if (process.platform === "darwin") {
       // Prefer ffmpeg on macOS (works on Apple Silicon/Homebrew setups).
       if (commandExists("ffmpeg")) {
-        cmd = `ffmpeg -hide_banner -loglevel error -f avfoundation -i ":0" -ar 16000 -ac 1 -t ${seconds} "${outPath}"`;
+        const micDevice = _cachedDevice ?? process.env.ASTRA_STT_DEVICE?.trim() ?? ":0";
+        cmd = `ffmpeg -hide_banner -loglevel error -f avfoundation -i "${micDevice}" -ar 16000 -ac 1 -t ${seconds} "${outPath}"`;
       } else if (commandExists("rec")) {
         cmd = `rec -q -r 16000 -c 1 "${outPath}" trim 0 ${seconds}`;
       } else {
@@ -62,12 +159,21 @@ const captureAudioChunk = async (seconds: number): Promise<string> => {
     cmd = cmd.replaceAll("{output}", outPath).replaceAll("{seconds}", String(seconds));
   }
 
+  // #region agent log
+  fetch('http://127.0.0.1:7573/ingest/fdd4f018-1ba3-4303-b1bb-375443267476',{method:'POST',headers:{'Content-Type':'application/json','X-Debug-Session-Id':'17f1ea'},body:JSON.stringify({sessionId:'17f1ea',runId:'voice_run_2',hypothesisId:'H6',location:'voice.ts:captureAudioChunk',message:'capture command selected',data:{platform:process.platform,seconds,usesCustom:Boolean(custom),cmdPreview:cmd.slice(0,180)},timestamp:Date.now()})}).catch(()=>{});
+  // #endregion
   await runShell(cmd);
+  // #region agent log
+  fetch('http://127.0.0.1:7573/ingest/fdd4f018-1ba3-4303-b1bb-375443267476',{method:'POST',headers:{'Content-Type':'application/json','X-Debug-Session-Id':'17f1ea'},body:JSON.stringify({sessionId:'17f1ea',runId:'voice_run_2',hypothesisId:'H6',location:'voice.ts:captureAudioChunk',message:'capture command completed',data:{outputPath:outPath},timestamp:Date.now()})}).catch(()=>{});
+  // #endregion
   return outPath;
 };
 
 const transcribeAudioFile = async (filePath: string): Promise<string> => {
   const bytes = await readFile(filePath);
+  // #region agent log
+  fetch('http://127.0.0.1:7573/ingest/fdd4f018-1ba3-4303-b1bb-375443267476',{method:'POST',headers:{'Content-Type':'application/json','X-Debug-Session-Id':'17f1ea'},body:JSON.stringify({sessionId:'17f1ea',runId:'voice_run_2',hypothesisId:'H7',location:'voice.ts:transcribeAudioFile',message:'audio chunk loaded',data:{filePath,byteLength:bytes.length},timestamp:Date.now()})}).catch(()=>{});
+  // #endregion
   const file = new File([bytes], basename(filePath), {type: "audio/wav"});
 
   // Backend proxy only: backend holds provider secrets.
@@ -83,12 +189,19 @@ const transcribeAudioFile = async (filePath: string): Promise<string> => {
     headers: {Authorization: `Bearer ${token}`},
     body: form
   });
+  // #region agent log
+  fetch('http://127.0.0.1:7573/ingest/fdd4f018-1ba3-4303-b1bb-375443267476',{method:'POST',headers:{'Content-Type':'application/json','X-Debug-Session-Id':'17f1ea'},body:JSON.stringify({sessionId:'17f1ea',runId:'voice_run_2',hypothesisId:'H7',location:'voice.ts:transcribeAudioFile',message:'backend transcribe response',data:{status:response.status,ok:response.ok},timestamp:Date.now()})}).catch(()=>{});
+  // #endregion
   if (!response.ok) {
     const detail = (await response.text()).slice(0, 400);
     throw new Error(`Backend transcription failed ${response.status}: ${detail}`);
   }
   const data = (await response.json()) as {text?: string};
-  return String(data.text ?? "").trim();
+  const out = String(data.text ?? "").trim();
+  // #region agent log
+  fetch('http://127.0.0.1:7573/ingest/fdd4f018-1ba3-4303-b1bb-375443267476',{method:'POST',headers:{'Content-Type':'application/json','X-Debug-Session-Id':'17f1ea'},body:JSON.stringify({sessionId:'17f1ea',runId:'voice_run_2',hypothesisId:'H8',location:'voice.ts:transcribeAudioFile',message:'transcribe text received',data:{textLen:out.length,textPreview:out.slice(0,80)},timestamp:Date.now()})}).catch(()=>{});
+  // #endregion
+  return out;
 };
 
 /**