@lokutor/sdk 1.5.0 → 1.6.0

package/dist/index.js

@@ -38,9 +38,11 @@ __export(index_exports, {
   calculateRMS: () => calculateRMS,
   float32ToPcm16: () => float32ToPcm16,
   isRetryable: () => isRetryable,
+  microphoneMessage: () => microphoneMessage,
   normalizeAudio: () => normalizeAudio,
   pcm16ToBytes: () => pcm16ToBytes,
   pcm16ToFloat32: () => pcm16ToFloat32,
+  requestMicrophone: () => requestMicrophone,
   resample: () => resample,
   resampleWithAntiAliasing: () => resampleWithAntiAliasing,
   simpleConversation: () => simpleConversation,
@@ -131,13 +133,19 @@ function isRetryableCode(code) {
     "auth.invalid_key",
     "auth.time_limited",
     "session.ended",
+    "audio.microphone_unavailable",
     "validation.invalid_voice",
     "validation.invalid_language",
     "validation.text_too_long",
     "validation.speed_out_of_range",
     "validation.steps_out_of_range",
     "validation.invalid_request_format",
-    "internal.cancelled"
+    "internal.cancelled",
+    "agent.not_found",
+    "billing.insufficient_balance",
+    "billing.topup_required",
+    "billing.limit_reached",
+    "billing.account_disputed"
   ];
   return !fatal.includes(code);
 }
@@ -285,6 +293,36 @@ var StreamResampler = class {
 };
 
 // src/browser-audio.ts
+function requestMicrophone(constraints = {}) {
+  if (typeof navigator === "undefined") {
+    return Promise.reject(new Error("Microphone capture needs a browser"));
+  }
+  const session = navigator.audioSession;
+  if (session && session.type !== "auto" && session.type !== "play-and-record") {
+    try {
+      session.type = "auto";
+    } catch (_) {
+    }
+  }
+  if (!navigator.mediaDevices?.getUserMedia) {
+    return Promise.reject(new Error("Microphone capture is not available here (it needs HTTPS)"));
+  }
+  return navigator.mediaDevices.getUserMedia({
+    audio: {
+      autoGainControl: constraints.autoGainControl ?? true,
+      echoCancellation: constraints.echoCancellation ?? true,
+      noiseSuppression: constraints.noiseSuppression ?? true
+    }
+  });
+}
+async function resumeWithin(ctx, ms) {
+  if (ctx.state === "running") return;
+  await Promise.race([
+    ctx.resume().catch(() => {
+    }),
+    new Promise((r) => setTimeout(r, ms))
+  ]);
+}
 var BrowserAudioManager = class {
   audioContext = null;
   mediaStreamAudioSourceNode = null;
@@ -307,6 +345,7 @@ var BrowserAudioManager = class {
   echoCancellation;
   noiseSuppression;
   keepAwake;
+  providedMicrophone;
   // Screen wake lock, held while the microphone is live. Browsers release it whenever the page is
   // hidden, so it is taken again when the page becomes visible.
   wakeLock = null;
@@ -324,6 +363,9 @@ var BrowserAudioManager = class {
     this.echoCancellation = config.echoCancellation ?? true;
     this.noiseSuppression = config.noiseSuppression ?? true;
     this.keepAwake = config.keepAwake ?? true;
+    this.providedMicrophone = config.microphone ?? null;
+    if (this.providedMicrophone instanceof Promise) this.providedMicrophone.catch(() => {
+    });
     this.onInputError = config.onInputError;
   }
   /**
@@ -339,9 +381,8 @@ var BrowserAudioManager = class {
     if (!this.audioContext) {
       throw new Error("Failed to initialize AudioContext");
     }
-    if (this.audioContext.state === "suspended") {
-      await this.audioContext.resume();
-      console.log("\u{1F442} AudioContext resumed");
+    if (this.audioContext.state !== "running") {
+      await resumeWithin(this.audioContext, 500);
     }
     if (analyserConfig?.enabled !== false) {
       this.analyserNode = this.audioContext.createAnalyser();
@@ -362,7 +403,10 @@ var BrowserAudioManager = class {
     try {
       this.onAudioInput = onAudioInput;
       this.isListening = true;
-      this.mediaStream = await navigator.mediaDevices.getUserMedia({
+      const provided = this.providedMicrophone;
+      this.providedMicrophone = null;
+      const stream = provided ? await provided : null;
+      this.mediaStream = stream && stream.getAudioTracks().some((t) => t.readyState === "live") ? stream : await navigator.mediaDevices.getUserMedia({
         audio: {
           autoGainControl: this.autoGainControl,
           echoCancellation: this.echoCancellation,
@@ -395,6 +439,7 @@ var BrowserAudioManager = class {
       console.log("\u{1F3A4} Microphone started");
       this.holdScreenAwake();
     } catch (error) {
+      this.isListening = false;
       const err = error instanceof Error ? error : new Error(String(error));
       if (this.onInputError) this.onInputError(err);
       throw err;
@@ -629,6 +674,13 @@ var BrowserAudioManager = class {
       this.analyserNode.disconnect();
       this.analyserNode = null;
     }
+    if (this.audioContext) {
+      const ctx = this.audioContext;
+      this.audioContext = null;
+      this.nextPlaybackTime = 0;
+      ctx.close().catch(() => {
+      });
+    }
   }
   /**
    * Get current audio context state
@@ -668,6 +720,9 @@ function nowMs() {
 function wsToHttp(url) {
   return url.replace(/^wss:/, "https:").replace(/^ws:/, "http:");
 }
+function apiOrigin(base) {
+  return new URL(wsToHttp(base || DEFAULT_URLS.VOICE_AGENT)).origin;
+}
 async function fetchJson(url, timeoutMs = 1e4) {
   const controller = new AbortController();
   const timer = setTimeout(() => controller.abort(), timeoutMs);
@@ -780,10 +835,16 @@ var VoiceAgentClient = class {
   serverPlaybackRate = 44100;
   serverInputRate = 16e3;
   serverUrl;
+  authProvider;
+  voiceExplicit = false;
+  languageExplicit = false;
   constructor(config) {
-    this.apiKey = config.apiKey;
+    this.apiKey = config.apiKey || "";
+    this.authProvider = config.auth;
     this.agentId = config.agentId || "";
-    this.prompt = config.prompt;
+    this.prompt = config.prompt ?? "";
+    this.voiceExplicit = config.voice !== void 0;
+    this.languageExplicit = config.language !== void 0;
     this.voice = config.voice || "F1" /* F1 */;
     this.language = config.language || "en" /* ENGLISH */;
     this.serverUrl = config.serverUrl || DEFAULT_URLS.VOICE_AGENT;
@@ -803,6 +864,15 @@ var VoiceAgentClient = class {
    */
   async connect(customAudioManager) {
     this.isUserDisconnect = false;
+    if (this.authProvider) {
+      try {
+        this.apiKey = await this.authProvider();
+      } catch (err) {
+        const error = new LokutorError("auth.missing_key", "The auth callback failed to return a credential", { original: err, retryable: true });
+        this.emit("error", error);
+        throw error;
+      }
+    }
     if (this.enableAudio || customAudioManager) {
       if (customAudioManager) {
         this.audioManager = customAudioManager;
@@ -825,11 +895,11 @@ var VoiceAgentClient = class {
         let url = this.serverUrl;
         if (this.apiKey) {
           const separator = url.includes("?") ? "&" : "?";
-          url += `${separator}api_key=${this.apiKey}`;
+          url += `${separator}api_key=${encodeURIComponent(this.apiKey)}`;
         }
         if (this.agentId) {
           const separator = url.includes("?") ? "&" : "?";
-          url += `${separator}agent_id=${this.agentId}`;
+          url += `${separator}agent_id=${encodeURIComponent(this.agentId)}`;
         }
         const redactedUrl = url.replace(/api_key=[^&]+/, "api_key=***");
         sdkTrace("ws.connect", {
@@ -851,11 +921,29 @@ var VoiceAgentClient = class {
           sdkTrace("ws.open");
           this.sendConfig();
           if (this.audioManager && !this.micStarted) {
-            await this.audioManager.startMicrophone((data) => {
-              if (this.isConnected) {
-                this.sendAudio(data);
+            try {
+              await this.audioManager.startMicrophone((data) => {
+                if (this.isConnected) {
+                  this.sendAudio(data);
+                }
+              });
+            } catch (e) {
+              const name = e?.name || "Error";
+              const error = new LokutorError(
+                "audio.microphone_unavailable",
+                name === "NotAllowedError" || name === "SecurityError" ? "Microphone access was not allowed." : "The microphone could not be started.",
+                { detail: `${name}: ${e?.message ?? e}`, original: e, retryable: false }
+              );
+              sdkTrace("mic.failed", { name });
+              settle(() => reject(error));
+              this.isUserDisconnect = true;
+              try {
+                this.ws?.close();
+              } catch (_) {
               }
-            });
+              this.emit("error", error);
+              return;
+            }
             this.micStarted = true;
           }
           settle(() => resolve(true));
@@ -877,7 +965,7 @@ var VoiceAgentClient = class {
           });
           console.error("\u274C WebSocket error:", error.message);
           sdkTrace("ws.error", { code: error.code, message: error.message });
-          if (this.onError) this.onError(error);
+          this.emit("error", error);
           if (!this.isConnected) {
             settle(() => reject(error));
           }
@@ -914,8 +1002,8 @@ var VoiceAgentClient = class {
             });
             console.log(`Session ended by the server (code ${event.code})`);
             this.emit("ended", { code: event.code, reason: event.reason || "" });
-            if (this.onError) this.onError(ended);
-            if (this.onStatus) this.onStatus("disconnected");
+            this.emit("error", ended);
+            this.emit("status", "disconnected");
             return;
           }
           if (!this.isUserDisconnect && this.reconnectAttempts < this.maxReconnectAttempts) {
@@ -923,7 +1011,7 @@ var VoiceAgentClient = class {
             this.reconnectAttempts++;
             const backoffDelay = Math.min(1e3 * Math.pow(2, this.reconnectAttempts), 1e4);
             console.warn(`Connection lost. Reconnecting in ${backoffDelay}ms (attempt ${this.reconnectAttempts}/${this.maxReconnectAttempts})`);
-            if (this.onStatus) this.onStatus("reconnecting");
+            this.emit("status", "reconnecting");
             if (this.reconnectTimer) clearTimeout(this.reconnectTimer);
             this.reconnectTimer = setTimeout(() => {
               this.reconnectTimer = null;
@@ -933,15 +1021,15 @@ var VoiceAgentClient = class {
             }, backoffDelay);
           } else if (this.isUserDisconnect) {
             console.log("Disconnected");
-            if (this.onStatus) this.onStatus("disconnected");
+            this.emit("status", "disconnected");
           } else {
             console.log("Max reconnection attempts reached");
-            if (this.onStatus) this.onStatus("disconnected");
+            this.emit("status", "disconnected");
           }
         };
       } catch (err) {
         const error = err instanceof LokutorError ? err : new LokutorError("internal.error", "Failed to create WebSocket connection", { original: err });
-        if (this.onError) this.onError(error);
+        this.emit("error", error);
         settle(() => reject(error));
       }
     });
@@ -969,13 +1057,14 @@ var VoiceAgentClient = class {
   sendConfig() {
     if (!this.ws || !this.isConnected) return;
     this.configConfirmed = false;
-    this.ws.send(JSON.stringify({ type: "voice", data: this.voice }));
-    this.ws.send(JSON.stringify({ type: "language", data: this.language }));
+    const agentSession = Boolean(this.agentId);
+    if (!agentSession || this.voiceExplicit) this.ws.send(JSON.stringify({ type: "voice", data: this.voice }));
+    if (!agentSession || this.languageExplicit) this.ws.send(JSON.stringify({ type: "language", data: this.language }));
     if (this.tools && this.tools.length > 0) {
       this.ws.send(JSON.stringify({ type: "tools", data: this.tools }));
     }
     this.ws.send(JSON.stringify({ type: "visemes", data: this.wantVisemes }));
-    this.ws.send(JSON.stringify({ type: "prompt", data: this.prompt }));
+    if (!agentSession || this.prompt) this.ws.send(JSON.stringify({ type: "prompt", data: this.prompt }));
     this.ws.send(JSON.stringify({ type: "rates", playback: 44100, input: 16e3 }));
     sdkTrace("ws.send.config", {
       promptLen: this.prompt?.length || 0,
@@ -1036,6 +1125,10 @@ var VoiceAgentClient = class {
           sdkTrace("server_rates", { playback: this.serverPlaybackRate, input: this.serverInputRate });
           break;
         case "transcript":
+          if (msg.partial) {
+            this.emit("transcription_partial", msg.data);
+            break;
+          }
           const role = msg.role === "user" ? "user" : "agent";
           this.messages.push({
             role,
@@ -1043,11 +1136,9 @@ var VoiceAgentClient = class {
             timestamp: nowMs()
           });
           if (msg.role === "user") {
-            if (this.onTranscription) this.onTranscription(msg.data);
             this.emit("transcription", msg.data);
             console.log(`\u{1F4AC} You: ${msg.data}`);
           } else {
-            if (this.onResponse) this.onResponse(msg.data);
             this.emit("response", msg.data);
             console.log(`\u{1F916} Agent: ${msg.data}`);
           }
@@ -1069,7 +1160,6 @@ var VoiceAgentClient = class {
           if (msg.data === "interrupted" && this.audioManager) {
             this.audioManager.stopPlayback();
           }
-          if (this.onStatus) this.onStatus(msg.data);
           this.emit("status", msg.data);
           const icons = {
             "interrupted": "\u26A1",
@@ -1107,7 +1197,6 @@ var VoiceAgentClient = class {
             detail: backendDetail,
             retryable: backendRetryable
           });
-          if (this.onError) this.onError(error);
           this.emit("error", error);
           console.error(`\u274C Server error: [${error.code}] ${error.message}`);
           break;
@@ -1120,11 +1209,12 @@ var VoiceAgentClient = class {
           }
           break;
         }
-        case "tool_call":
-          this.emit("tool_call", { name: msg.name, arguments: msg.arguments });
+        case "tool_call": {
+          const call = { name: msg.name, arguments: msg.arguments, call_id: msg.call_id };
           console.log(`\u{1F6E0}\uFE0F Tool Call: ${msg.name}(${msg.arguments})`);
-          this.emit("tool_call", msg);
+          this.emit("tool_call", call);
           break;
+        }
       }
     } catch (e) {
       sdkTrace("ws.recv.parse_error", { preview: text?.slice(0, 120) });
@@ -1238,7 +1328,7 @@ var VoiceAgentClient = class {
    * No authentication required.
    */
   static async fetchVoices(baseUrl) {
-    const url = wsToHttp(baseUrl || DEFAULT_URLS.VOICE_AGENT);
+    const url = apiOrigin(baseUrl);
     const data = await fetchJson(`${url}/voices`);
     return data.voices || [];
   }
@@ -1247,7 +1337,7 @@ var VoiceAgentClient = class {
    * No authentication required.
    */
   static async fetchLanguages(baseUrl) {
-    const url = wsToHttp(baseUrl || DEFAULT_URLS.VOICE_AGENT);
+    const url = apiOrigin(baseUrl);
     const data = await fetchJson(`${url}/languages`);
     return data.languages || [];
   }
@@ -1256,7 +1346,7 @@ var VoiceAgentClient = class {
    * No authentication required.
    */
   static async fetchModels(baseUrl) {
-    const url = wsToHttp(baseUrl || DEFAULT_URLS.VOICE_AGENT);
+    const url = apiOrigin(baseUrl);
     const data = await fetchJson(`${url}/models`);
     return data.models || [];
   }
@@ -1265,7 +1355,7 @@ var VoiceAgentClient = class {
    * No authentication required.
    */
   static async fetchConfig(baseUrl) {
-    const url = wsToHttp(baseUrl || DEFAULT_URLS.VOICE_AGENT);
+    const url = apiOrigin(baseUrl);
     return fetchJson(`${url}/config`);
   }
   /**
@@ -1273,16 +1363,16 @@ var VoiceAgentClient = class {
    * No authentication required.
    */
   static async fetchStatus(baseUrl) {
-    const url = wsToHttp(baseUrl || DEFAULT_URLS.VOICE_AGENT);
+    const url = apiOrigin(baseUrl);
     return fetchJson(`${url}/status`);
   }
   /**
-   * Fetch health/liveness status from the server.
-   * No authentication required.
+   * Fetch readiness from the server (GET /ready: 200 once it can serve).
+   * No authentication required. (/health is the operator dashboard's and needs its password.)
    */
   static async fetchHealth(baseUrl) {
-    const url = wsToHttp(baseUrl || DEFAULT_URLS.VOICE_AGENT);
-    return fetchJson(`${url}/health`);
+    const url = apiOrigin(baseUrl);
+    return fetchJson(`${url}/ready`);
   }
   /**
    * Update the system prompt mid-conversation
@@ -1307,6 +1397,7 @@ var VoiceAgentClient = class {
    */
   updateVoice(voice) {
     this.voice = voice;
+    this.voiceExplicit = true;
     if (this.ws && this.ws.readyState === WebSocket.OPEN && this.isConnected) {
       this.ws.send(JSON.stringify({ type: "voice", data: voice }));
       console.log(`\u2699\uFE0F Updated voice: ${voice}`);
@@ -1317,6 +1408,7 @@ var VoiceAgentClient = class {
    */
   updateLanguage(language) {
     this.language = language;
+    this.languageExplicit = true;
     if (this.ws && this.ws.readyState === WebSocket.OPEN && this.isConnected) {
       this.ws.send(JSON.stringify({ type: "language", data: language }));
       console.log(`\u2699\uFE0F Updated language: ${language}`);
@@ -1376,98 +1468,120 @@ var TTSClient = class {
    */
   synthesize(options) {
     return new Promise((resolve, reject) => {
-      let activityTimeout;
+      let timer;
       let ws;
       let startTime;
       let firstByteReceived = false;
-      const refreshTimeout = () => {
-        if (activityTimeout) clearTimeout(activityTimeout);
-        activityTimeout = setTimeout(() => {
-          console.log("\u23F1\uFE0F TTS synthesis reached inactivity timeout (2s) - resolving");
-          if (ws) ws.close();
+      let finished = false;
+      const finish = (err) => {
+        if (finished) return;
+        finished = true;
+        if (timer) clearTimeout(timer);
+        try {
+          ws?.close();
+        } catch {
+        }
+        if (err) {
+          if (options.onError) options.onError(err);
+          reject(err);
+        } else {
           resolve();
-        }, 2e3);
+        }
+      };
+      const arm = () => {
+        if (timer) clearTimeout(timer);
+        timer = setTimeout(
+          () => finish(new LokutorError(
+            "internal.timeout",
+            firstByteReceived ? "TTS stream stalled" : "No audio within 30 s",
+            { retryable: true }
+          )),
+          firstByteReceived ? 15e3 : 3e4
+        );
       };
       try {
         let url = DEFAULT_URLS.TTS;
         if (this.apiKey) {
           const separator = url.includes("?") ? "&" : "?";
-          url += `${separator}api_key=${this.apiKey}`;
+          url += `${separator}api_key=${encodeURIComponent(this.apiKey)}`;
         }
         ws = new WebSocket(url);
         ws.binaryType = "arraybuffer";
         ws.onopen = () => {
-          refreshTimeout();
+          arm();
           const req = {
             text: options.text,
             voice: options.voice || "F1" /* F1 */,
             language: options.language || "en" /* ENGLISH */,
-            speed: options.speed || 1.05,
-            steps: options.steps || 24,
             visemes: options.visemes || false
           };
+          if (options.speed !== void 0) req.speed = options.speed;
+          if (options.steps !== void 0) req.steps = options.steps;
           ws.send(JSON.stringify(req));
           startTime = nowMs();
         };
         ws.onmessage = async (event) => {
-          refreshTimeout();
           if (event.data instanceof ArrayBuffer) {
             if (!firstByteReceived) {
               const ttfb = nowMs() - startTime;
               if (options.onTTFB) options.onTTFB(ttfb);
               firstByteReceived = true;
             }
+            arm();
             if (options.onAudio) options.onAudio(new Uint8Array(event.data));
             return;
           }
           const text = event.data.toString();
           if (text === "EOS") {
-            if (activityTimeout) clearTimeout(activityTimeout);
-            ws.close();
-            resolve();
+            finish();
             return;
           }
+          let msg;
           try {
-            const msg = JSON.parse(text);
-            if (msg.type === "audio" && msg.data) {
-              const audioBuffer = base64ToUint8Array(msg.data);
-              if (!firstByteReceived) {
-                const ttfb = nowMs() - startTime;
-                if (options.onTTFB) options.onTTFB(ttfb);
-                firstByteReceived = true;
-              }
-              if (options.onAudio) options.onAudio(audioBuffer);
-              return;
-            }
-            if (msg.type === "visemes" && Array.isArray(msg.data) && options.onVisemes) {
-              options.onVisemes(normalizeVisemes(msg.data));
-              return;
-            }
-            if (Array.isArray(msg) && options.onVisemes) {
-              options.onVisemes(normalizeVisemes(msg));
-              return;
-            }
-            if (msg.type === "eos") {
-              if (activityTimeout) clearTimeout(activityTimeout);
-              ws.close();
-              resolve();
+            msg = JSON.parse(text);
+          } catch {
+            return;
+          }
+          if (msg.type === "error") {
+            const data = typeof msg.data === "object" && msg.data ? msg.data : { message: msg.data };
+            finish(new LokutorError(data.code ?? "internal.error", data.message ?? "TTS failed", {
+              detail: data.detail,
+              retryable: data.retryable ?? false
+            }));
+            return;
+          }
+          if (msg.type === "audio" && msg.data) {
+            const audioBuffer = base64ToUint8Array(msg.data);
+            if (!firstByteReceived) {
+              const ttfb = nowMs() - startTime;
+              if (options.onTTFB) options.onTTFB(ttfb);
+              firstByteReceived = true;
             }
-          } catch (e) {
+            arm();
+            if (options.onAudio) options.onAudio(audioBuffer);
+            return;
+          }
+          if (msg.type === "visemes" && Array.isArray(msg.data) && options.onVisemes) {
+            options.onVisemes(normalizeVisemes(msg.data));
+            return;
+          }
+          if (Array.isArray(msg) && options.onVisemes) {
+            options.onVisemes(normalizeVisemes(msg));
+            return;
+          }
+          if (msg.type === "eos") {
+            finish();
           }
         };
-        ws.onerror = (err) => {
-          if (activityTimeout) clearTimeout(activityTimeout);
-          if (options.onError) options.onError(err);
-          reject(err);
-        };
-        ws.onclose = () => {
-          if (activityTimeout) clearTimeout(activityTimeout);
-          resolve();
+        ws.onerror = (err) => finish(err);
+        ws.onclose = (ev) => {
+          if (!finished) {
+            if (firstByteReceived && ev.code === 1e3) finish();
+            else finish(new LokutorError("internal.error", `TTS socket closed (${ev.code}${ev.reason ? `: ${ev.reason}` : ""})`, { retryable: true }));
+          }
         };
       } catch (err) {
-        if (activityTimeout) clearTimeout(activityTimeout);
-        if (options.onError) options.onError(err);
-        reject(err);
+        finish(err);
       }
     });
   }
@@ -1573,17 +1687,28 @@ var SpeechToTextClient = class {
       try {
         let url = this.serverUrl;
         const separator = url.includes("?") ? "&" : "?";
-        url += `${separator}api_key=${this.apiKey}`;
+        url += `${separator}api_key=${encodeURIComponent(this.apiKey)}`;
         this.ws = new WebSocket(url);
         this.ws.onopen = async () => {
           this.isConnected = true;
           this.onStatusChange?.("connected");
           this.ws.send(JSON.stringify({ language: this.language || "en" /* ENGLISH */, vad: this.vad }));
-          await this.audioManager.startMicrophone((data) => {
-            if (this.isConnected && this.ws?.readyState === WebSocket.OPEN) {
-              this.ws.send(data);
+          try {
+            await this.audioManager.startMicrophone((data) => {
+              if (this.isConnected && this.ws?.readyState === WebSocket.OPEN) {
+                this.ws.send(data);
+              }
+            });
+          } catch (err) {
+            const error = err instanceof LokutorError ? err : new LokutorError("audio.microphone_unavailable", "Could not start the microphone", { original: err });
+            this.onError?.(error);
+            try {
+              this.ws?.close();
+            } catch {
             }
-          });
+            settle(() => reject(error));
+            return;
+          }
           settle(() => resolve(true));
         };
         this.ws.onmessage = (event) => {
@@ -1597,7 +1722,11 @@ var SpeechToTextClient = class {
                 this.onPartialTranscript?.(msg.data ?? "");
               }
             } else if (msg.type === "error") {
-              this.onError?.(new LokutorError("internal.error", msg.data ?? "STT error"));
+              const data = typeof msg.data === "object" && msg.data ? msg.data : { message: msg.data };
+              this.onError?.(new LokutorError(data.code ?? "internal.error", data.message ?? "STT error", {
+                detail: data.detail,
+                retryable: data.retryable ?? false
+              }));
             }
           } catch {
           }
@@ -2069,6 +2198,17 @@ function injectStyles() {
   document.head.appendChild(style);
   styleInjected = true;
 }
+function microphoneMessage(err) {
+  const name = String(err?.original?.name ?? err?.name ?? "");
+  const detail = String(err?.detail ?? err?.message ?? "");
+  if (/NotAllowedError|SecurityError/.test(name + " " + detail)) {
+    return "Microphone access is blocked. Allow it for this site in your browser settings, then try again.";
+  }
+  if (/NotFoundError|OverconstrainedError/.test(name + " " + detail)) {
+    return "No microphone was found on this device.";
+  }
+  return "The microphone could not start. Please try again.";
+}
 var ConversationalPanel = class {
   cfg;
   container;
@@ -2098,6 +2238,8 @@ var ConversationalPanel = class {
   countdownEl;
   noteEl;
   countdownTicker = null;
+  microphone = null;
+  micError = null;
   // Callbacks
   onTranscription;
   onResponse;
@@ -2199,14 +2341,23 @@ var ConversationalPanel = class {
     d.textContent = s;
     return d.innerHTML;
   }
-  /** Start the conversation (called when user clicks "Start Conversation" or externally) */
+  /**
+   * Start the conversation (called when user clicks "Start Conversation" or externally). Call it from
+   * inside the click or tap, before any await: it asks for the microphone there. Resolves true once the
+   * call is live, false when it could not start (the reason is shown, and passed to onError).
+   */
   async start() {
-    if (this.isRunning) return;
+    if (this.isRunning) return false;
     if (this._locked) {
       this.showError("This session has ended. Refresh the page to start a new one.");
-      return;
+      return false;
     }
     this.isRunning = true;
+    this.microphone = requestMicrophone();
+    this.micError = null;
+    this.microphone.catch((e) => {
+      this.micError = e;
+    });
     this.startBtn.disabled = true;
     this.errorEl.classList.remove("is-visible");
     this.playConnectingSound();
@@ -2257,8 +2408,9 @@ var ConversationalPanel = class {
         onError: (err) => {
           if (!this.isRunning) return;
           this.onError?.(err);
-          this.end(err?.code === "session.ended" && err?.message ? err.message : "Connection issue. Try again in a moment.");
-        }
+          this.end(err?.code === "audio.microphone_unavailable" ? microphoneMessage(err) : err?.code === "session.ended" && err?.message ? err.message : "Connection issue. Try again in a moment.");
+        },
+        microphone: this.microphone
       });
       this.agent = agentHandle;
       visualizer.setAudioClient(agentHandle);
@@ -2268,6 +2420,7 @@ var ConversationalPanel = class {
       } catch (_) {
       }
       const ok = await agentHandle.connect();
+      if (!this.isRunning) return false;
       if (ok) {
         this.fadeOutConnectingSound();
         const wrap = this.visualizerWrap;
@@ -2281,19 +2434,21 @@ var ConversationalPanel = class {
         this.startTimer();
         this.onStart?.();
         if (window.lucide) window.lucide.createIcons();
-      } else {
-        this.fadeOutConnectingSound();
-        this.playErrorTone();
-        this.curtain.classList.remove("is-up");
-        this.showError("Could not connect. Please try again.");
-        this.isRunning = false;
+        return true;
       }
+      this.fadeOutConnectingSound();
+      this.playErrorTone();
+      const micError = this.micError;
+      this.stop();
+      this.showError(micError ? microphoneMessage(micError) : "Could not connect. Please try again.");
+      return false;
     } catch (err) {
       this.fadeOutConnectingSound();
       this.playErrorTone();
       console.error("ConversationalPanel start error:", err);
       this.stop();
       this.showError("Something went wrong. Please try again.");
+      return false;
     } finally {
       this.startBtn.disabled = false;
     }
@@ -2311,6 +2466,10 @@ var ConversationalPanel = class {
       }
       this.agent = null;
     }
+    const mic = this.microphone;
+    this.microphone = null;
+    mic?.then((s) => s.getTracks().forEach((t) => t.stop()), () => {
+    });
     if (this.timerTicker) {
       clearInterval(this.timerTicker);
       this.timerTicker = null;
@@ -2535,9 +2694,11 @@ var ConversationalPanel = class {
   calculateRMS,
   float32ToPcm16,
   isRetryable,
+  microphoneMessage,
   normalizeAudio,
   pcm16ToBytes,
   pcm16ToFloat32,
+  requestMicrophone,
   resample,
   resampleWithAntiAliasing,
   simpleConversation,