@lokutor/sdk 1.4.1 → 1.5.1

package/dist/index.mjs

@@ -79,6 +79,8 @@ function isRetryableCode(code) {
     "auth.missing_key",
     "auth.invalid_key",
     "auth.time_limited",
+    "session.ended",
+    "audio.microphone_unavailable",
     "validation.invalid_voice",
     "validation.invalid_language",
     "validation.text_too_long",
@@ -233,6 +235,36 @@ var StreamResampler = class {
 };
 
 // src/browser-audio.ts
+function requestMicrophone(constraints = {}) {
+  if (typeof navigator === "undefined") {
+    return Promise.reject(new Error("Microphone capture needs a browser"));
+  }
+  const session = navigator.audioSession;
+  if (session && session.type !== "auto" && session.type !== "play-and-record") {
+    try {
+      session.type = "auto";
+    } catch (_) {
+    }
+  }
+  if (!navigator.mediaDevices?.getUserMedia) {
+    return Promise.reject(new Error("Microphone capture is not available here (it needs HTTPS)"));
+  }
+  return navigator.mediaDevices.getUserMedia({
+    audio: {
+      autoGainControl: constraints.autoGainControl ?? true,
+      echoCancellation: constraints.echoCancellation ?? true,
+      noiseSuppression: constraints.noiseSuppression ?? true
+    }
+  });
+}
+async function resumeWithin(ctx, ms) {
+  if (ctx.state === "running") return;
+  await Promise.race([
+    ctx.resume().catch(() => {
+    }),
+    new Promise((r) => setTimeout(r, ms))
+  ]);
+}
 var BrowserAudioManager = class {
   audioContext = null;
   mediaStreamAudioSourceNode = null;
@@ -254,6 +286,12 @@ var BrowserAudioManager = class {
   autoGainControl;
   echoCancellation;
   noiseSuppression;
+  keepAwake;
+  providedMicrophone;
+  // Screen wake lock, held while the microphone is live. Browsers release it whenever the page is
+  // hidden, so it is taken again when the page becomes visible.
+  wakeLock = null;
+  visibilityHandler = null;
   // Callbacks
   onAudioInput;
   onInputError;
@@ -266,6 +304,10 @@ var BrowserAudioManager = class {
     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;
+    if (this.providedMicrophone instanceof Promise) this.providedMicrophone.catch(() => {
+    });
     this.onInputError = config.onInputError;
   }
   /**
@@ -281,9 +323,8 @@ var BrowserAudioManager = class {
     if (!this.audioContext) {
       throw new Error("Failed to initialize AudioContext");
     }
-    if (this.audioContext.state === "suspended") {
-      await this.audioContext.resume();
-      console.log("\u{1F442} AudioContext resumed");
+    if (this.audioContext.state !== "running") {
+      await resumeWithin(this.audioContext, 500);
     }
     if (analyserConfig?.enabled !== false) {
       this.analyserNode = this.audioContext.createAnalyser();
@@ -297,10 +338,17 @@ 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;
-      this.mediaStream = await navigator.mediaDevices.getUserMedia({
+      const provided = this.providedMicrophone;
+      this.providedMicrophone = null;
+      const stream = provided ? await provided : null;
+      this.mediaStream = stream && stream.getAudioTracks().some((t) => t.readyState === "live") ? stream : await navigator.mediaDevices.getUserMedia({
         audio: {
           autoGainControl: this.autoGainControl,
           echoCancellation: this.echoCancellation,
@@ -331,7 +379,9 @@ var BrowserAudioManager = class {
         this._processAudioInput(event);
       };
       console.log("\u{1F3A4} Microphone started");
+      this.holdScreenAwake();
     } catch (error) {
+      this.isListening = false;
       const err = error instanceof Error ? error : new Error(String(error));
       if (this.onInputError) this.onInputError(err);
       throw err;
@@ -369,6 +419,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 +434,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
@@ -518,6 +616,13 @@ var BrowserAudioManager = class {
       this.analyserNode.disconnect();
       this.analyserNode = null;
     }
+    if (this.audioContext) {
+      const ctx = this.audioContext;
+      this.audioContext = null;
+      this.nextPlaybackTime = 0;
+      ctx.close().catch(() => {
+      });
+    }
   }
   /**
    * Get current audio context state
@@ -582,6 +687,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 +767,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 +840,35 @@ 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) {
-            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) {
+              const name = e?.name || "Error";
+              const error = new LokutorError(
+                "audio.microphone_unavailable",
+                name === "NotAllowedError" || name === "SecurityError" ? "Microphone access was not allowed." : "The microphone could not be started.",
+                { detail: `${name}: ${e?.message ?? e}`, original: e, retryable: false }
+              );
+              sdkTrace("mic.failed", { name });
+              settle(() => reject(error));
+              this.isUserDisconnect = true;
+              try {
+                this.ws?.close();
+              } catch (_) {
               }
-            });
+              this.emit("error", error);
+              return;
+            }
+            this.micStarted = true;
           }
           settle(() => resolve(true));
         };
@@ -790,6 +919,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++;
@@ -979,11 +1119,18 @@ var VoiceAgentClient = class {
             detail: backendDetail,
             retryable: backendRetryable
           });
-          if (this.onError) this.onError(error);
           this.emit("error", error);
           console.error(`\u274C Server error: [${error.code}] ${error.message}`);
           break;
         }
+        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 +1204,7 @@ var VoiceAgentClient = class {
     if (this.audioManager) {
       this.audioManager.cleanup();
     }
+    this.micStarted = false;
     this.isConnected = false;
     this.configConfirmed = false;
     this.reconnecting = false;
@@ -1706,6 +1854,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;
@@ -1916,6 +2080,17 @@ function injectStyles() {
   document.head.appendChild(style);
   styleInjected = true;
 }
+function microphoneMessage(err) {
+  const name = String(err?.original?.name ?? err?.name ?? "");
+  const detail = String(err?.detail ?? err?.message ?? "");
+  if (/NotAllowedError|SecurityError/.test(name + " " + detail)) {
+    return "Microphone access is blocked. Allow it for this site in your browser settings, then try again.";
+  }
+  if (/NotFoundError|OverconstrainedError/.test(name + " " + detail)) {
+    return "No microphone was found on this device.";
+  }
+  return "The microphone could not start. Please try again.";
+}
 var ConversationalPanel = class {
   cfg;
   container;
@@ -1942,6 +2117,11 @@ var ConversationalPanel = class {
   muteSvg;
   stopBtn;
   visualizerWrap;
+  countdownEl;
+  noteEl;
+  countdownTicker = null;
+  microphone = null;
+  micError = null;
   // Callbacks
   onTranscription;
   onResponse;
@@ -1949,6 +2129,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 +2175,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 +2212,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());
@@ -2033,14 +2223,23 @@ var ConversationalPanel = class {
     d.textContent = s;
     return d.innerHTML;
   }
-  /** Start the conversation (called when user clicks "Start Conversation" or externally) */
+  /**
+   * Start the conversation (called when user clicks "Start Conversation" or externally). Call it from
+   * inside the click or tap, before any await: it asks for the microphone there. Resolves true once the
+   * call is live, false when it could not start (the reason is shown, and passed to onError).
+   */
   async start() {
-    if (this.isRunning) return;
+    if (this.isRunning) return false;
     if (this._locked) {
       this.showError("This session has ended. Refresh the page to start a new one.");
-      return;
+      return false;
     }
     this.isRunning = true;
+    this.microphone = requestMicrophone();
+    this.micError = null;
+    this.microphone.catch((e) => {
+      this.micError = e;
+    });
     this.startBtn.disabled = true;
     this.errorEl.classList.remove("is-visible");
     this.playConnectingSound();
@@ -2071,7 +2270,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,9 +2290,9 @@ 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 === "audio.microphone_unavailable" ? microphoneMessage(err) : err?.code === "session.ended" && err?.message ? err.message : "Connection issue. Try again in a moment.");
+        },
+        microphone: this.microphone
       });
       this.agent = agentHandle;
       visualizer.setAudioClient(agentHandle);
@@ -2098,6 +2302,7 @@ var ConversationalPanel = class {
       } catch (_) {
       }
       const ok = await agentHandle.connect();
+      if (!this.isRunning) return false;
       if (ok) {
         this.fadeOutConnectingSound();
         const wrap = this.visualizerWrap;
@@ -2111,19 +2316,21 @@ var ConversationalPanel = class {
         this.startTimer();
         this.onStart?.();
         if (window.lucide) window.lucide.createIcons();
-      } else {
-        this.fadeOutConnectingSound();
-        this.playErrorTone();
-        this.curtain.classList.remove("is-up");
-        this.showError("Could not connect. Please try again.");
-        this.isRunning = false;
+        return true;
       }
+      this.fadeOutConnectingSound();
+      this.playErrorTone();
+      const micError = this.micError;
+      this.stop();
+      this.showError(micError ? microphoneMessage(micError) : "Could not connect. Please try again.");
+      return false;
     } catch (err) {
       this.fadeOutConnectingSound();
       this.playErrorTone();
       console.error("ConversationalPanel start error:", err);
       this.stop();
       this.showError("Something went wrong. Please try again.");
+      return false;
     } finally {
       this.startBtn.disabled = false;
     }
@@ -2141,10 +2348,16 @@ var ConversationalPanel = class {
       }
       this.agent = null;
     }
+    const mic = this.microphone;
+    this.microphone = null;
+    mic?.then((s) => s.getTracks().forEach((t) => t.stop()), () => {
+    });
     if (this.timerTicker) {
       clearInterval(this.timerTicker);
       this.timerTicker = null;
     }
+    this.stopCountdown();
+    this.setNote("");
     if (this.visualizer) {
       this.visualizer.stop();
       this.visualizer = null;
@@ -2220,6 +2433,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 +2480,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);
   }
@@ -2332,9 +2575,11 @@ export {
   calculateRMS,
   float32ToPcm16,
   isRetryable,
+  microphoneMessage,
   normalizeAudio,
   pcm16ToBytes,
   pcm16ToFloat32,
+  requestMicrophone,
   resample,
   resampleWithAntiAliasing,
   simpleConversation,

package/package.json

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