@olares/lares-core 0.15.11 → 0.15.12

package/voice/gpu-mode.js

@@ -2,8 +2,24 @@ import { readJsonFile, writeJsonFile } from "../tools/json-file.js";
 import { dshPluginConfigPath } from "../workspace/home.js";
 import { VoiceError } from "../router/stt.js";
 import { readConfig, writeConfig } from "./config.js";
+import { cliProblem, gpuProblem } from "./gpu-problem.js";
 import { chartPhase, currentChartRow, runOlaresCli, VOICE_CHARTS } from "./install.js";
 
+/** A GPU failure the settings panel explains; `params` reach the browser beside the code. */
+export class GpuError extends VoiceError {
+  /** @param {import('./gpu-problem.js').GpuProblem} problem */
+  constructor(problem, status = 502) {
+    super(problem.code, status, problem.detail || problem.code);
+    this.params = problem.params;
+    this.problem = problem;
+  }
+}
+
+function problemOf(err) {
+  if (err instanceof GpuError) return err.problem;
+  return gpuProblem("voice_gpu_failed", {}, err instanceof Error ? err.message : String(err));
+}
+
 /**
  * Reading answers while they are written needs the LLM and speech models on
  * the GPU at once, so the card is cut into memory slices. Reading finished
@@ -71,8 +87,8 @@ export function parseQuantity(text) {
  * @returns {Promise<{ app: string, title: string, source: string, phase: string, required: number }[]>}
  */
 export async function gpuApps(options = {}) {
-  const mine = await runOlaresCli(["market", "list", "--mine", "-o", "json"], options.spawnFn);
-  if (mine.code !== 0 || !Array.isArray(mine.json)) throw new VoiceError("voice_gpu_failed", 502, mine.message);
+  const mine = await runOlaresCli(["market", "list", "--mine", "-o", "json"], options.spawnFn, MANIFEST_LIMIT);
+  if (mine.code !== 0 || !Array.isArray(mine.json)) throw new GpuError(cliProblem(mine, "voice_gpu_failed"));
   const apps = await Promise.all(mine.json.map(async (row) => {
     const app = typeof row?.name === "string" ? row.name : "";
     if (!app) return null;
@@ -110,7 +126,7 @@ function speechDevice(nodes) {
 export async function speechGpu(options = {}) {
   const result = await runOlaresCli(["settings", "compute", "list", "-o", "json"], options.spawnFn);
   if (result.code !== 0 || !Array.isArray(result.json)) {
-    throw new VoiceError("voice_gpu_failed", 502, result.message);
+    throw new GpuError(cliProblem(result, "voice_gpu_failed"));
   }
   const device = speechDevice(result.json);
   if (!device) return null;
@@ -155,11 +171,48 @@ function sliceFlag(gpu, app, plan) {
   return `${gpu.node}:${gpu.device}:${Math.round(Number(plan.slices[app]) / MIB)}Mi`;
 }
 
+/** The binding an app had before this switch touched it, to put it back after a failure. */
+function bindingFlag(gpu, binding) {
+  return gpu.type === "MemorySlice" && binding.memory > 0
+    ? `${gpu.node}:${gpu.device}:${Math.round(binding.memory / MIB)}Mi`
+    : `${gpu.node}:${gpu.device}`;
+}
+
+function gib(bytes) {
+  return Math.round((bytes / 2 ** 30) * 10) / 10;
+}
+
+/**
+ * Entering MemorySlice with no slice planned would stop every app and start
+ * none. The first time, each running app on the card gets its manifest
+ * minimum; when that cannot fit, or nothing qualifies, the user plans it.
+ */
+async function ensureSlices(gpu, plan, options) {
+  if (slicePlan(null, plan).some((entry) => entry.enabled)) return plan;
+  const onCard = new Set(union(plan.apps, gpu.bindings.map((binding) => binding.app)));
+  const seeded = (await gpuApps(options)).filter((entry) => (
+    onCard.has(entry.app) && entry.phase === "running" && entry.required > 0 && !plan.off.includes(entry.app)
+  ));
+  if (!seeded.length) throw new GpuError(gpuProblem("voice_gpu_plan_empty"), 409);
+  const need = seeded.reduce((sum, entry) => sum + entry.required, 0);
+  if (gpu.memory > 0 && need > gpu.memory) {
+    throw new GpuError(gpuProblem("voice_gpu_plan_over", { need: gib(need), total: gib(gpu.memory) }), 409);
+  }
+  const slices = { ...plan.slices };
+  for (const entry of seeded) slices[entry.app] = Math.ceil(entry.required / MIB) * MIB;
+  const next = { ...plan, slices };
+  writePlan(next);
+  return next;
+}
+
 let job = null;
 
+const BUSY = new Set(["switching", "restoring", "resuming"]);
+
 /** The switch in progress or last finished, for the settings panel to poll. */
 export function gpuSwitchJob() {
-  return job ? { ...job, apps: job.apps.map((app) => ({ ...app })) } : null;
+  if (!job) return null;
+  return { ...job, apps: job.apps.map((app) => ({ ...app })), restored: job.restored.map((app) => ({ ...app })) };
 }
 
 /**
@@ -167,89 +220,121 @@ export function gpuSwitchJob() {
  * the plan. Switching the type stops every app bound to the card; within
  * MemorySlice only apps whose slice changed are stopped and rebound. Apps
  * resume smallest first, so the LLM is not starved of a slice.
+ * The reading mode is saved only once the card is where it needs to be; a
+ * failure before that puts the stopped apps back on their old bindings.
  * Returns at once; the job runs on and reports through `gpuSwitchJob`.
  */
 export function startGpuSwitch(streaming, options = {}) {
-  if (job?.phase === "switching" || job?.phase === "resuming") {
-    throw new VoiceError("voice_gpu_busy", 409, "the GPU is already switching");
+  if (BUSY.has(job?.phase)) {
+    throw new GpuError(gpuProblem("voice_gpu_busy"), 409);
   }
   const target = gpuTypeFor(streaming);
-  job = { target, phase: "switching", startedAt: Date.now(), apps: [], error: "" };
+  job = { target, phase: "switching", startedAt: Date.now(), apps: [], restored: [], problem: null };
   const current = job;
-  void runSwitch(current, options).catch((err) => {
+  void runSwitch(current, streaming, options).catch((err) => {
     current.phase = "failed";
-    current.error = err instanceof Error ? err.message : String(err);
+    current.problem = problemOf(err);
   });
   return gpuSwitchJob();
 }
 
-async function runSwitch(current, options) {
+async function runSwitch(current, streaming, options) {
   const run = (args) => runOlaresCli(args, options.spawnFn);
-  // set-type and unbind return before their stops settle, and a resume against a stopping app is refused.
-  const stop = (app) => run(["market", "stop", app, "--watch", "--watch-timeout", "10m", "-o", "json"]);
   const gpu = await speechGpu(options);
-  if (!gpu) throw new VoiceError("voice_gpu_failed", 404, "no NVIDIA GPU found");
   const sliced = current.target === "MemorySlice";
+  if (!gpu) {
+    if (sliced) throw new GpuError(gpuProblem("voice_gpu_no_gpu"), 404);
+    writeConfig({ streaming });
+    current.phase = "done";
+    return;
+  }
   const switching = gpu.type !== current.target;
+  if (switching && !gpu.available.includes(current.target)) {
+    throw new GpuError(gpuProblem("voice_gpu_unsupported", { model: gpu.model || gpu.device }), 400);
+  }
   if (gpu.bindings.length) rememberBound(gpu, switching);
-  const plan = readPlan();
+  const plan = sliced ? await ensureSlices(gpu, readPlan(), options) : readPlan();
   const kept = new Set();
-  if (switching) {
-    if (!gpu.available.includes(current.target)) {
-      throw new VoiceError("voice_gpu_failed", 400, `this GPU does not support ${current.target}`);
+  const stopped = [];
+  // set-type and unbind return before their stops settle, and a resume against a stopping app is refused.
+  const stop = async (binding) => {
+    const result = await run(["market", "stop", binding.app, "--watch", "--watch-timeout", "10m", "-o", "json"]);
+    if (result.code !== 0 && !(await settledAs(binding.app, "stopped", options))) {
+      throw new GpuError(cliProblem(result, "voice_gpu_stop_failed", { app: binding.app }));
     }
-    for (const binding of gpu.bindings) await stop(binding.app);
-    const switched = await run(["settings", "compute", "set-type", gpu.node, gpu.device, "--type", current.target, "--yes", "-o", "json"]);
-    if (switched.code !== 0) throw new VoiceError("voice_gpu_failed", 502, switched.message);
-  } else if (sliced) {
-    for (const binding of gpu.bindings) {
-      const wanted = plan.off.includes(binding.app) ? 0 : Number(plan.slices[binding.app]) || 0;
-      if (wanted === binding.memory) {
-        kept.add(binding.app);
-        continue;
+    stopped.push(binding);
+  };
+  try {
+    if (switching) {
+      for (const binding of gpu.bindings) await stop(binding);
+      const switched = await run(["settings", "compute", "set-type", gpu.node, gpu.device, "--type", current.target, "--yes", "-o", "json"]);
+      if (switched.code !== 0) {
+        throw new GpuError(cliProblem(switched, "voice_gpu_failed"));
+      }
+    } else if (sliced) {
+      for (const binding of gpu.bindings) {
+        const wanted = plan.off.includes(binding.app) ? 0 : Number(plan.slices[binding.app]) || 0;
+        if (wanted === binding.memory) {
+          kept.add(binding.app);
+          continue;
+        }
+        await stop(binding);
+        const unbound = await run(["settings", "compute", "unbind", binding.app, "--yes", "-o", "json"]);
+        if (unbound.code !== 0) throw new GpuError(cliProblem(unbound, "voice_gpu_failed", { app: binding.app }));
       }
-      await stop(binding.app);
-      const unbound = await run(["settings", "compute", "unbind", binding.app, "--yes", "-o", "json"]);
-      if (unbound.code !== 0) throw new VoiceError("voice_gpu_failed", 502, unbound.message);
     }
+  } catch (err) {
+    current.phase = "restoring";
+    for (const binding of stopped) {
+      const resumed = await resumeApp(binding.app, bindingFlag(gpu, binding), options);
+      current.restored.push({ app: binding.app, ok: !resumed });
+    }
+    throw err;
   }
+  writeConfig({ streaming });
   current.phase = "resuming";
   const apps = (sliced
     ? slicePlan(null, plan).filter((entry) => entry.enabled).map((entry) => entry.app)
     : plan.apps
   ).sort((a, b) => (Number(plan.slices[a]) || Infinity) - (Number(plan.slices[b]) || Infinity));
   for (const app of apps) {
-    const entry = { app, ok: false, message: "" };
+    const entry = { app, ok: false, problem: null };
     current.apps.push(entry);
     if (kept.has(app)) {
       entry.ok = true;
       continue;
     }
-    const resumed = await run([
-      "market", "resume", app,
-      "--compute-binding", sliced ? sliceFlag(gpu, app, plan) : `${gpu.node}:${gpu.device}`,
-      "--watch", "--watch-timeout", "15m", "-o", "json",
-    ]);
-    entry.ok = resumed.code === 0;
-    if (!entry.ok) entry.message = resumed.message;
+    entry.problem = await resumeApp(app, sliced ? sliceFlag(gpu, app, plan) : `${gpu.node}:${gpu.device}`, options);
+    entry.ok = !entry.problem;
   }
   current.phase = current.apps.every((app) => app.ok) ? "done" : "partial";
 }
 
+/** Resumes one app onto the card; null once it runs, else why it did not. */
+async function resumeApp(app, binding, options) {
+  const resumed = await runOlaresCli([
+    "market", "resume", app,
+    "--compute-binding", binding,
+    "--watch", "--watch-timeout", "15m", "-o", "json",
+  ], options.spawnFn);
+  if (resumed.code === 0 || await settledAs(app, "running", options)) return null;
+  return cliProblem(resumed, "voice_gpu_resume_failed", { app });
+}
+
 /** What the settings panel shows: the reading mode, the card, its slice plan, and any switch in progress. */
 export async function gpuModePayload(options = {}) {
   let gpu = null;
-  let error = "";
+  let problem = null;
   try {
     gpu = await speechGpu(options);
   } catch (err) {
-    error = err instanceof Error ? err.message : String(err);
+    problem = problemOf(err);
   }
   let apps = [];
   try {
     apps = await gpuApps(options);
   } catch (err) {
-    error ||= err instanceof Error ? err.message : String(err);
+    problem ||= problemOf(err);
   }
   const streaming = readConfig().streaming;
   const bound = new Set(gpu?.bindings.map((binding) => binding.app) ?? []);
@@ -262,18 +347,17 @@ export async function gpuModePayload(options = {}) {
       ...entry,
       bound: bound.has(entry.app),
       pending: pendingApps.get(entry.app) ?? "",
-      error: appErrors.get(entry.app) ?? "",
+      problem: appErrors.get(entry.app) ?? null,
     })),
     job: gpuSwitchJob(),
-    error,
+    problem,
   };
 }
 
-/** Saves the reading mode and starts moving the card to the type it needs. */
+/** Starts moving the card to the type the reading mode needs; the mode is saved once it gets there. */
 export async function switchReadingMode(streaming, options = {}) {
   if (typeof streaming !== "boolean") throw new VoiceError("voice_config_invalid", 400, "streaming must be a boolean");
   startGpuSwitch(streaming, options);
-  writeConfig({ streaming });
   return gpuModePayload(options);
 }
 
@@ -283,12 +367,12 @@ export async function switchReadingMode(streaming, options = {}) {
  * @param {unknown} entries `[{ app, enabled, memory }]`, memory in bytes
  */
 export async function saveSlicePlan(entries, options = {}) {
-  const invalid = (message) => {
-    throw new VoiceError("voice_config_invalid", 400, message);
+  const invalid = (code, params, detail) => {
+    throw new GpuError(gpuProblem(code, params, detail), 400);
   };
-  if (!Array.isArray(entries)) invalid("plan must be a list");
+  if (!Array.isArray(entries)) throw new VoiceError("voice_config_invalid", 400, "plan must be a list");
   const gpu = await speechGpu(options);
-  if (!gpu) throw new VoiceError("voice_gpu_failed", 404, "no NVIDIA GPU found");
+  if (!gpu) throw new GpuError(gpuProblem("voice_gpu_no_gpu"), 404);
   const plan = readPlan();
   const candidates = slicePlan(gpu, plan, await gpuApps(options));
   const known = new Set(candidates.map((entry) => entry.app));
@@ -298,12 +382,12 @@ export async function saveSlicePlan(entries, options = {}) {
   let total = 0;
   for (const entry of entries) {
     const app = entry?.app;
-    if (typeof app !== "string" || !known.has(app)) invalid(`unknown app ${String(app)}`);
-    if (typeof entry.enabled !== "boolean") invalid(`${app}: enabled must be a boolean`);
+    if (typeof app !== "string" || !known.has(app)) invalid("voice_gpu_unknown_app", { app: String(app) }, `unknown app ${String(app)}`);
+    if (typeof entry.enabled !== "boolean") throw new VoiceError("voice_config_invalid", 400, `${app}: enabled must be a boolean`);
     const memory = Number(entry.memory);
     const floor = Math.max(256 * MIB, required.get(app) || 0);
     if (entry.enabled && !(Number.isFinite(memory) && memory >= floor)) {
-      invalid(`${app}: memory must be at least ${Math.round(floor / MIB)}Mi`);
+      invalid("voice_gpu_plan_floor", { app, size: gib(floor) }, `${app}: memory must be at least ${Math.round(floor / MIB)}Mi`);
     }
     if (Number.isFinite(memory) && memory > 0) slices[app] = Math.round(memory / MIB) * MIB;
     if (entry.enabled) {
@@ -313,7 +397,9 @@ export async function saveSlicePlan(entries, options = {}) {
       off.add(app);
     }
   }
-  if (gpu.memory > 0 && total > gpu.memory) invalid("slices exceed the GPU memory");
+  if (gpu.memory > 0 && total > gpu.memory) {
+    invalid("voice_gpu_plan_over", { need: gib(total), total: gib(gpu.memory) }, "slices exceed the GPU memory");
+  }
   writePlan({ apps: union(plan.apps, gpu.bindings.map((binding) => binding.app)), slices, off: [...off] });
   if (gpu.type === "MemorySlice") startGpuSwitch(true, options);
   return gpuModePayload(options);
@@ -337,17 +423,19 @@ const appErrors = new Map();
  */
 export async function gpuAppAction(app, op, options = {}) {
   if (op !== "resume" && op !== "stop") throw new VoiceError("voice_config_invalid", 400, "op must be resume or stop");
-  if (job?.phase === "switching" || job?.phase === "resuming" || pendingApps.has(app)) {
-    throw new VoiceError("voice_gpu_busy", 409, "the GPU is busy");
+  if (BUSY.has(job?.phase) || pendingApps.has(app)) {
+    throw new GpuError(gpuProblem("voice_gpu_busy"), 409);
   }
   const [gpu, apps] = await Promise.all([speechGpu(options), gpuApps(options)]);
-  if (!gpu) throw new VoiceError("voice_gpu_failed", 404, "no NVIDIA GPU found");
-  if (!apps.some((entry) => entry.app === app)) throw new VoiceError("voice_config_invalid", 400, `${app} is not a GPU app`);
+  if (!gpu) throw new GpuError(gpuProblem("voice_gpu_no_gpu"), 404);
+  if (!apps.some((entry) => entry.app === app)) {
+    throw new GpuError(gpuProblem("voice_gpu_unknown_app", { app }, `${app} is not a GPU app`), 400);
+  }
   const plan = readPlan();
   let binding = `${gpu.node}:${gpu.device}`;
   if (op === "resume" && gpu.type === "MemorySlice") {
     if (plan.off.includes(app) || !(Number(plan.slices[app]) > 0)) {
-      throw new VoiceError("voice_config_invalid", 400, `${app} has no memory slice`);
+      throw new GpuError(gpuProblem("voice_gpu_no_slice", { app }, `${app} has no memory slice`), 400);
     }
     binding = sliceFlag(gpu, app, plan);
   }
@@ -359,14 +447,14 @@ export async function gpuAppAction(app, op, options = {}) {
   void runOlaresCli(args, options.spawnFn)
     .then(async (result) => {
       if (result.code !== 0 && !(await settledAs(app, op === "stop" ? "stopped" : "running", options))) {
-        appErrors.set(app, result.message);
+        appErrors.set(app, cliProblem(result, op === "stop" ? "voice_gpu_stop_failed" : "voice_gpu_resume_failed", { app }));
         return;
       }
       const latest = readPlan();
       const kept = latest.apps.filter((name) => name !== app);
       writePlan({ ...latest, apps: op === "resume" ? [...kept, app] : kept });
     })
-    .catch((err) => appErrors.set(app, err instanceof Error ? err.message : String(err)))
+    .catch((err) => appErrors.set(app, problemOf(err)))
     .finally(() => pendingApps.delete(app));
   return gpuModePayload(options);
 }

package/voice/gpu-problem.js

@@ -0,0 +1,47 @@
+/**
+ * Why a GPU step failed, as a code the settings panel turns into what to do
+ * next. `detail` keeps olares-cli's own words for what a code cannot explain.
+ * Shared by the Host and the browser, so it imports nothing.
+ *
+ * @typedef {{ code: string, params: Record<string, unknown>, detail: string }} GpuProblem
+ */
+
+/** @returns {GpuProblem} */
+export function gpuProblem(code, params = {}, detail = "") {
+  return { code, params, detail: String(detail ?? "") };
+}
+
+const FORBIDDEN = /\b403\b|forbidden|permission denied|not (allowed|permitted)|admin(istrator)? (role )?(is )?required/i;
+const LOGIN = /\b(401|459)\b|unauthori[sz]ed|invalidated|not logged in|profile login|credential (is )?(missing|absent|invalid)/i;
+const BLOCKED = /bound-apps-stop-blocked/i;
+const MEMORY = /out of memory|(insufficient|not enough)[^.\n]*(gpu|memory|vram)|gpu memory[^.\n]*(exceed|insufficient)/i;
+
+/**
+ * An olares-cli result → the problem the user acts on. Account and login
+ * failures are fixed outside Lares, so they win over the step's own code.
+ * @param {{ message?: string, text?: string }} result
+ * @param {string} fallback code for this step
+ */
+export function cliProblem(result, fallback, params = {}) {
+  const detail = String(result?.message ?? "");
+  const text = `${detail}\n${result?.text ?? ""}`;
+  if (FORBIDDEN.test(text)) return gpuProblem("voice_gpu_forbidden", params, detail);
+  if (LOGIN.test(text)) return gpuProblem("voice_gpu_login", params, detail);
+  if (BLOCKED.test(text)) return gpuProblem("voice_gpu_blocked", params, detail);
+  if (MEMORY.test(text)) return gpuProblem("voice_gpu_memory", params, detail);
+  return gpuProblem(fallback, params, detail);
+}
+
+/**
+ * Problem → sentence in the product language. Unknown codes fall back to the
+ * generic failure, which carries the CLI detail.
+ * @param {(key: string, params?: Record<string, unknown>) => string} translate
+ * @param {GpuProblem | null | undefined} problem
+ */
+export function gpuProblemText(translate, problem) {
+  if (!problem?.code) return "";
+  const params = { ...problem.params, detail: problem.detail || problem.code };
+  const key = `error.${problem.code}`;
+  const text = translate(key, params);
+  return text === key ? translate("error.voice_gpu_failed", params) : text;
+}

package/voice/host/bluetooth-ready.py

@@ -1131,6 +1131,8 @@ def dispatch(payload, directory):
         return play_file(directory, payload.get("file"))
     if op == "play-stream":
         return open_stream(directory, payload.get("file"), payload.get("rate"), payload.get("channels"))
+    if op == "playback-status":
+        return {"op": op, "playing": playback_proc is not None and playback_proc.poll() is None}
     if op == "playback-stop":
         return stop_playback_request()
     if op == "capture-start":

package/voice/host-input.js

@@ -0,0 +1,38 @@
+export function createHostInput(port) {
+  let abort = null;
+  return {
+    capabilities: { duplex: false, bargeIn: false, audio: "pcm16-16000" },
+    async capture({ signal, onTranscribing, continuous = false } = {}) {
+      abort = new AbortController();
+      const current = abort;
+      const cancel = () => current.abort();
+      signal?.addEventListener("abort", cancel, { once: true });
+      try {
+        if (signal?.aborted) return "";
+        const opened = await port.start(current.signal);
+        if (!opened.recording) throw new Error("voice_bluetooth_not_ready");
+        while (!current.signal.aborted) {
+          const state = await port.status(current.signal);
+          if (state.phase === "transcribing") onTranscribing?.();
+          if (state.phase === "done") return state.text;
+          if (state.phase === "error") {
+            if (continuous && ["voice_no_input", "voice_too_short"].includes(state.error)) return "";
+            throw new Error(state.error);
+          }
+          if (state.phase === "idle") return "";
+          await new Promise((resolve) => {
+            const finish = () => { clearTimeout(timer); current.signal.removeEventListener("abort", finish); resolve(); };
+            const timer = setTimeout(finish, 200);
+            current.signal.addEventListener("abort", finish, { once: true });
+          });
+        }
+        return "";
+      } catch (error) {
+        if (current.signal.aborted) return "";
+        throw error;
+      } finally { signal?.removeEventListener("abort", cancel); }
+    },
+    stop: () => port.stop(),
+    async cancel() { if (!abort) return; abort.abort(); abort = null; await port.cancel(); },
+  };
+}

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";
 }