@olares/lares-core 0.15.17 → 0.15.19

package/voice/stream-client.js

@@ -0,0 +1,165 @@
+import { postReport } from "../log/report.js";
+import { PCM_CAPTURE_WORKLET } from "./pcm-worklet.js";
+import { createPcmResampler } from "./realtime-audio.js";
+import { createPcmStreamPlayer } from "./pcm-player.js";
+import { wavBlob } from "./client.js";
+import { createBrowserPlayer } from "./browser-playback.js";
+
+export function browserAudioSocket(ticket) {
+  const url = new URL("/api/lares/voice/stream", globalThis.location.href); url.protocol = url.protocol === "https:" ? "wss:" : "ws:";
+  return new WebSocket(url, ["lares-voice", `lares-ticket.${ticket}`]);
+}
+
+export async function openAudioStream({ request, headers, operation, model, language, text, source, signal, socket = browserAudioSocket }) {
+  const response = await request("/api/lares/voice/stream/ticket", { method: "POST", headers, signal, body: { operation, model, language, text, source } });
+  if (!response?.ok) throw new Error(response?.body?.error?.code || "voice_stream_failed");
+  if (!response.body.supported) return null;
+  if (signal?.aborted) throw new Error("voice_cancelled");
+  const connection = socket(response.body.ticket); connection.binaryType = "arraybuffer";
+  const cancel = () => connection.close();
+  signal?.addEventListener("abort", cancel, { once: true });
+  connection.addEventListener("close", () => signal?.removeEventListener("abort", cancel), { once: true });
+  return connection;
+}
+
+/** Plays one confirmed reply. Receiving audio and rendering it run independently. */
+function streamMetric(options, event) {
+  if (options.metric) { options.metric(event); return; }
+  void postReport({ scope: "voice", event: "metric", voiceId: options.headers?.["x-lares-voice-id"], utteranceKey: options.key, at: Date.now(), ...event }, {
+    request: (path, init) => options.request(path, { ...init, headers: { ...init.headers, ...options.headers } }),
+  });
+}
+
+export async function playAudioStream(options) {
+  const started = Date.now();
+  const connection = await openAudioStream({ ...options, operation: "tts" });
+  if (!connection) {
+    const response = await options.request("/api/lares/voice/speak", { method: "POST", headers: options.headers, signal: options.signal, body: { text: options.text } });
+    if (!response?.ok) throw new Error(response?.body?.error?.code || "voice_stream_failed");
+    if (response.body.sentences === 0) return true;
+    if (response.body.bluetooth === "played") return true;
+    if (options.source) throw new Error("voice_reply_unavailable");
+    const fallback = createBrowserPlayer();
+    options.controls?.({ canPause: true, pause: () => fallback.pause(), resume: () => fallback.resume() });
+    options.onStatus?.("playing");
+    const cancel = () => fallback.stop(); options.signal?.addEventListener("abort", cancel, { once: true });
+    try { if (!options.signal?.aborted) await fallback.play(wavBlob(response.body.audio)); } finally { options.signal?.removeEventListener("abort", cancel); fallback.stop(); }
+    return true;
+  }
+  const file = createBrowserPlayer();
+  const player = createPcmStreamPlayer({ onProgress: (frames) => { if (connection.readyState === 1) connection.send(JSON.stringify({ type: "progress", frames })); },
+    onMetric: (event) => { if (event.stage === "playback_started") options.onStatus?.("playing"); streamMetric(options, { ...event, durationMs: Date.now() - started }); } });
+  let chain = Promise.resolve(), complete = false, firstReceived = false, ready = false, paused = false, segmentIndex = -1;
+  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" })); },
+    resume() { if (!ready || !paused) return; paused = false; player.resume(); void file.resume()?.catch(() => connection.close()); if (connection.readyState === 1) connection.send(JSON.stringify({ type: "resume" })); },
+  });
+  try {
+    await new Promise((resolve, reject) => {
+      const fail = (error) => { reject(error); connection.close(); };
+      const cancelled = () => { player.stop(); file.stop(); fail(new Error("voice_cancelled")); };
+      options.signal?.addEventListener("abort", cancelled, { once: true });
+      connection.addEventListener("message", ({ data }) => {
+        if (typeof data !== "string" && !firstReceived) { firstReceived = true; streamMetric(options, { stage: "playback_first_received", durationMs: Date.now() - started }); }
+        chain = chain.then(async () => {
+          if (options.signal?.aborted) throw new Error("voice_cancelled");
+          if (typeof data !== "string") { player.write(new Uint8Array(data)); return; }
+          const event = JSON.parse(data);
+          if (event.type === "segment") {
+            if (event.index !== segmentIndex + 1) throw new Error("voice_reply_sequence");
+            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 === "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(); }
+        }).catch(fail);
+      });
+      connection.addEventListener("error", () => fail(new Error("voice_disconnected")), { once: true });
+      connection.addEventListener("close", () => { options.signal?.removeEventListener("abort", cancelled); if (!complete) reject(new Error("voice_disconnected")); }, { once: true });
+      if (options.signal?.aborted) cancelled();
+    });
+    return true;
+  } finally { player.stop(); file.stop(); connection.close(); }
+}
+
+/** A single final ASR result; partials never submit a task or replace the draft. */
+export async function startTranscriptionStream(options) {
+  const connection = await openAudioStream({ ...options, operation: "stt" });
+  if (!connection) return null;
+  let final = null, finished = false, completed = false, failed = false, finishAt = 0, resolve, reject;
+  const result = new Promise((yes, no) => { resolve = yes; reject = no; });
+  void result.catch(() => {});
+  let readyResolve, readyReject;
+  const ready = new Promise((yes, no) => { readyResolve = yes; readyReject = no; });
+  const fail = (error) => {
+    if (completed || failed) return;
+    failed = true;
+    const code = /^voice_[a-z_]+$/.test(error.message) ? error.message : "voice_stream_failed";
+    if (code !== "voice_cancelled" && !options.signal?.aborted) void postReport({ scope: "voice", event: "stream-error", stage: "recognition", code }, {
+      request: (path, init) => options.request(path, { ...init, headers: { ...init.headers, ...options.headers } }),
+    });
+    readyReject(error); reject(error); connection.close();
+  };
+  connection.addEventListener("message", ({ data }) => {
+    try {
+      const event = JSON.parse(data);
+      if (event.type === "ready") readyResolve();
+      else if (event.type === "partial") options.onPartial?.(event.text);
+      else if (event.type === "final") final = event.text;
+      else if (event.type === "done" && finished && final !== null) { completed = true; streamMetric(options, { stage: "recognition_final_tail", durationMs: Date.now() - finishAt }); resolve(final); }
+      else if (event.type === "error") fail(new Error(event.code));
+    } catch { fail(new Error("voice_stream_failed")); }
+  });
+  connection.addEventListener("close", () => fail(new Error("voice_disconnected")), { once: true });
+  connection.addEventListener("error", () => fail(new Error("voice_disconnected")), { once: true });
+  if (options.signal?.aborted) fail(new Error("voice_cancelled"));
+  await ready;
+  return {
+    write(bytes) { if (finished || connection.readyState !== 1 || connection.bufferedAmount > 256 * 1024) throw new Error("voice_audio_backpressure"); connection.send(bytes); },
+    async finish() { finishAt = Date.now(); finished = true; connection.send(JSON.stringify({ type: "finish" })); try { return await result; } finally { connection.close(); } },
+    cancel() { fail(new Error("voice_cancelled")); },
+  };
+}
+
+export async function createStreamingCapture(stream, options) {
+  const port = await startTranscriptionStream(options);
+  if (!port) return null;
+  let context, source, node, failure, flushed;
+  const release = () => {
+    source?.disconnect(); source = null;
+    node?.disconnect(); if (node) node.port.onmessage = null; node = null;
+    const opened = context; context = null;
+    if (opened && opened.state !== "closed") void opened.close().catch(() => {});
+  };
+  try {
+    const Context = globalThis.AudioContext || globalThis.webkitAudioContext;
+    context = new Context();
+    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);
+    source = context.createMediaStreamSource(stream);
+    node = new AudioWorkletNode(context, "lares-pcm-capture", { numberOfOutputs: 1, outputChannelCount: [1] });
+    node.port.onmessage = ({ data }) => {
+      if (data.type === "flushed") { flushed?.(); return; }
+      try { port.write(convert(data.samples)); } catch (cause) { failure = cause; port.cancel(); }
+    };
+    source.connect(node); node.connect(context.destination);
+    return {
+      async finish() {
+        try {
+          await new Promise((resolve, reject) => { const timer = setTimeout(() => reject(new Error("voice_timeout")), 2000); flushed = () => { clearTimeout(timer); resolve(); }; node.port.postMessage({ type: "flush" }); });
+          // No capture messages may follow the ASR commit, even while finalization waits.
+          release();
+          if (failure) throw failure;
+          return await port.finish();
+        } catch (cause) { port.cancel(); throw cause; }
+        finally { release(); }
+      },
+      cancel() { port.cancel(); release(); },
+    };
+  } catch (cause) { port.cancel(); release(); throw cause; }
+}

package/voice/stream-gateway.js

@@ -0,0 +1,146 @@
+import { ttsVoiceForModel } from "./tts-voice.js";
+import { speechSegments } from "./script.js";
+import { randomUUID } from "node:crypto";
+import { WebSocket, WebSocketServer } from "ws";
+import { synthesizeStream } from "../router/tts.js";
+import { pickSttModelId, pickTtsModelId, VoiceError } from "../router/stt.js";
+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 = () => {} }) {
+  const tickets = new Map(), clients = new Set();
+  const server = new WebSocketServer({ noServer: true, maxPayload: 96 * 1024, perMessageDeflate: false,
+    handleProtocols: (values) => values.has("lares-voice") ? "lares-voice" : false });
+  return {
+    async ticket(scope, body) {
+      if (scope.device !== "device") return { supported: false };
+      if (!["tts", "stt"].includes(body.operation)) throw fault("voice_config_invalid", 400);
+      const tts = body.operation === "tts";
+      const snapshot = structuredClone(scope.voiceConfig || config());
+      if (tts && (scope.presentationSession || !scope.active)) {
+        const current = config();
+        snapshot.ttsModel = current.ttsModel; snapshot.voice = current.voice;
+        snapshot.ttsVoiceByModel = structuredClone(current.ttsVoiceByModel || {});
+      }
+      const rows = await models();
+      if (tts && !(scope.active ? scope.readAloud : snapshot.speak)) throw fault("voice_speak_disabled");
+      const selected = tts ? pickTtsModelId(rows, snapshot.ttsModel) : pickSttModelId(rows, body.model || snapshot.model);
+      if (!selected || tts && snapshot.ttsModel && selected !== snapshot.ttsModel) throw fault("voice_model_unavailable", 503);
+      if (!tts && !rows.find((row) => row.id === selected)?.supportsSttStream) return { supported: false };
+      if (tts && !body.source && (typeof body.text !== "string" || !body.text.trim() || body.text.length > 8192)) throw fault("voice_config_invalid", 400);
+      for (const [key, grant] of tickets) if (grant.expires < Date.now()) tickets.delete(key);
+      if (tickets.size >= 128 || clients.size >= 64) throw fault("voice_busy", 429);
+      const reply = tts && body.source ? await replies?.bind(scope, body.source) : null;
+      if (body.source && !reply) throw fault("voice_reply_unavailable");
+      const ticket = randomUUID();
+      tickets.set(ticket, { scope, model: selected, operation: body.operation, text: body.text, reply,
+        config: snapshot, language: body.language || snapshot.language, expires: Date.now() + 30000 });
+      return { supported: true, ticket };
+    },
+    upgrade(req, socket, head) {
+      const token = String(req.headers["sec-websocket-protocol"] || "").split(",").map((value) => value.trim()).find((value) => value.startsWith("lares-ticket."))?.slice(13);
+      const grant = tickets.get(token); tickets.delete(token);
+      if (!grant || grant.expires < Date.now()) { socket.end("HTTP/1.1 403 Forbidden\r\nConnection: close\r\n\r\n"); return; }
+      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 fileDone = null, pausedAt = 0, closing = false;
+        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(); clients.delete(client); client.close(); };
+        const error = (cause) => { send({ type: "error", code: cause.code || "voice_stream_failed" }); close(); };
+        const lifetime = setTimeout(() => error(fault("voice_timeout")), 180000);
+        client.on("close", close); client.on("error", close);
+        client.on("message", (raw, binary) => {
+          try {
+            if (grant.operation === "stt") {
+              if (!upstream || upstream.readyState !== 1 || committed) throw fault("voice_stream_state");
+              if (binary) {
+                received += raw.length;
+                if (raw.length % 2 || received > 16000 * 2 * 60 || upstream.bufferedAmount > 256 * 1024) throw fault("voice_audio_backpressure");
+                upstream.send(raw);
+              } else {
+                const frame = JSON.parse(String(raw));
+                if (frame.type !== "finish") throw fault("voice_stream_state");
+                committed = true; upstream.send(JSON.stringify({ type: "finish" }));
+              }
+            } 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 === "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");
+              playedFrames = frame.frames; waiter?.(); waiter = null;
+            }
+          } catch (cause) { error(cause); }
+        });
+        if (grant.operation === "stt") {
+          upstream = new WebSocket(`${routerGatewayUrl(env).replace(/^http/, "ws")}/audio/stream?model=${encodeURIComponent(grant.model)}`, {
+            headers: routerAuthHeaders(env.LARES_ROUTER_API_KEY, env.OLARES_APP_ID, grant.scope.owner), handshakeTimeout: 15000, maxPayload: 96 * 1024 });
+          upstream.on("open", () => { upstream.send(JSON.stringify({ type: "start", sample_rate: 16000, language: grant.language || undefined })); send({ type: "ready" }); });
+          upstream.on("message", (raw, binary) => {
+            try {
+              if (binary) throw fault("voice_audio_format");
+              const value = JSON.parse(String(raw));
+              if (["partial", "final"].includes(value.type)) send({ type: value.type, text: String(value.text || "") });
+              else if (value.type === "error") error(fault("voice_transcribe_failed", 502));
+              else if (value.type === "closed") { if (!committed) throw fault("voice_stream_state"); send({ type: "done" }); }
+            } catch (cause) { error(cause); }
+          });
+          upstream.on("error", error);
+          upstream.on("close", () => { send({ type: "eof" }); close(); });
+        } else {
+          // A stop/new output owns the scope's existing duplex lease too.
+          const lease = grant.scope.duplex.beginSpeech(abort.signal);
+          const segments = grant.reply ? grant.reply(lease.signal) : speechSegments(grant.text, { done: true }).map((text, index) => ({ text, index }));
+          let carry = null;
+          const run = async () => { for await (const segment of segments) {
+          if (!lease.active()) throw fault("voice_cancelled");
+          const { text, index } = segment;
+          metric({ stage: "synthesis_segment", voiceId: grant.scope.id, index, chars: text.length, at: Date.now() });
+          send({ type: "segment", index, attemptId: segment.attemptId, startFrame: sentFrames });
+          const result = await synthesize({ text, model: grant.model, voice: ttsVoiceForModel(grant.config, grant.model), signal: lease.signal,
+            onFormat(format) { if (outputFormat && (format.channels !== outputFormat.channels || format.encoding !== outputFormat.encoding)) throw fault("voice_audio_format"); outputFormat = format; if (!rate) { rate = format.sampleRate; send({ type: "format", ...format }); } else if (rate !== format.sampleRate) throw fault("voice_audio_format"); },
+          }, async (chunk) => {
+            if (!lease.active()) throw fault("voice_cancelled");
+            if (!rate) throw fault("voice_audio_format", 502);
+            if (carry !== null) { chunk = Buffer.concat([Buffer.from([carry]), chunk]); carry = null; }
+            if (chunk.length % 2) { carry = chunk[chunk.length - 1]; chunk = chunk.subarray(0, -1); }
+            for (let offset = 0; offset < chunk.length; offset += 16384) {
+              while (pausedAt || sentFrames - playedFrames > rate * 2 || client.bufferedAmount > 128 * 1024) {
+                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(); }; });
+                if (!lease.active() || abort.signal.aborted) throw fault("voice_cancelled");
+              }
+              if (!lease.active() || client.readyState !== 1) throw fault("voice_cancelled");
+              const part = chunk.subarray(offset, offset + 16384);
+              sentFrames += part.length / 2;
+              client.send(part);
+              if (!outputStarted) { outputStarted = true; metric({ stage: "synthesis_first_audio", voiceId: grant.scope.id, at: Date.now(), durationMs: Date.now() - started }); }
+            }
+          });
+          send({ type: "segment.end", index, endFrame: sentFrames });
+          if (carry !== null) throw fault("voice_audio_format");
+          if (!result.streamed) {
+            if (rate) throw fault("voice_audio_format");
+            await new Promise((resolve, reject) => {
+              const timer = setTimeout(() => reject(fault("voice_timeout")), 120000);
+              fileDone = () => { clearTimeout(timer); resolve(); };
+              send({ type: "file", audio: result.audio.toString("base64") });
+            });
+          }
+          if (!lease.active()) throw fault("voice_cancelled");
+          } };
+          const wake = () => { waiter?.(); waiter = null; fileDone?.(); fileDone = null; close(); };
+          lease.signal.addEventListener("abort", wake, { once: true });
+          void run().then(() => { if (!abort.signal.aborted) send({ type: "done" }); }).catch(error).finally(() => { lease.signal.removeEventListener("abort", wake); lease.finish(); });
+        }
+      });
+    },
+    close() { tickets.clear(); for (const client of clients) client.terminate(); server.close(); },
+  };
+}

package/voice/tts-preview.js

@@ -0,0 +1,27 @@
+/** Explicit audition is independent of automatic read-aloud and business sessions. */
+export async function previewTts({ model, voice, text, signal }, { fetcher = fetch, createAudio = url => new Audio(url) } = {}) {
+  const response = await fetcher("/llm/v1/audio/speech", {
+    method: "POST", headers: { "content-type": "application/json" }, signal,
+    body: JSON.stringify({ model, input: text, response_format: "wav", ...(voice ? { voice } : {}) }),
+  });
+  if (!response.ok) throw new Error("tts_preview_failed");
+  const blob = await response.blob(); signal.throwIfAborted();
+  const url = URL.createObjectURL(blob);
+  try {
+    await new Promise((resolve, reject) => {
+      const audio = createAudio(url);
+      let done = false;
+      const finish = error => {
+        if (done) return; done = true;
+        audio.pause(); audio.removeAttribute?.("src"); audio.load?.();
+        signal.removeEventListener("abort", cancelled);
+        error ? reject(error) : resolve();
+      };
+      const cancelled = () => finish(signal.reason);
+      audio.addEventListener("ended", () => finish(), { once: true });
+      audio.addEventListener("error", () => finish(new Error("tts_preview_failed")), { once: true });
+      signal.addEventListener("abort", cancelled, { once: true });
+      if (signal.aborted) cancelled(); else Promise.resolve(audio.play()).catch(finish);
+    });
+  } finally { URL.revokeObjectURL(url); }
+}

package/voice/tts-settings.js

@@ -0,0 +1,79 @@
+import { ttsVoiceForModel, fetchTtsVoices } from "./tts-voice.js";
+import { voiceActivity } from "./activity.js";
+
+export const TTS_PREVIEW_TEXT = "你好，这是 Lares 的语音试听。";
+
+export function ttsSettingsModel(value) {
+  const config = value?.config || {};
+  const ids = value?.ttsModels || [];
+  return config.ttsModel ? ids.includes(config.ttsModel) ? config.ttsModel : null : value?.ttsDefault || ids[0] || null;
+}
+
+/** 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 };
+  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(); };
+  const stop = () => { playing?.abort(); playing = null; emit({ playing: false }); };
+  const selection = () => ttsVoiceForModel(preferences.getSnapshot().value?.config || {}, state.model) || "";
+  const updateSelection = () => {
+    const selected = selection();
+    emit({ selected, unavailable: Boolean(selected && !state.loading && !state.error && !state.voices.some(row => row.id === selected)) });
+  };
+  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 });
+    updateSelection();
+    if (!model) return;
+    const abort = listing = new AbortController();
+    try {
+      const voices = await list(model, { signal: AbortSignal.any([abort.signal, AbortSignal.timeout(10000)]) });
+      if (token !== generation || disposed) return;
+      emit({ voices, loading: false }); updateSelection();
+    } catch (error) {
+      if (token === generation && !disposed && !abort.signal.aborted) emit({ loading: false, error: "tts_voices_failed" });
+    }
+  };
+  let wasLoading = preferences.getSnapshot().loading, catalog = JSON.stringify(preferences.getSnapshot().value?.ttsModels || []);
+  const off = preferences.subscribe(() => {
+    const view = preferences.getSnapshot(), refreshed = wasLoading && !view.loading;
+    wasLoading = view.loading;
+    const nextCatalog = JSON.stringify(view.value?.ttsModels || []), changed = catalog !== nextCatalog; catalog = nextCatalog;
+    const model = ttsSettingsModel(preferences.getSnapshot().value);
+    if (model !== state.model || model && (refreshed || changed)) { void load(); return; }
+    if (selection() !== state.selected) { stop(); updateSelection(); }
+  });
+  const offActivity = activity.subscribe(() => { const blocked = activity.getSnapshot(); if (blocked) stop(); emit({ blocked }); });
+  return {
+    getSnapshot: () => state,
+    subscribe(listener) { listeners.add(listener); return () => listeners.delete(listener); },
+    load,
+    stop,
+    async selectModel(model) {
+      if (state.saving) return;
+      stop(); emit({ saving: true, previewError: null });
+      try { await preferences.patch({ ttsModel: model }); }
+      finally { emit({ saving: false }); }
+    },
+    async selectVoice(voice) {
+      if (state.loading || state.error || state.saving || !state.model || voice && !state.voices.some(row => row.id === voice)) return;
+      const model = state.model; stop(); emit({ saving: true, previewError: null });
+      try { await preferences.saveTtsVoice(model, voice); updateSelection(); }
+      finally { emit({ saving: false }); }
+    },
+    async audition() {
+      if (state.playing) { stop(); return; }
+      if (!state.model || state.loading || state.error || state.saving || state.unavailable || state.blocked) return;
+      const abort = playing = new AbortController();
+      const take = { model: state.model, voice: state.selected || undefined, text: TTS_PREVIEW_TEXT, signal: AbortSignal.any([abort.signal, AbortSignal.timeout(60000)]) };
+      emit({ playing: true, previewError: null });
+      try { await preview(take); }
+      catch { if (playing === abort && !abort.signal.aborted) emit({ previewError: "tts_preview_failed" }); }
+      finally { if (playing === abort) { playing = null; emit({ playing: false }); } }
+    },
+    dispose() { generation++; listing?.abort(); stop(); off(); offActivity(); disposed = true; listeners.clear(); },
+  };
+}

package/voice/tts-voice.js

@@ -0,0 +1,20 @@
+/** A legacy voice belongs only to the model for which it was explicitly saved. */
+export function ttsVoiceForModel(config, model) {
+  if (Object.hasOwn(config.ttsVoiceByModel || {}, model)) return config.ttsVoiceByModel[model] || undefined;
+  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 }];
+  });
+}

package/webhook/client.js

@@ -0,0 +1,34 @@
+import { createSnapshotStore } from "../tools/async.js";
+
+export const API = "/api/lares/webhook";
+
+const settings = createSnapshotStore();
+
+async function readPayload(res, path) {
+  const payload = await res.json().catch(() => ({}));
+  if (!res.ok) {
+    throw new Error(payload?.error?.message ?? payload?.error?.code ?? `${path} → ${res.status}`);
+  }
+  return settings.remember(payload);
+}
+
+async function post(path, body) {
+  const res = await fetch(`${API}${path}`, {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify(body),
+  });
+  return readPayload(res, path);
+}
+
+export function rememberedWebhookSettings() {
+  return settings.peek();
+}
+
+export function loadWebhookSettings(options = {}) {
+  return settings.load(async () => readPayload(await fetch(API), "/"), options);
+}
+
+export function saveWebhookSettings(config) {
+  return post("/config", config);
+}

package/webhook/config.js

@@ -0,0 +1,55 @@
+import { isAbsolute, join } from "node:path";
+import { HttpError } from "../tools/http.js";
+import { readJsonFile, writeJsonFile } from "../tools/json-file.js";
+
+export const WEBHOOK_ROUTE = "/api/lares/webhook";
+const MAX_PROMPT = 16_000;
+const MAX_PATH = 1024;
+
+export function webhookConfigPath(dataDir) {
+  return join(dataDir, "webhook.json");
+}
+
+export function defaultWebhookConfig() {
+  return { enabled: false, workspacePath: "" };
+}
+
+/** @param {unknown} value */
+export function normalizeWebhookConfig(value) {
+  const source = value && typeof value === "object" ? value : {};
+  const workspacePath = typeof source.workspacePath === "string" ? source.workspacePath.trim() : "";
+  if (workspacePath.length > MAX_PATH) throw new HttpError("bad_request", 400, "workspacePath is too long");
+  if (workspacePath && !isAbsolute(workspacePath)) {
+    throw new HttpError("bad_request", 400, "workspacePath must be an absolute path");
+  }
+  return {
+    enabled: source.enabled === true,
+    workspacePath,
+  };
+}
+
+export function loadWebhookConfig(dataDir) {
+  return normalizeWebhookConfig(readJsonFile(webhookConfigPath(dataDir)) ?? {});
+}
+
+export function saveWebhookConfig(dataDir, value) {
+  const config = normalizeWebhookConfig(value);
+  writeJsonFile(webhookConfigPath(dataDir), config);
+  return config;
+}
+
+/** @param {Record<string, unknown>} body */
+export function webhookPrompt(body) {
+  const prompt = typeof body?.prompt === "string" ? body.prompt.trim() : "";
+  if (!prompt) throw new HttpError("bad_request", 400, "prompt is required");
+  if (prompt.length > MAX_PROMPT) throw new HttpError("bad_request", 400, "prompt is too long");
+  return prompt;
+}
+
+export function webhookView(config) {
+  return {
+    ...config,
+    endpoint: WEBHOOK_ROUTE,
+    jobsEndpoint: `${WEBHOOK_ROUTE}/jobs`,
+  };
+}

package/webhook/public.js

@@ -0,0 +1,11 @@
+/**
+ * Public call URLs. The host is the webhook entrance, so the path is empty.
+ * POST submits a prompt; GET with ?id= reads that session.
+ *
+ * @param {string} [origin]
+ */
+export function webhookCallUrls(origin) {
+  const root = String(origin ?? "").replace(/\/$/, "");
+  const base = root ? `${root}/` : "/";
+  return { post: base, jobs: `${base}?id=` };
+}

package/webhook/reply.js

@@ -0,0 +1,12 @@
+import { textFromBlocks } from "../larepass/transcript.js";
+
+/** Latest non-empty assistant text. An empty trailing message does not erase the previous reply. */
+export function lastAssistantText(messages) {
+  let text = "";
+  for (const message of Array.isArray(messages) ? messages : []) {
+    if (message?.role !== "assistant") continue;
+    const next = textFromBlocks(message.content);
+    if (next) text = next;
+  }
+  return text;
+}