@olares/lares-core 0.15.24 → 0.15.26

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/reply-stream.js

@@ -6,13 +6,17 @@ const STATUS = { voice_reply_invalid: 400, voice_reply_forbidden: 403 };
 const fault = code => new VoiceError(code, STATUS[code] ?? 409, code);
 const identity = source => JSON.stringify([source.sessionId, source.turn, source.step]);
 
-/** Only trusted Agent events may authorize live text; client input supplies an address, never text. */
-export function createReplyStreamRegistry({ inspect, owner, now = Date.now, segmenterFactory = () => createSpeechSegmenter({ now }) } = {}) {
+/**
+ * Trusted Agent text only; a client supplies an address, never the words.
+ * Read-while-writing releases each closed sentence as it arrives. Reading the
+ * finished answer waits until that text has settled. A tool call ends either readout.
+ */
+export function createReplyStreamRegistry({ inspect, owner, now = Date.now, segmenterFactory = () => createSpeechSegmenter({ now }), streaming = () => false } = {}) {
   const rows = new Map();
   const notify = row => { row.version = (row.version || 0) + 1; for (const wake of row.listeners) wake(); };
   const fail = (row, code) => { row.segmenter.reset(); row.ready = []; row.error = code; row.done = true; row.at = now(); notify(row); };
   const advance = row => {
-    if (!row.subscribers || row.error || !row.eligible && !row.done) return;
+    if (!row.subscribers || row.error || streaming() !== true && !row.done) return;
     try { row.ready.push(...row.segmenter.update(row.utterance?.text || "", { done: row.done })); }
     catch (error) { fail(row, error.message === "voice_reply_rewritten" ? error.message : "voice_reply_invalid"); }
   };
@@ -28,7 +32,7 @@ export function createReplyStreamRegistry({ inspect, owner, now = Date.now, segm
         }
         if (rows.size >= 128) return;
         rows.set(key, { sessionId, turn: frame.turn, step: frame.step, attemptId: frame.attemptId,
-          segmenter: segmenterFactory(), ready: [], eligible: frame.speechEligible === true, utterance: null, next: 0, done: false, error: null, at: now(), listeners: new Set(), subscribers: 0 });
+          segmenter: segmenterFactory(), ready: [], utterance: null, next: 0, done: false, error: null, at: now(), listeners: new Set(), subscribers: 0 });
         return;
       }
       for (const row of rows.values()) {

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/service.js

@@ -158,6 +158,12 @@ export async function saveVoiceConfig(body) {
       throw new VoiceError("voice_model_unavailable", 400, "selected speech model is not available");
     }
   }
+  if (patch.streaming === true) {
+    const { speechGpu } = await import("./gpu-mode.js");
+    const gpu = await speechGpu();
+    if (!gpu) throw new VoiceError("voice_gpu_no_gpu", 409, "no NVIDIA GPU");
+    if (gpu.type !== "MemorySlice") throw new VoiceError("voice_streaming_time_slice", 409, gpu.type || "TimeSlice");
+  }
   if (patch.ttsVoiceByModel) {
     const current = readConfig().ttsVoiceByModel;
     const changed = Object.entries(patch.ttsVoiceByModel).filter(([model, voice]) => voice && current[model] !== voice);

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/spoken-text.js

@@ -100,6 +100,14 @@ function withoutEmoji(text) {
   });
 }
 
+// A longer unbroken identifier is not speech. Synthesizing it stalls the one
+// shared speech path, so this answer and the next one stay silent. Dots stay
+// outside the run so "First one." is still a sentence; a following short
+// extension (`name.jpg`) leaves with the run.
+function withoutUnsayable(text) {
+  return text.replace(/[A-Za-z0-9][A-Za-z0-9_~:/?#@!$&*+=%-]{31,}(?:\.[A-Za-z0-9]{1,8})?/g, "");
+}
+
 /** The assistant's spoken copy; never apply this to stored messages or raw TTS API input. */
 function prepareSource(text, done, structural = false) {
   let pending = false;
@@ -143,9 +151,10 @@ export function spokenLines(text, { done = true } = {}) {
       plain = plain.slice(0, lineStart) + end.slice(0, tail.index);
       pending = true;
     }
-    if (pending || inline.pending) plain += "\uFFFC";
   }
-  return withoutEmoji(plain).split("\n").map((line) => line.replace(/\s+/g, " ").trim());
+  plain = withoutUnsayable(withoutEmoji(plain));
+  if (!done && (pending || inline.pending)) plain += "\uFFFC";
+  return plain.split("\n").map((line) => line.replace(/\s+/g, " ").trim());
 }
 
 
@@ -183,8 +192,9 @@ export function spokenBlocks(text, { done = true } = {}) {
         const tail = [...graphemes.segment(plain.trimEnd())].at(-1);
         if (tail && (emojiRegex().test(tail.segment) || /[\uD800-\uDBFF]$/.test(tail.segment))) { plain = plain.slice(0, tail.index); opaque = true; }
       }
+      plain = withoutUnsayable(withoutEmoji(plain));
       if (!done && opaque) plain += "\uFFFC";
-      plain = withoutEmoji(plain).replace(/\s+/g, " ").trim();
+      plain = plain.replace(/\s+/g, " ").trim();
       const continuation = lists.length && paragraphs.has(items.at(-1));
       if (lists.length) paragraphs.add(items.at(-1));
       if (plain) result.push({ id, text: plain, closed,

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),
+  };
+}