@olares/lares-core 0.15.29 → 0.15.31

package/i18n/voice.js

@@ -4,6 +4,7 @@ export const ZH = {
   "tts.default": "模型默认",
   "tts.loading": "正在加载音色…",
   "tts.loadFailed": "音色加载失败，请重试",
+  "tts.stale": "这次没能刷新音色，显示的是上次成功加载的列表。",
   "tts.noPresets": "此模型不提供预设音色，使用模型默认声音。",
   "tts.preview": "试听",
   "tts.stopPreview": "停止试听",
@@ -314,6 +315,7 @@ export const EN = {
   "tts.default": "Model default",
   "tts.loading": "Loading voices…",
   "tts.loadFailed": "Could not load voices. Try again.",
+  "tts.stale": "Could not refresh voices; showing the last list that loaded.",
   "tts.noPresets": "This model has no preset voices. Its default voice will be used.",
   "tts.preview": "Preview voice",
   "tts.stopPreview": "Stop preview",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@olares/lares-core",
-  "version": "0.15.29",
+  "version": "0.15.31",
   "description": "Lares 共享业务核心：Router、workspace、文件/媒体、Olares 身份（无 UI、无平台壳）",
   "type": "module",
   "repository": {
@@ -115,6 +115,7 @@
     "./voice/stream-client": "./voice/stream-client.js",
     "./voice/pcm-player": "./voice/pcm-player.js",
     "./voice/pcm-worklet": "./voice/pcm-worklet.js",
+    "./voice/wake-lock": "./voice/wake-lock.js",
     "./voice/config": "./voice/config.js",
     "./voice/languages": "./voice/languages.js",
     "./voice/service": "./voice/service.js",

package/voice/lares-realtime-gateway.js

@@ -20,6 +20,9 @@ const BARGE_IN_LIMIT_MS = 10_000;
 // 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 } });
@@ -179,7 +182,7 @@ export function createLaresRealtimeGateway({ service, config, transcribe, synthe
           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 > 10_000) throw new Error("voice_audio_backpressure");
+          if (Date.now() - playedAt > PLAYOUT_STALL_MS) throw new Error("voice_audio_backpressure");
           await new Promise((resolve) => setTimeout(resolve, 20));
         }
         if (current.abort.signal.aborted || current.done || closed || client.readyState !== 1) return;

package/voice/pcm-player.js

@@ -3,6 +3,21 @@ import { pcmSamples } from "./realtime-audio.js";
 
 let primed = null;
 const worklets = new WeakMap();
+let watchingVisibility = false;
+
+/** iOS/macOS suspend the page's context on a call, the lock screen or a device switch. */
+function resumeIfInterrupted(context) {
+  if (!context || context.state === "closed" || context.state === "running") return;
+  void context.resume?.().catch(() => {});
+}
+
+function watchVisibility() {
+  if (watchingVisibility || typeof document === "undefined" || !document.addEventListener) return;
+  watchingVisibility = true;
+  document.addEventListener("visibilitychange", () => {
+    if (document.visibilityState === "visible") resumeIfInterrupted(primed);
+  });
+}
 
 function ensureWorklet(ctx) {
   const pending = worklets.get(ctx);
@@ -35,7 +50,9 @@ export function createPcmStreamPlayer({ onProgress = () => {}, onMetric = () =>
    * gets a fresh context instead of a silent failure.
    */
   const openContext = async (shared) => {
+    watchVisibility();
     if (shared) {
+      shared.addEventListener?.("statechange", () => resumeIfInterrupted(shared));
       try {
         await ensureWorklet(shared);
         await shared.resume?.();
@@ -49,6 +66,7 @@ export function createPcmStreamPlayer({ onProgress = () => {}, onMetric = () =>
     }
     const fresh = new Context();
     owned = true;
+    fresh.addEventListener?.("statechange", () => resumeIfInterrupted(fresh));
     try {
       await ensureWorklet(fresh);
       await fresh.resume?.();
@@ -117,6 +135,9 @@ export function createPcmStreamPlayer({ onProgress = () => {}, onMetric = () =>
     pause() { paused = true; node?.port.postMessage({ type: "pause" }); },
     resume() { paused = false; node?.port.postMessage({ type: "resume" }); },
     get paused() { return paused; },
+    /** The browser's own view; a phone can report "running" while the OS has muted it. */
+    contextState: () => context?.state || "missing",
+    sampleRate: () => context?.sampleRate || 0,
     playedFrames: () => played,
     stop,
   };

package/voice/presentation.js

@@ -39,17 +39,14 @@ export function voiceCallFailure(view) {
 }
 
 /**
- * Playback stays visible at the composer until it ends.
- * A hidden readout call and a chat reader both use this one strip:
- * status plus the control that stops it. The hold button is not that strip.
+ * 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.
  */
-export function voicePlaybackChrome(view, readout) {
+export function voicePlaybackChrome(view) {
   const playback = view?.snapshot?.playback;
-  if (playback && playback !== "idle") {
-    return { status: voicePanelPresentation(view).status, stop: "call", stopLabel: "panel.close" };
-  }
-  if (!readout) return null;
-  return { status: `readout.${readout.status}`, stop: "readout", stopLabel: readout.status === "error" ? "readout.dismiss" : "panel.close" };
+  if (!playback || playback === "idle") return null;
+  return { status: voicePanelPresentation(view).status, stop: "call", stopLabel: "panel.close" };
 }
 
 /** Shared inline labels; clients own focus, positioning and the timer tick. */

package/voice/stream-client.js

@@ -30,13 +30,34 @@ function streamMetric(options, event) {
   });
 }
 
+/**
+ * What a phone-side failure needs next to the frames: a WebView can keep
+ * reporting a running context while the app is hidden or the OS muted it, so
+ * the page and platform state travel with the metric.
+ */
+function clientFacts() {
+  const nav = globalThis.navigator || {};
+  return {
+    visibility: String(globalThis.document?.visibilityState || "unknown").slice(0, 16),
+    hidden: globalThis.document?.hidden === true,
+    platform: String(nav.userAgentData?.platform || nav.platform || "").slice(0, 40),
+    ua: String(nav.userAgent || "").slice(0, 180),
+  };
+}
+
 export async function playAudioStream(options) {
   const started = Date.now();
   const connection = await openAudioStream({ ...options, operation: "tts" });
   if (!connection) throw new Error("voice_stream_failed");
   const file = createBrowserPlayer();
   let progressNoted = false, progressBlocked = false;
+  // A phone that suspends the WebView stops the worklet without closing the
+  // socket, so the host waits for frames that will never come. Report that gap
+  // with the page/context state instead of leaving the next test guessing.
+  let lastProgressAt = Date.now(), gapReported = false, gapAt = 0, formatNoted = false;
   const player = createPcmStreamPlayer({ onProgress: (frames) => {
+    lastProgressAt = Date.now();
+    if (gapReported) { gapReported = false; streamMetric(options, { stage: "playback_gap_end", frames, gapMs: Date.now() - gapAt, ...clientFacts(), context: player.contextState() }); }
     if (connection.readyState !== 1) {
       if (!progressBlocked) { progressBlocked = true; streamMetric(options, { stage: "playback_progress_blocked", readyState: connection.readyState, frames }); }
       return;
@@ -50,6 +71,17 @@ export async function playAudioStream(options) {
   },
     onMetric: (event) => { if (event.stage === "playback_started") options.onStatus?.("playing"); streamMetric(options, { ...event, durationMs: Date.now() - started }); } });
   let chain = Promise.resolve(), complete = false, ending = false, firstReceived = false, ready = false, paused = false, segmentIndex = -1;
+  const gapWatch = setInterval(() => {
+    if (!ready || paused || complete || gapReported || Date.now() - lastProgressAt < 4000) return;
+    gapReported = true;
+    gapAt = lastProgressAt;
+    streamMetric(options, { stage: "playback_gap", gapMs: Date.now() - lastProgressAt, frames: player.playedFrames(), ...clientFacts(), context: player.contextState(), sampleRate: player.sampleRate() });
+  }, 1000);
+  gapWatch.unref?.();
+  const noteVisibility = () => {
+    if (ready && !complete) streamMetric(options, { stage: "playback_visibility", frames: player.playedFrames(), paused, ...clientFacts(), context: player.contextState() });
+  };
+  if (typeof document !== "undefined" && document.addEventListener) document.addEventListener("visibilitychange", noteVisibility);
   options.controls?.({
     get canPause() { return ready; },
     pause() { if (!ready || paused) return; paused = true; player.pause(); file.pause(); if (connection.readyState === 1) connection.send(JSON.stringify({ type: "pause" })); },
@@ -82,7 +114,10 @@ export async function playAudioStream(options) {
             segmentIndex = event.index;
           }
           else if (event.type === "segment.end") options.onSegment?.(event);
-          else if (event.type === "format") { await player.start(event); ready = true; if (paused) player.pause(); }
+          else if (event.type === "format") {
+            await player.start(event); ready = true; lastProgressAt = Date.now(); if (paused) player.pause();
+            if (!formatNoted) { formatNoted = true; streamMetric(options, { stage: "playback_client", sampleRate: event.sampleRate, context: player.contextState(), ...clientFacts() }); }
+          }
           else if (event.type === "file") { ready = true; options.onStatus?.("playing"); await file.play(wavBlob(event.audio)); if (connection.readyState === 1) connection.send(JSON.stringify({ type: "file.done" })); }
           else if (event.type === "error") throw new Error(event.code || "voice_stream_failed");
           else if (event.type === "done") { await player.finish(); complete = true; resolve(); }
@@ -97,7 +132,11 @@ export async function playAudioStream(options) {
       if (options.signal?.aborted) cancelled();
     });
     return true;
-  } finally { player.stop(); file.stop(); connection.close(); }
+  } finally {
+    clearInterval(gapWatch);
+    if (typeof document !== "undefined" && document.removeEventListener) document.removeEventListener("visibilitychange", noteVisibility);
+    player.stop(); file.stop(); connection.close();
+  }
 }
 
 /** A single final ASR result; partials never submit a task or replace the draft. */

package/voice/stream-gateway.js

@@ -10,7 +10,7 @@ import { routerGatewayUrl, routerAuthHeaders } from "../router/gateway.js";
 const fault = (code, status = 409) => new VoiceError(code, status, code);
 
 /** Single-use HTTP grants bind raw audio sockets to the authenticated Host scope. */
-export function createAudioStreamGateway({ config, models, replies, synthesize = synthesizeStream, env = process.env, metric = () => {} }) {
+export function createAudioStreamGateway({ config, models, replies, synthesize = synthesizeStream, env = process.env, metric = () => {}, playbackStallMs = 45_000, pauseHoldMs = 120_000, lifetimeMs = 300_000 }) {
   const tickets = new Map(), clients = new Set();
   const synthesis = createSynthesisRuns({ synthesize, metric });
   const server = new WebSocketServer({ noServer: true, maxPayload: 96 * 1024, perMessageDeflate: false,
@@ -66,7 +66,7 @@ export function createAudioStreamGateway({ config, models, replies, synthesize =
           if (grant.operation === "tts" && code !== "voice_cancelled") metric({ stage: "playback_stop", voiceId: grant.scope.id, code, sentFrames, playedFrames });
           send({ type: "error", code }); close();
         };
-        const lifetime = setTimeout(() => error(fault("voice_timeout")), 180000);
+        const lifetime = setTimeout(() => error(fault("voice_timeout")), lifetimeMs);
         client.on("close", close); client.on("error", close);
         client.on("message", (raw, binary) => {
           try {
@@ -145,7 +145,17 @@ export function createAudioStreamGateway({ config, models, replies, synthesize =
                 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) }); }
-                    await new Promise((resolve, reject) => { const timer = setTimeout(() => { waiter = null; reject(fault(pausedAt ? "voice_interruption_timeout" : "voice_audio_backpressure")); }, pausedAt ? Math.max(1, 10000 - (Date.now() - pausedAt)) : 10000); waiter = () => { clearTimeout(timer); resolve(); }; });
+                    // 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.
+                    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(); };
+                    });
                     if (abort.signal.aborted || client.readyState !== 1) throw fault("voice_cancelled");
                   }
                   if (client.readyState !== 1) throw fault("voice_cancelled");

package/voice/tts-settings.js

@@ -12,7 +12,10 @@ export function ttsSettingsModel(value) {
 /** Framework-neutral settings lifecycle; model switches invalidate both audio and directory results. */
 export function createTtsSettings({ preferences, list = fetchTtsVoices, preview, activity = voiceActivity }) {
   const initialModel = ttsSettingsModel(preferences.getSnapshot().value);
-  let state = { model: initialModel, voices: [], selected: ttsVoiceForModel(preferences.getSnapshot().value?.config || {}, initialModel) || "", loading: Boolean(initialModel), error: null, saving: false, playing: false, previewError: null, blocked: activity.getSnapshot(), unavailable: false };
+  let state = { model: initialModel, voices: [], selected: ttsVoiceForModel(preferences.getSnapshot().value?.config || {}, initialModel) || "", loading: Boolean(initialModel), error: null, stale: false, saving: false, playing: false, previewError: null, blocked: activity.getSnapshot(), unavailable: false };
+  // A transient failure keeps the last directory this page loaded for the model
+  // instead of turning a working voice picker into an error screen.
+  const cached = new Map();
   const listeners = new Set();
   let generation = 0, listing = null, playing = null, disposed = false;
   const emit = patch => { if (disposed) return; state = { ...state, ...patch }; for (const listener of listeners) listener(); };
@@ -25,16 +28,20 @@ export function createTtsSettings({ preferences, list = fetchTtsVoices, preview,
   const load = async () => {
     const token = ++generation; listing?.abort(); stop();
     const model = ttsSettingsModel(preferences.getSnapshot().value);
-    emit({ model, voices: [], loading: Boolean(model), error: null, unavailable: false, previewError: null });
+    emit({ model, voices: [], loading: Boolean(model), error: null, stale: false, unavailable: false, previewError: null });
     updateSelection();
     if (!model) return;
     const abort = listing = new AbortController();
     try {
-      const voices = await list(model, { signal: AbortSignal.any([abort.signal, AbortSignal.timeout(10000)]) });
+      const voices = await list(model, { signal: AbortSignal.any([abort.signal, AbortSignal.timeout(30_000)]) });
       if (token !== generation || disposed) return;
-      emit({ voices, loading: false }); updateSelection();
+      cached.set(model, voices);
+      emit({ voices, loading: false, error: null, stale: false }); updateSelection();
     } catch (error) {
-      if (token === generation && !disposed && !abort.signal.aborted) emit({ loading: false, error: "tts_voices_failed" });
+      if (token !== generation || disposed || abort.signal.aborted) return;
+      const previous = cached.get(model);
+      if (previous) { emit({ voices: previous, loading: false, error: null, stale: true }); updateSelection(); }
+      else emit({ loading: false, error: "tts_voices_failed", stale: false });
     }
   };
   let wasLoading = preferences.getSnapshot().loading, catalog = JSON.stringify(preferences.getSnapshot().value?.ttsModels || []);

package/voice/tts-voice.js

@@ -4,17 +4,58 @@ export function ttsVoiceForModel(config, model) {
   return config.ttsModel === model ? config.voice || undefined : undefined;
 }
 
-export async function fetchTtsVoices(model, { signal, fetcher = fetch } = {}) {
-  const res = await fetcher(`/llm/v1/audio/voices?model=${encodeURIComponent(model)}`, { signal: signal ?? AbortSignal.timeout(10000) });
-  const body = await res.json().catch(() => null);
-  if ((res.status === 404 && /no preset voices/i.test(String(body?.detail || body?.error?.message || ""))) || res.status === 405 || res.status === 501) return [];
-  if (!res.ok) throw new Error("tts_voices_failed");
-  if (!Array.isArray(body?.voices)) throw new Error("tts_voices_failed");
-  const seen = new Set();
-  return body.voices.flatMap(row => {
-    const id = typeof row === "string" ? row : row?.id;
-    if (typeof id !== "string" || !id || seen.has(id)) return [];
-    seen.add(id);
-    return [{ id, label: typeof row?.name === "string" && row.name.trim() ? row.name : id }];
+// A cold or busy TTS engine answers 5xx until its model is ready. The directory
+// is metadata, so a couple of short retries are enough and keep the settings
+// usable instead of failing on the first probe.
+const ATTEMPT_TIMEOUT_MS = 8_000;
+const RETRY_DELAYS_MS = [500, 1_500];
+const TRANSIENT_STATUS = new Set([429, 500, 502, 503, 504]);
+
+function delay(ms, signal) {
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => { cleanup(); resolve(); }, ms);
+    const stop = () => { cleanup(); reject(new Error("voice_voices_aborted")); };
+    const cleanup = () => { clearTimeout(timer); signal?.removeEventListener("abort", stop); };
+    signal?.addEventListener("abort", stop, { once: true });
+    if (signal?.aborted) stop();
   });
 }
+
+function attemptSignal(signal) {
+  const timeout = typeof AbortSignal?.timeout === "function" ? AbortSignal.timeout(ATTEMPT_TIMEOUT_MS) : null;
+  if (signal && timeout && typeof AbortSignal.any === "function") {
+    try { return AbortSignal.any([signal, timeout]); } catch { /* caller signal only */ }
+  }
+  return signal ?? timeout ?? undefined;
+}
+
+export async function fetchTtsVoices(model, { signal, fetcher = fetch, retryDelays = RETRY_DELAYS_MS } = {}) {
+  const url = `/llm/v1/audio/voices?model=${encodeURIComponent(model)}`;
+  const failure = new Error("tts_voices_failed");
+  for (let attempt = 0; ; attempt += 1) {
+    try {
+      const res = await fetcher(url, { signal: attemptSignal(signal) });
+      const body = await res.json().catch(() => null);
+      if ((res.status === 404 && /no preset voices/i.test(String(body?.detail || body?.error?.message || ""))) || res.status === 405 || res.status === 501) return [];
+      if (!res.ok) {
+        if (TRANSIENT_STATUS.has(res.status) && attempt < retryDelays.length && !signal?.aborted) {
+          await delay(retryDelays[attempt], signal);
+          continue;
+        }
+        throw failure;
+      }
+      if (!Array.isArray(body?.voices)) throw failure;
+      const seen = new Set();
+      return body.voices.flatMap(row => {
+        const id = typeof row === "string" ? row : row?.id;
+        if (typeof id !== "string" || !id || seen.has(id)) return [];
+        seen.add(id);
+        return [{ id, label: typeof row?.name === "string" && row.name.trim() ? row.name : id }];
+      });
+    } catch (error) {
+      if (error === failure) throw failure;
+      if (signal?.aborted || attempt >= retryDelays.length) throw failure;
+      await delay(retryDelays[attempt], signal);
+    }
+  }
+}

package/voice/wake-lock.js

@@ -0,0 +1,52 @@
+/**
+ * A phone that turns its screen off suspends the WebView: the AudioContext is
+ * interrupted and the socket is torn down, so a long answer stops after the
+ * first sentences. Keeping the screen awake for the length of a readout is the
+ * only part of that chain the page itself can control.
+ *
+ * The lock is only a hint. A WebView without `navigator.wakeLock`, or a request
+ * the platform refuses (no gesture, low power mode), must leave playback alone.
+ */
+export function createScreenWakeLock(nav = globalThis.navigator, doc = globalThis.document) {
+  let sentinel = null;
+  let wanted = false;
+  let watching = false;
+  const supported = () => typeof nav?.wakeLock?.request === "function";
+
+  const drop = () => {
+    const held = sentinel;
+    sentinel = null;
+    if (!held) return;
+    try { void held.release?.()?.catch?.(() => {}); } catch { /* already released */ }
+  };
+
+  const acquire = async () => {
+    if (!wanted || sentinel || !supported() || doc?.visibilityState === "hidden") return false;
+    try {
+      const held = await nav.wakeLock.request("screen");
+      // The answer may have ended while the platform was answering the request.
+      if (!wanted) { try { void held.release?.()?.catch?.(() => {}); } catch { /* already released */ } return false; }
+      sentinel = held;
+      held.addEventListener?.("release", () => { if (sentinel === held) sentinel = null; });
+      return true;
+    } catch {
+      return false;
+    }
+  };
+
+  // A hidden page loses its lock. Re-acquire through the platform's own rule
+  // instead of guessing when the page is allowed to hold one again.
+  const watch = () => {
+    if (watching || !doc?.addEventListener) return;
+    watching = true;
+    doc.addEventListener("visibilitychange", () => { if (wanted && doc.visibilityState === "visible") void acquire(); });
+  };
+
+  return {
+    get supported() { return supported(); },
+    get held() { return Boolean(sentinel); },
+    /** Ask for the lock; resolves to whether the platform granted it. */
+    async hold() { wanted = true; watch(); return acquire(); },
+    release() { wanted = false; drop(); },
+  };
+}