@olares/lares-core 0.15.10 → 0.15.12

package/voice/host-service.js

@@ -0,0 +1,171 @@
+import { createVoiceAgentSession } from "./agent-session.js";
+import { createVoiceRecords } from "./records.js";
+import { createVoiceDialogue, cleanDictation } from "./dialogue.js";
+import { readConfig } from "./config.js";
+import { VOICE_PRESETS } from "./options.js";
+
+const failure = (code, status) => Object.assign(new Error(code), { code, status });
+
+/** Presets and task policy stay in core; the Host supplies an authenticated scope. */
+export function createVoiceHostService(api, { env = process.env, metric = () => {}, records = createVoiceRecords(), config = readConfig, chat } = {}) {
+  const ownerOf = (scope) => scope.owner || "@local";
+  const keyOf = (scope) => scope.session?.snapshot().sessionId || `voice:${scope.contextId || scope.id}`;
+  const append = (scope, role, text, turnId, taskId = null) => records.append(ownerOf(scope), keyOf(scope), {
+    id: `${scope.id}:${turnId}:${role}`, voiceId: scope.id, clientId: scope.id, turnId, role, text: text.slice(0, 16000), taskId,
+  });
+  const scopes = new Set();
+  const service = {
+    async clean(scope, text) {
+      if (typeof text !== "string" || text.length > 16000) throw failure("voice_input_invalid", 400);
+      return cleanDictation(text, { config: config(), owner: scope.owner, chat });
+    },
+    async open(scope, body) {
+      if (scope.active || scope.opening || scope.closing) throw failure("voice_session_active", 409);
+      const epoch = scope.epoch = (scope.epoch || 0) + 1;
+      scope.opening = true;
+      try {
+      if (body.sessionId != null && (typeof body.sessionId !== "string" || !body.sessionId || body.sessionId.length > 256)) throw failure("voice_session_invalid", 400);
+      if (body.contextId != null && (typeof body.contextId !== "string" || !/^[a-zA-Z0-9_-]{8,128}$/.test(body.contextId))) throw failure("voice_context_invalid", 400);
+      scope.contextId = body.contextId || scope.id;
+      const binding = records.read(ownerOf(scope), `voice:${scope.contextId}`).binding;
+      const boundSessionId = body.sessionId || binding || null;
+      if (boundSessionId) await api.inspect(boundSessionId);
+      if (scope.epoch !== epoch) throw failure("voice_session_closed", 409);
+      await scope.session?.close();
+      const selected = config();
+      const preset = body.preset || selected.preset;
+      if (!VOICE_PRESETS.includes(preset)) throw failure("voice_preset_invalid", 400);
+      scopes.add(scope);
+      scope.voiceAbort = new AbortController();
+      scope.voiceConfig = { ...selected, preset };
+      const history = records.read(ownerOf(scope), boundSessionId || `voice:${scope.contextId || scope.id}`);
+      scope.recoveryContext = history.summary || null;
+      const restoredRequests = [...new Set(history.records.map((row) => row.taskId).filter(Boolean))].map((requestId) => ({ requestId }));
+      scope.session = createVoiceAgentSession(api, { sessionId: boundSessionId,
+        preset: scope.authorizedBinding?.agentPreset || env.LARES_VOICE_AGENT_PRESET || undefined, workspaceId: scope.authorizedBinding?.workspaceId || env.LARES_VOICE_WORKSPACE_ID || undefined, restoredRequests,
+        metric: (fields) => metric({ voiceId: scope.id, ...fields }),
+      });
+      await scope.session.open();
+      if (scope.epoch !== epoch) throw failure("voice_session_closed", 409);
+      scope.recordKey = keyOf(scope);
+      scope.voiceResults = []; scope.summaryError = null;
+      scope.active = true; scope.readAloud = body.readAloud === true;
+      scope.voiceState = { version: 0, running: false, utterance: null, error: null };
+      scope.voiceRequests = new Map(); scope.deliveredTasks = new Set(restoredRequests.map((item) => item.requestId));
+      scope.dialogue = createVoiceDialogue({ config: scope.voiceConfig, owner: scope.owner, context: history.summary?.recent || [], summary: history.summary?.text || "", chat,
+        submit: async (text, requestId, operation) => {
+          if (operation === "status") return scope.session.snapshot();
+          const id = `${requestId}:delegate`;
+          // The source transcript is persisted before any side effect, even for lazy business sessions.
+          const before = keyOf(scope);
+          append(scope, "task", text, requestId, id);
+          let state;
+          try { state = await scope.session.submit(text, id, scope.submitMode || "queue"); }
+          finally { if (before !== keyOf(scope)) {
+            for (const row of records.read(ownerOf(scope), before).records) records.append(ownerOf(scope), keyOf(scope), row);
+            records.clear(ownerOf(scope), before);
+            records.bind(ownerOf(scope), scope.contextId, keyOf(scope));
+          } }
+          return { status: "pending", sessionId: state.sessionId, requestId: id };
+        },
+      });
+      return service.state(scope);
+      } finally { if (scope.epoch === epoch) scope.opening = false; }
+    },
+    async prompt(scope, body) {
+      if (!scope.active || !scope.session) throw failure("voice_session_closed", 409);
+      if (typeof body.text !== "string" || !body.text.trim() || body.text.length > 16000 || typeof body.requestId !== "string" || !body.requestId || body.requestId.length > 128) throw failure("voice_session_invalid", 400);
+      if (scope.voiceConfig.preset === "dictation") return { ...service.state(scope), text: body.text };
+      if (scope.voiceConfig.preset === "direct") {
+        const before = keyOf(scope);
+        append(scope, "user", body.text, body.requestId, body.requestId);
+        try { return await scope.session.submit(body.text, body.requestId, body.mode); }
+        finally {
+          if (before !== keyOf(scope)) {
+            for (const row of records.read(ownerOf(scope), before).records) records.append(ownerOf(scope), keyOf(scope), row);
+            records.clear(ownerOf(scope), before);
+            records.bind(ownerOf(scope), scope.contextId, keyOf(scope));
+          }
+        }
+      }
+      if (scope.voiceRequests.has(body.requestId)) return scope.voiceRequests.get(body.requestId);
+      if (scope.voiceRequests.size >= 256) throw failure("voice_session_limit", 429);
+      const operation = (scope.voiceSerial || Promise.resolve()).catch(() => {}).then(async () => {
+        if (!scope.active || scope.voiceAbort.signal.aborted) throw failure("voice_session_closed", 409);
+        scope.submitMode = body.mode === "steer" ? "steer" : "queue";
+        scope.voiceState.running = true; scope.voiceState.error = null; scope.voiceState.version++;
+        append(scope, "user", body.text, body.requestId);
+        try {
+          const text = await scope.dialogue.reply(body.text, body.requestId, scope.voiceAbort.signal);
+          append(scope, "assistant", text, body.requestId);
+          const key = keyOf(scope);
+          const checkpointVersion = records.read(ownerOf(scope), key).version;
+          scope.summaryTask = scope.dialogue.summarize().then((summary) => records.checkpoint(ownerOf(scope), key, summary, checkpointVersion)).catch((cause) => {
+            scope.summaryError = cause.code || cause.message || "voice_summary_failed";
+          });
+          scope.voiceState.utterance = { key: body.requestId, turn: scope.voiceState.version, step: 0, text, done: true, silent: false };
+        } catch (cause) { scope.voiceState.error = cause.code || cause.message || "voice_failed"; throw cause; }
+        finally { scope.voiceState.running = false; scope.voiceState.version++; }
+        return service.state(scope);
+      });
+      scope.voiceSerial = operation;
+      scope.voiceRequests.set(body.requestId, operation);
+      return operation;
+    },
+    state(scope) {
+      const state = scope.session?.snapshot() || {};
+      if (!scope.voiceState) return { ...state, contextId: scope.contextId, active: scope.active === true };
+      // Completion is keyed by durable request/turn, never by the session's aggregate idle flag.
+      for (const task of state.tasks || []) {
+        if (!["completed", "failed", "cancelled"].includes(task.status) || scope.deliveredTasks.has(task.requestId)) continue;
+        append(scope, "task", JSON.stringify(task), `${task.requestId}:result`, task.requestId);
+        scope.deliveredTasks.add(task.requestId);
+        scope.voiceResults ??= [];
+        scope.voiceResults.push(task);
+      }
+      if (scope.voiceConfig.preset === "direct") return { ...state, contextId: scope.contextId, active: scope.active === true };
+      // Pending business work does not block the next speech turn.
+      if (scope.active && !scope.voiceState.running && scope.voiceResults?.length && !scope.voiceInputActive) {
+        const task = scope.voiceResults.shift();
+        scope.dialogue.observeTask(task);
+        const text = task.status === "completed" ? task.text : `Task ${task.status}: ${task.error || ""}`;
+        scope.voiceState.utterance = { key: `task:${task.requestId}`, turn: ++scope.voiceState.version, step: 0, text, done: true, silent: false };
+        append(scope, "assistant", text, `result:${task.requestId}`, task.requestId);
+      }
+      return { ...state, ...scope.voiceState, contextId: scope.contextId, active: scope.active === true, backgroundRunning: state.running, summaryError: scope.summaryError || null, preset: scope.voiceConfig.preset };
+    },
+    async remove(sessionId) {
+      for (const scope of scopes) if (scope.session?.snapshot().sessionId === sessionId) { await service.close(scope); scopes.delete(scope); }
+      records.clearConversation(sessionId);
+    },
+    record(scope, role, text, turnId) {
+      const key = keyOf(scope);
+      if (scope.recordKey && scope.recordKey !== key) {
+        for (const row of records.read(ownerOf(scope), scope.recordKey).records) records.append(ownerOf(scope), key, row);
+        records.clear(ownerOf(scope), scope.recordKey);
+        records.bind(ownerOf(scope), scope.contextId, key);
+      }
+      scope.recordKey = key;
+      return append(scope, role, text.slice(0, 16000), String(turnId || scope.voiceState.version), role === "task" ? String(turnId) : null);
+    },
+    records(scope) { return records.read(ownerOf(scope), keyOf(scope)); },
+    async clearRecords(scope) { const key = keyOf(scope); await service.close(scope); records.clear(ownerOf(scope), key); },
+    output(scope, value) { if (typeof value !== "boolean") throw failure("voice_output_invalid", 400); scope.readAloud = value; },
+    resume: (scope) => scope.session?.resume(),
+    cancel: (scope) => scope.session?.cancel(),
+    async close(scope) {
+      scope.epoch = (scope.epoch || 0) + 1; scope.opening = false; scope.closing = true;
+      scope.active = false; scope.voiceAbort?.abort(); scope.realtimeSocket?.close();
+      try {
+        scope.capture?.stop(true);
+        const cleanup = await Promise.allSettled([scope.duplex?.interrupt(), scope.realtimeAudio?.stop(), scope.session?.close()]);
+        await scope.voiceSerial?.catch(() => {});
+        await scope.summaryTask;
+        scopes.delete(scope);
+        const failed = cleanup.find((result) => result.status === "rejected");
+        if (failed) throw failed.reason;
+      } finally { scope.closing = false; }
+    },
+  };
+  return service;
+}

package/voice/input.js

@@ -1,4 +1,5 @@
 /** Where a take is recorded. The desktop page uses the headset; the phone page uses its own mic. */
-export function captureSource(surface) {
+export function captureSource(surface, selected = "auto") {
+  if (selected === "device" || selected === "headset") return selected;
   return surface === "mobile" ? "device" : "headset";
 }

package/voice/install.js

@@ -1,10 +1,14 @@
 import { spawn } from "node:child_process";
 import { VoiceError } from "../router/stt.js";
 
-/** Charts the voice panel installs, stops, and resumes through olares-cli market. */
+/**
+ * Charts the voice panel installs, stops, and resumes through olares-cli market.
+ * No version is pinned: install takes whatever the market holds, and status
+ * and model matching go by app name, so chart updates need no Lares release.
+ */
 export const VOICE_CHARTS = {
-  stt: { app: "audioqwen3asr06v3", version: "1.0.0", model: "Qwen3-ASR-0.6B" },
-  tts: { app: "audioqwen3tts06v3", version: "1.0.0", model: "Qwen3-TTS-12Hz-0.6B-CustomVoice" },
+  stt: { app: "audioqwen3asr06v3", model: "Qwen3-ASR-0.6B" },
+  tts: { app: "audioqwen3tts06v3", model: "Qwen3-TTS-12Hz-0.6B-CustomVoice" },
 };
 
 const OUTPUT_LIMIT = 8000;
@@ -47,7 +51,11 @@ function describe(chart, row) {
   };
 }
 
-function runMarket(args, spawnFn) {
+/**
+ * Runs olares-cli as the app's profile; resolves with exit code, parsed JSON, and a readable message.
+ * Output past `limit` characters is cut from the front, so JSON larger than that does not parse.
+ */
+export function runOlaresCli(args, spawnFn = spawn, limit = OUTPUT_LIMIT) {
   return new Promise((resolve, reject) => {
     const child = spawnFn("olares-cli", args, {
       env: process.env,
@@ -56,8 +64,8 @@ function runMarket(args, spawnFn) {
     let stdout = "";
     let stderr = "";
     const take = (bucket) => (chunk) => {
-      if (bucket === "stdout") stdout = `${stdout}${chunk}`.slice(-OUTPUT_LIMIT);
-      else stderr = `${stderr}${chunk}`.slice(-OUTPUT_LIMIT);
+      if (bucket === "stdout") stdout = `${stdout}${chunk}`.slice(-limit);
+      else stderr = `${stderr}${chunk}`.slice(-limit);
     };
     child.stdout?.on("data", take("stdout"));
     child.stderr?.on("data", take("stderr"));
@@ -96,25 +104,38 @@ function accepted(result) {
 export async function installVoiceChart(kind, options = {}) {
   const chart = chartFor(kind);
   const spawnFn = options.spawnFn ?? spawn;
-  const result = await runMarket(
-    ["market", "install", chart.app, "-s", "market.test", "--version", chart.version, "--compute-mode", "nvidia", "-o", "json"],
+  const result = await runOlaresCli(
+    ["market", "install", chart.app, "-s", "market.test", "--compute-mode", "nvidia", "-o", "json"],
     spawnFn,
   );
   if (!accepted(result)) {
     throw new VoiceError("voice_install_failed", 502, result.message);
   }
-  return { app: chart.app, version: chart.version };
+  return { app: chart.app };
+}
+
+/**
+ * `status -a` returns one row per market source (catalog, test, upload). An
+ * app reinstalled from another source keeps its old `uninstalled` row, so the
+ * live one is the latest row that is still installed.
+ * @param {unknown} json
+ */
+export function currentChartRow(json) {
+  const rows = (Array.isArray(json) ? json : [json]).filter((row) => row && typeof row === "object");
+  const installed = rows.filter((row) => chartPhase(row) !== "absent");
+  const time = (row) => Date.parse(row.statusTime) || 0;
+  return [...(installed.length ? installed : rows)].sort((a, b) => time(b) - time(a))[0] ?? null;
 }
 
 /** @param {"stt" | "tts"} kind */
 export async function voiceChartStatus(kind, options = {}) {
   const chart = chartFor(kind);
-  const result = await runMarket(
+  const result = await runOlaresCli(
     ["market", "status", chart.app, "-a", "-o", "json"],
     options.spawnFn ?? spawn,
   );
   if (!result.json) throw new VoiceError("voice_install_failed", 502, result.message);
-  return describe(chart, result.json);
+  return describe(chart, currentChartRow(result.json));
 }
 
 export async function voiceChartsStatus(options = {}) {
@@ -127,7 +148,7 @@ export async function voiceChartsStatus(options = {}) {
 
 async function settle(kind, verb, code, options) {
   const chart = chartFor(kind);
-  const result = await runMarket(
+  const result = await runOlaresCli(
     ["market", verb, chart.app, "--watch", "-o", "json"],
     options.spawnFn ?? spawn,
   );

package/voice/languages.js

@@ -14,7 +14,7 @@ export function voiceValueFromMenu(id) {
   return id === VOICE_AUTO ? "" : id;
 }
 
-export const EMPTY_VOICE_CONFIG = { model: "", ttsModel: "", language: "", speak: false };
+export { VOICE_DEFAULTS as EMPTY_VOICE_CONFIG } from "./options.js";
 
 export function voiceChoiceItems(ids) {
   return ids.map((id) => ({ id, label: id }));
@@ -32,8 +32,4 @@ export function voiceLanguageItems(autoLabel) {
 
 export function voiceModelItems(sttIds, autoLabel) {
   return [{ id: VOICE_AUTO, label: autoLabel }, ...sttIds.map((id) => ({ id, label: id }))];
-}
-
-export function voiceStatusReady(status) {
-  return Boolean(status?.modelAvailable);
-}
+}

package/voice/lease.js

@@ -0,0 +1,16 @@
+/** Physical audio is shared; a new page must not silently evict its owner. */
+export function createDeviceLease({ now = Date.now, ttlMs = 30_000 } = {}) {
+  let lease = null;
+  const busy = () => Object.assign(new Error("voice_device_busy"), { code: "voice_device_busy", status: 409 });
+  return {
+    acquire(owner) {
+      if (lease && lease.owner !== owner && lease.until > now()) throw busy();
+      lease = { owner, until: now() + ttlMs };
+    },
+    touch(owner) {
+      if (lease?.owner === owner) lease.until = now() + ttlMs;
+    },
+    release(owner) { if (lease?.owner === owner) lease = null; },
+    owns: (owner) => lease?.owner === owner && lease.until > now(),
+  };
+}

package/voice/options.js

@@ -0,0 +1,23 @@
+export const VOICE_DEFAULTS = {
+  preset: "assistant",
+  dictationCleanup: false,
+  chatModel: "default-chat",
+  instructions: "",
+  voice: "",
+  mode: "single",
+  mobileMode: "continuous",
+  endpointSilenceMs: 500,
+  idleTimeoutMs: 300_000,
+  recoveryTimeoutMs: 120_000,
+  device: "auto",
+  backend: "pipeline",
+  realtimeModel: "",
+  model: "",
+  ttsModel: "",
+  language: "",
+  speak: false,
+  // Read answers while they are written. Needs the GPU in MemorySlice, see gpu-mode.js.
+  streaming: false,
+};
+
+export const VOICE_PRESETS = Object.freeze(["dictation", "chat", "assistant", "direct"]);

package/voice/protocol-client.js

@@ -0,0 +1,24 @@
+/** Transport-neutral client: the caller obtains an authenticated Router socket. */
+export function createVoiceProtocolClient(socket, { onEvent = () => {}, onClose = () => {} } = {}) {
+  const send = (event) => {
+    if (socket.readyState !== 1) throw new Error("voice_disconnected");
+    if (socket.bufferedAmount > 1024 * 1024) throw new Error("voice_audio_backpressure");
+    socket.send(JSON.stringify(event));
+  };
+  const message = (event) => {
+    let value;
+    try { value = JSON.parse(String(event.data)); } catch { onEvent({ type: "error", error: { code: "voice_protocol" } }); return; }
+    if (value && typeof value.type === "string") onEvent(value);
+  };
+  const close = () => onClose();
+  socket.addEventListener("message", message); socket.addEventListener("close", close);
+  return {
+    configure({ automatic = false, contextId, audio = true } = {}) { send({ type: "session.update", session: { type: "realtime", output_modalities: audio ? ["audio"] : ["text"], ...(contextId ? { voice_context_id: contextId } : {}), audio: { input: { format: { type: "audio/pcm", rate: 24000 }, turn_detection: automatic ? { type: "server_vad" } : null }, output: { format: { type: "audio/pcm", rate: 24000 } } } }); },
+    append(audio) { if (typeof audio !== "string" || audio.length > 64000) throw new Error("voice_audio_limit"); send({ type: "input_audio_buffer.append", audio }); },
+    commit() { send({ type: "input_audio_buffer.commit" }); },
+    discard() { send({ type: "input_audio_buffer.clear" }); },
+    playbackCompleted() { send({ type: "voice.playback.completed" }); },
+    stopOutput() { send({ type: "response.cancel" }); },
+    close() { socket.removeEventListener("message", message); socket.removeEventListener("close", close); socket.close(); },
+  };
+}

package/voice/realtime-audio.js

@@ -0,0 +1,107 @@
+/** Streaming rate conversion keeps fractional phase across device frames. */
+export function createPcmResampler(inputRate, outputRate = 24000) {
+  if (!(inputRate > 0 && outputRate > 0)) throw new Error("voice_audio_format");
+  let position = 0;
+  return (samples) => {
+    const values = [];
+    const step = inputRate / outputRate;
+    for (; position < samples.length; position += step) {
+      const i = Math.floor(position);
+      const fraction = position - i;
+      const value = samples[i] * (1 - fraction) + samples[Math.min(i + 1, samples.length - 1)] * fraction;
+      values.push(Math.max(-1, Math.min(1, value)));
+    }
+    position -= samples.length;
+    const bytes = new Uint8Array(values.length * 2);
+    const view = new DataView(bytes.buffer);
+    for (let i = 0; i < values.length; i++) view.setInt16(i * 2, Math.round(values[i] * 32767), true);
+    return bytes;
+  };
+}
+export function pcmSamples(bytes) {
+  if (bytes.length % 2) throw new Error("voice_audio_format");
+  const values = new Float32Array(bytes.length / 2);
+  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  for (let i = 0; i < values.length; i++) values[i] = view.getInt16(i * 2, true) / 32768;
+  return values;
+}
+function base64(bytes) { return btoa(String.fromCharCode(...bytes)); }
+function unbase64(value) { return Uint8Array.from(atob(value), (c) => c.charCodeAt(0)); }
+
+export function createPcmBrowserAudio({ send, onPlayback = () => {}, onError = () => {} }) {
+  let context;
+  let stream;
+  let source;
+  let processor;
+  let mute;
+  let next = 0;
+  let first = 0;
+  let closed = true;
+  let generation = 0;
+  const players = new Set();
+  const drains = new Set();
+  const stopPlayback = () => {
+    generation++;
+    for (const player of players) { player.onended = null; player.stop(); player.disconnect(); }
+    players.clear();
+    next = context?.currentTime || 0;
+    for (const resolve of drains) resolve();
+    drains.clear();
+    onPlayback(false);
+  };
+  return {
+    async start() {
+      const epoch = ++generation;
+      closed = false;
+      const AudioCtx = globalThis.AudioContext || globalThis.webkitAudioContext;
+      if (!AudioCtx || !globalThis.navigator?.mediaDevices?.getUserMedia) throw new Error("voice_unsupported");
+      const opened = await navigator.mediaDevices.getUserMedia({ audio: { channelCount: 1, echoCancellation: true, noiseSuppression: true, autoGainControl: true } });
+      if (closed || epoch !== generation) { opened.getTracks().forEach((track) => track.stop()); return; }
+      stream = opened;
+      for (const track of stream.getTracks()) track.addEventListener("ended", () => { if (!closed) onError(new Error("voice_device_lost")); }, { once: true });
+      context ??= new AudioCtx(); await context.resume();
+      source = context.createMediaStreamSource(stream);
+      processor = context.createScriptProcessor(2048, 1, 1);
+      mute = context.createGain(); mute.gain.value = 0;
+      const convert = createPcmResampler(context.sampleRate);
+      processor.onaudioprocess = (event) => {
+        if (closed || players.size) return;
+        send({ type: "input_audio_buffer.append", audio: base64(convert(event.inputBuffer.getChannelData(0))) });
+      };
+      source.connect(processor); processor.connect(mute); mute.connect(context.destination);
+    },
+    pauseInput() {
+      generation++;
+      if (processor) processor.onaudioprocess = null;
+      source?.disconnect(); processor?.disconnect(); mute?.disconnect();
+      source = null; processor = null; mute = null;
+      stream?.getTracks().forEach((track) => track.stop()); stream = null;
+    },
+    write(value) {
+      if (!context || closed) return;
+      const samples = pcmSamples(unbase64(value));
+      if (next - context.currentTime > 15) throw new Error("voice_audio_backpressure");
+      const buffer = context.createBuffer(1, samples.length, 24000); buffer.copyToChannel(samples, 0);
+      const player = context.createBufferSource(); player.buffer = buffer; player.connect(context.destination);
+      if (!players.size) { first = context.currentTime; onPlayback(true); }
+      players.add(player);
+      player.onended = () => {
+        players.delete(player); player.disconnect();
+        if (!players.size) {
+          for (const resolve of drains) resolve(); drains.clear(); onPlayback(false);
+        }
+      };
+      next = Math.max(context.currentTime + 0.02, next); player.start(next); next += buffer.duration;
+    },
+    drain() { return players.size ? new Promise((resolve) => drains.add(resolve)) : Promise.resolve(); },
+    playedMs() { return context ? Math.max(0, Math.floor((Math.min(context.currentTime, next) - first) * 1000)) : 0; },
+    stopPlayback,
+    async stop() {
+      closed = true; stopPlayback();
+      if (processor) processor.onaudioprocess = null;
+      source?.disconnect(); processor?.disconnect(); mute?.disconnect();
+      stream?.getTracks().forEach((track) => track.stop()); stream = null;
+      await context?.close(); context = null;
+    },
+  };
+}

package/voice/realtime-conversation.js

@@ -0,0 +1,122 @@
+import { createVoiceController } from "./controller.js";
+import { createPcmBrowserAudio } from "./realtime-audio.js";
+import { mintRpcId } from "../larepass/rpc.js";
+
+export function createRealtimeConversation({ request, socket: openSocket, device = "device", playback, onCaption = () => {}, idleTimeoutMs, recoveryTimeoutMs, readAloud = true }) {
+  const voiceId = mintRpcId();
+  const headers = { "x-lares-voice-id": voiceId, "x-lares-voice-device": device };
+  let socket;
+  let intentional = false;
+  let currentItem = null;
+  let responseActive = false;
+  let receivedMs = 0;
+  let boundSessionId = null;
+  let pollTimer;
+  let audio;
+  const send = (value) => {
+    if (socket?.readyState !== 1) return;
+    if (socket.bufferedAmount > 1024 * 1024) { void controller.disconnect("voice_audio_backpressure"); return; }
+    socket.send(JSON.stringify(value));
+  };
+  const call = async (path, body) => {
+    const res = await request(`/api/lares/voice${path}`, { method: body === undefined ? "GET" : "POST", headers, ...(body === undefined ? {} : { body }) });
+    if (!res?.ok) throw new Error(res?.body?.error?.code || "voice_failed");
+    return res.body;
+  };
+  const stopPlayback = async () => {
+    const played = Math.min(receivedMs, audio?.playedMs() || 0);
+    audio?.stopPlayback(); playback?.stop?.();
+    if (responseActive) send({ type: "response.cancel" });
+    responseActive = false;
+    if (currentItem && device === "device") send({ type: "conversation.item.truncate", item_id: currentItem, content_index: 0, audio_end_ms: played });
+    controller.observePlayback(false);
+  };
+  const controller = createVoiceController({ voiceId, idleTimeoutMs, recoveryTimeoutMs,
+    onExpired: async () => { intentional = true; clearTimeout(pollTimer); socket?.close(); await audio?.stop(); await call("/session/close", {}); },
+    input: { capabilities: { duplex: device === "device", bargeIn: false, listenWhileWorking: true, audio: "pcm16-24000" },
+      capture: ({ signal }) => new Promise((resolve, reject) => {
+        send({ type: "lares.input.resume" });
+        if (device === "device") void audio.start().catch(reject);
+        signal.addEventListener("abort", () => resolve(""), { once: true });
+      }), cancel: async () => { send({ type: "lares.input.pause" }); audio?.pauseInput(); },
+    }, output: { stop: stopPlayback }, agent: {
+      create: async () => boundSessionId,
+      submit: async () => {},
+      cancel: () => call("/session/cancel", {}),
+      running: async () => (await call("/session")).running === true,
+    },
+  });
+  audio = createPcmBrowserAudio({ send, onPlayback: (playing) => controller.observePlayback(playing), onError: (error) => { void controller.disconnect(error.message); } });
+  const connect = async () => {
+    intentional = false;
+    const grant = await call("/realtime/ticket", {});
+    await new Promise((resolve, reject) => {
+      const timeout = setTimeout(() => { socket?.close(); reject(new Error("voice_realtime_timeout")); }, 20_000);
+      socket = openSocket(grant.ticket);
+      const connectedSocket = socket;
+      socket.addEventListener("message", (message) => {
+        if (socket !== connectedSocket) return;
+        let event;
+        try { event = JSON.parse(message.data); } catch { return; }
+        if (!event || typeof event !== "object") return;
+        if (event.type === "input_audio_buffer.speech_started") controller.noteActivity();
+        if (event.type === "lares.ready") { clearTimeout(timeout); resolve(); }
+        else if (event.type === "lares.error") { clearTimeout(timeout); reject(new Error(event.code)); void controller.disconnect(event.code); }
+        else if (["response.output_audio.delta", "response.audio.delta"].includes(event.type)) {
+          currentItem = event.item_id || currentItem;
+          receivedMs += atob(event.delta).length / 48;
+          try { audio.write(event.delta); } catch (error) { void controller.disconnect(error.message); }
+        } else if (event.type === "response.created") { responseActive = true; receivedMs = 0; currentItem = null; }
+        else if (event.type === "response.done") responseActive = false;
+        else if (event.type === "lares.playback") controller.observePlayback(event.playing === true);
+        else if (event.type === "lares.task") {
+          if (event.sessionId) { boundSessionId = event.sessionId; controller.bindSession(boundSessionId); }
+          controller.observeAgent(event.status === "pending");
+        } else if (["response.output_audio_transcript.delta", "response.audio_transcript.delta", "response.output_text.delta", "response.text.delta"].includes(event.type)) onCaption(event.delta, "assistant");
+      });
+      socket.addEventListener("error", () => { if (socket !== connectedSocket) return; clearTimeout(timeout); reject(new Error("voice_disconnected")); });
+      socket.addEventListener("close", () => {
+        if (socket !== connectedSocket) return;
+        clearTimeout(timeout); reject(new Error("voice_disconnected"));
+        if (!intentional) void controller.disconnect("voice_disconnected");
+      });
+    });
+  };
+  const watch = async () => {
+    if (intentional || controller.getSnapshot().connection !== "open") return;
+    try {
+      const state = await call("/session");
+      if (state.sessionId) { boundSessionId = state.sessionId; controller.bindSession(boundSessionId); }
+      controller.observeAgent(Boolean(state.running));
+    } catch { await controller.disconnect("voice_disconnected"); return; }
+    pollTimer = setTimeout(watch, 1000);
+  };
+  return {
+    controller, headers,
+    async start({ sessionId = null } = {}) {
+      boundSessionId = sessionId;
+      const initial = await call("/session", { sessionId, readAloud });
+      await connect();
+      await controller.start({ sessionId, continuous: true, running: initial.running });
+      controller.setOutputMuted(!readAloud);
+      void watch();
+    },
+    async setReadAloud(value) {
+      readAloud = value === true; controller.setOutputMuted(!readAloud);
+      if (!readAloud) await stopPlayback();
+      send({ type: "lares.output", enabled: readAloud });
+    },
+    async stop() {
+      intentional = true; clearTimeout(pollTimer);
+      await controller.disconnect(); await audio?.stop(); socket?.close();
+      await call("/session/close", {});
+    },
+    async resume() {
+      const state = await call("/session");
+      if (!state.active) await call("/session", { sessionId: boundSessionId, readAloud });
+      else await call("/session/resume", {});
+      await audio?.stop();
+      await connect(); await controller.resume(); void watch();
+    },
+  };
+}