@lokutor/sdk 1.5.0 → 1.5.1

package/dist/index.d.mts

@@ -289,7 +289,7 @@ interface ToolCall {
 /**
  * Error code enum matching the backend API error catalog
  */
-type ErrorCode = 'auth.missing_key' | 'auth.invalid_key' | 'auth.rate_limited' | 'auth.time_limited' | 'validation.invalid_voice' | 'validation.invalid_language' | 'validation.text_too_long' | 'validation.speed_out_of_range' | 'validation.steps_out_of_range' | 'validation.invalid_request_format' | 'tts.synthesis_failed' | 'tts.voice_unavailable' | 'tts.model_not_found' | 'tts.session_limit_reached' | 'stt.not_configured' | 'stt.stream_create_failed' | 'stt.language_not_supported' | 'agent.session_failed' | 'agent.provider_error' | 'session.ended' | 'internal.error' | 'internal.timeout' | 'internal.cancelled' | 'ws.close';
+type ErrorCode = 'auth.missing_key' | 'auth.invalid_key' | 'auth.rate_limited' | 'auth.time_limited' | 'validation.invalid_voice' | 'validation.invalid_language' | 'validation.text_too_long' | 'validation.speed_out_of_range' | 'validation.steps_out_of_range' | 'validation.invalid_request_format' | 'tts.synthesis_failed' | 'tts.voice_unavailable' | 'tts.model_not_found' | 'tts.session_limit_reached' | 'stt.not_configured' | 'stt.stream_create_failed' | 'stt.language_not_supported' | 'agent.session_failed' | 'agent.provider_error' | 'session.ended' | 'audio.microphone_unavailable' | 'internal.error' | 'internal.timeout' | 'internal.cancelled' | 'ws.close';
 /**
  * Typed error class for all Lokutor SDK errors.
  * Includes the backend error code, human-readable message,
@@ -699,8 +699,26 @@ interface BrowserAudioConfig {
      * the call goes silent in both directions. Set false if your app manages this itself.
      */
     keepAwake?: boolean;
+    /**
+     * A microphone stream the page already asked for, ideally with requestMicrophone() inside the tap that
+     * started the call. startMicrophone uses it instead of calling getUserMedia again later, after the
+     * connection opens -- which iOS Safari can refuse without showing its prompt.
+     */
+    microphone?: MediaStream | Promise<MediaStream>;
     onInputError?: (error: Error) => void;
 }
+/**
+ * Ask for the microphone now, from inside the tap or click that starts a call, and return the pending stream.
+ *
+ * Call it synchronously in the gesture handler, before any await, and pass the result to BrowserAudioManager
+ * as `microphone` (ConversationalPanel does this itself). Two iOS Safari behaviours made a later request fail
+ * with no prompt at all -- the call connected, the agent spoke, and nothing the caller said was heard:
+ *  - a request outside a user gesture may be refused instead of prompting;
+ *  - while the page's audio session is in 'playback' mode (set by pages so audio plays through the mute
+ *    switch), capture is refused outright. It is put back to 'auto', under which Safari switches to
+ *    play-and-record itself when capture starts and keeps the loudspeaker.
+ */
+declare function requestMicrophone(constraints?: Pick<BrowserAudioConfig, 'autoGainControl' | 'echoCancellation' | 'noiseSuppression'>): Promise<MediaStream>;
 /**
  * Analyser configuration for audio visualization
  */
@@ -729,6 +747,7 @@ declare class BrowserAudioManager {
     private echoCancellation;
     private noiseSuppression;
     private keepAwake;
+    private providedMicrophone;
     private wakeLock;
     private visibilityHandler;
     private onAudioInput?;
@@ -848,7 +867,11 @@ interface ConversationalPanelConfig {
     backgroundColor?: string;
     /** API key for connecting to the voice agent */
     apiKey: string;
-    /** Reference to the ConvoAgent class */
+    /**
+     * Reference to the ConvoAgent class. Its constructor options include `microphone`, a
+     * Promise<MediaStream> requested inside the Start tap (see requestMicrophone); pass it on to
+     * BrowserAudioManager as `microphone` so the call uses it instead of asking again later.
+     */
     ConvoAgent: any;
     /** Reference to the SphereVisualizer class */
     SphereVisualizer: any;
@@ -863,6 +886,9 @@ interface ConversationalPanelConfig {
     /** Seconds of silence before auto-close (default 60) */
     silenceTimeout?: number;
 }
+/** What to tell the caller when the microphone did not start: a DOMException from getUserMedia, or the
+ *  SDK's 'audio.microphone_unavailable' error wrapping one. */
+declare function microphoneMessage(err: any): string;
 declare class ConversationalPanel {
     private cfg;
     private container;
@@ -892,6 +918,8 @@ declare class ConversationalPanel {
     private countdownEl;
     private noteEl;
     private countdownTicker;
+    private microphone;
+    private micError;
     onTranscription?: (text: string) => void;
     onResponse?: (text: string) => void;
     onStart?: () => void;
@@ -907,8 +935,12 @@ declare class ConversationalPanel {
     constructor(cfg: ConversationalPanelConfig);
     private buildDOM;
     private esc;
-    /** Start the conversation (called when user clicks "Start Conversation" or externally) */
-    start(): Promise<void>;
+    /**
+     * 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).
+     */
+    start(): Promise<boolean>;
     /** Stop / disconnect the conversation */
     stop(): void;
     /** Update accent color dynamically */
@@ -941,4 +973,4 @@ declare class ConversationalPanel {
     private playErrorTone;
 }
 
-export { AUDIO_CONFIG, type AnalyserConfig, type AudioManager, type BrowserAudioConfig, BrowserAudioManager, type BrowserAudioOptions, ConversationalPanel, type ConversationalPanelConfig, DEFAULT_URLS, type ErrorCode, type HealthStatus, Language, type LanguageInfo, type LokutorConfig, LokutorError, type ModelInfo, NodeAudioManager, STTClient, type ServerConfig, type ServerStatus, type SessionLimit, SpeechToTextClient, type SpeechToTextOptions, StreamResampler, type SynthesizeOptions, TTSClient, type ToolCall, type ToolDefinition, type TranscribeOptions, type TranscribeResult, type TranscribeSegment, type Viseme, VoiceAgentClient, type VoiceAgentOptions, type VoiceId, type VoiceInfo, VoiceStyle, applyLowPassFilter, bytesToPcm16, calculateRMS, float32ToPcm16, isRetryable, normalizeAudio, pcm16ToBytes, pcm16ToFloat32, resample, resampleWithAntiAliasing, simpleConversation, simpleTTS, simpleTranscribe };
+export { AUDIO_CONFIG, type AnalyserConfig, type AudioManager, type BrowserAudioConfig, BrowserAudioManager, type BrowserAudioOptions, ConversationalPanel, type ConversationalPanelConfig, DEFAULT_URLS, type ErrorCode, type HealthStatus, Language, type LanguageInfo, type LokutorConfig, LokutorError, type ModelInfo, NodeAudioManager, STTClient, type ServerConfig, type ServerStatus, type SessionLimit, SpeechToTextClient, type SpeechToTextOptions, StreamResampler, type SynthesizeOptions, TTSClient, type ToolCall, type ToolDefinition, type TranscribeOptions, type TranscribeResult, type TranscribeSegment, type Viseme, VoiceAgentClient, type VoiceAgentOptions, type VoiceId, type VoiceInfo, VoiceStyle, applyLowPassFilter, bytesToPcm16, calculateRMS, float32ToPcm16, isRetryable, microphoneMessage, normalizeAudio, pcm16ToBytes, pcm16ToFloat32, requestMicrophone, resample, resampleWithAntiAliasing, simpleConversation, simpleTTS, simpleTranscribe };

package/dist/index.d.ts

@@ -289,7 +289,7 @@ interface ToolCall {
 /**
  * Error code enum matching the backend API error catalog
  */
-type ErrorCode = 'auth.missing_key' | 'auth.invalid_key' | 'auth.rate_limited' | 'auth.time_limited' | 'validation.invalid_voice' | 'validation.invalid_language' | 'validation.text_too_long' | 'validation.speed_out_of_range' | 'validation.steps_out_of_range' | 'validation.invalid_request_format' | 'tts.synthesis_failed' | 'tts.voice_unavailable' | 'tts.model_not_found' | 'tts.session_limit_reached' | 'stt.not_configured' | 'stt.stream_create_failed' | 'stt.language_not_supported' | 'agent.session_failed' | 'agent.provider_error' | 'session.ended' | 'internal.error' | 'internal.timeout' | 'internal.cancelled' | 'ws.close';
+type ErrorCode = 'auth.missing_key' | 'auth.invalid_key' | 'auth.rate_limited' | 'auth.time_limited' | 'validation.invalid_voice' | 'validation.invalid_language' | 'validation.text_too_long' | 'validation.speed_out_of_range' | 'validation.steps_out_of_range' | 'validation.invalid_request_format' | 'tts.synthesis_failed' | 'tts.voice_unavailable' | 'tts.model_not_found' | 'tts.session_limit_reached' | 'stt.not_configured' | 'stt.stream_create_failed' | 'stt.language_not_supported' | 'agent.session_failed' | 'agent.provider_error' | 'session.ended' | 'audio.microphone_unavailable' | 'internal.error' | 'internal.timeout' | 'internal.cancelled' | 'ws.close';
 /**
  * Typed error class for all Lokutor SDK errors.
  * Includes the backend error code, human-readable message,
@@ -699,8 +699,26 @@ interface BrowserAudioConfig {
      * the call goes silent in both directions. Set false if your app manages this itself.
      */
     keepAwake?: boolean;
+    /**
+     * A microphone stream the page already asked for, ideally with requestMicrophone() inside the tap that
+     * started the call. startMicrophone uses it instead of calling getUserMedia again later, after the
+     * connection opens -- which iOS Safari can refuse without showing its prompt.
+     */
+    microphone?: MediaStream | Promise<MediaStream>;
     onInputError?: (error: Error) => void;
 }
+/**
+ * Ask for the microphone now, from inside the tap or click that starts a call, and return the pending stream.
+ *
+ * Call it synchronously in the gesture handler, before any await, and pass the result to BrowserAudioManager
+ * as `microphone` (ConversationalPanel does this itself). Two iOS Safari behaviours made a later request fail
+ * with no prompt at all -- the call connected, the agent spoke, and nothing the caller said was heard:
+ *  - a request outside a user gesture may be refused instead of prompting;
+ *  - while the page's audio session is in 'playback' mode (set by pages so audio plays through the mute
+ *    switch), capture is refused outright. It is put back to 'auto', under which Safari switches to
+ *    play-and-record itself when capture starts and keeps the loudspeaker.
+ */
+declare function requestMicrophone(constraints?: Pick<BrowserAudioConfig, 'autoGainControl' | 'echoCancellation' | 'noiseSuppression'>): Promise<MediaStream>;
 /**
  * Analyser configuration for audio visualization
  */
@@ -729,6 +747,7 @@ declare class BrowserAudioManager {
     private echoCancellation;
     private noiseSuppression;
     private keepAwake;
+    private providedMicrophone;
     private wakeLock;
     private visibilityHandler;
     private onAudioInput?;
@@ -848,7 +867,11 @@ interface ConversationalPanelConfig {
     backgroundColor?: string;
     /** API key for connecting to the voice agent */
     apiKey: string;
-    /** Reference to the ConvoAgent class */
+    /**
+     * Reference to the ConvoAgent class. Its constructor options include `microphone`, a
+     * Promise<MediaStream> requested inside the Start tap (see requestMicrophone); pass it on to
+     * BrowserAudioManager as `microphone` so the call uses it instead of asking again later.
+     */
     ConvoAgent: any;
     /** Reference to the SphereVisualizer class */
     SphereVisualizer: any;
@@ -863,6 +886,9 @@ interface ConversationalPanelConfig {
     /** Seconds of silence before auto-close (default 60) */
     silenceTimeout?: number;
 }
+/** What to tell the caller when the microphone did not start: a DOMException from getUserMedia, or the
+ *  SDK's 'audio.microphone_unavailable' error wrapping one. */
+declare function microphoneMessage(err: any): string;
 declare class ConversationalPanel {
     private cfg;
     private container;
@@ -892,6 +918,8 @@ declare class ConversationalPanel {
     private countdownEl;
     private noteEl;
     private countdownTicker;
+    private microphone;
+    private micError;
     onTranscription?: (text: string) => void;
     onResponse?: (text: string) => void;
     onStart?: () => void;
@@ -907,8 +935,12 @@ declare class ConversationalPanel {
     constructor(cfg: ConversationalPanelConfig);
     private buildDOM;
     private esc;
-    /** Start the conversation (called when user clicks "Start Conversation" or externally) */
-    start(): Promise<void>;
+    /**
+     * 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).
+     */
+    start(): Promise<boolean>;
     /** Stop / disconnect the conversation */
     stop(): void;
     /** Update accent color dynamically */
@@ -941,4 +973,4 @@ declare class ConversationalPanel {
     private playErrorTone;
 }
 
-export { AUDIO_CONFIG, type AnalyserConfig, type AudioManager, type BrowserAudioConfig, BrowserAudioManager, type BrowserAudioOptions, ConversationalPanel, type ConversationalPanelConfig, DEFAULT_URLS, type ErrorCode, type HealthStatus, Language, type LanguageInfo, type LokutorConfig, LokutorError, type ModelInfo, NodeAudioManager, STTClient, type ServerConfig, type ServerStatus, type SessionLimit, SpeechToTextClient, type SpeechToTextOptions, StreamResampler, type SynthesizeOptions, TTSClient, type ToolCall, type ToolDefinition, type TranscribeOptions, type TranscribeResult, type TranscribeSegment, type Viseme, VoiceAgentClient, type VoiceAgentOptions, type VoiceId, type VoiceInfo, VoiceStyle, applyLowPassFilter, bytesToPcm16, calculateRMS, float32ToPcm16, isRetryable, normalizeAudio, pcm16ToBytes, pcm16ToFloat32, resample, resampleWithAntiAliasing, simpleConversation, simpleTTS, simpleTranscribe };
+export { AUDIO_CONFIG, type AnalyserConfig, type AudioManager, type BrowserAudioConfig, BrowserAudioManager, type BrowserAudioOptions, ConversationalPanel, type ConversationalPanelConfig, DEFAULT_URLS, type ErrorCode, type HealthStatus, Language, type LanguageInfo, type LokutorConfig, LokutorError, type ModelInfo, NodeAudioManager, STTClient, type ServerConfig, type ServerStatus, type SessionLimit, SpeechToTextClient, type SpeechToTextOptions, StreamResampler, type SynthesizeOptions, TTSClient, type ToolCall, type ToolDefinition, type TranscribeOptions, type TranscribeResult, type TranscribeSegment, type Viseme, VoiceAgentClient, type VoiceAgentOptions, type VoiceId, type VoiceInfo, VoiceStyle, applyLowPassFilter, bytesToPcm16, calculateRMS, float32ToPcm16, isRetryable, microphoneMessage, normalizeAudio, pcm16ToBytes, pcm16ToFloat32, requestMicrophone, resample, resampleWithAntiAliasing, simpleConversation, simpleTTS, simpleTranscribe };

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,6 +133,7 @@ function isRetryableCode(code) {
     "auth.invalid_key",
     "auth.time_limited",
     "session.ended",
+    "audio.microphone_unavailable",
     "validation.invalid_voice",
     "validation.invalid_language",
     "validation.text_too_long",
@@ -285,6 +288,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 +340,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 +358,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 +376,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 +398,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 +434,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 +669,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
@@ -851,11 +898,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));
@@ -1107,7 +1172,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;
@@ -2069,6 +2133,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 +2173,8 @@ var ConversationalPanel = class {
   countdownEl;
   noteEl;
   countdownTicker = null;
+  microphone = null;
+  micError = null;
   // Callbacks
   onTranscription;
   onResponse;
@@ -2199,14 +2276,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 +2343,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 +2355,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 +2369,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 +2401,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 +2629,11 @@ var ConversationalPanel = class {
   calculateRMS,
   float32ToPcm16,
   isRetryable,
+  microphoneMessage,
   normalizeAudio,
   pcm16ToBytes,
   pcm16ToFloat32,
+  requestMicrophone,
   resample,
   resampleWithAntiAliasing,
   simpleConversation,

package/dist/index.mjs

@@ -80,6 +80,7 @@ function isRetryableCode(code) {
     "auth.invalid_key",
     "auth.time_limited",
     "session.ended",
+    "audio.microphone_unavailable",
     "validation.invalid_voice",
     "validation.invalid_language",
     "validation.text_too_long",
@@ -234,6 +235,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;
@@ -256,6 +287,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;
@@ -273,6 +305,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;
   }
   /**
@@ -288,9 +323,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();
@@ -311,7 +345,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,
@@ -344,6 +381,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;
@@ -578,6 +616,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
@@ -800,11 +845,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));
@@ -1056,7 +1119,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;
@@ -2018,6 +2080,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;
@@ -2047,6 +2120,8 @@ var ConversationalPanel = class {
   countdownEl;
   noteEl;
   countdownTicker = null;
+  microphone = null;
+  micError = null;
   // Callbacks
   onTranscription;
   onResponse;
@@ -2148,14 +2223,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();
@@ -2206,8 +2290,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);
@@ -2217,6 +2302,7 @@ var ConversationalPanel = class {
       } catch (_) {
       }
       const ok = await agentHandle.connect();
+      if (!this.isRunning) return false;
       if (ok) {
         this.fadeOutConnectingSound();
         const wrap = this.visualizerWrap;
@@ -2230,19 +2316,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;
     }
@@ -2260,6 +2348,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;
@@ -2483,9 +2575,11 @@ export {
   calculateRMS,
   float32ToPcm16,
   isRetryable,
+  microphoneMessage,
   normalizeAudio,
   pcm16ToBytes,
   pcm16ToFloat32,
+  requestMicrophone,
   resample,
   resampleWithAntiAliasing,
   simpleConversation,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lokutor/sdk",
-  "version": "1.5.0",
+  "version": "1.5.1",
   "description": "JavaScript/TypeScript SDK for Lokutor Real-time Voice AI",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",

package/src/browser-audio.ts

@@ -16,9 +16,61 @@ export interface BrowserAudioConfig {
    * the call goes silent in both directions. Set false if your app manages this itself.
    */
   keepAwake?: boolean;
+  /**
+   * A microphone stream the page already asked for, ideally with requestMicrophone() inside the tap that
+   * started the call. startMicrophone uses it instead of calling getUserMedia again later, after the
+   * connection opens -- which iOS Safari can refuse without showing its prompt.
+   */
+  microphone?: MediaStream | Promise<MediaStream>;
   onInputError?: (error: Error) => void;
 }
 
+/**
+ * Ask for the microphone now, from inside the tap or click that starts a call, and return the pending stream.
+ *
+ * Call it synchronously in the gesture handler, before any await, and pass the result to BrowserAudioManager
+ * as `microphone` (ConversationalPanel does this itself). Two iOS Safari behaviours made a later request fail
+ * with no prompt at all -- the call connected, the agent spoke, and nothing the caller said was heard:
+ *  - a request outside a user gesture may be refused instead of prompting;
+ *  - while the page's audio session is in 'playback' mode (set by pages so audio plays through the mute
+ *    switch), capture is refused outright. It is put back to 'auto', under which Safari switches to
+ *    play-and-record itself when capture starts and keeps the loudspeaker.
+ */
+export function requestMicrophone(
+  constraints: Pick<BrowserAudioConfig, 'autoGainControl' | 'echoCancellation' | 'noiseSuppression'> = {}
+): Promise<MediaStream> {
+  if (typeof navigator === 'undefined') {
+    return Promise.reject(new Error('Microphone capture needs a browser'));
+  }
+  const session = (navigator as any).audioSession;
+  if (session && session.type !== 'auto' && session.type !== 'play-and-record') {
+    try { session.type = 'auto'; } catch (_) { /* read-only in this browser */ }
+  }
+  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,
+    },
+  });
+}
+
+/**
+ * Resume an AudioContext without waiting on it forever. Outside a user gesture iOS Safari leaves resume()'s
+ * promise pending, which stalled the whole call start; the context starts on its own once capture is live,
+ * and playback resumes it again anyway.
+ */
+async function resumeWithin(ctx: AudioContext, ms: number): Promise<void> {
+  if (ctx.state === 'running') return;
+  await Promise.race([
+    ctx.resume().catch(() => {}),
+    new Promise<void>((r) => setTimeout(r, ms)),
+  ]);
+}
+
 /**
  * Analyser configuration for audio visualization
  */
@@ -55,6 +107,7 @@ export class BrowserAudioManager {
   private echoCancellation: boolean;
   private noiseSuppression: boolean;
   private keepAwake: boolean;
+  private providedMicrophone: MediaStream | Promise<MediaStream> | null;
 
   // 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.
@@ -76,6 +129,9 @@ export class BrowserAudioManager {
     this.echoCancellation = config.echoCancellation ?? true;
     this.noiseSuppression = config.noiseSuppression ?? true;
     this.keepAwake = config.keepAwake ?? true;
+    this.providedMicrophone = config.microphone ?? null;
+    // Never an unhandled rejection: startMicrophone reports it.
+    if (this.providedMicrophone instanceof Promise) this.providedMicrophone.catch(() => {});
     this.onInputError = config.onInputError;
   }
 
@@ -98,9 +154,8 @@ export class BrowserAudioManager {
       throw new Error('Failed to initialize AudioContext');
     }
 
-    if (this.audioContext.state === 'suspended') {
-      await this.audioContext.resume();
-      console.log('👂 AudioContext resumed');
+    if (this.audioContext.state !== 'running') {
+      await resumeWithin(this.audioContext, 500);
     }
 
     // Setup analyser for visualization if enabled
@@ -132,14 +187,20 @@ export class BrowserAudioManager {
       this.onAudioInput = onAudioInput;
       this.isListening = true;
 
-      // Request microphone access with constraints
-      this.mediaStream = await navigator.mediaDevices.getUserMedia({
-        audio: {
-          autoGainControl: this.autoGainControl,
-          echoCancellation: this.echoCancellation,
-          noiseSuppression: this.noiseSuppression,
-        },
-      });
+      // The page's own request (made inside the tap), when it has one and its track is still live;
+      // otherwise ask now.
+      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,
+            noiseSuppression: this.noiseSuppression,
+          },
+        });
 
       // Create source from microphone stream
       this.mediaStreamAudioSourceNode =
@@ -190,6 +251,7 @@ export class BrowserAudioManager {
       console.log('🎤 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;
@@ -478,8 +540,15 @@ export class BrowserAudioManager {
       this.analyserNode = null;
     }
 
-    // Don't close AudioContext - it can be expensive to recreate
-    // Just leave it suspended if no longer needed
+    // Closed, not left open: a page makes a new manager per call, so every open context was one more
+    // left running for the life of the page (iOS Safari showed five at the start of a second call, which
+    // then hung). init() makes a fresh one if this manager is used again.
+    if (this.audioContext) {
+      const ctx = this.audioContext;
+      this.audioContext = null;
+      this.nextPlaybackTime = 0;
+      ctx.close().catch(() => {});
+    }
   }
 
   /**

package/src/client.ts

@@ -314,11 +314,29 @@ export class VoiceAgentClient {
           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) {
+              // No microphone, no call. Uncaught here, this left connect() pending forever while the session
+              // it had opened went on talking: the caller heard the agent, nothing they said reached it, and
+              // the page never learned why (iOS refusing capture with no prompt, 2026-09-28).
+              const name = (e as { name?: string } | null)?.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 as Error)?.message ?? e}`, original: e, retryable: false });
+              sdkTrace('mic.failed', { name });
+              settle(() => reject(error));
+              this.isUserDisconnect = true;
+              try { this.ws?.close(); } catch (_) { /* already closing */ }
+              this.emit('error', error); // reaches onError too
+              return;
+            }
             this.micStarted = true;
           }
 
@@ -600,8 +618,7 @@ export class VoiceAgentClient {
             detail: backendDetail,
             retryable: backendRetryable,
           });
-          if (this.onError) this.onError(error);
-          this.emit('error', error);
+          this.emit('error', error); // reaches onError too (calling it here as well delivered every server error twice)
           console.error(`❌ Server error: [${error.code}] ${error.message}`);
           break;
         }

package/src/conversational-panel.ts

@@ -1,3 +1,5 @@
+import { requestMicrophone } from './browser-audio';
+
 const PANEL_CSS = /*css*/ `
   .cv-panel {
     position: relative;
@@ -349,7 +351,11 @@ export interface ConversationalPanelConfig {
   backgroundColor?: string;
   /** API key for connecting to the voice agent */
   apiKey: string;
-  /** Reference to the ConvoAgent class */
+  /**
+   * Reference to the ConvoAgent class. Its constructor options include `microphone`, a
+   * Promise<MediaStream> requested inside the Start tap (see requestMicrophone); pass it on to
+   * BrowserAudioManager as `microphone` so the call uses it instead of asking again later.
+   */
   ConvoAgent: any;
   /** Reference to the SphereVisualizer class */
   SphereVisualizer: any;
@@ -365,6 +371,20 @@ export interface ConversationalPanelConfig {
   silenceTimeout?: number;
 }
 
+/** What to tell the caller when the microphone did not start: a DOMException from getUserMedia, or the
+ *  SDK's 'audio.microphone_unavailable' error wrapping one. */
+export function microphoneMessage(err: any): string {
+  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.';
+}
+
 export class ConversationalPanel {
   private cfg: ConversationalPanelConfig;
   private container: HTMLElement;
@@ -394,6 +414,8 @@ export class ConversationalPanel {
   private countdownEl!: HTMLElement;
   private noteEl!: HTMLElement;
   private countdownTicker: number | null = null;
+  private microphone: Promise<MediaStream> | null = null;
+  private micError: unknown = null;
 
   // Callbacks
   onTranscription?: (text: string) => void;
@@ -507,14 +529,25 @@ export class ConversationalPanel {
     return d.innerHTML;
   }
 
-  /** Start the conversation (called when user clicks "Start Conversation" or externally) */
-  async start() {
-    if (this.isRunning) return;
+  /**
+   * 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(): Promise<boolean> {
+    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;
+    // First, while this is still the tap: iOS Safari only reliably shows its microphone prompt for a request
+    // made inside a user gesture, and refuses capture with no prompt at all while the page's audio session
+    // is in playback mode. Asked for later, after the connection opened, the call went live with the agent
+    // talking and the caller's microphone never captured (2026-09-28).
+    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();
@@ -577,10 +610,13 @@ export class ConversationalPanel {
           this.onError?.(err);
           // The server's own words when it ended the session on purpose (e.g. "Demo time limit
           // reached..."); a generic line for anything else.
-          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;
@@ -591,6 +627,8 @@ export class ConversationalPanel {
       try { agentHandle.unlockAudioForMobile?.(); } catch (_) { /* ignore */ }
 
       const ok = await agentHandle.connect();
+      // Ended while connecting (the microphone was refused, the server closed): the reason is already shown.
+      if (!this.isRunning) return false;
       if (ok) {
         this.fadeOutConnectingSound();
         // Resize canvas to container
@@ -605,19 +643,22 @@ export class ConversationalPanel {
         this.startTimer();
         this.onStart?.();
         if ((window as any).lucide) (window as any).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();
+      // The microphone's own failure when that is what stopped the call, not a generic connection line.
+      const micError = this.micError;
+      this.stop();
+      this.showError(micError ? microphoneMessage(micError) : 'Could not connect. Please try again.');
+      return false;
     } catch (err: any) {
       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;
     }
@@ -633,6 +674,11 @@ export class ConversationalPanel {
       try { this.agent.disconnect(); } catch (_) {}
       this.agent = null;
     }
+    // Release the stream asked for at Start even if the agent never took it over (a ConvoAgent that
+    // ignores `microphone` asks again itself); stopping tracks the agent already stopped is harmless.
+    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; }
     this.stopCountdown();
     this.setNote('');

package/src/index.ts

@@ -14,7 +14,7 @@ export {
 } from './client';
 export { BrowserAudioManager } from './browser-audio';
 export { NodeAudioManager } from './node-audio';
-export { ConversationalPanel } from './conversational-panel';
+export { ConversationalPanel, microphoneMessage } from './conversational-panel';
 export type { ConversationalPanelConfig } from './conversational-panel';
 export {
   pcm16ToFloat32,

package/src/types.ts

@@ -339,6 +339,7 @@ export type ErrorCode =
   | 'agent.session_failed'
   | 'agent.provider_error'
   | 'session.ended'
+  | 'audio.microphone_unavailable'
   | 'internal.error'
   | 'internal.timeout'
   | 'internal.cancelled'
@@ -371,6 +372,7 @@ function isRetryableCode(code: ErrorCode): boolean {
     'auth.invalid_key',
     'auth.time_limited',
     'session.ended',
+    'audio.microphone_unavailable',
     'validation.invalid_voice',
     'validation.invalid_language',
     'validation.text_too_long',