@lokutor/sdk 1.5.0 → 1.6.0

package/README.md

@@ -11,7 +11,7 @@ Official JavaScript/TypeScript SDK for [Lokutor AI](https://lokutor.com), provid
 
 - ⚡ **Ultra-low latency**: Optimized WebSocket streaming for real-time interactions.
 - 🗣️ **Conversational Intelligence**: Integrated STT, LLM, and TTS with VAD and barge-in support.
-- 🌍 **Multi-lingual**: Support for English, Spanish, French, Portuguese, and Korean.
+- 🌍 **Multi-lingual**: English, Spanish, Catalan, Galician, Basque, Portuguese, French, Italian and German (Catalan, Galician and Basque are speak-only: no speech recognition yet).
 - 🎨 **Natural Voices**: Multiple high-quality male and female voice styles.
 - 💻 **TypeScript First**: Full type definitions included.
 
@@ -63,9 +63,36 @@ await client.synthesize({
 });
 ```
 
+## Using the SDK in a browser without exposing your key
+
+Never ship an API key in browser code. Mint a short-lived ticket on your server and let the SDK fetch a
+fresh one before every connect (tickets last 10 minutes, so reconnects need a new one):
+
+```js
+// Your server (Node 22+, key stays here)
+app.post('/lokutor-ticket', async (_req, res) => {
+  const r = await fetch('https://api.lokutor.com/ws-ticket', {
+    method: 'POST',
+    headers: { Authorization: `Bearer ${process.env.LOKUTOR_API_KEY}` },
+  });
+  res.json(await r.json()); // { ticket: "wst_...", expires_in: 600 }
+});
+
+// The page
+const agent = new VoiceAgentClient({
+  auth: async () => (await (await fetch('/lokutor-ticket', { method: 'POST' })).json()).ticket,
+  prompt: 'You are a helpful assistant.',
+  enableAudio: true,
+});
+await agent.connect();
+```
+
+To run an agent you configured in the dashboard, pass `agentId` and leave out `prompt`, `voice` and
+`language`: only what you set explicitly overrides the agent.
+
 ## Hardware Compatibility
 
-This SDK is platform-agnostic and works in both **Node.js** and **Browser** environments. 
+This SDK is platform-agnostic and works in both **Node.js** (22 or newer, for the global `WebSocket`) and **Browser** environments. 
 
 ### For Node.js
 We recommend using `node-record-lpcm16` for recording and `speaker` for playback. See the [examples](./examples) folder for a complete Node.js CLI implementation.

package/dist/index.d.mts

@@ -4,13 +4,13 @@
 /**
  * Built-in voices.
  *
- * Versa 2.0 names each voice for the language its reference speaker was recorded in: `EN_*` are
- * English speakers, `ESCA_*` Spanish/Catalan. That is a guide to how a voice sounds, not a
- * restriction — the model is zero-shot, so any voice can speak any supported language.
+ * Use `F1`–`F5` / `M1`–`M5` (what GET /voices lists). Each is a slot: the server resolves it to the
+ * native speaker of the call's language in that slot, so `F1` in Spanish is a Spanish speaker and `F1`
+ * in English an English one.
  *
- * The bare `F1`–`M5` values are the Versa 1.x names. They still work: the server maps them onto
- * the matching Versa 2.0 voice, keeping the language family of the call. Prefer the explicit names
- * in new code.
+ * `EN_*` pin the English speakers regardless of language. `ESCA_*` is the retired Spanish/Catalan pack
+ * (its recordings measure as noisy in the top octave); do not use it in new code — `F1`–`M5` with
+ * `language: 'es'` gives the vetted Spanish voices.
  *
  * This enum is a convenience, not the full set — a cloned voice's id (`clone_…`) is also a valid
  * `voice`, which is why the config fields accept any string.
@@ -26,35 +26,35 @@ declare enum VoiceStyle {
     EN_M3 = "en_m3",
     EN_M4 = "en_m4",
     EN_M5 = "en_m5",
+    /** @deprecated Retired pack; use F1 with language "es". */
     ESCA_F1 = "esca_f1",
+    /** @deprecated Retired pack; use F2 with language "es". */
     ESCA_F2 = "esca_f2",
+    /** @deprecated Retired pack; use F3 with language "es". */
     ESCA_F3 = "esca_f3",
+    /** @deprecated Retired pack; use F4 with language "es". */
     ESCA_F4 = "esca_f4",
+    /** @deprecated Retired pack; use F5 with language "es". */
     ESCA_F5 = "esca_f5",
+    /** @deprecated Retired pack; use M1 with language "es". */
     ESCA_M1 = "esca_m1",
+    /** @deprecated Retired pack; use M2 with language "es". */
     ESCA_M2 = "esca_m2",
+    /** @deprecated Retired pack; use M3 with language "es". */
     ESCA_M3 = "esca_m3",
+    /** @deprecated Retired pack; use M4 with language "es". */
     ESCA_M4 = "esca_m4",
+    /** @deprecated Retired pack; use M5 with language "es". */
     ESCA_M5 = "esca_m5",
-    /** @deprecated Versa 1.x name, mapped server-side. Use EN_F1 / ESCA_F1. */
     F1 = "F1",
-    /** @deprecated Versa 1.x name, mapped server-side. */
     F2 = "F2",
-    /** @deprecated Versa 1.x name, mapped server-side. */
     F3 = "F3",
-    /** @deprecated Versa 1.x name, mapped server-side. */
     F4 = "F4",
-    /** @deprecated Versa 1.x name, mapped server-side. */
     F5 = "F5",
-    /** @deprecated Versa 1.x name, mapped server-side. */
     M1 = "M1",
-    /** @deprecated Versa 1.x name, mapped server-side. */
     M2 = "M2",
-    /** @deprecated Versa 1.x name, mapped server-side. */
     M3 = "M3",
-    /** @deprecated Versa 1.x name, mapped server-side. */
     M4 = "M4",
-    /** @deprecated Versa 1.x name, mapped server-side. */
     M5 = "M5"
 }
 /**
@@ -107,7 +107,14 @@ declare const DEFAULT_URLS: {
  * SDK Configuration interface
  */
 interface LokutorConfig {
-    apiKey: string;
+    /** An API key, or a short-lived wst_ ticket from POST /ws-ticket. Optional when `auth` is given. */
+    apiKey?: string;
+    /**
+     * Called before every connect (and reconnect) for the credential to use. In a browser, have it ask
+     * your backend for a fresh ticket (POST https://api.lokutor.com/ws-ticket with your API key) so the
+     * key itself never reaches the page; a ticket lasts 10 minutes, so reconnects need a new one.
+     */
+    auth?: () => string | Promise<string>;
     agentId?: string;
     onTranscription?: (text: string) => void;
     onResponse?: (text: string) => void;
@@ -285,11 +292,13 @@ interface ToolDefinition {
 interface ToolCall {
     name: string;
     arguments: string;
+    /** Pass to submitToolResult(call_id, result). */
+    call_id: string;
 }
 /**
  * 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' | 'agent.not_found' | 'billing.insufficient_balance' | 'billing.topup_required' | 'billing.limit_reached' | 'billing.account_disputed' | '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,
@@ -369,8 +378,12 @@ declare class VoiceAgentClient {
     private serverPlaybackRate;
     private serverInputRate;
     private serverUrl;
+    private authProvider?;
+    private voiceExplicit;
+    private languageExplicit;
     constructor(config: LokutorConfig & {
-        prompt: string;
+        /** Required unless agentId is set (a dashboard agent brings its own prompt). */
+        prompt?: string;
         voice?: VoiceId;
         language?: Language;
         visemes?: boolean;
@@ -466,8 +479,8 @@ declare class VoiceAgentClient {
      */
     static fetchStatus(baseUrl?: string): Promise<ServerStatus>;
     /**
-     * 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 fetchHealth(baseUrl?: string): Promise<HealthStatus>;
     /**
@@ -699,8 +712,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 +760,7 @@ declare class BrowserAudioManager {
     private echoCancellation;
     private noiseSuppression;
     private keepAwake;
+    private providedMicrophone;
     private wakeLock;
     private visibilityHandler;
     private onAudioInput?;
@@ -848,7 +880,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 +899,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 +931,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 +948,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 +986,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

@@ -4,13 +4,13 @@
 /**
  * Built-in voices.
  *
- * Versa 2.0 names each voice for the language its reference speaker was recorded in: `EN_*` are
- * English speakers, `ESCA_*` Spanish/Catalan. That is a guide to how a voice sounds, not a
- * restriction — the model is zero-shot, so any voice can speak any supported language.
+ * Use `F1`–`F5` / `M1`–`M5` (what GET /voices lists). Each is a slot: the server resolves it to the
+ * native speaker of the call's language in that slot, so `F1` in Spanish is a Spanish speaker and `F1`
+ * in English an English one.
  *
- * The bare `F1`–`M5` values are the Versa 1.x names. They still work: the server maps them onto
- * the matching Versa 2.0 voice, keeping the language family of the call. Prefer the explicit names
- * in new code.
+ * `EN_*` pin the English speakers regardless of language. `ESCA_*` is the retired Spanish/Catalan pack
+ * (its recordings measure as noisy in the top octave); do not use it in new code — `F1`–`M5` with
+ * `language: 'es'` gives the vetted Spanish voices.
  *
  * This enum is a convenience, not the full set — a cloned voice's id (`clone_…`) is also a valid
  * `voice`, which is why the config fields accept any string.
@@ -26,35 +26,35 @@ declare enum VoiceStyle {
     EN_M3 = "en_m3",
     EN_M4 = "en_m4",
     EN_M5 = "en_m5",
+    /** @deprecated Retired pack; use F1 with language "es". */
     ESCA_F1 = "esca_f1",
+    /** @deprecated Retired pack; use F2 with language "es". */
     ESCA_F2 = "esca_f2",
+    /** @deprecated Retired pack; use F3 with language "es". */
     ESCA_F3 = "esca_f3",
+    /** @deprecated Retired pack; use F4 with language "es". */
     ESCA_F4 = "esca_f4",
+    /** @deprecated Retired pack; use F5 with language "es". */
     ESCA_F5 = "esca_f5",
+    /** @deprecated Retired pack; use M1 with language "es". */
     ESCA_M1 = "esca_m1",
+    /** @deprecated Retired pack; use M2 with language "es". */
     ESCA_M2 = "esca_m2",
+    /** @deprecated Retired pack; use M3 with language "es". */
     ESCA_M3 = "esca_m3",
+    /** @deprecated Retired pack; use M4 with language "es". */
     ESCA_M4 = "esca_m4",
+    /** @deprecated Retired pack; use M5 with language "es". */
     ESCA_M5 = "esca_m5",
-    /** @deprecated Versa 1.x name, mapped server-side. Use EN_F1 / ESCA_F1. */
     F1 = "F1",
-    /** @deprecated Versa 1.x name, mapped server-side. */
     F2 = "F2",
-    /** @deprecated Versa 1.x name, mapped server-side. */
     F3 = "F3",
-    /** @deprecated Versa 1.x name, mapped server-side. */
     F4 = "F4",
-    /** @deprecated Versa 1.x name, mapped server-side. */
     F5 = "F5",
-    /** @deprecated Versa 1.x name, mapped server-side. */
     M1 = "M1",
-    /** @deprecated Versa 1.x name, mapped server-side. */
     M2 = "M2",
-    /** @deprecated Versa 1.x name, mapped server-side. */
     M3 = "M3",
-    /** @deprecated Versa 1.x name, mapped server-side. */
     M4 = "M4",
-    /** @deprecated Versa 1.x name, mapped server-side. */
     M5 = "M5"
 }
 /**
@@ -107,7 +107,14 @@ declare const DEFAULT_URLS: {
  * SDK Configuration interface
  */
 interface LokutorConfig {
-    apiKey: string;
+    /** An API key, or a short-lived wst_ ticket from POST /ws-ticket. Optional when `auth` is given. */
+    apiKey?: string;
+    /**
+     * Called before every connect (and reconnect) for the credential to use. In a browser, have it ask
+     * your backend for a fresh ticket (POST https://api.lokutor.com/ws-ticket with your API key) so the
+     * key itself never reaches the page; a ticket lasts 10 minutes, so reconnects need a new one.
+     */
+    auth?: () => string | Promise<string>;
     agentId?: string;
     onTranscription?: (text: string) => void;
     onResponse?: (text: string) => void;
@@ -285,11 +292,13 @@ interface ToolDefinition {
 interface ToolCall {
     name: string;
     arguments: string;
+    /** Pass to submitToolResult(call_id, result). */
+    call_id: string;
 }
 /**
  * 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' | 'agent.not_found' | 'billing.insufficient_balance' | 'billing.topup_required' | 'billing.limit_reached' | 'billing.account_disputed' | '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,
@@ -369,8 +378,12 @@ declare class VoiceAgentClient {
     private serverPlaybackRate;
     private serverInputRate;
     private serverUrl;
+    private authProvider?;
+    private voiceExplicit;
+    private languageExplicit;
     constructor(config: LokutorConfig & {
-        prompt: string;
+        /** Required unless agentId is set (a dashboard agent brings its own prompt). */
+        prompt?: string;
         voice?: VoiceId;
         language?: Language;
         visemes?: boolean;
@@ -466,8 +479,8 @@ declare class VoiceAgentClient {
      */
     static fetchStatus(baseUrl?: string): Promise<ServerStatus>;
     /**
-     * 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 fetchHealth(baseUrl?: string): Promise<HealthStatus>;
     /**
@@ -699,8 +712,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 +760,7 @@ declare class BrowserAudioManager {
     private echoCancellation;
     private noiseSuppression;
     private keepAwake;
+    private providedMicrophone;
     private wakeLock;
     private visibilityHandler;
     private onAudioInput?;
@@ -848,7 +880,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 +899,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 +931,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 +948,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 +986,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 };