@olares/lares-core 0.15.32 → 0.15.34

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@olares/lares-core",
-  "version": "0.15.32",
+  "version": "0.15.34",
   "description": "Lares 共享业务核心：Router、workspace、文件/媒体、Olares 身份（无 UI、无平台壳）",
   "type": "module",
   "repository": {

package/voice/browser-capture.js

@@ -49,7 +49,22 @@ export function prepareBrowserCapture({ media, onTrace = () => {}, now = Date.no
   })();
   // Permission may fail while other initialization is still pending.
   void ready.catch(() => {});
+  const live = async () => {
+    let next;
+    try { next = await ready; }
+    catch (err) {
+      if (err instanceof Error && err.message.startsWith("voice_")) throw err;
+      throw new Error(micFailure(err));
+    }
+    if (consumed || cancelled || !next) throw new Error("voice_cancelled");
+    if (next.getTracks().every((track) => track.readyState === "ended")) throw new Error("voice_device_lost");
+    return next;
+  };
   return {
+    /** Resolves once the microphone is open. Does not take the stream. */
+    opened: live,
+    /** Another take of the same voice session. Does not open a second microphone. */
+    borrow: live,
     recording() {
       try { onTrace("ready", { durationMs: now() - started }); } catch { /* Telemetry is optional. */ }
     },
@@ -79,6 +94,7 @@ export function createVoiceCapture({
   now = Date.now,
   media,
   preparation,
+  retainStream = false,
 }) {
   const mediaDevices = media?.mediaDevices ?? globalThis.navigator?.mediaDevices;
   const Recorder = media?.MediaRecorder ?? globalThis.MediaRecorder;
@@ -122,7 +138,9 @@ export function createVoiceCapture({
   const release = () => {
     detector?.stop?.();
     detector = null;
-    stream?.getTracks().forEach((track) => track.stop());
+    // A session microphone stays open for the next hold. Only a take that
+    // opened its own stream stops the tracks when the take ends.
+    if (!retainStream) stream?.getTracks().forEach((track) => track.stop());
     stream = null;
     recorder = null;
   };
@@ -241,7 +259,7 @@ export function createVoiceCapture({
     async start() {
       if (dead || phase === "preparing" || phase === "recording" || phase === "transcribing") return;
       if (typeof Recorder === "undefined" || !mediaDevices?.getUserMedia) {
-        preparation?.cancel();
+        if (!retainStream) preparation?.cancel();
         fail("voice_unsupported");
         return;
       }
@@ -253,9 +271,9 @@ export function createVoiceCapture({
       emit("preparing", { elapsed: 0, error: "" });
       let next;
       try {
-        next = await (preparation ? preparation.consume() : openDeviceMic(mediaDevices));
+        next = await (retainStream ? preparation.borrow() : preparation ? preparation.consume() : openDeviceMic(mediaDevices));
       } catch (err) {
-        preparation?.cancel();
+        if (!retainStream) preparation?.cancel();
         const code = micFailure(err);
         trace("mic-fail", { code, name: err?.name || "" });
         if (!dead) fail(code);
@@ -351,7 +369,7 @@ export function createVoiceCapture({
       }
     },
     dispose() {
-      preparation?.cancel();
+      if (!retainStream) preparation?.cancel();
       inputAbort?.abort();
       dead = true;
       cancel = true;

package/voice/device-input.js

@@ -32,8 +32,8 @@ export function createDeviceInput({ transcribe, onPhase = () => {}, endpoint = d
         let ready = false;
         settle = resolve;
         const done = (text) => { clearTimeout(timer); signal?.removeEventListener("abort", cancel); settle = null; resolve(text); };
-        const prepared = preparation; preparation = null;
-        recorder = createVoiceCapture({ media, streamInput, preparation: prepared, transcribe, submit: done, onStream: (stream) => {
+        const retainStream = continuous && typeof preparation?.borrow === "function";
+        recorder = createVoiceCapture({ media, streamInput, preparation, retainStream, transcribe, submit: done, onStream: (stream) => {
           for (const track of stream.getTracks()) track.addEventListener?.("ended", () => { settle = null; cancel(); reject(new Error("voice_device_lost")); }, { once: true });
           if (!automatic) return createInputMeter(stream, onLevel);
           return endpoint(stream, (heard = true) => { if (heard) recorder?.stop(); else { cancel(); done(""); } }, onSpeech, onLevel, { silenceMs: endpointSilenceMs, interruptionMs: echoTested ? 500 : 0 });

package/voice/lares-realtime-gateway.js

@@ -3,6 +3,7 @@ import { WebSocketServer } from "ws";
 import { validateConfigPatch } from "./config.js";
 import { createSpeechEndpoint, frameRms } from "./endpoint.js";
 import { pcmSamples } from "./realtime-audio.js";
+import { createPlayoutClock, PLAYOUT_LEAD_MS, SOCKET_FUSE_BYTES } from "./playout-clock.js";
 import { speechSegments } from "./script.js";
 import { bindRouterSession } from "../router/session-alias.js";
 
@@ -16,13 +17,6 @@ const SPEECH_RMS = 0.004;
 // and a suspected interruption that never resolves stops the reply.
 const BARGE_IN_MS = 500;
 const BARGE_IN_LIMIT_MS = 10_000;
-// How far ahead of the client's actual playout the Host may send. The client's
-// AudioWorklet keeps a bounded queue; sending a whole answer at network speed
-// overflowed it and dropped audio.
-const PLAY_AHEAD_MS = 2_000;
-// A temporarily interrupted AudioContext (device switch, lock screen) must not
-// end a reply; only a client that stays silent this long is treated as stuck.
-const PLAYOUT_STALL_MS = 30_000;
 const TICKET_MS = 30_000;
 // Usage lives in the child ASR/LLM/TTS requests; the OpenAI shape stays parseable (Router ADR-83).
 const ZERO_USAGE = Object.freeze({ total_tokens: 0, input_tokens: 0, output_tokens: 0, input_token_details: { text_tokens: 0, audio_tokens: 0, cached_tokens: 0 }, output_token_details: { text_tokens: 0, audio_tokens: 0 } });
@@ -44,6 +38,9 @@ const ticketOf = (req) => String(req.headers["sec-websocket-protocol"] || "").sp
 const CJK_END = /[　-〿㐀-鿿＀-￯]$/;
 const CJK_START = /^[　-〿㐀-鿿＀-￯]/;
 const separator = (before, after) => !before || CJK_END.test(before) || CJK_START.test(after) ? "" : " ";
+// `done === false` is a live partial. A finished utterance sets done, and a caller
+// that never reports it (tests, a one-shot reply) is spoken as-is.
+const speakableUtterance = (utterance) => Boolean(utterance?.text) && utterance.done !== false && !utterance.silent;
 /** Spoken segments are cleaned clauses; rejoin them without inventing spaces inside CJK text. */
 export function joinSpoken(parts) {
   return parts.reduce((text, part) => `${text}${separator(text, part)}${part}`, "");
@@ -161,29 +158,23 @@ export function createLaresRealtimeGateway({ service, config, transcribe, synthe
         return hostOutput;
       }
       if (acknowledges) { awaitingPlayback = true; watchAck(); }
-      // A long reply is several seconds of PCM. Dumping it in one burst fills the
-      // socket and used to close the call, which cut the readout off and made the
-      // client's next progress tick throw voice_disconnected. Wait for the buffer
-      // the way the speech stream does; a stuck client fails this reply only.
-      const OUTPUT_BUFFER = 128 * 1024;
+      // A client that announces playback acknowledgement used to stop after two
+      // seconds unless later ticks kept arriving. Those ticks are observations.
+      // The reply keeps moving with the clock; the socket fuse is only for a
+      // client that has stopped reading.
+      if (!current.clock) current.clock = createPlayoutClock({ leadMs: PLAYOUT_LEAD_MS });
+      const clock = current.clock;
       let sentAt = Date.now();
-      let lastPlayed = played.get(current.itemId) ?? 0;
-      let playedAt = Date.now();
       for (let offset = 0; offset < audio.length; offset += CHUNK_BYTES) {
-        while (client.bufferedAmount > OUTPUT_BUFFER) {
+        clock.start();
+        clock.heard(played.get(current.itemId) ?? 0);
+        while ((acknowledges && clock.blocked(current.outputMs)) || client.bufferedAmount > SOCKET_FUSE_BYTES) {
           if (current.abort.signal.aborted || current.done || closed || client.readyState !== 1) return;
-          if (Date.now() - sentAt > 10_000) throw new Error("voice_audio_backpressure");
-          await new Promise((resolve) => setTimeout(resolve, 20));
-        }
-        // Playout credit: never get more than two seconds ahead of what the
-        // client has actually rendered. Progress advances in real time, so a
-        // long answer waits here instead of filling the worklet queue.
-        while (acknowledges && current.outputMs - lastPlayed > PLAY_AHEAD_MS) {
-          if (current.abort.signal.aborted || current.done || closed || client.readyState !== 1) return;
-          const heard = played.get(current.itemId) ?? 0;
-          if (heard > lastPlayed) { lastPlayed = heard; playedAt = Date.now(); }
-          if (Date.now() - playedAt > PLAYOUT_STALL_MS) throw new Error("voice_audio_backpressure");
-          await new Promise((resolve) => setTimeout(resolve, 20));
+          clock.heard(played.get(current.itemId) ?? 0);
+          if (client.bufferedAmount > SOCKET_FUSE_BYTES && Date.now() - sentAt > 10_000) throw new Error("voice_audio_backpressure");
+          if (!((acknowledges && clock.blocked(current.outputMs)) || client.bufferedAmount > SOCKET_FUSE_BYTES)) break;
+          const delay = client.bufferedAmount > SOCKET_FUSE_BYTES ? 20 : Math.max(20, Math.min(200, clock.wait(current.outputMs)));
+          await new Promise((resolve) => setTimeout(resolve, delay));
         }
         if (current.abort.signal.aborted || current.done || closed || client.readyState !== 1) return;
         const chunk = audio.subarray(offset, offset + CHUNK_BYTES);
@@ -213,6 +204,8 @@ export function createLaresRealtimeGateway({ service, config, transcribe, synthe
           if (current.suspended && await current.suspended.wait === "stop") return;
           if (current.abort.signal.aborted || closed) return;
           send({ type: "response.output_audio_transcript.delta", ...part, delta: `${separator(current.sentences.at(-1)?.text, sentence)}${sentence}` });
+          // A slice has to reach the player before synthesize continues, so a
+          // caller that pauses after the first slice can still be interrupted.
           const audio = await synthesize(sentence, scope, (pcm) => playOut(current, pcm));
           if (current.abort.signal.aborted || closed) return;
           if (audio) await playOut(current, audio);
@@ -260,7 +253,9 @@ export function createLaresRealtimeGateway({ service, config, transcribe, synthe
         if (!turn.accepted) await service.withdraw?.(scope, requestId).catch(() => {});
         return;
       }
-      if (state.utterance?.text && !state.utterance.silent) { lastReply = state.utterance.key; speak(state.utterance.text, "turn", state.utterance.key, input); }
+      // A snapshot taken while the answer is still streaming only has the first
+      // sentence. Speaking that and remembering the key drops the rest.
+      if (speakableUtterance(state.utterance)) { lastReply = state.utterance.key; speak(state.utterance.text, "turn", state.utterance.key, input); }
     };
     const userItem = (id, content) => send({ type: "conversation.item.done", item: { id, object: "realtime.item", type: "message", role: "user", status: "completed", content: [content] } });
     const commit = async () => {
@@ -512,7 +507,7 @@ export function createLaresRealtimeGateway({ service, config, transcribe, synthe
         observeTasks();
         if (busy || speaking || awaitingPlayback || response) return;
         const state = service.state(scope);
-        if (!state.utterance?.text || state.utterance.key === lastReply || state.utterance.silent) return;
+        if (!speakableUtterance(state.utterance) || state.utterance.key === lastReply) return;
         lastReply = state.utterance.key;
         speak(state.utterance.text, String(state.utterance.key).startsWith("task:") ? "task" : "turn", state.utterance.key, 0);
       } catch { close(); }

package/voice/panel.js

@@ -168,9 +168,25 @@ export function createVoicePanel({ create, complete, loadConfig = async () => ({
       if (state.busy) return Promise.resolve();
       cancelPreparation();
       const snapshot = configSnapshot ? structuredClone(configSnapshot) : null;
-      if (mode === "single" && snapshot && !(sessionId === state.sessionId ? state.raw : drafts.get(sessionId)?.raw)) inputPreparation = prepareInput(snapshot);
-      const token = ++intent; emit({ visible: true });
+      const held = sessionId === state.sessionId ? state.raw : drafts.get(sessionId)?.raw;
+      if (!(mode === "single" && held)) inputPreparation = prepareInput(snapshot || {});
+      const mic = inputPreparation;
+      const token = ++intent;
+      // The composer stays on text until the microphone is actually open.
+      if (!mic) emit({ visible: true });
       return enqueue(async () => {
+        if (mic) {
+          try { await mic.opened(); }
+          catch (error) {
+            if (inputPreparation === mic) cancelPreparation();
+            if (token !== intent) return;
+            const code = error.code || error.message || "voice_failed";
+            if (code !== "voice_cancelled") emit({ visible: false, error: code });
+            return;
+          }
+          if (token !== intent) return;
+          emit({ visible: true, error: null });
+        }
         if (sessionId !== state.sessionId || mode !== state.mode) {
           try { await pause(); } finally { await end(); save(); const held = drafts.get(sessionId); config = held?.config || null; emit({ sessionId, mode, raw: mode === "single" ? held?.raw || "" : "", draft: mode === "single" ? held?.draft || "" : "", edited: mode === "single" && (held?.edited || false), preset: held?.preset || "raw", stage: mode === "single" && held?.raw ? "preview" : "idle" }); }
         }
@@ -188,7 +204,7 @@ export function createVoicePanel({ create, complete, loadConfig = async () => ({
       return enqueue(async () => { try { await pause(); } finally { await end(); save(); const held = drafts.get(sessionId); config = held?.config || null; emit({ sessionId, raw: held?.raw || "", draft: held?.draft || "", edited: held?.edited || false, preset: held?.preset || "raw", stage: held?.raw ? "preview" : "idle" }); } });
     },
     close() { intent++; cancelPreparation(); cancelProcessing(); emit({ visible: false, holding: false, cancelArmed: false }); if (state.mode === "continuous") void call?.controller.cancelRecording(); return enqueue(pause); },
-    pause() { intent++; cancelPreparation(); cancelProcessing(); emit({ holding: false, cancelArmed: false }); if (state.mode === "continuous") void call?.controller.cancelRecording(); return enqueue(pause); },
+    pause() { intent++; if (!state.inputActive) cancelPreparation(); cancelProcessing(); emit({ holding: false, cancelArmed: false }); if (state.mode === "continuous") void call?.controller.cancelRecording(); return enqueue(pause); },
     start() { armOutput(); const token = ++intent; return enqueue(() => prepare(token)); },
     openReadout() {
       if (state.mode !== "continuous") return Promise.resolve();
@@ -219,6 +235,17 @@ export function createVoicePanel({ create, complete, loadConfig = async () => ({
       if (state.busy || state.holding || state.snapshot?.capture === "transcribing") return Promise.resolve();
       const token = ++intent; emit({ holding: true, cancelArmed: false });
       return enqueue(async () => {
+        if (inputPreparation?.borrow) {
+          try { await inputPreparation.borrow(); }
+          catch (error) {
+            cancelPreparation();
+            if (token !== intent) return;
+            const code = error.code || error.message || "voice_failed";
+            if (code !== "voice_cancelled") emit({ visible: false, holding: false, cancelArmed: false, error: code });
+            else emit({ visible: false, holding: false, cancelArmed: false });
+            return;
+          }
+        }
         await prepare(token);
         if (token !== intent || !state.holding || !state.visible) return;
         await call?.controller.stopPlayback();

package/voice/pcm-player.js

@@ -1,6 +1,9 @@
 import { PCM_PLAYER_WORKLET } from "./pcm-worklet.js";
 import { pcmSamples } from "./realtime-audio.js";
 
+/** Unread audio the speaker may be holding. A longer reply waits here; it is not a failed call. */
+export const PLAYBACK_QUEUE_SECONDS = 4;
+
 let primed = null;
 const worklets = new WeakMap();
 let watchingVisibility = false;
@@ -43,7 +46,10 @@ export function primePlaybackContext(Context = globalThis.AudioContext || global
 }
 
 export function createPcmStreamPlayer({ onProgress = () => {}, onMetric = () => {}, context: Context = globalThis.AudioContext || globalThis.webkitAudioContext } = {}) {
-  let context, node, resolve, reject, played = 0, generation = 0, pendingByte = null, failed = null, paused = false, owned = false;
+  let context, node, resolve, reject, played = 0, accepted = 0, rate = 0, generation = 0, pendingByte = null, paused = false, owned = false;
+  let tail = Promise.resolve();
+  const waiters = new Set();
+  const wake = () => { for (const listen of [...waiters]) listen(); };
   /**
    * The page shares one primed context. iOS interrupts it (a call, the lock
    * screen) and it never resumes on its own, so a reply that starts after that
@@ -85,11 +91,14 @@ export function createPcmStreamPlayer({ onProgress = () => {}, onMetric = () =>
     owned = false;
     if (closing && closing.state !== "closed") void closing.close().catch(() => {});
     context = null; resolve?.(); resolve = reject = null; pendingByte = null;
+    wake();
+    tail = Promise.resolve();
   };
   return {
     async start({ sampleRate, channels, encoding }) {
-      stop(); failed = null; played = 0;
+      stop(); played = 0; accepted = 0;
       if (!Context || channels !== 1 || encoding !== "pcm_s16le" || !Number.isInteger(sampleRate) || sampleRate < 8000 || sampleRate > 192000) throw new Error("voice_audio_format");
+      rate = sampleRate;
       const epoch = generation;
       const shared = primed && primed.state !== "closed" ? primed : null;
       let opened;
@@ -109,27 +118,61 @@ export function createPcmStreamPlayer({ onProgress = () => {}, onMetric = () =>
       });
       node.port.onmessage = ({ data }) => {
         if (epoch !== generation) return;
-        if (data.type === "progress") { played = data.frames; onProgress(played); }
+        if (data.type === "progress") { played = data.frames; onProgress(played); wake(); }
         if (data.type === "started" || data.type === "underrun") onMetric({ stage: `playback_${data.type}` });
         if (data.type === "done") { resolve?.(); resolve = reject = null; }
-        if (data.type === "error") { failed = new Error("voice_audio_backpressure"); reject?.(failed); }
       };
       node.connect(opened.destination);
     },
     write(bytes) {
-      if (!node) throw new Error("voice_cancelled");
-      let chunk = bytes;
-      if (pendingByte !== null) { chunk = new Uint8Array(bytes.length + 1); chunk[0] = pendingByte; chunk.set(bytes, 1); pendingByte = null; }
-      if (chunk.length % 2) { pendingByte = chunk[chunk.length - 1]; chunk = chunk.subarray(0, -1); }
-      if (!chunk.length) return;
-      const samples = pcmSamples(chunk);
-      node.port.postMessage({ type: "audio", samples }, [samples.buffer]);
+      const epoch = generation;
+      const run = () => {
+        if (epoch !== generation || !node) throw new Error("voice_cancelled");
+        let chunk = bytes;
+        if (pendingByte !== null) { chunk = new Uint8Array(bytes.length + 1); chunk[0] = pendingByte; chunk.set(bytes, 1); pendingByte = null; }
+        if (chunk.length % 2) { pendingByte = chunk[chunk.length - 1]; chunk = chunk.subarray(0, -1); }
+        if (!chunk.length) return;
+        const source = pcmSamples(chunk);
+        const budget = rate * PLAYBACK_QUEUE_SECONDS;
+        let offset = 0;
+        const post = (from, count) => {
+          const samples = count === source.length && from === 0 ? source : source.slice(from, from + count);
+          accepted += samples.length;
+          node.port.postMessage({ type: "audio", samples }, [samples.buffer]);
+        };
+        const pump = () => {
+          while (offset < source.length) {
+            const room = budget - (accepted - played);
+            if (room <= 0) return false;
+            const count = Math.min(source.length - offset, room);
+            post(offset, count);
+            offset += count;
+          }
+          return true;
+        };
+        if (pump()) return;
+        // The rest of a long reply plays as the speaker catches up.
+        return new Promise((done, fail) => {
+          const listen = () => {
+            if (epoch !== generation || !node) { waiters.delete(listen); fail(new Error("voice_cancelled")); return; }
+            if (!pump()) return;
+            waiters.delete(listen);
+            done();
+          };
+          waiters.add(listen);
+        });
+      };
+      const pending = tail.then(run, run);
+      tail = pending.catch(() => {});
+      return pending;
     },
     finish() {
-      if (failed) return Promise.reject(failed);
-      if (!node) return Promise.resolve();
-      if (pendingByte !== null) return Promise.reject(new Error("voice_audio_format"));
-      return new Promise((done, fail) => { resolve = done; reject = fail; node.port.postMessage({ type: "finish" }); });
+      const epoch = generation;
+      return tail.catch(() => {}).then(() => {
+        if (epoch !== generation || !node) return;
+        if (pendingByte !== null) throw new Error("voice_audio_format");
+        return new Promise((done, fail) => { resolve = done; reject = fail; node.port.postMessage({ type: "finish" }); });
+      });
     },
     canPause: true,
     pause() { paused = true; node?.port.postMessage({ type: "pause" }); },

package/voice/pcm-worklet.js

@@ -10,7 +10,6 @@ class LaresPcmPlayer extends AudioWorkletProcessor {
     this.paused = false; this.queued = 0; this.finished = false; this.started = false; this.starved = false;
     this.port.onmessage = ({ data }) => {
       if (data.type === 'audio') {
-        if (this.queued + data.samples.length > this.rate * 4) { this.port.postMessage({ type: 'error' }); return; }
         this.queue.push(data.samples); this.queued += data.samples.length;
       } else if (data.type === 'finish') this.finished = true;
       else if (data.type === 'pause') this.paused = true;

package/voice/playout-clock.js

@@ -0,0 +1,55 @@
+/**
+ * How far ahead of playout a reply may be sent, and the socket buffer that
+ * means the client has stopped reading. Both gates share this so a dropped
+ * progress tick cannot freeze one path while the other keeps going.
+ *
+ * The player holds about four seconds. While reports are still arriving, the
+ * wall clock may lead the speaker by one send-ahead and no further: a long
+ * reply is not already played just because time passed. A report that stops
+ * falls back to the wall clock, so one missed tick does not end the reply.
+ */
+export const PLAYOUT_LEAD_MS = 2_000;
+export const SOCKET_FUSE_BYTES = 1024 * 1024;
+
+/**
+ * Credit for one reply. The playhead moves at 1x and stops when it catches
+ * the audio already handed to the client. A gap while the next sentence is
+ * synthesized does not pre-pay a burst. Pause freezes the clock.
+ */
+export function createPlayoutClock({ leadMs = PLAYOUT_LEAD_MS, now = Date.now } = {}) {
+  let heard = 0, heardAt = 0, heldAt = 0, playhead = 0, markedAt = 0, sent = 0;
+  const stamp = () => heldAt || now();
+  const advance = (sentMs) => {
+    if (Number.isFinite(sentMs) && sentMs > sent) sent = sentMs;
+    const t = stamp();
+    if (!markedAt) { markedAt = t; return; }
+    playhead = Math.min(sent, playhead + Math.max(0, t - markedAt));
+    markedAt = t;
+  };
+  return {
+    heard(ms) { if (Number.isFinite(ms) && ms > heard) { heard = ms; heardAt = stamp(); } },
+    pause() {
+      if (heldAt) return;
+      advance(sent);
+      heldAt = now();
+    },
+    resume() {
+      if (!heldAt) return;
+      heldAt = 0;
+      markedAt = now();
+    },
+    get paused() { return heldAt !== 0; },
+    start() { if (!markedAt) markedAt = now(); },
+    credit(sentMs) {
+      advance(sentMs);
+      const wall = Math.max(heard, playhead);
+      if (heardAt && stamp() - heardAt <= leadMs) return Math.min(wall, heard + leadMs);
+      return wall;
+    },
+    blocked(sentMs) { return sentMs - this.credit(sentMs) > leadMs; },
+    wait(sentMs) {
+      const delay = sentMs - leadMs - this.credit(sentMs);
+      return delay > 0 ? delay : 0;
+    },
+  };
+}

package/voice/presentation.js

@@ -39,9 +39,10 @@ export function voiceCallFailure(view) {
 }
 
 /**
- * A voice call that is still playing keeps one strip at the composer until it
- * ends: status plus the control that stops it. The hold button is not that
- * strip. A chat readout stays on the assistant row that is being read.
+ * A voice call that is still playing keeps one strip until it ends: status
+ * plus the control that stops it. The hold button is not that strip. Clients
+ * render it under the assistant reply that owns playback. A chat readout stays
+ * on that same reply and is not this strip.
  */
 export function voicePlaybackChrome(view) {
   const playback = view?.snapshot?.playback;

package/voice/stream-client.js

@@ -126,7 +126,7 @@ export async function playAudioStream(options) {
       }
       if (!progressNoted) { progressNoted = true; streamMetric(options, { stage: "playback_progress_sent", frames }); }
     };
-    const writeAudio = (bytes) => {
+    const writeAudio = async (bytes) => {
       let chunk = bytes;
       if (skipBytes > 0) {
         const drop = Math.min(skipBytes, chunk.length);
@@ -136,7 +136,7 @@ export async function playAudioStream(options) {
         chunk = chunk.subarray(drop);
         if (!chunk.length) return;
       }
-      player.write(chunk);
+      await player.write(chunk);
     };
     const gapWatch = setInterval(() => {
       if (!ready || paused || complete || gapReported || Date.now() - lastProgressAt < 4000) return;
@@ -168,7 +168,7 @@ export async function playAudioStream(options) {
           }
           chain = chain.then(async () => {
             if (options.signal?.aborted) throw new Error("voice_cancelled");
-            if (typeof data !== "string") { writeAudio(new Uint8Array(data)); return; }
+            if (typeof data !== "string") { await writeAudio(new Uint8Array(data)); return; }
             if (event.type === "segment") {
               if (event.index !== segmentIndex + 1) throw new Error("voice_reply_sequence");
               segmentIndex = event.index;

package/voice/stream-gateway.js

@@ -1,5 +1,6 @@
 import { ttsVoiceForModel } from "./tts-voice.js";
 import { speechSegments } from "./script.js";
+import { createPlayoutClock, SOCKET_FUSE_BYTES } from "./playout-clock.js";
 import { createSynthesisRuns, utteranceKey } from "./synthesis-run.js";
 import { randomUUID } from "node:crypto";
 import { WebSocket, WebSocketServer } from "ws";
@@ -48,14 +49,15 @@ export function createAudioStreamGateway({ config, models, replies, synthesize =
       server.handleUpgrade(req, socket, head, (client) => {
         clients.add(client);
         const abort = new AbortController();
-        let upstream = null, sentFrames = 0, playedFrames = 0, rate = 0, waiter = null, outputFormat = null;
+        let upstream = null, sentFrames = 0, playedFrames = 0, rate = 0, eventWaiter = null, creditWaiter = null, outputFormat = null;
+        const clock = createPlayoutClock();
         let fileDone = null, pausedAt = 0, closing = false, ttsKey = null;
         let received = 0, committed = false, outputStarted = false;
         const started = Date.now();
         const send = (value) => { if (client.readyState === 1) client.send(JSON.stringify(value)); };
         const close = () => {
           if (closing) return;
-          closing = true; abort.abort(); waiter?.(); fileDone?.(); clearTimeout(lifetime); upstream?.terminate();
+          closing = true; abort.abort(); eventWaiter?.(); creditWaiter?.(); eventWaiter = creditWaiter = null; fileDone?.(); clearTimeout(lifetime); upstream?.terminate();
           // A consumer that disappeared stops its synthesis instead of leaving
           // the whole answer to be rendered with nobody listening.
           if (ttsKey) synthesis.release(ttsKey);
@@ -84,12 +86,14 @@ export function createAudioStreamGateway({ config, models, replies, synthesize =
             } else {
               if (binary) throw fault("voice_stream_state");
               const frame = JSON.parse(String(raw));
-              if (frame.type === "pause") { if (!pausedAt) pausedAt = Date.now(); waiter?.(); waiter = null; return; }
-              if (frame.type === "resume") { pausedAt = 0; waiter?.(); waiter = null; return; }
+              if (frame.type === "pause") { clock.pause(); if (!pausedAt) pausedAt = Date.now(); creditWaiter?.(); creditWaiter = null; return; }
+              if (frame.type === "resume") { clock.resume(); pausedAt = 0; creditWaiter?.(); creditWaiter = null; return; }
               if (frame.type === "file.done" && fileDone) { fileDone(); fileDone = null; return; }
               if (frame.type !== "progress" || !Number.isSafeInteger(frame.frames) || frame.frames < playedFrames || frame.frames > sentFrames) throw fault("voice_stream_state");
               const firstProgress = playedFrames === 0 && frame.frames > 0;
-              playedFrames = frame.frames; waiter?.(); waiter = null;
+              playedFrames = frame.frames;
+              if (rate) clock.heard(frame.frames * 1000 / rate);
+              creditWaiter?.(); creditWaiter = null;
               if (firstProgress) metric({ stage: "playback_progress", voiceId: grant.scope.id, frames: playedFrames });
             }
           } catch (cause) { error(cause); }
@@ -117,11 +121,16 @@ export function createAudioStreamGateway({ config, models, replies, synthesize =
             for (let index = 0; index < parts.length; index += 1) yield { text: parts[index], index };
           })(), { model: grant.model, voice: ttsVoiceForModel(grant.config, grant.model), voiceId: grant.scope.id });
           let cursor = 0;
-          const unsub = run.subscribe(() => { waiter?.(); waiter = null; });
+          const wakeEvent = () => { const fn = eventWaiter; eventWaiter = null; fn?.(); };
+          // New PCM must not clear the playout timer. A long answer keeps
+          // producing chunks; waking the credit wait on each one restarted the
+          // stall deadline, so a phone that had already played its buffer never
+          // received the rest and never got an error either.
+          const unsub = run.subscribe(wakeEvent);
           const waitFor = () => new Promise((resolve, reject) => {
             if (abort.signal.aborted) { reject(fault("voice_cancelled")); return; }
-            const wake = () => { abort.signal.removeEventListener("abort", wake); waiter = null; if (abort.signal.aborted) reject(fault("voice_cancelled")); else resolve(); };
-            waiter = wake;
+            const wake = () => { abort.signal.removeEventListener("abort", wake); eventWaiter = null; if (abort.signal.aborted) reject(fault("voice_cancelled")); else resolve(); };
+            eventWaiter = wake;
             abort.signal.addEventListener("abort", wake, { once: true });
           });
           let reportedWait = false;
@@ -143,21 +152,23 @@ export function createAudioStreamGateway({ config, models, replies, synthesize =
               } else if (event.type === "audio") {
                 if (!rate) throw fault("voice_audio_format", 502);
                 for (let offset = 0; offset < event.chunk.length; offset += 16384) {
-                  while (pausedAt || sentFrames - playedFrames > rate * 2 || client.bufferedAmount > 128 * 1024) {
-                    if (!reportedWait) { reportedWait = true; metric({ stage: "playback_wait", voiceId: grant.scope.id, sentFrames, playedFrames, paused: Boolean(pausedAt) }); }
-                    // A device switch or a locked screen can stop playout for a
-                    // while without the client being gone. Wait for it to come
-                    // back instead of ending the answer after ten seconds.
+                  // Stay a short lead ahead of playout. Reported frames move
+                  // the playhead; if those ticks stop, the reply still advances
+                  // with the clock. The socket buffer is only a fuse for a
+                  // client that has stopped reading.
+                  const sentMs = () => sentFrames * 1000 / rate;
+                  while (clock.paused || clock.blocked(sentMs()) || client.bufferedAmount > SOCKET_FUSE_BYTES) {
+                    if (!reportedWait) { reportedWait = true; metric({ stage: "playback_wait", voiceId: grant.scope.id, sentFrames, playedFrames, paused: clock.paused }); }
                     await new Promise((resolve, reject) => {
-                      // A locked screen or a device switch is a pause, not a
-                      // lost client: hold the answer long enough for the page
-                      // to come back before failing it.
-                      const limit = pausedAt ? Math.max(1, pauseHoldMs - (Date.now() - pausedAt)) : playbackStallMs;
-                      const timer = setTimeout(() => { waiter = null; reject(fault(pausedAt ? "voice_interruption_timeout" : "voice_audio_backpressure")); }, limit);
-                      waiter = () => { clearTimeout(timer); resolve(); };
+                      const reading = !clock.paused && client.bufferedAmount <= SOCKET_FUSE_BYTES;
+                      const limit = clock.paused ? Math.max(1, pauseHoldMs - (Date.now() - pausedAt)) : reading ? Math.max(15, Math.min(250, clock.wait(sentMs()) || 15)) : playbackStallMs;
+                      const timer = setTimeout(() => { creditWaiter = null; if (reading) resolve(); else reject(fault(clock.paused ? "voice_interruption_timeout" : "voice_audio_backpressure")); }, limit);
+                      creditWaiter = () => { clearTimeout(timer); resolve(); };
+                      if (!(clock.paused || clock.blocked(sentMs()) || client.bufferedAmount > SOCKET_FUSE_BYTES)) { clearTimeout(timer); creditWaiter = null; resolve(); }
                     });
                     if (abort.signal.aborted || client.readyState !== 1) throw fault("voice_cancelled");
                   }
+                  clock.start();
                   if (client.readyState !== 1) throw fault("voice_cancelled");
                   const part = event.chunk.subarray(offset, offset + 16384);
                   sentFrames += part.length / 2;

package/voice/unified-conversation.js

@@ -64,7 +64,7 @@ export function createUnifiedConversation({ request, socket: openSocket = browse
         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 = current.chain.then(() => { if (reply === current) return player.write(decodeBase64(delta)); });
       current.chain.catch(() => {});
     },
     async done() {