@lokutor/sdk 1.4.0 → 1.5.0

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' | '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' | 'internal.error' | 'internal.timeout' | 'internal.cancelled' | 'ws.close';
 /**
  * Typed error class for all Lokutor SDK errors.
  * Includes the backend error code, human-readable message,
@@ -325,6 +325,13 @@ interface AudioManager {
     setMuted(muted: boolean): void;
     getAmplitude(): number;
 }
+/** What the server announced about how long this session may run (landing-page demo sessions). */
+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;
+}
 /**
  * Main client for Lokutor Voice Agent SDK
  *
@@ -358,6 +365,7 @@ declare class VoiceAgentClient {
     private reconnectAttempts;
     private maxReconnectAttempts;
     private reconnectTimer;
+    private micStarted;
     private serverPlaybackRate;
     private serverInputRate;
     private serverUrl;
@@ -685,6 +693,12 @@ 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;
     onInputError?: (error: Error) => void;
 }
 /**
@@ -714,6 +728,9 @@ declare class BrowserAudioManager {
     private autoGainControl;
     private echoCancellation;
     private noiseSuppression;
+    private keepAwake;
+    private wakeLock;
+    private visibilityHandler;
     private onAudioInput?;
     private onInputError?;
     private isMuted;
@@ -735,6 +752,13 @@ declare class BrowserAudioManager {
      * Stop capturing microphone input
      */
     stopMicrophone(): void;
+    /**
+     * 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;
+    private requestWakeLock;
+    private releaseScreenAwake;
     /**
      * Play back audio received from the server
      * @param pcm16Data Int16 PCM audio data at SPEAKER_SAMPLE_RATE
@@ -865,12 +889,21 @@ declare class ConversationalPanel {
     private muteSvg;
     private stopBtn;
     private visualizerWrap;
+    private countdownEl;
+    private noteEl;
+    private countdownTicker;
     onTranscription?: (text: string) => void;
     onResponse?: (text: string) => void;
     onStart?: () => void;
     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);
     private buildDOM;
     private esc;
@@ -893,6 +926,12 @@ declare class ConversationalPanel {
     setTools(tools: any[]): void;
     /** Show an error message */
     showError(text: string): void;
+    /** End the call for a reason other than the End button, and say why. */
+    private end;
+    /** Show how long the session may still run, as announced by the server. */
+    private startCountdown;
+    private stopCountdown;
+    private setNote;
     /** Destroy the component, removing all DOM and stopping any active session */
     destroy(): void;
     private startTimer;
@@ -902,4 +941,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, 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, normalizeAudio, pcm16ToBytes, pcm16ToFloat32, 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' | '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' | 'internal.error' | 'internal.timeout' | 'internal.cancelled' | 'ws.close';
 /**
  * Typed error class for all Lokutor SDK errors.
  * Includes the backend error code, human-readable message,
@@ -325,6 +325,13 @@ interface AudioManager {
     setMuted(muted: boolean): void;
     getAmplitude(): number;
 }
+/** What the server announced about how long this session may run (landing-page demo sessions). */
+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;
+}
 /**
  * Main client for Lokutor Voice Agent SDK
  *
@@ -358,6 +365,7 @@ declare class VoiceAgentClient {
     private reconnectAttempts;
     private maxReconnectAttempts;
     private reconnectTimer;
+    private micStarted;
     private serverPlaybackRate;
     private serverInputRate;
     private serverUrl;
@@ -685,6 +693,12 @@ 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;
     onInputError?: (error: Error) => void;
 }
 /**
@@ -714,6 +728,9 @@ declare class BrowserAudioManager {
     private autoGainControl;
     private echoCancellation;
     private noiseSuppression;
+    private keepAwake;
+    private wakeLock;
+    private visibilityHandler;
     private onAudioInput?;
     private onInputError?;
     private isMuted;
@@ -735,6 +752,13 @@ declare class BrowserAudioManager {
      * Stop capturing microphone input
      */
     stopMicrophone(): void;
+    /**
+     * 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;
+    private requestWakeLock;
+    private releaseScreenAwake;
     /**
      * Play back audio received from the server
      * @param pcm16Data Int16 PCM audio data at SPEAKER_SAMPLE_RATE
@@ -865,12 +889,21 @@ declare class ConversationalPanel {
     private muteSvg;
     private stopBtn;
     private visualizerWrap;
+    private countdownEl;
+    private noteEl;
+    private countdownTicker;
     onTranscription?: (text: string) => void;
     onResponse?: (text: string) => void;
     onStart?: () => void;
     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);
     private buildDOM;
     private esc;
@@ -893,6 +926,12 @@ declare class ConversationalPanel {
     setTools(tools: any[]): void;
     /** Show an error message */
     showError(text: string): void;
+    /** End the call for a reason other than the End button, and say why. */
+    private end;
+    /** Show how long the session may still run, as announced by the server. */
+    private startCountdown;
+    private stopCountdown;
+    private setNote;
     /** Destroy the component, removing all DOM and stopping any active session */
     destroy(): void;
     private startTimer;
@@ -902,4 +941,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, 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, normalizeAudio, pcm16ToBytes, pcm16ToFloat32, resample, resampleWithAntiAliasing, simpleConversation, simpleTTS, simpleTranscribe };

package/dist/index.js

@@ -130,6 +130,7 @@ function isRetryableCode(code) {
     "auth.missing_key",
     "auth.invalid_key",
     "auth.time_limited",
+    "session.ended",
     "validation.invalid_voice",
     "validation.invalid_language",
     "validation.text_too_long",
@@ -305,6 +306,11 @@ var BrowserAudioManager = class {
   autoGainControl;
   echoCancellation;
   noiseSuppression;
+  keepAwake;
+  // 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;
+  visibilityHandler = null;
   // Callbacks
   onAudioInput;
   onInputError;
@@ -317,6 +323,7 @@ var BrowserAudioManager = class {
     this.autoGainControl = config.autoGainControl ?? true;
     this.echoCancellation = config.echoCancellation ?? true;
     this.noiseSuppression = config.noiseSuppression ?? true;
+    this.keepAwake = config.keepAwake ?? true;
     this.onInputError = config.onInputError;
   }
   /**
@@ -348,6 +355,10 @@ var BrowserAudioManager = class {
     if (!this.audioContext) {
       await this.init();
     }
+    if (this.isListening && this.mediaStream) {
+      this.onAudioInput = onAudioInput;
+      return;
+    }
     try {
       this.onAudioInput = onAudioInput;
       this.isListening = true;
@@ -382,6 +393,7 @@ var BrowserAudioManager = class {
         this._processAudioInput(event);
       };
       console.log("\u{1F3A4} Microphone started");
+      this.holdScreenAwake();
     } catch (error) {
       const err = error instanceof Error ? error : new Error(String(error));
       if (this.onInputError) this.onInputError(err);
@@ -420,6 +432,7 @@ var BrowserAudioManager = class {
    */
   stopMicrophone() {
     this.isListening = false;
+    this.releaseScreenAwake();
     if (this.mediaStream) {
       this.mediaStream.getTracks().forEach((track) => track.stop());
       this.mediaStream = null;
@@ -434,6 +447,53 @@ var BrowserAudioManager = class {
     }
     console.log("\u{1F3A4} 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).
+   */
+  holdScreenAwake() {
+    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();
+  }
+  async requestWakeLock() {
+    if (!this.keepAwake || this.wakeLock || typeof navigator === "undefined") return;
+    const api = navigator.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;
+      lock.addEventListener?.("release", () => {
+        if (this.wakeLock === lock) this.wakeLock = null;
+      });
+    } catch (_) {
+    }
+  }
+  releaseScreenAwake() {
+    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
@@ -633,6 +693,7 @@ async function fetchJson(url, timeoutMs = 1e4) {
     });
   }
 }
+var RECONNECTABLE_CLOSE_CODES = /* @__PURE__ */ new Set([1001, 1006, 1011, 1012, 1013, 1014]);
 function base64ToUint8Array(base64) {
   const binaryString = atob(base64);
   const bytes = new Uint8Array(binaryString.length);
@@ -712,6 +773,9 @@ var VoiceAgentClient = class {
   reconnectAttempts = 0;
   maxReconnectAttempts = 5;
   reconnectTimer = 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.
+  micStarted = false;
   // Runtime state
   serverPlaybackRate = 44100;
   serverInputRate = 16e3;
@@ -782,15 +846,17 @@ var VoiceAgentClient = class {
           this.isConnected = true;
           this.reconnectAttempts = 0;
           this.reconnecting = false;
+          this.currentGeneration = 0;
           console.log("\u2705 Connected to voice agent!");
           sdkTrace("ws.open");
           this.sendConfig();
-          if (this.audioManager) {
+          if (this.audioManager && !this.micStarted) {
             await this.audioManager.startMicrophone((data) => {
               if (this.isConnected) {
                 this.sendAudio(data);
               }
             });
+            this.micStarted = true;
           }
           settle(() => resolve(true));
         };
@@ -841,6 +907,17 @@ var VoiceAgentClient = class {
             console.error("   URL:", this.serverUrl.replace(/api_key=[^&]+/, "api_key=***"));
           }
           console.log(`\u{1F50C} WebSocket closed \u2014 code: ${event.code}, reason: "${event.reason || "none"}", clean: ${event.wasClean}`);
+          if (!this.isUserDisconnect && !RECONNECTABLE_CLOSE_CODES.has(event.code)) {
+            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++;
@@ -1035,6 +1112,14 @@ var VoiceAgentClient = class {
           console.error(`\u274C Server error: [${error.code}] ${error.message}`);
           break;
         }
+        case "session_limit": {
+          const seconds = Number(msg.data?.seconds ?? msg.seconds);
+          if (Number.isFinite(seconds) && seconds >= 0) {
+            const limit = { 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(`\u{1F6E0}\uFE0F Tool Call: ${msg.name}(${msg.arguments})`);
@@ -1108,6 +1193,7 @@ var VoiceAgentClient = class {
     if (this.audioManager) {
       this.audioManager.cleanup();
     }
+    this.micStarted = false;
     this.isConnected = false;
     this.configConfirmed = false;
     this.reconnecting = false;
@@ -1757,6 +1843,22 @@ var PANEL_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;
@@ -1993,6 +2095,9 @@ var ConversationalPanel = class {
   muteSvg;
   stopBtn;
   visualizerWrap;
+  countdownEl;
+  noteEl;
+  countdownTicker = null;
   // Callbacks
   onTranscription;
   onResponse;
@@ -2000,6 +2105,12 @@ var ConversationalPanel = class {
   onStop;
   onError;
   onToolCall;
+  /**
+   * 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;
   constructor(cfg) {
     this.cfg = cfg;
     this.container = cfg.container;
@@ -2040,6 +2151,8 @@ var ConversationalPanel = class {
       </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>
@@ -2075,6 +2188,8 @@ var ConversationalPanel = class {
     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");
     this.startBtn.addEventListener("click", () => this.start());
     this.stopBtn.addEventListener("click", () => this.stop());
     this.muteBtn.addEventListener("click", () => this.toggleMute());
@@ -2122,7 +2237,12 @@ var ConversationalPanel = class {
           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");
+          this.setNote(status === "reconnecting" ? "Reconnecting\u2026" : "");
+          if (status === "disconnected" && this.isRunning) {
+            this.end("The call has ended.");
+          }
         },
+        onSessionLimit: (seconds) => this.startCountdown(seconds),
         onTranscription: (text) => {
           this._lastSpeechTime = Date.now();
           this.onTranscription?.(text);
@@ -2137,8 +2257,7 @@ var ConversationalPanel = class {
         onError: (err) => {
           if (!this.isRunning) return;
           this.onError?.(err);
-          this.stop();
-          this.showError("Connection issue. Try again in a moment.");
+          this.end(err?.code === "session.ended" && err?.message ? err.message : "Connection issue. Try again in a moment.");
         }
       });
       this.agent = agentHandle;
@@ -2196,6 +2315,8 @@ var ConversationalPanel = class {
       clearInterval(this.timerTicker);
       this.timerTicker = null;
     }
+    this.stopCountdown();
+    this.setNote("");
     if (this.visualizer) {
       this.visualizer.stop();
       this.visualizer = null;
@@ -2271,6 +2392,38 @@ var ConversationalPanel = class {
       this.errorEl.classList.remove("is-visible");
     }, 5e3);
   }
+  /** End the call for a reason other than the End button, and say why. */
+  end(message) {
+    this.stop();
+    this.showError(message);
+    this.onEnded?.(message);
+  }
+  /** Show how long the session may still run, as announced by the server. */
+  startCountdown(seconds) {
+    this.stopCountdown();
+    const endsAt = Date.now() + seconds * 1e3;
+    const render = () => {
+      const left = Math.max(0, Math.round((endsAt - Date.now()) / 1e3));
+      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, 1e3);
+  }
+  stopCountdown(hide = true) {
+    if (this.countdownTicker) {
+      clearInterval(this.countdownTicker);
+      this.countdownTicker = null;
+    }
+    if (hide) this.countdownEl?.classList.remove("is-visible", "is-low");
+  }
+  setNote(text) {
+    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();
@@ -2286,14 +2439,12 @@ var ConversationalPanel = class {
       elapsed++;
       if (elapsed >= maxDur) {
         this._locked = true;
-        this.stop();
-        this.showError("Tiempo l\xEDmite alcanzado.");
+        this.end("Time limit reached.");
         return;
       }
       if (Date.now() - this._lastSpeechTime > silentMax * 1e3) {
         this._locked = true;
-        this.stop();
-        this.showError("Sesi\xF3n finalizada por inactividad.");
+        this.end("The call ended after a long silence.");
       }
     }, 1e3);
   }

package/dist/index.mjs

@@ -79,6 +79,7 @@ function isRetryableCode(code) {
     "auth.missing_key",
     "auth.invalid_key",
     "auth.time_limited",
+    "session.ended",
     "validation.invalid_voice",
     "validation.invalid_language",
     "validation.text_too_long",
@@ -254,6 +255,11 @@ var BrowserAudioManager = class {
   autoGainControl;
   echoCancellation;
   noiseSuppression;
+  keepAwake;
+  // 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;
+  visibilityHandler = null;
   // Callbacks
   onAudioInput;
   onInputError;
@@ -266,6 +272,7 @@ var BrowserAudioManager = class {
     this.autoGainControl = config.autoGainControl ?? true;
     this.echoCancellation = config.echoCancellation ?? true;
     this.noiseSuppression = config.noiseSuppression ?? true;
+    this.keepAwake = config.keepAwake ?? true;
     this.onInputError = config.onInputError;
   }
   /**
@@ -297,6 +304,10 @@ var BrowserAudioManager = class {
     if (!this.audioContext) {
       await this.init();
     }
+    if (this.isListening && this.mediaStream) {
+      this.onAudioInput = onAudioInput;
+      return;
+    }
     try {
       this.onAudioInput = onAudioInput;
       this.isListening = true;
@@ -331,6 +342,7 @@ var BrowserAudioManager = class {
         this._processAudioInput(event);
       };
       console.log("\u{1F3A4} Microphone started");
+      this.holdScreenAwake();
     } catch (error) {
       const err = error instanceof Error ? error : new Error(String(error));
       if (this.onInputError) this.onInputError(err);
@@ -369,6 +381,7 @@ var BrowserAudioManager = class {
    */
   stopMicrophone() {
     this.isListening = false;
+    this.releaseScreenAwake();
     if (this.mediaStream) {
       this.mediaStream.getTracks().forEach((track) => track.stop());
       this.mediaStream = null;
@@ -383,6 +396,53 @@ var BrowserAudioManager = class {
     }
     console.log("\u{1F3A4} 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).
+   */
+  holdScreenAwake() {
+    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();
+  }
+  async requestWakeLock() {
+    if (!this.keepAwake || this.wakeLock || typeof navigator === "undefined") return;
+    const api = navigator.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;
+      lock.addEventListener?.("release", () => {
+        if (this.wakeLock === lock) this.wakeLock = null;
+      });
+    } catch (_) {
+    }
+  }
+  releaseScreenAwake() {
+    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
@@ -582,6 +642,7 @@ async function fetchJson(url, timeoutMs = 1e4) {
     });
   }
 }
+var RECONNECTABLE_CLOSE_CODES = /* @__PURE__ */ new Set([1001, 1006, 1011, 1012, 1013, 1014]);
 function base64ToUint8Array(base64) {
   const binaryString = atob(base64);
   const bytes = new Uint8Array(binaryString.length);
@@ -661,6 +722,9 @@ var VoiceAgentClient = class {
   reconnectAttempts = 0;
   maxReconnectAttempts = 5;
   reconnectTimer = 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.
+  micStarted = false;
   // Runtime state
   serverPlaybackRate = 44100;
   serverInputRate = 16e3;
@@ -731,15 +795,17 @@ var VoiceAgentClient = class {
           this.isConnected = true;
           this.reconnectAttempts = 0;
           this.reconnecting = false;
+          this.currentGeneration = 0;
           console.log("\u2705 Connected to voice agent!");
           sdkTrace("ws.open");
           this.sendConfig();
-          if (this.audioManager) {
+          if (this.audioManager && !this.micStarted) {
             await this.audioManager.startMicrophone((data) => {
               if (this.isConnected) {
                 this.sendAudio(data);
               }
             });
+            this.micStarted = true;
           }
           settle(() => resolve(true));
         };
@@ -790,6 +856,17 @@ var VoiceAgentClient = class {
             console.error("   URL:", this.serverUrl.replace(/api_key=[^&]+/, "api_key=***"));
           }
           console.log(`\u{1F50C} WebSocket closed \u2014 code: ${event.code}, reason: "${event.reason || "none"}", clean: ${event.wasClean}`);
+          if (!this.isUserDisconnect && !RECONNECTABLE_CLOSE_CODES.has(event.code)) {
+            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++;
@@ -984,6 +1061,14 @@ var VoiceAgentClient = class {
           console.error(`\u274C Server error: [${error.code}] ${error.message}`);
           break;
         }
+        case "session_limit": {
+          const seconds = Number(msg.data?.seconds ?? msg.seconds);
+          if (Number.isFinite(seconds) && seconds >= 0) {
+            const limit = { 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(`\u{1F6E0}\uFE0F Tool Call: ${msg.name}(${msg.arguments})`);
@@ -1057,6 +1142,7 @@ var VoiceAgentClient = class {
     if (this.audioManager) {
       this.audioManager.cleanup();
     }
+    this.micStarted = false;
     this.isConnected = false;
     this.configConfirmed = false;
     this.reconnecting = false;
@@ -1706,6 +1792,22 @@ var PANEL_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;
@@ -1942,6 +2044,9 @@ var ConversationalPanel = class {
   muteSvg;
   stopBtn;
   visualizerWrap;
+  countdownEl;
+  noteEl;
+  countdownTicker = null;
   // Callbacks
   onTranscription;
   onResponse;
@@ -1949,6 +2054,12 @@ var ConversationalPanel = class {
   onStop;
   onError;
   onToolCall;
+  /**
+   * 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;
   constructor(cfg) {
     this.cfg = cfg;
     this.container = cfg.container;
@@ -1989,6 +2100,8 @@ var ConversationalPanel = class {
       </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>
@@ -2024,6 +2137,8 @@ var ConversationalPanel = class {
     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");
     this.startBtn.addEventListener("click", () => this.start());
     this.stopBtn.addEventListener("click", () => this.stop());
     this.muteBtn.addEventListener("click", () => this.toggleMute());
@@ -2071,7 +2186,12 @@ var ConversationalPanel = class {
           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");
+          this.setNote(status === "reconnecting" ? "Reconnecting\u2026" : "");
+          if (status === "disconnected" && this.isRunning) {
+            this.end("The call has ended.");
+          }
         },
+        onSessionLimit: (seconds) => this.startCountdown(seconds),
         onTranscription: (text) => {
           this._lastSpeechTime = Date.now();
           this.onTranscription?.(text);
@@ -2086,8 +2206,7 @@ var ConversationalPanel = class {
         onError: (err) => {
           if (!this.isRunning) return;
           this.onError?.(err);
-          this.stop();
-          this.showError("Connection issue. Try again in a moment.");
+          this.end(err?.code === "session.ended" && err?.message ? err.message : "Connection issue. Try again in a moment.");
         }
       });
       this.agent = agentHandle;
@@ -2145,6 +2264,8 @@ var ConversationalPanel = class {
       clearInterval(this.timerTicker);
       this.timerTicker = null;
     }
+    this.stopCountdown();
+    this.setNote("");
     if (this.visualizer) {
       this.visualizer.stop();
       this.visualizer = null;
@@ -2220,6 +2341,38 @@ var ConversationalPanel = class {
       this.errorEl.classList.remove("is-visible");
     }, 5e3);
   }
+  /** End the call for a reason other than the End button, and say why. */
+  end(message) {
+    this.stop();
+    this.showError(message);
+    this.onEnded?.(message);
+  }
+  /** Show how long the session may still run, as announced by the server. */
+  startCountdown(seconds) {
+    this.stopCountdown();
+    const endsAt = Date.now() + seconds * 1e3;
+    const render = () => {
+      const left = Math.max(0, Math.round((endsAt - Date.now()) / 1e3));
+      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, 1e3);
+  }
+  stopCountdown(hide = true) {
+    if (this.countdownTicker) {
+      clearInterval(this.countdownTicker);
+      this.countdownTicker = null;
+    }
+    if (hide) this.countdownEl?.classList.remove("is-visible", "is-low");
+  }
+  setNote(text) {
+    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();
@@ -2235,14 +2388,12 @@ var ConversationalPanel = class {
       elapsed++;
       if (elapsed >= maxDur) {
         this._locked = true;
-        this.stop();
-        this.showError("Tiempo l\xEDmite alcanzado.");
+        this.end("Time limit reached.");
         return;
       }
       if (Date.now() - this._lastSpeechTime > silentMax * 1e3) {
         this._locked = true;
-        this.stop();
-        this.showError("Sesi\xF3n finalizada por inactividad.");
+        this.end("The call ended after a long silence.");
       }
     }, 1e3);
   }

package/package.json

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

package/src/browser-audio.ts

@@ -10,6 +10,12 @@ 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;
   onInputError?: (error: Error) => void;
 }
 
@@ -48,6 +54,12 @@ export class BrowserAudioManager {
   private autoGainControl: boolean;
   private echoCancellation: boolean;
   private noiseSuppression: boolean;
+  private keepAwake: boolean;
+
+  // 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 +75,7 @@ export class BrowserAudioManager {
     this.autoGainControl = config.autoGainControl ?? true;
     this.echoCancellation = config.echoCancellation ?? true;
     this.noiseSuppression = config.noiseSuppression ?? true;
+    this.keepAwake = config.keepAwake ?? true;
     this.onInputError = config.onInputError;
   }
 
@@ -107,6 +120,14 @@ 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;
@@ -167,6 +188,7 @@ export class BrowserAudioManager {
       };
 
       console.log('🎤 Microphone started');
+      this.holdScreenAwake();
     } catch (error) {
       const err = error instanceof Error ? error : new Error(String(error));
       if (this.onInputError) this.onInputError(err);
@@ -226,6 +248,7 @@ export class BrowserAudioManager {
    */
   stopMicrophone(): void {
     this.isListening = false;
+    this.releaseScreenAwake();
 
     if (this.mediaStream) {
       this.mediaStream.getTracks().forEach((track) => track.stop());
@@ -245,6 +268,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

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,21 @@ 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) {
+          if (this.audioManager && !this.micStarted) {
             await this.audioManager.startMicrophone((data) => {
               if (this.isConnected) {
                 this.sendAudio(data);
               }
             });
+            this.micStarted = true;
           }
 
           settle(() => resolve(true));
@@ -352,6 +378,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++;
@@ -566,6 +605,17 @@ export class VoiceAgentClient {
           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 +698,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

@@ -102,6 +102,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;
@@ -375,6 +391,9 @@ export class ConversationalPanel {
   private muteSvg!: SVGElement;
   private stopBtn!: HTMLElement;
   private visualizerWrap!: HTMLElement;
+  private countdownEl!: HTMLElement;
+  private noteEl!: HTMLElement;
+  private countdownTicker: number | null = null;
 
   // Callbacks
   onTranscription?: (text: string) => void;
@@ -383,6 +402,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 +452,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 +492,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());
@@ -523,7 +552,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,8 +575,11 @@ 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 === 'session.ended' && err?.message
+            ? err.message
+            : 'Connection issue. Try again in a moment.');
         }
       });
 
@@ -594,6 +634,8 @@ export class ConversationalPanel {
       this.agent = null;
     }
     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 +725,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 +778,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/types.ts

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