@olares/lares-core 0.15.11 → 0.15.13

package/voice/host-service.js

@@ -0,0 +1,216 @@
+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, fields = {}) => 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, anchorSeq: scope.session?.snapshot().cursor ?? -1, ...fields,
+  });
+  const ensurePresentation = async (scope) => {
+    if (!scope.presentationSession || scope.session.snapshot().sessionId) return;
+    const before = keyOf(scope);
+    await scope.session.ensureSession();
+    if (!scope.active) throw failure("voice_session_closed", 409);
+    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));
+  };
+  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.presentationSession = body.presentationSession === true;
+      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,
+        onChange: () => { if (scope.active) service.state(scope); },
+        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);
+          const source = records.read(ownerOf(scope), keyOf(scope)).records.find((row) => row.id === `${scope.id}:${requestId}:user`);
+          if (source) append(scope, "user", source.text, requestId, id);
+          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 };
+      await ensurePresentation(scope);
+      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, (partial) => {
+            const source = records.read(ownerOf(scope), keyOf(scope)).records.find((row) => row.id === `${scope.id}:${body.requestId}:user`);
+            append(scope, "assistant", partial, body.requestId, source?.taskId || null, { status: "streaming" });
+          });
+          const source = records.read(ownerOf(scope), keyOf(scope)).records.find((row) => row.id === `${scope.id}:${body.requestId}:user`);
+          append(scope, "assistant", text, body.requestId, source?.taskId || null);
+          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";
+          const partial = records.read(ownerOf(scope), keyOf(scope)).records.find((row) => row.id === `${scope.id}:${body.requestId}:assistant`);
+          if (partial) append(scope, "assistant", partial.text, body.requestId, partial.taskId, { status: "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, { taskTurn: task.turn });
+      }
+      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);
+    },
+    async record(scope, role, text, turnId, fields = {}) {
+      if (!text?.trim()) return;
+      if (role === "user") await ensurePresentation(scope);
+      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, fields);
+    },
+    async history(scope, body, signal) {
+      const { sessionId, version, waitMs = 0 } = body;
+      if (typeof sessionId !== "string" || !sessionId || sessionId.length > 256 || !Number.isInteger(waitMs) || waitMs < 0 || waitMs > 20000) throw failure("voice_records_invalid", 400);
+      await api.inspect(sessionId);
+      const owner = ownerOf(scope);
+      const page = () => records.page(owner, sessionId, body);
+      let result = page();
+      if (waitMs && result.version === version && !signal?.aborted) {
+        await new Promise((resolve) => {
+          let timer;
+          const done = () => { clearTimeout(timer); unsubscribe(); signal?.removeEventListener("abort", done); resolve(); };
+          const unsubscribe = records.subscribe(owner, sessionId, done);
+          signal?.addEventListener("abort", done, { once: true });
+          timer = setTimeout(done, waitMs);
+          if (signal?.aborted) done();
+        });
+        result = page();
+      }
+      return result;
+    },
+    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;
@@ -101,13 +105,13 @@ export async function installVoiceChart(kind, options = {}) {
   const chart = chartFor(kind);
   const spawnFn = options.spawnFn ?? spawn;
   const result = await runOlaresCli(
-    ["market", "install", chart.app, "-s", "market.test", "--version", chart.version, "--compute-mode", "nvidia", "-o", "json"],
+    ["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 };
 }
 
 /**

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, streaming: false };
+export { VOICE_DEFAULTS as EMPTY_VOICE_CONFIG } from "./options.js";
 
 export function voiceChoiceItems(ids) {
   return ids.map((id) => ({ id, label: id }));

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

@@ -0,0 +1,88 @@
+/** Framework-independent panel lifetime; factories only supply audio/platform ports. */
+export function createVoicePanel({ create, complete, onSession = () => {} }) {
+  let state = { visible: false, mode: "single", sessionId: null, draft: "", snapshot: null, busy: false, error: null, device: "", levels: [], startedAt: null, elapsedMs: 0 };
+  let call = null;
+  let unsubscribe = () => {};
+  let serial = Promise.resolve();
+  let generation = 0;
+  const drafts = new Map();
+  const listeners = new Set();
+  const emit = (patch) => { state = { ...state, ...patch }; for (const listener of listeners) listener(); };
+  const enqueue = (operation) => {
+    const result = serial.catch(() => {}).then(async () => { emit({ busy: true, error: null }); try { return await operation(); } catch (error) { emit({ error: error.code || error.message }); throw error; } finally { emit({ busy: false }); } });
+    serial = result; return result;
+  };
+  const finishCapture = async () => {
+    if (!call || state.mode !== "single") return;
+    const controller = call.controller;
+    if (!["recording", "transcribing"].includes(controller.getSnapshot().capture)) return;
+    await new Promise((resolve, reject) => {
+      const timer = setTimeout(() => { off(); reject(new Error("voice_recognition_timeout")); }, 45000);
+      const check = () => { if (controller.getSnapshot().capture === "idle") { clearTimeout(timer); off(); resolve(); } };
+      const off = controller.subscribe(check);
+      controller.stopRecording(); check();
+    });
+  };
+  const pause = async () => { try { await finishCapture(); } finally { if (call?.controller.getSnapshot().connection === "open") await call.pause(); } };
+  const end = async () => { generation++; unsubscribe(); unsubscribe = () => {}; const previous = call; call = null; try { await previous?.stop(); } finally { emit({ snapshot: null, startedAt: null, elapsedMs: 0, levels: [] }); } };
+  const reset = async (patch) => {
+    try { await pause(); } finally { try { await end(); } finally { emit(patch); } }
+  };
+  return {
+    getSnapshot: () => state,
+    subscribe(listener) { listeners.add(listener); return () => listeners.delete(listener); },
+    get conversation() { return call; },
+    open({ mode = state.mode, sessionId = state.sessionId } = {}) {
+      emit({ visible: true });
+      return enqueue(async () => {
+        if (sessionId !== state.sessionId) { await reset({ sessionId, draft: drafts.get(sessionId) || "" }); }
+        if (mode !== state.mode) { await reset({ mode }); }
+      });
+    },
+    bind(sessionId) {
+      if (sessionId === state.sessionId) return Promise.resolve();
+      return enqueue(async () => { await reset({ sessionId, draft: drafts.get(sessionId) || "" }); });
+    },
+    close() { emit({ visible: false }); return enqueue(pause); },
+    pause: () => enqueue(pause),
+    start() { return enqueue(async () => {
+      if (call?.controller.getSnapshot().connection === "paused") { await call.resume(); return; }
+      if (call?.controller.getSnapshot().connection === "open") return;
+      await end();
+      const target = state.sessionId; const token = ++generation;
+      const conversation = await create({ mode: state.mode, sessionId: target,
+        onTranscript({ text }) {
+          if (token !== generation) return;
+          const next = [drafts.get(target), text].filter(Boolean).join(" ");
+          drafts.set(target, next);
+          if (state.sessionId === target) emit({ draft: next });
+        },
+        onDevice(device) { if (token === generation) emit({ device }); },
+      });
+      call = conversation;
+      unsubscribe = call.controller.subscribe(() => {
+        if (token !== generation) return;
+        const snapshot = call.controller.getSnapshot();
+        if (!state.sessionId && snapshot.sessionId) { emit({ sessionId: snapshot.sessionId }); onSession(snapshot.sessionId); }
+        emit({ snapshot, ...(snapshot.inputLevel == null ? {} : { levels: [...state.levels.slice(-19), snapshot.inputLevel] }),
+          ...(snapshot.capture === "recording" && state.snapshot?.capture !== "recording" ? { startedAt: Date.now(), elapsedMs: 0 } : snapshot.capture !== "recording" && state.startedAt ? { startedAt: null, elapsedMs: Date.now() - state.startedAt } : {}) });
+      });
+      await call.start({ sessionId: target, continuous: state.mode === "continuous" });
+    }); },
+    complete() { return enqueue(async () => {
+      await finishCapture();
+      const text = state.draft;
+      if (!text) return;
+      await complete({ sessionId: state.sessionId, text });
+      drafts.delete(state.sessionId); emit({ draft: "", visible: false }); await end();
+    }); },
+    discard() { return enqueue(async () => { await end(); drafts.delete(state.sessionId); emit({ draft: "" }); }); },
+    end: () => enqueue(end),
+    action(action) { return enqueue(async () => {
+      if (action === "mute") await call?.setReadAloud(state.snapshot.outputMuted);
+      if (action === "playback") await call?.controller.stopPlayback();
+      if (action === "input") { if (state.snapshot.inputPaused) call?.controller.resumeInput(); else await call?.controller.pauseInput(); }
+    }); },
+    dispose: () => enqueue(async () => { try { await end(); } finally { listeners.clear(); drafts.clear(); } }),
+  };
+}

package/voice/projection.js

@@ -0,0 +1,67 @@
+/** Read-only records: native dsh events remain the authority for task execution. */
+export function projectVoiceRecords(records, native = []) {
+  const tasks = new Map();
+  for (const row of records) {
+    if (row.role !== "task" || !row.taskId) continue;
+    try { const task = JSON.parse(row.text); if (Number.isInteger(task.turn)) tasks.set(row.taskId, task.turn); } catch { /* A delegation request is text, not a result. */ }
+  }
+  const request = (row) => row.requestId || row.data?.source?.rpcId;
+  const turn = (row) => row.turn ?? row.data?.turn ?? row.location?.turn?.turn;
+  const role = (row) => row.type || row.kind;
+  const rows = [];
+  for (const record of records) {
+    if (!["user", "assistant"].includes(record.role) || !record.text) continue;
+    const taskTurn = record.taskTurn ?? tasks.get(record.taskId) ?? turn(native.find((row) => request(row) === record.taskId) || {});
+    const match = record.taskId && [...native].reverse().find((row) => record.role === "user"
+      ? role(row) === "user" && request(row) === record.taskId
+      : ["assistant", "closing", "turn-tail"].includes(role(row)) && taskTurn != null && turn(row) === taskTurn);
+    if (match) {
+      if (record.role === "assistant" && tasks.has(record.taskId) && !record.turnId?.startsWith("result:")) continue;
+      if (record.role === "assistant" && record.text !== (match.text || match.data?.text || (match.data?.closing?.blocks || match.data?.blocks || []).filter((block) => block.type === "text").map((block) => block.text).join(""))) rows.push({ ...record, attachedTo: match.key || match.id, summary: true });
+      continue;
+    }
+    rows.push({ ...record, type: record.role, pending: record.status === "streaming" });
+  }
+  return rows.sort((a, b) => a.anchorSeq - b.anchorSeq || a.sequence - b.sequence || a.id.localeCompare(b.id));
+}
+
+export function mergeVoiceTranscript(native, records) {
+  const projected = projectVoiceRecords(records, native);
+  const rows = [...native];
+  for (const row of projected.filter((item) => !item.summary)) {
+    const next = rows.findIndex((item) => !item.voiceId && (item.anchorSeq ?? item.seq ?? Infinity) > row.anchorSeq);
+    rows.splice(next < 0 ? rows.length : next, 0, row);
+  }
+  for (const row of projected.filter((item) => item.summary)) {
+    const index = rows.findIndex((item) => (item.key || item.id) === row.attachedTo);
+    if (index >= 0) rows[index] = { ...rows[index], voiceSummary: row.text };
+  }
+  return rows;
+}
+
+/** Paginated long polling is independent of capture, panel mounts and playback. */
+export function subscribeVoiceHistory({ request, sessionId, onRecords, onError = () => {} }) {
+  const abort = new AbortController();
+  let version = -1;
+  const task = (async () => {
+    while (!abort.signal.aborted) {
+      try {
+        let after = 0; let next; let snapshotVersion; const rows = [];
+        do {
+          const response = await request("/api/lares/voice/history", { method: "POST", signal: abort.signal,
+            body: { sessionId, after, limit: 200, version: after ? undefined : version, waitMs: after || version < 0 ? 0 : 20000 } });
+          if (!response.ok) throw new Error(response.body?.error?.code || "voice_records_failed");
+          if (snapshotVersion != null && response.body.version !== snapshotVersion) { version = -1; break; }
+          snapshotVersion = response.body.version;
+          rows.push(...response.body.records); next = response.body.next; after = next;
+          if (!next) { version = response.body.version; if (!abort.signal.aborted) onRecords(rows); }
+        } while (next && !abort.signal.aborted);
+      } catch (error) {
+        if (abort.signal.aborted) return;
+        onError(error);
+        await new Promise((resolve) => { const finish = () => { clearTimeout(timer); abort.signal.removeEventListener("abort", finish); resolve(); }; const timer = setTimeout(finish, 2000); abort.signal.addEventListener("abort", finish, { once: true }); });
+      }
+    }
+  })();
+  return Object.assign(() => abort.abort(), { done: task });
+}

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