@olares/lares-core 0.15.23 → 0.15.25

package/voice/pcm-player.js

@@ -56,7 +56,10 @@ export function createPcmStreamPlayer({ onProgress = () => {}, onMetric = () =>
         owned = false; context = null;
         throw error;
       }
-      node = new AudioWorkletNode(opened, "lares-pcm-player", { processorOptions: { inputRate: sampleRate }, numberOfInputs: 0, numberOfOutputs: 1, outputChannelCount: [1] });
+      node = new AudioWorkletNode(opened, "lares-pcm-player", {
+        processorOptions: { inputRate: sampleRate, outputRate: opened.sampleRate || sampleRate, preroll: Math.round(sampleRate * 0.2) },
+        numberOfInputs: 0, numberOfOutputs: 1, outputChannelCount: [1],
+      });
       node.port.onmessage = ({ data }) => {
         if (epoch !== generation) return;
         if (data.type === "progress") { played = data.frames; onProgress(played); }

package/voice/pcm-worklet.js

@@ -3,7 +3,10 @@ export const PCM_PLAYER_WORKLET = `
 class LaresPcmPlayer extends AudioWorkletProcessor {
   constructor(options) {
     super(); this.queue = []; this.offset = 0; this.frames = 0; this.reported = 0;
-    this.rate = options.processorOptions.inputRate; this.step = this.rate / sampleRate;
+    this.rate = options.processorOptions.inputRate;
+    const outputRate = options.processorOptions.outputRate || sampleRate;
+    this.step = this.rate / outputRate;
+    this.preroll = options.processorOptions.preroll || 0;
     this.paused = false; this.queued = 0; this.finished = false; this.started = false; this.starved = false;
     this.port.onmessage = ({ data }) => {
       if (data.type === 'audio') {
@@ -18,6 +21,8 @@ class LaresPcmPlayer extends AudioWorkletProcessor {
     const out = outputs[0][0];
     out.fill(0);
     if (this.paused) return true;
+    // A late first packet must not open a hole inside the first syllable.
+    if (!this.started && !this.finished && this.queued < this.preroll) return true;
     for (let i = 0; i < out.length; i++) {
       while (this.queue.length && this.offset >= this.queue[0].length) {
         const head = this.queue.shift(); this.offset -= head.length; this.queued -= head.length;

package/voice/presentation.js

@@ -6,26 +6,35 @@ export function voicePanelPresentation(view) {
   const preview = view.mode === "single" && ["preview", "processing"].includes(view.stage);
   const preparing = view.busy || capture === "recording" && view.snapshot?.inputReady === false;
   const recording = capture === "recording" && !preparing;
-  const reported = view.error || view.snapshot?.error;
-  // A muted call is not a listen session. "Resume to listen again" is the readout copy.
-  const error = reported === "voice_disconnected" && view.snapshot?.outputMuted ? "voice_background" : reported;
+  const error = visibleCallError(view);
   const phase = view.cancelArmed ? "cancel" : error ? "error" : processing ? "processing" : transcribing ? "transcribing" : preparing ? "preparing" : recording ? "recording" : preview ? "preview" : view.snapshot && view.snapshot.playback !== "idle" ? "speaking" : view.snapshot?.agent === "running" ? "working" : "waiting";
   const status = error ? `error.${error}` : ({ cancel: "gesture.cancelRelease", processing: "dictation.processing", transcribing: "mic.transcribing", preparing: "mic.preparing", recording: "call.listening", preview: "dictation.preview", speaking: "dictation.speaking", working: "call.working", waiting: view.mode === "continuous" ? "gesture.waiting" : "dictation.preview" })[phase];
   return { phase, status, preview, recording, pending: processing || transcribing || preparing, error };
 }
 
-const RESTART_ERRORS = new Set(["voice_recovery_expired", "voice_idle_timeout"]);
+const QUIET_ENDINGS = new Set(["voice_recovery_expired", "voice_idle_timeout"]);
+
+/**
+ * Recovery, idle, and a dropped continuous socket are not failures.
+ * Hold-to-speak and send open the call again, so the composer stays quiet.
+ * A muted dictation is not a listen session.
+ */
+function visibleCallError(view) {
+  const reported = view?.error || view?.snapshot?.error;
+  if (!reported || QUIET_ENDINGS.has(reported)) return null;
+  if (view.mode === "continuous" && reported === "voice_disconnected") return null;
+  return reported === "voice_disconnected" && view.snapshot?.outputMuted ? "voice_background" : reported;
+}
 
 /**
  * A continuous call that has failed is one composer banner.
- * The session can still be resumed while it is paused; once the recovery
- * window has closed, the only way back is a new call.
+ * A paused session can still be resumed. Quiet endings have no banner.
  */
 export function voiceCallFailure(view) {
   if (!view?.visible || view.mode !== "continuous") return null;
   const ui = voicePanelPresentation(view);
   if (!ui.error) return null;
-  const recoverable = view.snapshot?.connection === "paused" && !RESTART_ERRORS.has(ui.error);
+  const recoverable = view.snapshot?.connection === "paused" && !QUIET_ENDINGS.has(ui.error);
   return { code: ui.error, action: recoverable ? "resume" : "restart" };
 }
 
@@ -45,7 +54,7 @@ export function voiceDictationPresentation(view, now = Date.now()) {
 }
 
 export function voiceIndicatorPresentation(view, settingsError = null) {
-  const error = view.error || view.snapshot?.error || view.readAloudError || settingsError;
+  const error = visibleCallError(view) || view.readAloudError || settingsError;
   const continuous = view.mode === "continuous";
   const active = view.visible && (view.snapshot?.connection === "open" || view.busy && !view.snapshot);
   return {

package/voice/protocol-client.js

@@ -1,4 +1,4 @@
-/** Transport-neutral client: the caller obtains an authenticated Router socket. */
+/** Transport-neutral `lares-realtime-v1` client: the caller obtains an authenticated socket. */
 export function createVoiceProtocolClient(socket, { onEvent = () => {}, onClose = () => {} } = {}) {
   const send = (event) => {
     if (socket.readyState !== 1) throw new Error("voice_disconnected");
@@ -13,12 +13,25 @@ export function createVoiceProtocolClient(socket, { onEvent = () => {}, onClose
   const close = () => onClose();
   socket.addEventListener("message", message); socket.addEventListener("close", close);
   return {
-    configure({ automatic = false, contextId, audio = true } = {}) { send({ type: "session.update", session: { type: "realtime", output_modalities: audio ? ["audio"] : ["text"], ...(contextId ? { voice_context_id: contextId } : {}), audio: { input: { format: { type: "audio/pcm", rate: 24000 }, turn_detection: automatic ? { type: "server_vad" } : null }, output: { format: { type: "audio/pcm", rate: 24000 } } } }); },
+    // Announcing playback acknowledgement up front keeps the first reply half-duplex too.
+    configure({ type = "realtime", automatic = false, contextId, audio = true, busyTurn } = {}) {
+      const input = { format: { type: "audio/pcm", rate: 24000 }, turn_detection: automatic ? { type: "server_vad" } : null };
+      const lares = { ...(contextId ? { context_id: contextId } : {}), ...(busyTurn ? { busy_turn: busyTurn } : {}) };
+      send({ type: "session.update", session: { type, ...(type === "realtime" ? { output_modalities: audio ? ["audio"] : ["text"], audio: { input, output: { format: { type: "audio/pcm", rate: 24000 } } } } : { audio: { input } }), ...(Object.keys(lares).length ? { lares } : {}) } });
+      send({ type: "lares.playback.progress", item_id: null, played_ms: 0 });
+    },
     append(audio) { if (typeof audio !== "string" || audio.length > 64000) throw new Error("voice_audio_limit"); send({ type: "input_audio_buffer.append", audio }); },
     commit() { send({ type: "input_audio_buffer.commit" }); },
     discard() { send({ type: "input_audio_buffer.clear" }); },
-    playbackCompleted() { send({ type: "voice.playback.completed" }); },
+    say(text) { send({ type: "conversation.item.create", item: { type: "message", role: "user", content: [{ type: "input_text", text }] } }); },
+    playbackProgress(itemId, playedMs) { send({ type: "lares.playback.progress", item_id: itemId, played_ms: playedMs }); },
+    playbackCompleted(itemId = null) { send({ type: "lares.playback.completed", item_id: itemId }); },
     stopOutput() { send({ type: "response.cancel" }); },
+    truncate(itemId, audioEndMs) { send({ type: "conversation.item.truncate", item_id: itemId, content_index: 0, audio_end_ms: Math.max(0, Math.round(audioEndMs)) }); },
+    setOutput(audio) { send({ type: "session.update", session: { output_modalities: [audio ? "audio" : "text"] } }); },
+    setBusyTurn(mode) { send({ type: "session.update", session: { lares: { busy_turn: mode === "steer" ? "steer" : "queue" } } }); },
+    deviceInput(active) { send({ type: active ? "lares.device.input.resume" : "lares.device.input.pause" }); },
+    cancelTask(taskId) { send({ type: "lares.task.cancel", task_id: taskId }); },
     close() { socket.removeEventListener("message", message); socket.removeEventListener("close", close); socket.close(); },
   };
 }

package/voice/realtime-gateway.js

@@ -2,6 +2,7 @@ import { randomUUID } from "node:crypto";
 import { WebSocket, WebSocketServer } from "ws";
 import { routerAuthHeaders, routerGatewayUrl } from "../router/gateway.js";
 import { createRealtimeDelegate, LARES_TOOL, REALTIME_INSTRUCTIONS, validatedRealtimeModels } from "./realtime.js";
+import { REALTIME_CAPABILITIES } from "./lares-realtime-gateway.js";
 
 /** HTTP-issued, single-use tickets keep upstream credentials and tools on the Host. */
 export function createRealtimeGateway({ models, config, audio, record = () => {}, env = process.env }) {
@@ -9,6 +10,7 @@ export function createRealtimeGateway({ models, config, audio, record = () => {}
   const connections = new Set();
   const server = new WebSocketServer({ noServer: true, maxPayload: 96 * 1024, perMessageDeflate: false, handleProtocols: (values) => values.has("lares-voice") ? "lares-voice" : false });
   return {
+    owns(req) { return tickets.has(String(req.headers["sec-websocket-protocol"] || "").split(",").map((s) => s.trim()).find((s) => s.startsWith("lares-ticket."))?.slice(13)); },
     async ticket(scope) {
       if (!scope.active || !scope.session) throw Object.assign(new Error("voice session closed"), { status: 409, code: "voice_session_closed" });
       if (scope.voiceConfig && !["chat", "assistant"].includes(scope.voiceConfig.preset)) throw Object.assign(new Error("This preset requires the pipeline backend"), { status: 409, code: "voice_preset_backend_unsupported" });
@@ -51,10 +53,18 @@ export function createRealtimeGateway({ models, config, audio, record = () => {}
         let responding = false;
         let userSpeaking = false;
         const completed = [];
+        // Lares clients speak lares-realtime-v1 here too (docs/realtime-protocol.md); the native upstream stays OpenAI.
+        const translate = (value) => {
+          if (value.type === "lares.ready") return { type: "session.created", session: { id: scope.id, object: "realtime.session", type: "realtime", model: grant.model, output_modalities: [scope.readAloud ? "audio" : "text"], lares: { capabilities: { ...REALTIME_CAPABILITIES, message_truncation: scope.device === "headset" ? "none" : "played", backend: "native" }, context_id: scope.contextId, device: scope.device === "headset" ? "headset" : "device" } } };
+          if (value.type === "lares.error") return { type: "error", error: { type: "server_error", code: value.code, message: "Voice session failed" } };
+          if (value.type === "lares.playback") return { type: "lares.device.playback", playing: value.playing };
+          if (value.type === "lares.task") return { type: "lares.task.updated", task_id: value.requestId || null, status: value.status, session_id: value.sessionId || null };
+          return value;
+        };
         const sendClient = (value) => {
           if (client.readyState !== WebSocket.OPEN) return;
           if (client.bufferedAmount > 1024 * 1024) { close("voice_audio_backpressure"); return; }
-          client.send(JSON.stringify(value));
+          client.send(JSON.stringify(translate(value)));
         };
         const send = (value) => {
           if (closed || upstream.readyState !== WebSocket.OPEN) return;
@@ -151,9 +161,12 @@ export function createRealtimeGateway({ models, config, audio, record = () => {}
           try { event = JSON.parse(raw.toString()); } catch { close("voice_realtime_protocol"); return; }
           if (!event || typeof event !== "object" || Array.isArray(event)) { close("voice_realtime_protocol"); return; }
           if (event.type === "input_audio_buffer.append" && scope.device === "device" && typeof event.audio === "string" && event.audio.length <= 64 * 1024 && /^[A-Za-z0-9+/]*={0,2}$/.test(event.audio)) send({ type: event.type, audio: event.audio });
-          else if (event.type === "lares.output" && typeof event.enabled === "boolean") { scope.readAloud = event.enabled; send({ type: "session.update", session: { output_modalities: event.enabled ? ["audio"] : ["text"] } }); }
-          else if (event.type === "lares.input.pause") { send({ type: "input_audio_buffer.clear" }); void Promise.resolve(audioPort?.pauseInput()).catch(() => close("voice_device_unavailable")); }
-          else if (event.type === "lares.input.resume") void Promise.resolve(audioPort?.resumeInput()).catch(() => close("voice_device_unavailable"));
+          else if (event.type === "session.update" && event.session && Object.keys(event.session).every((key) => key === "output_modalities") && Array.isArray(event.session.output_modalities) && ["audio", "text"].includes(event.session.output_modalities[0])) {
+            scope.readAloud = event.session.output_modalities[0] === "audio"; send({ type: "session.update", session: { output_modalities: [event.session.output_modalities[0]] } });
+          }
+          else if (event.type === "lares.playback.progress" || event.type === "lares.playback.completed") return;
+          else if (event.type === "lares.device.input.pause") { send({ type: "input_audio_buffer.clear" }); void Promise.resolve(audioPort?.pauseInput()).catch(() => close("voice_device_unavailable")); }
+          else if (event.type === "lares.device.input.resume") void Promise.resolve(audioPort?.resumeInput()).catch(() => close("voice_device_unavailable"));
           else if (event.type === "response.cancel") { audioGeneration++; send({ type: "response.cancel" }); void Promise.resolve(audioPort?.interrupt()).catch(() => close("voice_device_unavailable")); }
           else if (event.type === "conversation.item.truncate" && typeof currentItem === "string" && event.item_id === currentItem && event.content_index === 0 && Number.isInteger(event.audio_end_ms) && event.audio_end_ms >= 0 && event.audio_end_ms <= Math.ceil(receivedMs)) send({ type: event.type, item_id: currentItem, content_index: 0, audio_end_ms: event.audio_end_ms });
           else close("voice_realtime_event_forbidden");

package/voice/records.js

@@ -56,7 +56,7 @@ export function createVoiceRecords({ directory = join(dshHome(), "voice-records"
         taskId: record.taskId || null, requestId: record.requestId || record.taskId || record.turnId,
         taskTurn: Number.isInteger(record.taskTurn) ? record.taskTurn : null,
         anchorSeq: previous?.anchorSeq ?? (Number.isInteger(record.anchorSeq) ? record.anchorSeq : -1),
-        status: ["streaming", "failed"].includes(record.status) ? record.status : "completed",
+        status: ["streaming", "failed", "truncated"].includes(record.status) ? record.status : "completed",
         sequence: previous?.sequence || (index >= 0 ? index + 1 : value.records.length + 1), at: previous?.at || now() };
       if (previous && JSON.stringify(previous) === JSON.stringify(next)) return value;
       if (index < 0) value.records.push(next); else value.records[index] = next;

package/voice/router-audio.js

@@ -1,5 +1,7 @@
+import { WebSocket } from "ws";
 import { ttsVoiceForModel } from "./tts-voice.js";
-import { transcribe } from "../router/stt.js";
+import { listModels, pickSttModelId, pickTtsModelId, transcribe } from "../router/stt.js";
+import { routerAuthHeaders, routerGatewayUrl } from "../router/gateway.js";
 import { pcmToWav, synthesizeStream } from "../router/tts.js";
 import { normalizeSttPcm } from "./pcm.js";
 import { createPcmResampler, pcmSamples } from "./realtime-audio.js";
@@ -14,17 +16,58 @@ export function wavData(wav) {
   throw new Error("voice_audio_format");
 }
 
+// Router groups child requests of one Realtime session by this header (Router ADR-83).
+const routerSession = (scope) => scope.routerSessionId ? { "x-session-id": scope.routerSessionId } : undefined;
+
 export function createRouterAudio(config) {
   return {
-    transcribe: (pcm, scope) => transcribe({ bytes: pcmToWav(pcm, 24000), filename: "voice.wav", contentType: "audio/wav", model: config().model || "default-stt", language: config().language || undefined, signal: scope.voiceAbort?.signal, once: true }),
+    // Same resolution as the streaming path: a configured model that is not installed falls back to one that is.
+    transcribe: async (pcm, scope) => transcribe({ bytes: pcmToWav(pcm, 24000), filename: "voice.wav", contentType: "audio/wav", model: pickSttModelId(await listModels(), config().model) || config().model || "default-stt", language: scope.voiceOverrides?.language || config().language || undefined, signal: scope.voiceAbort?.signal, once: true, headers: routerSession(scope) }),
+    /**
+     * Streaming ASR for one turn when the selected model supports it: 24 kHz PCM in,
+     * partial transcripts out. Returns null so the caller keeps the batch path otherwise.
+     */
+    async openTranscription(scope, onPartial, { env = process.env } = {}) {
+      const rows = await listModels();
+      const settings = config();
+      const model = pickSttModelId(rows, settings.model);
+      if (!model || !rows.find((row) => row.id === model)?.supportsSttStream) return null;
+      const socket = new WebSocket(`${routerGatewayUrl(env).replace(/^http/, "ws")}/audio/stream?model=${encodeURIComponent(model)}`, {
+        headers: { ...routerAuthHeaders(env.LARES_ROUTER_API_KEY, env.OLARES_APP_ID, scope.owner), ...routerSession(scope) }, handshakeTimeout: 15_000, maxPayload: 96 * 1024 });
+      const convert = createPcmResampler(24000, 16000);
+      let text = "", settle;
+      const final = new Promise((resolve, reject) => { settle = { resolve, reject }; });
+      final.catch(() => {});
+      const opened = new Promise((resolve, reject) => {
+        socket.once("open", () => { socket.send(JSON.stringify({ type: "start", sample_rate: 16000, language: scope.voiceOverrides?.language || settings.language || undefined })); resolve(); });
+        socket.once("error", reject);
+      });
+      opened.catch(() => {});
+      socket.on("message", (raw, binary) => {
+        if (binary) return;
+        let value;
+        try { value = JSON.parse(String(raw)); } catch { return; }
+        if (value.type === "partial") { text = String(value.text || ""); onPartial(text); }
+        if (value.type === "final") { text = String(value.text || ""); settle.resolve(text); }
+        if (value.type === "error") settle.reject(new Error(value.code || "voice_stream_failed"));
+      });
+      socket.on("close", () => settle.reject(new Error("voice_stream_closed")));
+      socket.on("error", () => settle.reject(new Error("voice_stream_failed")));
+      let chain = opened;
+      return {
+        write(pcm) { chain = chain.then(() => { if (socket.readyState === 1) socket.send(Buffer.from(convert(pcmSamples(pcm)))); }); chain.catch(() => {}); },
+        async finish() { await chain; socket.send(JSON.stringify({ type: "finish" })); try { return await final; } finally { socket.close(); } },
+        cancel() { socket.terminate(); },
+      };
+    },
     async synthesize(text, scope, onChunk) {
-      const settings = structuredClone(config());
-      const model = settings.ttsModel || "default-tts";
+      const settings = { ...structuredClone(config()), ...scope.voiceOverrides?.voice && { voice: scope.voiceOverrides.voice } };
+      const model = pickTtsModelId(await listModels(), settings.ttsModel) || settings.ttsModel || "default-tts";
       const chunks = [];
       let convert = null;
       const write = async (pcm) => { if (onChunk) await onChunk(pcm); else chunks.push(pcm); };
       let pending = Buffer.alloc(0);
-      const result = await synthesizeStream({ text, model, voice: settings.voice || ttsVoiceForModel(settings, model), signal: scope.outputAbort?.signal,
+      const result = await synthesizeStream({ text, model, voice: settings.voice || ttsVoiceForModel(settings, model), signal: scope.outputAbort?.signal, headers: routerSession(scope),
         onFormat: (format) => { convert = createPcmResampler(format.sampleRate, 24000); },
       }, async (chunk) => {
         const joined = Buffer.concat([pending, chunk]);

package/voice/speech.js

@@ -197,6 +197,9 @@ export function createSentencePlayer({ send, play, halt, silence, fail = () => {
   const emitOutput = value => {
     if (value || readoutState.getSnapshot()?.key === lastKey || onOutput !== readoutState.publish) onOutput(value);
   };
+  // A dropped socket is the same quiet ending as a cancel: the next utterance
+  // opens a new stream. It is not a broken voice setting.
+  const quietPlayback = new Set(["voice_cancelled", "voice_output_owned", "voice_disconnected"]);
   const failed = (run, err) => {
     if (run.gen !== gen) return;
     run.abort?.abort();
@@ -204,7 +207,10 @@ export function createSentencePlayer({ send, play, halt, silence, fail = () => {
     run.wake?.();
     current = null;
     onState(false); emitOutput(null);
-    if (!["voice_cancelled", "voice_output_owned"].includes(err?.code || err?.message)) { emitOutput({ ...run.identity, status: "error", error: err?.code || err?.message || "voice_playback_failed", stop: () => emitOutput(null) }); fail(err); }
+    const code = err?.code || err?.message;
+    if (quietPlayback.has(code)) return;
+    emitOutput({ ...run.identity, status: "error", error: code || "voice_playback_failed", stop: () => emitOutput(null) });
+    fail(err);
   };
 
   const handOver = (run) => {

package/voice/stream-client.js

@@ -136,8 +136,9 @@ export async function startTranscriptionStream(options) {
   };
 }
 
+/** `options.port` swaps the `/stream` STT socket for another PCM sink at `options.sampleRate`. */
 export async function createStreamingCapture(stream, options) {
-  const port = await startTranscriptionStream(options);
+  const port = await (options.port ? options.port(options) : startTranscriptionStream(options));
   if (!port) return null;
   let context, source, node, failure, flushed;
   const release = () => {
@@ -152,7 +153,7 @@ export async function createStreamingCapture(stream, options) {
     const url = URL.createObjectURL(new Blob([PCM_CAPTURE_WORKLET], { type: "text/javascript" }));
     try { await context.audioWorklet.addModule(url); await context.resume(); } finally { URL.revokeObjectURL(url); }
     if (options.signal?.aborted) throw new Error("voice_cancelled");
-    const convert = createPcmResampler(context.sampleRate, 16000);
+    const convert = createPcmResampler(context.sampleRate, options.sampleRate || 16000);
     source = context.createMediaStreamSource(stream);
     node = new AudioWorkletNode(context, "lares-pcm-capture", { numberOfOutputs: 1, outputChannelCount: [1] });
     node.port.onmessage = ({ data }) => {

package/voice/unified-conversation.js

@@ -0,0 +1,256 @@
+import { createVoiceController } from "./controller.js";
+import { createDeviceInput } from "./device-input.js";
+import { createPcmStreamPlayer } from "./pcm-player.js";
+import { createVoiceProtocolClient } from "./protocol-client.js";
+import { createStreamingCapture } from "./stream-client.js";
+import { mintRpcId } from "../larepass/rpc.js";
+
+const RATE = 24000;
+const PROGRESS_MS = 250;
+
+export function encodeBase64(bytes) {
+  let text = "";
+  for (let i = 0; i < bytes.length; i += 0x8000) text += String.fromCharCode(...bytes.subarray(i, i + 0x8000));
+  return btoa(text);
+}
+const decodeBase64 = (value) => Uint8Array.from(atob(value), (c) => c.charCodeAt(0));
+
+export function browserRealtimeSocket(ticket) {
+  const url = new URL("/api/lares/voice/realtime", globalThis.location.href); url.protocol = url.protocol === "https:" ? "wss:" : "ws:";
+  return new WebSocket(url, ["lares-voice", `lares-ticket.${ticket}`]);
+}
+
+/**
+ * The Lares client conversation over `lares-realtime-v1` (docs/realtime-protocol.md). It keeps the
+ * shape of `createVoiceConversation`, so the panel and controller stay transport-neutral: the
+ * microphone streams PCM into the socket, the Host transcribes, submits and speaks, and the reply
+ * audio plays from the socket instead of a separate synthesis stream.
+ */
+export function createUnifiedConversation({ request, socket: openSocket = browserRealtimeSocket, onPhase, mode = () => "queue", device = "device", metric = () => {}, readAloud = true, preset, presentationSession = false, endpointSilenceMs, idleTimeoutMs, recoveryTimeoutMs, onText = () => {}, onTranscript = null, preparation, media, player: createPlayer = createPcmStreamPlayer, input: inputPort }) {
+  const voiceId = mintRpcId();
+  const headset = device === "headset";
+  const headers = { "x-lares-voice-id": voiceId, "x-lares-voice-device": headset ? "headset" : "device" };
+  let protocol = null, socketOpen = null, disposed = false, timer = null, lastSessionId = null, continuous = false;
+  let turn = null, reply = null, outputSerial = Promise.resolve(), confirmedReadAloud = readAloud;
+  const call = async (path, body, signal) => {
+    const res = await request(`/api/lares/voice${path}`, { method: body === undefined ? "GET" : "POST", headers, ...(body === undefined ? {} : { body }), signal });
+    if (!res?.ok) throw new Error(res?.body?.error?.code || "voice_failed");
+    return res.body;
+  };
+  const sessionBody = (sessionId) => ({ sessionId, readAloud, presentationSession, preset: onTranscript ? "dictation" : preset, backend: "pipeline" });
+
+  // Reply playback: one PCM player per response, acknowledged back to the Host.
+  const player = createPlayer({ onProgress: (frames) => {
+    if (!reply || !protocol) return;
+    reply.playedMs = frames / (RATE / 1000);
+    if (Date.now() - (reply.reported || 0) >= PROGRESS_MS) { reply.reported = Date.now(); protocol.playbackProgress(reply.itemId, Math.round(reply.playedMs)); }
+  } });
+  const playback = {
+    begin(event) {
+      reply = { id: event.response?.id, itemId: null, text: "", audio: false, playedMs: 0, chain: Promise.resolve() };
+    },
+    write(delta) {
+      const current = reply;
+      if (!current) return;
+      if (!current.audio) { current.audio = true; current.chain = current.chain.then(() => player.start({ sampleRate: RATE, channels: 1, encoding: "pcm_s16le" })); controller.observePlayback(true); }
+      current.chain = current.chain.then(() => { if (reply === current) player.write(decodeBase64(delta)); });
+      current.chain.catch(() => {});
+    },
+    async done() {
+      const current = reply;
+      if (!current) return;
+      if (current.audio) {
+        try { await current.chain; await player.finish(); } catch {}
+        if (reply !== current) return;
+        protocol?.playbackCompleted(current.itemId);
+      }
+      if (reply === current) reply = null;
+      controller.observePlayback(false);
+    },
+    async stop() {
+      const current = reply;
+      reply = null;
+      player.stop();
+      if (!current || !protocol) return;
+      protocol.stopOutput();
+      if (current.itemId && current.audio) protocol.truncate(current.itemId, current.playedMs);
+    },
+  };
+
+  // Takes: the device microphone streams PCM over the socket; the Host transcribes on commit.
+  const take = () => {
+    const current = { resolve: null, reject: null, onPartial: null };
+    turn = current;
+    return current;
+  };
+  const transcription = ({ onPartial }) => {
+    if (!protocol) throw new Error("voice_disconnected");
+    const current = take();
+    current.onPartial = onPartial;
+    return {
+      write(bytes) { if (turn === current && protocol) protocol.append(encodeBase64(bytes)); },
+      finish() {
+        return new Promise((resolve, reject) => {
+          current.resolve = resolve; current.reject = reject;
+          if (!onTranscript) protocol.setBusyTurn(mode());
+          protocol.commit();
+        });
+      },
+      cancel() { if (turn === current) { turn = null; protocol?.discard(); } },
+    };
+  };
+  const deviceInput = () => createDeviceInput({ media, preparation, onPhase, endpointSilenceMs,
+    transcribe: async () => { throw new Error("voice_unsupported"); },
+    streamInput: (stream, options) => createStreamingCapture(stream, { ...options, sampleRate: RATE, port: async () => transcription(options) }),
+  });
+  // Headset: the Host owns the microphone; the socket only opens and closes it.
+  const hostInput = () => ({
+    capabilities: { duplex: false, bargeIn: false, audio: "pcm16-24000" },
+    capture({ signal, onReady, onSpeech, onTranscribing }) {
+      const current = take();
+      current.onSpeech = onSpeech; current.onTranscribing = onTranscribing;
+      return new Promise((resolve, reject) => {
+        current.resolve = (text) => { protocol?.deviceInput(false); resolve(text); };
+        current.reject = (error) => { protocol?.deviceInput(false); reject(error); };
+        signal.addEventListener("abort", () => { if (turn === current) { turn = null; protocol?.discard(); protocol?.deviceInput(false); resolve(""); } }, { once: true });
+        if (!onTranscript) protocol.setBusyTurn(mode());
+        protocol.deviceInput(true);
+        onReady?.();
+      });
+    },
+    stop() { protocol?.commit(); },
+    cancel() { const current = turn; turn = null; protocol?.discard(); protocol?.deviceInput(false); current?.resolve?.(""); },
+  });
+  const input = inputPort ?? (headset ? hostInput() : deviceInput());
+
+  const onEvent = (event) => {
+    switch (event.type) {
+      case "input_audio_buffer.speech_started": turn?.onSpeech?.(); break;
+      case "input_audio_buffer.committed": turn?.onTranscribing?.(); break;
+      case "conversation.item.input_audio_transcription.delta": if (turn?.onPartial) { turn.partial = `${turn.partial || ""}${event.delta}`; turn.onPartial(turn.partial); } break;
+      case "conversation.item.input_audio_transcription.completed": { const current = turn; turn = null; current?.resolve?.(event.transcript || ""); break; }
+      case "response.created": playback.begin(event); break;
+      case "response.output_item.added": if (reply) reply.itemId = event.item?.id || null; break;
+      case "response.output_audio_transcript.delta":
+      case "response.output_text.delta": if (reply) { reply.text += event.delta || ""; onText(reply.text); } break;
+      case "response.output_audio.delta": playback.write(event.delta); break;
+      case "response.done": void playback.done(); break;
+      case "lares.device.playback": controller.observePlayback(event.playing === true); break;
+      case "error": {
+        const code = event.error?.code || "voice_failed";
+        if (turn && ["unsupported_audio_format", "audio_limit_exceeded", "turn_busy", "waiting_for_playback", "upstream_failed"].includes(code)) { const current = turn; turn = null; current.reject?.(new Error(code)); }
+        if (code === "session_expired") void controller.disconnect("voice_idle_timeout");
+        break;
+      }
+      default: break;
+    }
+  };
+  const connect = async () => {
+    if (protocol) return;
+    const { ticket } = await call("/realtime/ticket", {});
+    const ws = openSocket(ticket);
+    socketOpen = new Promise((resolve, reject) => {
+      const timeout = setTimeout(() => reject(new Error("voice_realtime_timeout")), 15_000);
+      protocol = createVoiceProtocolClient(ws, {
+        onEvent: (event) => { if (event.type === "session.created") { clearTimeout(timeout); resolve(); } onEvent(event); },
+        onClose: () => { clearTimeout(timeout); reject(new Error("voice_disconnected")); protocol = null; const current = turn; turn = null; current?.reject?.(new Error("voice_disconnected")); if (!disposed) void controller.disconnect("voice_disconnected"); },
+      });
+    });
+    socketOpen.catch(() => {});
+    await socketOpen;
+    // Device takes keep client endpointing; the headset microphone lives on the Host, so its VAD does.
+    protocol.configure({ type: onTranscript ? "transcription" : "realtime", automatic: headset && continuous, audio: readAloud });
+  };
+  const disconnectSocket = () => { const current = protocol; protocol = null; current?.close(); };
+
+  const controller = createVoiceController({ voiceId, input, idleTimeoutMs, recoveryTimeoutMs, onExpired: () => stop(),
+    onTranscript: onTranscript ? async (value) => { await onTranscript(value); if (!continuous) await stop(); } : null,
+    metric: (event) => { metric(event); void call("/session/metric", { stage: event.stage, durationMs: event.durationMs }).catch(() => {}); },
+    output: { get canPause() { return !headset; }, key: () => reply?.id, pause: () => player.pause?.(), resume: () => player.resume?.(), stop: () => playback.stop() },
+    agent: {
+      lazy: true,
+      create: async () => null,
+      // The Host submitted this turn when its audio was committed; only the lifecycle remains to observe.
+      async submit() { await poll(); },
+      cancel: () => call("/session/cancel", {}),
+      running: async () => (await call("/session")).running === true,
+    },
+  });
+  const poll = async () => {
+    if (disposed || onTranscript) return;
+    const state = await call("/session");
+    if (disposed || controller.getSnapshot().connection !== "open") return;
+    lastSessionId = state.sessionId;
+    if (lastSessionId) controller.bindSession(lastSessionId);
+    if (state.error && state.error !== "voice_cancelled") throw new Error(state.error);
+    controller.observeAgent(Boolean(state.running) || Boolean(reply), Boolean(reply?.audio));
+  };
+  const watch = async () => {
+    if (disposed || controller.getSnapshot().connection !== "open") return;
+    try { await poll(); }
+    catch (error) { await controller.disconnect(error.code || error.message || "voice_disconnected"); return; }
+    if (!disposed) timer = setTimeout(watch, 500);
+  };
+  const stop = async () => {
+    disposed = true; clearTimeout(timer);
+    player.stop(); reply = null;
+    await controller.disconnect();
+    disconnectSocket();
+    await call("/session/close", {}).catch(() => {});
+  };
+  return {
+    controller, headers,
+    // Reply audio is played here, not by the panel's reader.
+    playbackState() {},
+    get sessionId() { return lastSessionId; },
+    async start({ sessionId = null, continuous: nextContinuous = false, manual = false, shouldStart = () => true } = {}) {
+      continuous = nextContinuous; disposed = false; clearTimeout(timer);
+      const initial = await call("/session", sessionBody(sessionId));
+      if (!shouldStart()) { await stop(); return; }
+      await connect();
+      if (!shouldStart()) { await stop(); return; }
+      await controller.start({ sessionId, continuous, manual, running: initial.running, shouldStart });
+      controller.setOutputMuted(!readAloud);
+      if (!onTranscript) void watch();
+    },
+    stop,
+    async pause() { clearTimeout(timer); await controller.pause(); },
+    async resume(options = {}) {
+      disposed = false;
+      if (!onTranscript) {
+        const current = await call("/session");
+        if (!current.active) await call("/session", sessionBody(lastSessionId));
+        else await call("/session/resume", {});
+      }
+      await connect();
+      await controller.resume(options);
+      if (!onTranscript) void watch();
+    },
+    setReadAloud(value) {
+      const next = value === true;
+      if (readAloud === next && confirmedReadAloud === next) return Promise.resolve();
+      readAloud = next;
+      controller.setOutputMuted(!next);
+      const stopped = !next ? Promise.resolve(controller.stopPlayback()).then(() => null, (error) => error) : Promise.resolve(null);
+      const result = outputSerial.catch(() => {}).then(async () => {
+        const error = await stopped;
+        if (error) throw error;
+        if (protocol) protocol.setOutput(next);
+        confirmedReadAloud = next;
+      });
+      outputSerial = result;
+      return result;
+    },
+    records: async () => {
+      const res = await request("/api/lares/voice/records", { method: "GET", headers });
+      if (!res?.ok) throw new Error("voice_records_failed");
+      return res.body;
+    },
+    clearRecords: async () => {
+      await stop();
+      const res = await request("/api/lares/voice/records", { method: "DELETE", headers });
+      if (!res?.ok) throw new Error("voice_records_failed");
+    },
+    speak: (body) => call("/speak", body),
+  };
+}