@olares/lares-core 0.15.10 → 0.15.12

package/voice/composite-gateway.js

@@ -0,0 +1,156 @@
+import { randomUUID } from "node:crypto";
+import { WebSocketServer } from "ws";
+import { verifyVoicePrincipal, authorizeVoicePreset } from "./external.js";
+import { createSpeechEndpoint, frameRms } from "./endpoint.js";
+import { pcmSamples } from "./realtime-audio.js";
+
+export const COMPOSITE_CAPABILITIES = Object.freeze({ protocol: "olares-voice-ws-v1", transport: "websocket", input: "pcm16-mono-24000", output: "pcm16-mono-24000", turnDetection: ["manual", "server_vad"], contextResume: true, requiresPlaybackAck: true, clientTools: false, truncation: false, webrtc: false, sip: false, usage: "child-models" });
+
+/** Minimal declared Realtime subset. It never accepts arbitrary client tools or business bindings. */
+export function createCompositeGateway({ service, config, transcribe, synthesize, secret, grants = {}, hostOwner = "", enabled = false }) {
+  const server = new WebSocketServer({ noServer: true, maxPayload: 96 * 1024, perMessageDeflate: false });
+  const clients = new Map();
+  const nonces = new Map();
+  return {
+    capabilities: () => ({ ...COMPOSITE_CAPABILITIES, enabled: enabled && typeof secret === "string" && secret.length >= 32 }),
+    upgrade(req, socket, head) {
+      let identity;
+      let grant;
+      try {
+        if (!enabled) throw new Error("voice_external_disabled");
+        identity = verifyVoicePrincipal(req.headers, secret);
+        const model = new URL(req.url, "http://voice.invalid").searchParams.get("model");
+        grant = authorizeVoicePreset(identity, grants, model);
+        if (["assistant", "direct"].includes(grant.preset) && grant.owner !== hostOwner) throw new Error("voice_external_owner_mismatch");
+        const dependencies = config();
+        if ([dependencies.model, dependencies.chatModel, dependencies.ttsModel, dependencies.realtimeModel].some((id) => id === model || id?.endsWith(`/${model}`))) throw new Error("voice_recursive_model");
+        for (const [nonce, expires] of nonces) if (expires < Date.now()) nonces.delete(nonce);
+        if (nonces.has(identity.nonce) || nonces.size >= 4096 || clients.size >= 64) throw new Error("voice_external_limit");
+        nonces.set(identity.nonce, Date.now() + 120000);
+      } catch {
+        socket.end("HTTP/1.1 403 Forbidden\r\nConnection: close\r\n\r\n"); return;
+      }
+      server.handleUpgrade(req, socket, head, (client) => {
+        clients.set(client, () => close());
+        const scope = { id: randomUUID(), owner: grant.owner, authorizedBinding: grant, device: "device" };
+        let chunks = [], bytes = 0, automatic = false, closed = false, busy = false, generation = 0, seconds = 0;
+        let endpoint = createSpeechEndpoint({ silenceMs: config().endpointSilenceMs || 500 });
+        let lastReply = null;
+        let awaitingPlayback = false;
+        let audioOutput = true;
+        let responseId = null;
+        let speaking = false;
+        let configuring = false;
+        let submittedTurns = 0;
+        let alive = true;
+        const send = (event) => {
+          if (client.readyState !== 1) return;
+          if (client.bufferedAmount > 1024 * 1024) { close(); return; }
+          client.send(JSON.stringify({ event_id: randomUUID(), ...event }));
+        };
+        const reset = () => { chunks = []; bytes = 0; speaking = false; endpoint = createSpeechEndpoint({ silenceMs: config().endpointSilenceMs || 500 }); };
+        const done = (id, status = "completed") => send({ type: "response.done", response: { id, status, output: [] }, voice_usage: { input_audio_seconds: seconds, billing: "child-models" } });
+        const emit = async (text, id, epoch) => {
+          responseId = id;
+          send({ type: "response.created", response: { id, status: "in_progress" } });
+          send({ type: "response.output_audio_transcript.delta", response_id: id, delta: text });
+          if (!audioOutput) { done(id); return; }
+          scope.outputAbort = new AbortController();
+          const audio = await synthesize(text, scope);
+          if (closed || epoch !== generation) return;
+          awaitingPlayback = true;
+          for (let offset = 0; offset < audio.length; offset += 24000) send({ type: "response.output_audio.delta", response_id: id, item_id: id, delta: audio.subarray(offset, offset + 24000).toString("base64") });
+          send({ type: "response.output_audio.done", response_id: id });
+          done(id);
+        };
+        const commit = async () => {
+          if (!bytes || busy) return;
+          const input = Buffer.concat(chunks); reset(); busy = true;
+          const epoch = generation;
+          const id = randomUUID(); submittedTurns++;
+          try {
+            let text = await transcribe(input, scope);
+            if (grant.preset === "dictation") text = await service.clean(scope, text);
+            if (closed || epoch !== generation || !text.trim()) return;
+            send({ type: "conversation.item.input_audio_transcription.completed", item_id: id, content_index: 0, transcript: text });
+            if (grant.preset === "dictation") return;
+            const state = await service.prompt(scope, { text, requestId: id });
+            if (closed || epoch !== generation) return;
+            if (state.utterance?.text && !state.utterance.silent) { lastReply = state.utterance.key; await emit(state.utterance.text, id, epoch); }
+          } catch (cause) { if (!closed && epoch === generation) send({ type: "error", error: { code: cause.code || "voice_failed", message: "Voice operation failed" } }); }
+          finally { busy = false; }
+        };
+        const close = () => {
+          if (closed) return;
+          closed = true; scope.outputAbort?.abort(); generation++; reset(); clearInterval(heartbeat); clearInterval(results); clearTimeout(idle);
+          clients.delete(client); client.close(); void service.close(scope).catch(() => {});
+        };
+        let idle;
+        const touch = () => { clearTimeout(idle); idle = setTimeout(close, config().idleTimeoutMs || 300000); };
+        touch();
+        const heartbeat = setInterval(() => { if (!alive) close(); else { alive = false; client.ping(); } }, 15000);
+        const results = setInterval(() => {
+          if (!scope.active || busy || speaking || awaitingPlayback) return;
+          try {
+            const state = service.state(scope);
+            if (!state.utterance?.text || state.utterance.key === lastReply || state.utterance.silent) return;
+            lastReply = state.utterance.key; busy = true;
+            void emit(state.utterance.text, randomUUID(), generation).catch(() => close()).finally(() => { busy = false; });
+          } catch { close(); }
+        }, 250);
+        client.on("pong", () => { alive = true; });
+        client.on("close", close); client.on("error", close);
+        void service.open(scope, { preset: grant.preset, sessionId: grant.sessionId, readAloud: false }).then(() => {
+          send({ type: "session.created", session: { id: scope.id, voice_context_id: scope.contextId, model: identity.model, type: "realtime", capabilities: COMPOSITE_CAPABILITIES } });
+          client.on("message", async (raw) => {
+            try {
+              if (configuring) throw new Error("voice_not_ready");
+              const event = JSON.parse(raw.toString());
+              if (event.type === "session.update") {
+                touch();
+                const session = event.session || {};
+                if (session.type && session.type !== "realtime") throw new Error("voice_session_forbidden");
+                if (session.audio?.input && Object.keys(session.audio.input).some((key) => !["format", "turn_detection"].includes(key))) throw new Error("voice_audio_unsupported");
+                if (session.audio?.output && Object.keys(session.audio.output).some((key) => key !== "format")) throw new Error("voice_audio_unsupported");
+                if (Object.keys(session).some((key) => !["type", "model", "audio", "output_modalities", "voice_context_id"].includes(key)) || (session.model && session.model !== identity.model)) throw new Error("voice_session_forbidden");
+                if (session.voice_context_id && session.voice_context_id !== scope.contextId) {
+                  if (submittedTurns || bytes || busy) throw new Error("voice_context_locked");
+                  configuring = true;
+                  try {
+                    await service.close(scope);
+                    await service.open(scope, { preset: grant.preset, sessionId: grant.sessionId, contextId: session.voice_context_id, readAloud: false });
+                  } finally { configuring = false; }
+                }
+                const detection = session.audio?.input?.turn_detection;
+                if (detection && (detection.type !== "server_vad" || Object.keys(detection).some((key) => key !== "type"))) throw new Error("voice_turn_detection_unsupported");
+                for (const format of [session.audio?.input?.format, session.audio?.output?.format].filter(Boolean)) if (format.type !== "audio/pcm" || format.rate !== 24000) throw new Error("voice_audio_format");
+                if (session.output_modalities && (!Array.isArray(session.output_modalities) || session.output_modalities.length !== 1 || !["audio", "text"].includes(session.output_modalities[0]))) throw new Error("voice_output_unsupported");
+                audioOutput = !session.output_modalities || session.output_modalities[0] === "audio";
+                automatic = detection?.type === "server_vad";
+                send({ type: "session.updated", session: { id: scope.id, voice_context_id: scope.contextId, model: identity.model, type: "realtime", capabilities: COMPOSITE_CAPABILITIES } });
+              } else if (event.type === "input_audio_buffer.append") {
+                if (awaitingPlayback) throw new Error("voice_waiting_for_playback");
+                if (busy) throw new Error("voice_turn_busy");
+                if (typeof event.audio !== "string" || event.audio.length > 64000 || !/^[A-Za-z0-9+/]*={0,2}$/.test(event.audio)) throw new Error("voice_audio_format");
+                const chunk = Buffer.from(event.audio, "base64");
+                if (chunk.length % 2 || bytes + chunk.length > 2880000) throw new Error("voice_audio_limit");
+                chunks.push(chunk); bytes += chunk.length; seconds += chunk.length / 48000;
+                const samples = pcmSamples(chunk);
+                if (frameRms(samples) >= 0.004) touch();
+                if (frameRms(samples) >= 0.004 && !speaking) { speaking = true; scope.voiceInputActive = true; send({ type: "input_audio_buffer.speech_started" }); }
+                if (automatic && endpoint.push(1, frameRms(samples), chunk.length / 48)) {
+                  scope.voiceInputActive = false; send({ type: "input_audio_buffer.speech_stopped" }); void commit();
+                }
+              } else if (event.type === "input_audio_buffer.commit") { scope.voiceInputActive = false; void commit(); }
+              else if (event.type === "input_audio_buffer.clear") { reset(); scope.voiceInputActive = false; send({ type: "input_audio_buffer.cleared" }); }
+              else if (event.type === "voice.playback.completed") { awaitingPlayback = false; }
+              else if (event.type === "response.cancel") { scope.outputAbort?.abort(); generation++; reset(); awaitingPlayback = false; done(responseId || randomUUID(), "cancelled"); }
+              else throw new Error("voice_event_unsupported");
+            } catch (cause) { send({ type: "error", error: { code: cause.message, message: "Unsupported or invalid voice event" } }); }
+          });
+        }).catch(close);
+      });
+    },
+    close() { for (const close of clients.values()) close(); server.close(); },
+  };
+}

package/voice/config.js

@@ -4,12 +4,7 @@ import { STT_LANGUAGE_CHOICES } from "./languages.js";
 
 export { STT_LANGUAGE_CHOICES, VOICE_AUTO, voiceMenuValue, voiceValueFromMenu } from "./languages.js";
 
-const DEFAULTS = {
-  model: "",
-  ttsModel: "",
-  language: "",
-  speak: false,
-};
+import { VOICE_DEFAULTS as DEFAULTS, VOICE_PRESETS } from "./options.js";
 
 const WRITABLE = new Set(Object.keys(DEFAULTS));
 const SUPPORTED_LANGUAGES = new Set(["", ...STT_LANGUAGE_CHOICES.map((item) => item.id)]);
@@ -25,14 +20,34 @@ export function validateConfigPatch(raw) {
   const patch = {};
   for (const [key, value] of Object.entries(raw)) {
     if (!WRITABLE.has(key)) invalid(`unknown voice setting: ${key}`);
-    if (key === "speak") {
-      if (typeof value !== "boolean") invalid("speak must be a boolean");
-      patch.speak = value;
+    if (key === "preset") {
+      if (!VOICE_PRESETS.includes(value)) invalid("invalid voice preset");
+      patch[key] = value; continue;
+    }
+    if (key === "endpointSilenceMs") {
+      if (!Number.isInteger(value) || value < 200 || value > 3000) invalid("invalid endpoint delay");
+      patch[key] = value; continue;
+    }
+    if (key === "idleTimeoutMs" || key === "recoveryTimeoutMs") {
+      if (!Number.isInteger(value) || value < 10_000 || value > 3_600_000) invalid(`invalid ${key}`);
+      patch[key] = value;
+      continue;
+    }
+    if (key === "speak" || key === "streaming" || key === "dictationCleanup") {
+      if (typeof value !== "boolean") invalid(`${key} must be a boolean`);
+      patch[key] = value;
+      continue;
+    }
+    if (["mode", "mobileMode", "device", "backend"].includes(key)) {
+      const choices = { mobileMode: ["single", "continuous"], mode: ["single", "continuous"], device: ["auto", "device", "headset"], backend: ["pipeline", "realtime"] };
+      if (!choices[key].includes(value)) invalid(`invalid ${key}`);
+      patch[key] = value;
       continue;
     }
     if (typeof value !== "string") invalid(`${key} must be a string`);
     const normalized = value.trim();
-    if ((key === "model" || key === "ttsModel") && !SAFE_MODEL.test(normalized)) invalid("invalid voice model");
+    if ((key === "model" || key === "ttsModel" || key === "realtimeModel" || key === "chatModel" || key === "voice") && !SAFE_MODEL.test(normalized)) invalid("invalid voice model");
+    if (key === "instructions" && normalized.length > 8000) invalid("voice instructions too long");
     if (key === "language" && !SUPPORTED_LANGUAGES.has(normalized)) invalid("unsupported recognition language");
     patch[key] = normalized;
   }
@@ -47,13 +62,11 @@ function configPath() {
 export function readConfig() {
   const stored = readJsonFile(configPath());
   const merged = { ...DEFAULTS };
-  const model = typeof stored?.model === "string" ? stored.model.trim() : "";
-  const ttsModel = typeof stored?.ttsModel === "string" ? stored.ttsModel.trim() : "";
-  const language = typeof stored?.language === "string" ? stored.language.trim() : "";
-  if (SAFE_MODEL.test(model)) merged.model = model;
-  if (SAFE_MODEL.test(ttsModel)) merged.ttsModel = ttsModel;
-  if (SUPPORTED_LANGUAGES.has(language)) merged.language = language;
-  if (stored?.speak === true) merged.speak = true;
+  for (const key of Object.keys(DEFAULTS)) {
+    if (stored?.[key] !== undefined) {
+      try { Object.assign(merged, validateConfigPatch({ [key]: stored[key] })); } catch {}
+    }
+  }
   return merged;
 }
 

package/voice/controller.js

@@ -0,0 +1,147 @@
+import { mintRpcId } from "../larepass/rpc.js";
+
+/** Device, agent and playback ports are injected; UI frameworks own no turn state. */
+export function createVoiceController({ input, agent, output, voiceId = mintRpcId(), metric = () => {}, onTranscript = null, idleTimeoutMs = 300_000, recoveryTimeoutMs = 120_000, onExpired = () => {}, now = Date.now, schedule = setTimeout, unschedule = clearTimeout }) {
+  let epoch = 0;
+  let take = null;
+  let idleTimer = null;
+  let recoveryTimer = null;
+  const clearTimers = () => { unschedule(idleTimer); unschedule(recoveryTimer); };
+  const expire = async (code) => {
+    await controller.disconnect();
+    await onExpired(code);
+    change({ error: code });
+  };
+  const touch = () => {
+    unschedule(idleTimer);
+    if (state.connection !== "open") return;
+    idleTimer = schedule(() => { void expire("voice_idle_timeout"); }, idleTimeoutMs);
+    idleTimer.unref?.();
+  };
+  let creating = null;
+  let state = Object.freeze({ voiceId, sessionId: null, connection: "closed", capture: "idle", agent: "idle", playback: "idle", continuous: false, inputPaused: false, userSpeaking: false, inputLevel: null, outputMuted: false, error: null });
+  const listeners = new Set();
+  const change = (patch) => {
+    state = Object.freeze({ ...state, ...patch });
+    for (const listener of listeners) listener();
+  };
+  const report = (stage, started, extra = {}) => {
+    try { metric({ voiceId: state.voiceId, sessionId: state.sessionId, stage, durationMs: Math.max(0, now() - started), ...extra }); } catch {}
+  };
+  const live = (run) => run.epoch === epoch && !run.abort.signal.aborted && state.connection === "open";
+  const ensureSession = async () => {
+    if (state.sessionId) return state.sessionId;
+    creating ??= Promise.resolve(agent.create()).then((sessionId) => {
+      if (!sessionId && !agent.lazy) throw new Error("voice_session_failed");
+      return sessionId;
+    });
+    return creating;
+  };
+  const cancelInput = async () => {
+    const old = take;
+    take = null;
+    old?.abort.abort();
+    try { if (old) await input.cancel?.(); } finally { change({ capture: "idle", userSpeaking: false, inputLevel: null }); }
+  };
+  const stopPlayback = async () => {
+    const started = now();
+    await output.stop();
+    change({ playback: "idle" });
+    report("interrupt", started);
+  };
+  const listen = async () => {
+    if (state.connection !== "open" || state.inputPaused || take || state.capture !== "idle") return;
+    if (state.continuous && (
+      (state.agent !== "idle" && !input.capabilities?.listenWhileWorking)
+      || (state.playback !== "idle" && !input.capabilities?.bargeIn)
+    )) return;
+    const run = { epoch, abort: new AbortController(), id: mintRpcId(), started: now() };
+    take = run;
+    change({ capture: "recording", error: null });
+    try {
+      const text = String(await input.capture({ signal: run.abort.signal, continuous: state.continuous, onLevel: (level) => { if (live(run)) change({ inputLevel: Math.max(0, Math.min(1, level)) }); }, onSpeech: () => {
+        if (live(run)) { touch(); change({ userSpeaking: true }); if (input.capabilities?.bargeIn) void stopPlayback(); }
+      }, onTranscribing: () => { if (live(run)) change({ capture: "transcribing", userSpeaking: false }); } }) ?? "").trim();
+      if (!live(run)) return;
+      report("recognition", run.started, { turnId: run.id });
+      if (!text) return;
+      touch();
+      if (onTranscript) {
+        await onTranscript({ text, turnId: run.id, voiceId: state.voiceId, sessionId: state.sessionId, signal: run.abort.signal });
+        return;
+      }
+      const sessionId = await ensureSession();
+      if (!live(run)) return;
+      change({ sessionId, capture: "idle", agent: "running" });
+      await agent.submit({ sessionId, text, requestId: run.id, signal: run.abort.signal });
+      // Acceptance is not completion; observeAgent receives the durable turn lifecycle.
+    } catch (error) {
+      if (live(run)) {
+        await controller.disconnect(error.code || error.message || "voice_failed");
+      }
+    } finally {
+      if (take === run) {
+        take = null;
+        change({ capture: "idle", userSpeaking: false, inputLevel: null });
+        if (state.continuous && state.connection === "open" && (state.agent === "idle" || input.capabilities?.listenWhileWorking) && state.playback === "idle") {
+          queueMicrotask(() => { void listen(); });
+        }
+      }
+    }
+  };
+  const controller = {
+    getSnapshot: () => state,
+    noteActivity: touch,
+    setOutputMuted(outputMuted) { change({ outputMuted }); },
+    bindSession(sessionId) { if (sessionId) change({ sessionId }); },
+    subscribe(listener) { listeners.add(listener); return () => listeners.delete(listener); },
+    async start({ sessionId = null, continuous = false, running = false } = {}) {
+      const startedEpoch = ++epoch;
+      creating = null;
+      await cancelInput();
+      if (startedEpoch !== epoch) return;
+      await stopPlayback();
+      if (startedEpoch !== epoch) return;
+      change({ voiceId, sessionId, continuous, inputPaused: false, connection: "open", agent: running ? "running" : "idle", error: null });
+      clearTimers(); touch();
+      void listen();
+    },
+    listen,
+    stopRecording: () => input.stop?.(),
+    cancelRecording: cancelInput,
+    async pauseInput() { change({ inputPaused: true }); await cancelInput(); },
+    resumeInput() { change({ inputPaused: false }); void listen(); },
+    stopPlayback,
+    async cancelTask() {
+      if (state.sessionId) await agent.cancel(state.sessionId);
+    },
+    observeAgent(running, playbackExpected = false) {
+      if (playbackExpected && take && !input.capabilities?.bargeIn) void cancelInput();
+      change({ agent: running ? "running" : "idle", ...(playbackExpected ? { playback: "pending" } : {}) });
+      if (!running && state.continuous) void listen();
+    },
+    observePlayback(playing) {
+      if (playing !== (state.playback === "playing")) touch();
+      change({ playback: playing ? "playing" : "idle" });
+      if (!playing && state.continuous) void listen();
+    },
+    async disconnect(code = null) {
+      clearTimers();
+      if (code) {
+        recoveryTimer = schedule(() => { void expire("voice_recovery_expired"); }, recoveryTimeoutMs);
+        recoveryTimer.unref?.();
+      }
+      epoch += 1;
+      change({ connection: code ? "paused" : "closed", error: code });
+      await Promise.allSettled([cancelInput(), stopPlayback()]);
+    },
+    async resume() {
+      if (state.connection !== "paused") return;
+      const running = state.sessionId ? await agent.running(state.sessionId) : false;
+      clearTimers();
+      change({ connection: "open", agent: running ? "running" : "idle", error: null });
+      touch(); void listen();
+    },
+  };
+  return controller;
+}

package/voice/conversation.js

@@ -0,0 +1,131 @@
+import { createVoiceController } from "./controller.js";
+import { createDeviceInput } from "./device-input.js";
+import { createHostInput } from "./host-input.js";
+import { mintRpcId } from "../larepass/rpc.js";
+
+export function createVoiceConversation({ request, transcribe, playback, onReply = () => {}, onPhase, mode = () => "queue", device = "device", metric = () => {}, readAloud = true, preset, endpointSilenceMs, idleTimeoutMs, recoveryTimeoutMs, onText = () => {}, onTranscript = null, input: inputPort }) {
+  const voiceId = mintRpcId();
+  const headers = { "x-lares-voice-id": voiceId, "x-lares-voice-device": device };
+  let timer = null;
+  let disposed = false;
+  let version = -1;
+  let lastSessionId = null;
+  let spokenKey = null;
+  let lastReplyKey = null;
+  let mutedKey = null;
+  let submitted = false;
+  let finalSeen = false;
+  let continuous = false;
+  let reading = false;
+  const call = async (path, body, signal) => {
+    const res = await request(`/api/lares/voice${path}`, { method: body === undefined ? "GET" : "POST", headers: { ...headers, "x-lares-voice-speaking": controller.getSnapshot().userSpeaking ? "true" : "false" }, ...(body === undefined ? {} : { body }), signal });
+    if (!res?.ok) throw new Error(res?.body?.error?.code || "voice_failed");
+    return res.body;
+  };
+  const input = inputPort ?? (device === "headset" ? createHostInput({
+    start: (signal) => call("/capture", {}, signal), status: (signal) => call("/capture", undefined, signal),
+    stop: () => call("/capture/stop", {}), cancel: () => call("/capture/cancel", {}),
+  }) : createDeviceInput({ transcribe, onPhase, endpointSilenceMs }));
+  const controller = createVoiceController({ voiceId, input, idleTimeoutMs, recoveryTimeoutMs, onExpired: () => stop(), onTranscript: onTranscript ? async (value) => { const cleaned = await call("/dictation/clean", { text: value.text }, value.signal); value.signal.throwIfAborted(); if (typeof cleaned.text !== "string") throw new Error("voice_cleanup_failed"); await onTranscript({ ...value, text: cleaned.text }); if (!continuous) await stop(); } : null, metric: (event) => {
+    metric(event);
+    void call("/session/metric", { stage: event.stage, durationMs: event.durationMs }).catch(() => {});
+  }, output: { async stop() { playback.stop(); await call("/playback/stop", {}); } }, agent: {
+    lazy: true,
+    create: async () => null,
+    async submit({ text, requestId, signal }) {
+      const state = await call("/session/prompt", { text, requestId, mode: mode() }, signal);
+      submitted = true;
+      lastSessionId = state.sessionId;
+      await poll();
+    },
+    cancel: () => call("/session/cancel", {}),
+    running: async () => (await call("/session")).running === true,
+  } });
+  const poll = async () => {
+    if (disposed) return;
+    const state = await call("/session");
+    if (disposed || controller.getSnapshot().connection !== "open") return;
+    lastSessionId = state.sessionId;
+    if (lastSessionId) controller.bindSession(lastSessionId);
+    if (state.error && state.error !== "voice_cancelled") throw new Error(state.error);
+    if (state.version !== version) {
+      version = state.version;
+      // Reserve playback before releasing the completed Agent turn.
+      const reply = state.utterance;
+      if (reply?.text && !reply.silent) onText(reply.text);
+      const key = reply ? `${state.sessionId}:${reply.key}` : null;
+      lastReplyKey = key;
+      const reserve = readAloud && key !== mutedKey && reply?.text && !reply.silent && key !== spokenKey;
+      if (reserve) spokenKey = key;
+      controller.observeAgent(Boolean(state.running), Boolean(reserve));
+      if (!readAloud || reply?.silent) controller.observePlayback(false);
+      if (readAloud && key !== mutedKey && reply) onReply({ ...reply, key: `${voiceId}:${state.sessionId}:${reply.key}` }, headers);
+    }
+    if (device === "headset" && !state.running && !reading) {
+      const audio = await call("/playback/status");
+      controller.observePlayback(Boolean(audio.playing));
+    }
+    finalSeen = submitted && !state.running;
+    return state;
+  };
+  const watch = async () => {
+    if (disposed || controller.getSnapshot().connection !== "open") return;
+    try { await poll(); }
+    catch (error) { await controller.disconnect(error.code || error.message || "voice_disconnected"); return; }
+    if (!continuous && finalSeen && controller.getSnapshot().playback === "idle") {
+      try { await stop(); } catch { await controller.disconnect("voice_disconnected"); }
+      return;
+    }
+    if (!disposed) timer = setTimeout(watch, 250);
+  };
+  const stop = async () => {
+    disposed = true; clearTimeout(timer);
+    await controller.disconnect();
+    if (!onTranscript) await call("/session/close", {});
+  };
+  return {
+    controller, headers,
+    playbackState(playing) {
+      reading = playing;
+      if (!playing && device === "headset" && !disposed) controller.observePlayback(true);
+      else controller.observePlayback(playing);
+    },
+    get sessionId() { return lastSessionId; },
+    async start({ sessionId = null, continuous: nextContinuous = false } = {}) {
+      continuous = nextContinuous; submitted = false; finalSeen = false; spokenKey = null;
+      disposed = false; version = -1;
+      clearTimeout(timer);
+      const initial = onTranscript ? {} : await call("/session", { sessionId, readAloud, ...(preset ? { preset } : {}) });
+      await controller.start({ sessionId, continuous, running: initial.running });
+      controller.setOutputMuted(!readAloud);
+      if (!onTranscript) void watch();
+    },
+    stop,
+    async resume() {
+      if (onTranscript) { await controller.resume(); return; }
+      const current = await call("/session");
+      if (!current.active) await call("/session", { sessionId: lastSessionId, readAloud });
+      else await call("/session/resume", {});
+      disposed = false;
+      await controller.resume();
+      void watch();
+    },
+    async setReadAloud(value) {
+      readAloud = value === true; mutedKey = lastReplyKey;
+      controller.setOutputMuted(!readAloud);
+      if (!readAloud) await controller.stopPlayback();
+      await call("/session/output", { readAloud });
+    },
+    records: async () => {
+      const res = await request("/api/lares/voice/records", { method: "GET", headers });
+      if (!res?.ok) throw new Error("voice_records_failed");
+      return res.body;
+    },
+    clearRecords: async () => {
+      await stop();
+      const res = await request("/api/lares/voice/records", { method: "DELETE", headers });
+      if (!res?.ok) throw new Error("voice_records_failed");
+    },
+    speak: (request) => call("/speak", request),
+  };
+}

package/voice/device-input.js

@@ -0,0 +1,79 @@
+import { createVoiceCapture } from "./browser-capture.js";
+import { createSpeechEndpoint, frameRms } from "./endpoint.js";
+
+export function createEnergyEndpoint(stream, end, onSpeech = () => {}, onLevel = () => {}, options = {}) {
+  const AudioCtx = globalThis.AudioContext || globalThis.webkitAudioContext;
+  if (!AudioCtx) throw new Error("voice_unsupported");
+  const context = new AudioCtx();
+  const source = context.createMediaStreamSource(stream);
+  const processor = context.createScriptProcessor(2048, 1, 1);
+  const gain = context.createGain();
+  gain.gain.value = 0;
+  const endpoint = createSpeechEndpoint(options);
+  let heard = false;
+  const silenceTimer = setTimeout(() => { if (!heard) end(false); }, 10_000);
+  processor.onaudioprocess = (event) => {
+    const samples = event.inputBuffer.getChannelData(0);
+    const rms = frameRms(samples);
+    onLevel(rms);
+    if (rms >= 0.004 && !heard) { heard = true; onSpeech(); }
+    if (endpoint.push(1, rms, samples.length * 1000 / context.sampleRate)) end(true);
+  };
+  source.connect(processor); processor.connect(gain); gain.connect(context.destination);
+  void context.resume();
+  return { stop() { clearTimeout(silenceTimer); processor.onaudioprocess = null; source.disconnect(); processor.disconnect(); gain.disconnect(); void context.close(); } };
+}
+
+function createInputMeter(stream, onLevel) {
+  const AudioCtx = globalThis.AudioContext || globalThis.webkitAudioContext;
+  if (!AudioCtx) return { stop() {} };
+  const context = new AudioCtx();
+  const source = context.createMediaStreamSource(stream);
+  const analyser = context.createAnalyser(); analyser.fftSize = 512;
+  source.connect(analyser);
+  const samples = new Float32Array(analyser.fftSize);
+  const timer = setInterval(() => { analyser.getFloatTimeDomainData(samples); onLevel(frameRms(samples)); }, 80);
+  void context.resume();
+  return { stop() { clearInterval(timer); source.disconnect(); analyser.disconnect(); void context.close(); } };
+}
+
+export function createDeviceInput({ transcribe, onPhase = () => {}, endpoint = createEnergyEndpoint, endpointSilenceMs = 500, media } = {}) {
+  let recorder = null;
+  let settle = null;
+  let timer = null;
+  const cancel = () => {
+    clearTimeout(timer);
+    recorder?.dispose(); recorder = null;
+    settle?.(""); settle = null;
+  };
+  return {
+    capabilities: { duplex: true, bargeIn: false, listenWhileWorking: true, audio: "encoded" },
+    capture({ signal, onTranscribing, onSpeech, onLevel = () => {}, continuous = false } = {}) {
+      cancel();
+      return new Promise((resolve, reject) => {
+        settle = resolve;
+        const done = (text) => { clearTimeout(timer); signal?.removeEventListener("abort", cancel); settle = null; resolve(text); };
+        recorder = createVoiceCapture({ media, transcribe, submit: done, onStream: (stream) => {
+          for (const track of stream.getTracks()) track.addEventListener?.("ended", () => { settle = null; cancel(); reject(new Error("voice_device_lost")); }, { once: true });
+          if (!continuous) return createInputMeter(stream, onLevel);
+          return endpoint(stream, (heard = true) => { if (heard) recorder?.stop(); else {
+            if (continuous) { cancel(); done(""); }
+            else { settle = null; cancel(); reject(new Error("voice_no_input")); }
+          } }, onSpeech, onLevel, { silenceMs: endpointSilenceMs });
+        }, onPhase(phase, extra) {
+          onPhase(phase, extra);
+          if (phase === "transcribing") onTranscribing?.();
+          if (phase === "error") {
+            if (continuous && ["voice_no_input", "voice_too_short"].includes(extra.error)) { done(""); return; }
+            clearTimeout(timer); signal?.removeEventListener("abort", cancel); settle = null; reject(new Error(extra.error)); }
+        } });
+        signal?.addEventListener("abort", cancel, { once: true });
+        if (signal?.aborted) { cancel(); return; }
+        timer = setTimeout(() => recorder?.stop(), 60_000);
+        void recorder.start();
+      });
+    },
+    stop: () => recorder?.stop(),
+    cancel,
+  };
+}