@lokutor/sdk 1.4.1 → 1.5.1

package/src/browser-audio.ts

@@ -10,9 +10,67 @@ export interface BrowserAudioConfig {
   autoGainControl?: boolean;
   echoCancellation?: boolean;
   noiseSuppression?: boolean;
+  /**
+   * Keep the screen awake while the microphone is live (Screen Wake Lock API), as a video player does.
+   * Default true: a phone that dims and locks mid-call suspends the page's microphone and audio, and
+   * 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
  */
@@ -48,6 +106,13 @@ export class BrowserAudioManager {
   private autoGainControl: boolean;
   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.
+  private wakeLock: { release(): Promise<void> } | null = null;
+  private visibilityHandler: (() => void) | null = null;
 
   // Callbacks
   private onAudioInput?: (pcm16Data: Uint8Array) => void;
@@ -63,6 +128,10 @@ export class BrowserAudioManager {
     this.autoGainControl = config.autoGainControl ?? true;
     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;
   }
 
@@ -85,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
@@ -107,18 +175,32 @@ export class BrowserAudioManager {
       await this.init();
     }
 
+    // Already capturing: take the new callback and keep the one pipeline. A second getUserMedia +
+    // ScriptProcessor here used to run two captures into the same resampler, doubling and scrambling
+    // what the server heard.
+    if (this.isListening && this.mediaStream) {
+      this.onAudioInput = onAudioInput;
+      return;
+    }
+
     try {
       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 =
@@ -167,7 +249,9 @@ 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;
@@ -226,6 +310,7 @@ export class BrowserAudioManager {
    */
   stopMicrophone(): void {
     this.isListening = false;
+    this.releaseScreenAwake();
 
     if (this.mediaStream) {
       this.mediaStream.getTracks().forEach((track) => track.stop());
@@ -245,6 +330,50 @@ export class BrowserAudioManager {
     console.log('🎤 Microphone stopped');
   }
 
+  /**
+   * Keep the screen on while the microphone is live, and bring audio back when the page returns
+   * to the foreground (iOS leaves the context "interrupted" after the screen locks).
+   */
+  private holdScreenAwake(): void {
+    if (typeof document === 'undefined') return;
+    if (!this.visibilityHandler) {
+      this.visibilityHandler = () => {
+        if (document.visibilityState !== 'visible' || !this.isListening) return;
+        if (this.audioContext && this.audioContext.state !== 'running') {
+          this.audioContext.resume().catch(() => {});
+        }
+        void this.requestWakeLock();
+      };
+      document.addEventListener('visibilitychange', this.visibilityHandler);
+    }
+    void this.requestWakeLock();
+  }
+
+  private async requestWakeLock(): Promise<void> {
+    if (!this.keepAwake || this.wakeLock || typeof navigator === 'undefined') return;
+    const api = (navigator as any).wakeLock;
+    if (!api?.request || document.visibilityState !== 'visible') return;
+    try {
+      const lock = await api.request('screen');
+      if (!this.isListening) { await lock.release().catch(() => {}); return; }
+      this.wakeLock = lock;
+      // The browser drops the lock when the page is hidden; forget it so it is taken again on return.
+      lock.addEventListener?.('release', () => { if (this.wakeLock === lock) this.wakeLock = null; });
+    } catch (_) {
+      // Not allowed right now (battery saver, permissions policy): the call works, the screen may dim.
+    }
+  }
+
+  private releaseScreenAwake(): void {
+    if (this.visibilityHandler && typeof document !== 'undefined') {
+      document.removeEventListener('visibilitychange', this.visibilityHandler);
+      this.visibilityHandler = null;
+    }
+    const lock = this.wakeLock;
+    this.wakeLock = null;
+    lock?.release().catch(() => {});
+  }
+
   /**
    * Play back audio received from the server
    * @param pcm16Data Int16 PCM audio data at SPEAKER_SAMPLE_RATE
@@ -411,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

@@ -91,6 +91,24 @@ export interface AudioManager {
   getAmplitude(): number;
 }
 
+/**
+ * Close codes after which the client reconnects: the connection dropped or the server went away
+ * (a deploy, a restart, a network change), so another attempt can succeed. Every other close is
+ * the server ending the session on purpose -- 1000 when the agent ends the call, 1008 when a limit
+ * is reached (the landing demo's time allowance), 4xxx for application reasons -- and reconnecting
+ * after one of those used to open a fresh session behind the caller's back: a new conversation
+ * with no memory of the old one, a second microphone pipeline, and every reply discarded as stale.
+ */
+const RECONNECTABLE_CLOSE_CODES = new Set([1001, 1006, 1011, 1012, 1013, 1014]);
+
+/** What the server announced about how long this session may run (landing-page demo sessions). */
+export interface SessionLimit {
+  /** Seconds the session may still run, from when the message arrived. */
+  seconds: number;
+  /** Why there is a limit, e.g. "demo". */
+  reason?: string;
+}
+
 // Browser-compatible base64 to Uint8Array
 function base64ToUint8Array(base64: string): Uint8Array {
   const binaryString = atob(base64);
@@ -189,6 +207,9 @@ export class VoiceAgentClient {
   private reconnectAttempts: number = 0;
   private maxReconnectAttempts: number = 5;
   private reconnectTimer: ReturnType<typeof setTimeout> | null = null;
+  // The microphone is started once per session of this client, not once per socket: a reconnect
+  // reuses it. Starting it again on every open ran two capture pipelines into one resampler.
+  private micStarted: boolean = false;
 
   // Runtime state
   private serverPlaybackRate: number = 44100;
@@ -284,16 +305,39 @@ export class VoiceAgentClient {
           this.isConnected = true;
           this.reconnectAttempts = 0;
           this.reconnecting = false;
+          // Every socket is a new server session, and a new session numbers its replies from 1.
+          // Keeping the previous session's count here discarded every reply after a reconnect as
+          // "ghost audio" -- the agent answered and the caller heard nothing.
+          this.currentGeneration = 0;
           console.log('✅ Connected to voice agent!');
           sdkTrace('ws.open');
           this.sendConfig();
 
-          if (this.audioManager) {
-            await this.audioManager.startMicrophone((data) => {
-              if (this.isConnected) {
-                this.sendAudio(data);
-              }
-            });
+          if (this.audioManager && !this.micStarted) {
+            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;
           }
 
           settle(() => resolve(true));
@@ -352,6 +396,19 @@ export class VoiceAgentClient {
 
           console.log(`🔌 WebSocket closed — code: ${event.code}, reason: "${event.reason || 'none'}", clean: ${event.wasClean}`);
 
+          if (!this.isUserDisconnect && !RECONNECTABLE_CLOSE_CODES.has(event.code)) {
+            // The server ended the session on purpose. Say so, with its reason, and stay closed.
+            const ended = new LokutorError('session.ended', event.reason || 'The session was ended by the server.', {
+              detail: `close code ${event.code}`,
+              retryable: false,
+            });
+            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');
+            return;
+          }
+
           if (!this.isUserDisconnect && this.reconnectAttempts < this.maxReconnectAttempts) {
             this.reconnecting = true;
             this.reconnectAttempts++;
@@ -561,11 +618,21 @@ 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;
         }
+        case 'session_limit': {
+          // How long this session may run, sent by the server when there is a limit (the landing
+          // page's key-less demo). A UI can show it as a countdown instead of the call just ending.
+          const seconds = Number(msg.data?.seconds ?? msg.seconds);
+          if (Number.isFinite(seconds) && seconds >= 0) {
+            const limit: SessionLimit = { seconds, reason: msg.data?.reason ?? msg.reason };
+            this.emit('session_limit', limit);
+          }
+          break;
+        }
+
         case 'tool_call':
           this.emit('tool_call', { name: msg.name, arguments: msg.arguments });
           console.log(`🛠️ Tool Call: ${msg.name}(${msg.arguments})`);
@@ -648,6 +715,7 @@ export class VoiceAgentClient {
     if (this.audioManager) {
       this.audioManager.cleanup();
     }
+    this.micStarted = false;
     this.isConnected = false;
     this.configConfirmed = false;
     this.reconnecting = false;

package/src/conversational-panel.ts

@@ -1,3 +1,5 @@
+import { requestMicrophone } from './browser-audio';
+
 const PANEL_CSS = /*css*/ `
   .cv-panel {
     position: relative;
@@ -102,6 +104,22 @@ const PANEL_CSS = /*css*/ `
     margin-bottom: auto;
     padding-top: 1.5rem;
   }
+  .cv-countdown, .cv-note {
+    display: none;
+    margin-top: 0.4rem;
+    padding: 0.15rem 0.6rem;
+    border-radius: 999px;
+    border: 1px solid var(--cv-ui-border, rgba(255,255,255,0.1));
+    background: var(--cv-ui-bg, rgba(255,255,255,0.05));
+    color: var(--cv-text-dim, rgba(255,255,255,0.6));
+    font-size: 0.75rem;
+    font-variant-numeric: tabular-nums;
+    width: fit-content;
+    margin-left: auto;
+    margin-right: auto;
+  }
+  .cv-countdown.is-visible, .cv-note.is-visible { display: block; }
+  .cv-countdown.is-low { color: var(--cv-accent); border-color: var(--cv-accent); }
   .cv-title {
     font-size: clamp(1rem, 2.5vw, 1.75rem);
     font-weight: 700;
@@ -333,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;
@@ -349,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;
@@ -375,6 +411,11 @@ export class ConversationalPanel {
   private muteSvg!: SVGElement;
   private stopBtn!: HTMLElement;
   private visualizerWrap!: HTMLElement;
+  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;
@@ -383,6 +424,12 @@ export class ConversationalPanel {
   onStop?: () => void;
   onError?: (err: any) => void;
   onToolCall?: (tool: any) => void;
+  /**
+   * The call ended without the visitor pressing End: a time limit, the silence timeout, the server
+   * closing the session, or the connection being lost. Receives the message the panel shows, so a
+   * page that renders its own chrome (and hides this panel's curtain) can show it too.
+   */
+  onEnded?: (message: string) => void;
 
   constructor(cfg: ConversationalPanelConfig) {
     this.cfg = cfg;
@@ -427,6 +474,8 @@ export class ConversationalPanel {
       </div>
       <div class="cv-header">
         <h2 class="cv-title">${this.esc(this.cfg.title || "Voice Chat")}</h2>
+        <div class="cv-countdown" aria-live="off"></div>
+        <div class="cv-note" role="status"></div>
       </div>
       <div class="cv-visualizer-wrap">
         <canvas class="cv-canvas"></canvas>
@@ -465,6 +514,8 @@ export class ConversationalPanel {
     this.muteSvg = this.muteBtn.querySelector('svg')!;
     this.stopBtn = this.el.querySelector('.cv-btn--end')!;
     this.visualizerWrap = this.el.querySelector('.cv-visualizer-wrap')!;
+    this.countdownEl = this.el.querySelector('.cv-countdown')!;
+    this.noteEl = this.el.querySelector('.cv-note')!;
 
     // Events
     this.startBtn.addEventListener('click', () => this.start());
@@ -478,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();
@@ -523,7 +585,15 @@ export class ConversationalPanel {
           this.el.classList.remove('cv-is-speaking', 'cv-is-thinking');
           if (status === 'speaking') this.el.classList.add('cv-is-speaking');
           else if (status === 'thinking') this.el.classList.add('cv-is-thinking');
+          // A dropped connection is retried by the client; say so instead of looking live.
+          this.setNote(status === 'reconnecting' ? 'Reconnecting…' : '');
+          // The client gave up, or the server ended the session: the call is over. Never leave a
+          // panel that looks live while nothing can answer.
+          if (status === 'disconnected' && this.isRunning) {
+            this.end('The call has ended.');
+          }
         },
+        onSessionLimit: (seconds: number) => this.startCountdown(seconds),
         onTranscription: (text: string) => {
           this._lastSpeechTime = Date.now();
           this.onTranscription?.(text);
@@ -538,9 +608,15 @@ export class ConversationalPanel {
         onError: (err: any) => {
           if (!this.isRunning) return;
           this.onError?.(err);
-          this.stop();
-          this.showError('Connection issue. Try again in a moment.');
-        }
+          // 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 === '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;
@@ -551,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
@@ -565,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;
     }
@@ -593,7 +674,14 @@ 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('');
     if (this.visualizer) { this.visualizer.stop(); this.visualizer = null; }
     this.curtain.classList.remove('is-up');
     this.el.classList.remove('cv-is-speaking', 'cv-is-thinking');
@@ -683,6 +771,39 @@ export class ConversationalPanel {
     }, 5000);
   }
 
+  /** End the call for a reason other than the End button, and say why. */
+  private end(message: string) {
+    this.stop();
+    this.showError(message);
+    this.onEnded?.(message);
+  }
+
+  /** Show how long the session may still run, as announced by the server. */
+  private startCountdown(seconds: number) {
+    this.stopCountdown();
+    const endsAt = Date.now() + seconds * 1000;
+    const render = () => {
+      const left = Math.max(0, Math.round((endsAt - Date.now()) / 1000));
+      this.countdownEl.textContent = `${Math.floor(left / 60)}:${String(left % 60).padStart(2, '0')} left`;
+      this.countdownEl.classList.toggle('is-low', left <= 30);
+      if (left === 0) this.stopCountdown(false);
+    };
+    this.countdownEl.classList.add('is-visible');
+    render();
+    this.countdownTicker = window.setInterval(render, 1000);
+  }
+
+  private stopCountdown(hide = true) {
+    if (this.countdownTicker) { clearInterval(this.countdownTicker); this.countdownTicker = null; }
+    if (hide) this.countdownEl?.classList.remove('is-visible', 'is-low');
+  }
+
+  private setNote(text: string) {
+    if (!this.noteEl) return;
+    this.noteEl.textContent = text;
+    this.noteEl.classList.toggle('is-visible', Boolean(text));
+  }
+
   /** Destroy the component, removing all DOM and stopping any active session */
   destroy() {
     this.stop();
@@ -703,15 +824,13 @@ export class ConversationalPanel {
 
       if (elapsed >= maxDur) {
         this._locked = true;
-        this.stop();
-        this.showError('Tiempo límite alcanzado.');
+        this.end('Time limit reached.');
         return;
       }
 
       if (Date.now() - this._lastSpeechTime > silentMax * 1000) {
         this._locked = true;
-        this.stop();
-        this.showError('Sesión finalizada por inactividad.');
+        this.end('The call ended after a long silence.');
       }
     }, 1000);
   }

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

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