@xopcai/xopc 0.0.264 → 0.0.266

package/dist/src/voice/realtime/omniEngine.js

@@ -1,7 +1,8 @@
 import { createLogger } from "../../utils/logger/index.js";
 import { init_logger } from "../../utils/logger.js";
 import { AudioPlaybackWindow } from "./audio-playback-window.js";
-import { ConversationTurn } from "./conversationTurn.js";
+import { TurnCoordinator } from "./turnPolicy.js";
+import { PcmFrameBuffer } from "./pcmFrameBuffer.js";
 import crypto from "node:crypto";
 import WebSocket from "ws";
 //#region src/voice/realtime/omniEngine.ts
@@ -50,8 +51,16 @@ function createOmniVoiceEngine(options) {
 	let uploadTimer;
 	let turnSettled = false;
 	const speaking = /* @__PURE__ */ new Set();
-	const turn = new ConversationTurn(options.silenceDurationMs, () => {
+	const turn = new TurnCoordinator(options.silenceDurationMs, (_text, decision, turnId) => {
 		if (closed || failed || muted || inputBlocked) return;
+		options.send("turn.decision", {
+			turnId,
+			disposition: decision.disposition,
+			confidence: decision.confidence,
+			source: decision.source,
+			committed: true
+		});
+		options.send("turn.committed", { turnId });
 		turnSettled = true;
 		if (active) publish(active);
 	});
@@ -146,6 +155,23 @@ function createOmniVoiceEngine(options) {
 		options.send("response.text.done", { responseId: response.id });
 		await response.tail;
 		if (active !== response || closed) return;
+		const finalFrame = response.pcm.finish();
+		if (finalFrame) {
+			await response.playback.reserve(finalFrame.byteLength, response.abort.signal);
+			if (active !== response || closed) return;
+			if (!response.audio) {
+				response.audio = true;
+				options.send("response.audio.started", {
+					responseId: response.id,
+					format: {
+						encoding: "pcm_s16le",
+						channels: 1,
+						sampleRate: 24e3
+					}
+				});
+			}
+			options.sendAudio(response.id, finalFrame);
+		}
 		await response.playback.drain(response.abort.signal);
 		if (active !== response || closed) return;
 		save({
@@ -361,7 +387,8 @@ function createOmniVoiceEngine(options) {
 								tail: Promise.resolve(),
 								published: false,
 								settled,
-								release
+								release,
+								pcm: new PcmFrameBuffer()
 							};
 							if (turnSettled) publish(active);
 						} else if (active && event.response_id === active.id && event.type === "response.audio_transcript.delta") {
@@ -392,9 +419,8 @@ function createOmniVoiceEngine(options) {
 							response.queuedBytes += audio.length;
 							response.tail = response.tail.then(async () => {
 								await response.settled;
-								for (let offset = 0; offset < audio.length; offset += 24e3) {
+								for (const chunk of response.pcm.push(audio)) {
 									if (closed || active !== response) return;
-									const chunk = audio.subarray(offset, offset + 24e3);
 									await response.playback.reserve(chunk.length, response.abort.signal);
 									if (closed || active !== response) return;
 									if (!response.audio) {
@@ -471,8 +497,11 @@ function createOmniVoiceEngine(options) {
 			if (reason === "client_cancelled") discardInput();
 			return cancel(reason);
 		},
-		acknowledge(responseId, playedBytes) {
-			if (active?.id === responseId) active.playback.acknowledge(playedBytes);
+		async cancelTask() {
+			return false;
+		},
+		acknowledge(responseId, playedDurationMs) {
+			if (active?.id === responseId) active.playback.acknowledge(playedDurationMs * 48);
 		},
 		close() {
 			if (closed) return writes;

package/dist/src/voice/realtime/pcmFrameBuffer.d.ts

@@ -0,0 +1,6 @@
+/** Converts arbitrary PCM16 chunks into exact 20 ms wire frames. */
+export declare class PcmFrameBuffer {
+    private remainder;
+    push(bytes: Uint8Array): Uint8Array[];
+    finish(): Uint8Array | undefined;
+}

package/dist/src/voice/realtime/pcmFrameBuffer.js

@@ -0,0 +1,29 @@
+//#region src/voice/realtime/pcmFrameBuffer.ts
+const PCM_24KHZ_20MS_BYTES = 960;
+/** Converts arbitrary PCM16 chunks into exact 20 ms wire frames. */
+var PcmFrameBuffer = class {
+	remainder = new Uint8Array();
+	push(bytes) {
+		if (!bytes.byteLength || bytes.byteLength % 2) throw new Error("PCM16 audio must contain complete samples");
+		const pending = new Uint8Array(this.remainder.byteLength + bytes.byteLength);
+		pending.set(this.remainder);
+		pending.set(bytes, this.remainder.byteLength);
+		const frames = [];
+		let offset = 0;
+		while (offset + PCM_24KHZ_20MS_BYTES <= pending.byteLength) {
+			frames.push(pending.slice(offset, offset + PCM_24KHZ_20MS_BYTES));
+			offset += PCM_24KHZ_20MS_BYTES;
+		}
+		this.remainder = pending.slice(offset);
+		return frames;
+	}
+	finish() {
+		if (!this.remainder.byteLength) return void 0;
+		const frame = new Uint8Array(PCM_24KHZ_20MS_BYTES);
+		frame.set(this.remainder);
+		this.remainder = new Uint8Array();
+		return frame;
+	}
+};
+//#endregion
+export { PcmFrameBuffer };

package/dist/src/voice/realtime/runtime.js

@@ -10,7 +10,7 @@ import { resolveSTTProviderChain } from "../stt/factory.js";
 import { mergeSttConfigFromAppConfig } from "../stt/config.js";
 import { voiceConversationInstructions } from "./conversation-context.js";
 import { createPreauthConnectionBudget } from "../../gateway/security/preauth-connection-budget.js";
-import { encodeVoiceAudioFrame } from "../../../packages/realtime-protocol/src/voice-audio.js";
+import { decodeVoiceUplinkAudioFrame, encodeVoiceAudioFrame } from "../../../packages/realtime-protocol/src/voice-audio.js";
 import { VOICE_REALTIME_HEARTBEAT_INTERVAL_MS, VOICE_REALTIME_MAX_BINARY_FRAME_BYTES, VOICE_REALTIME_START_TIMEOUT_MS, VOICE_REALTIME_WS_PATH, parseVoiceClientJsonFrame, parseVoiceClientMessage } from "../../../packages/realtime-protocol/src/voice.js";
 import { createAgentVoiceEngine } from "./agentEngine.js";
 import { resolveOmniRoute } from "./omniRoute.js";
@@ -157,27 +157,28 @@ var VoiceRealtimeRuntime = class {
 		const config = structuredClone(this.options.getConfig());
 		this.pruneTickets(now);
 		if (!config.voice?.realtime?.enabled) throw new VoiceSessionCreationError("VOICE_DISABLED", "Realtime voice is disabled", 503);
+		const defaultMode = config.voice.realtime.defaultEngine === "omni" ? "natural" : "assistant";
 		request = request.purpose === "conversation" ? {
 			...request,
-			engine: request.engine ?? config.voice.realtime.defaultEngine
+			mode: request.mode ?? defaultMode
 		} : request;
 		let omni;
-		if (request.engine === "omni") try {
+		if (request.mode === "natural") try {
 			omni = await resolveOmniRoute(config);
 		} catch {
 			throw new VoiceSessionCreationError("PROVIDER_UNAVAILABLE", "Natural conversation is unavailable. Check its model, endpoint and credentials.", 503);
 		}
 		if (omni && (!this.options.recordOmniTranscript || !this.options.getConversationContext)) throw new VoiceSessionCreationError("PROVIDER_UNAVAILABLE", "Natural conversation storage is unavailable", 503);
 		const conversationSessionId = request.purpose === "conversation" && request.sessionKey ? await this.options.getSessionIdentity?.(request.sessionKey) : void 0;
-		if (omni && !conversationSessionId) throw new VoiceSessionCreationError("SESSION_NOT_FOUND", "Conversation session was not found", 404);
+		if (request.purpose === "conversation" && !conversationSessionId) throw new VoiceSessionCreationError("SESSION_NOT_FOUND", "Conversation session was not found", 404);
 		const stt = omni ? void 0 : resolveStreamingStt(config, request.language);
 		if (!omni && !stt) throw new VoiceSessionCreationError("PROVIDER_UNAVAILABLE", "No configured streaming speech-to-text provider is available", 503);
 		const inputMode = "server_vad";
 		if (stt && !stt.plugin.streamingAudio.turnDetection.includes(inputMode)) throw new VoiceSessionCreationError("PROVIDER_UNAVAILABLE", `Streaming speech-to-text provider does not support ${inputMode}`, 503);
-		const tts = request.engine === "agent" ? resolveStreamingTts(config) : void 0;
+		const tts = request.mode === "assistant" ? resolveStreamingTts(config) : void 0;
 		if (request.purpose === "conversation") {
 			if (!request.sessionKey || !await this.options.sessionExists(request.sessionKey)) throw new VoiceSessionCreationError("SESSION_NOT_FOUND", "Conversation session was not found", 404);
-			if (this.options.sessionBusy(request.sessionKey)) throw new VoiceSessionCreationError("SESSION_CONFLICT", "Conversation session already has an active response", 409);
+			if (request.mode === "natural" && this.options.sessionBusy(request.sessionKey)) throw new VoiceSessionCreationError("SESSION_CONFLICT", "Conversation session already has an active response", 409);
 			if (this.conversationReservations.has(request.sessionKey)) throw new VoiceSessionCreationError("SESSION_CONFLICT", "Conversation session already has a voice connection", 409);
 			if (!omni && !tts) throw new VoiceSessionCreationError("PROVIDER_UNAVAILABLE", "No configured PCM streaming text-to-speech provider is available", 503);
 		}
@@ -200,11 +201,14 @@ var VoiceRealtimeRuntime = class {
 		request = resolvedRequest;
 		const sessionId = crypto.randomUUID();
 		const ticket = crypto.randomBytes(32).toString("base64url");
+		const connectionEpoch = crypto.randomInt(1, 4294967296);
 		const maxSessionMs = request.purpose === "conversation" ? Math.min(config.voice.realtime.maxConversationMs, omni?.route.managed ? 30 * 6e4 : Number.MAX_SAFE_INTEGER) : config.voice.realtime.maxDictationMs;
 		const claim = {
 			conversationSessionId,
 			sessionId,
+			connectionEpoch,
 			principalId,
+			...request.purpose === "conversation" && request.mode ? { mode: request.mode } : {},
 			request,
 			inputMode,
 			idleTimeoutMs: config.voice.realtime.idleTimeoutMs,
@@ -224,8 +228,10 @@ var VoiceRealtimeRuntime = class {
 			ticket,
 			ticketExpiresAt: new Date(claim.expiresAt).toISOString(),
 			websocketPath: VOICE_REALTIME_WS_PATH,
-			protocolVersion: 2,
+			protocolVersion: 3,
+			connectionEpoch,
 			purpose: request.purpose,
+			...request.purpose === "conversation" && request.mode ? { mode: request.mode } : {},
 			inputMode,
 			bargeIn: config.voice.realtime.bargeIn,
 			inputFormat: {
@@ -233,6 +239,11 @@ var VoiceRealtimeRuntime = class {
 				sampleRate: 16e3,
 				channels: 1
 			},
+			media: {
+				transport: "websocket-pcm",
+				codec: "pcm_s16le",
+				frameDurationMs: 20
+			},
 			limits: {
 				maxBinaryFrameBytes: VOICE_REALTIME_MAX_BINARY_FRAME_BYTES,
 				maxSessionMs,
@@ -252,7 +263,7 @@ var VoiceRealtimeRuntime = class {
 		};
 	}
 	handleUpgrade(req, socket, head) {
-		if (new URL(req.url ?? "/", "http://gateway.local").pathname !== "/api/voice/realtime/v2/ws") return false;
+		if (new URL(req.url ?? "/", "http://gateway.local").pathname !== "/api/voice/realtime/v3/ws") return false;
 		if (this.closed || this.wss.clients.size >= MAX_CONNECTIONS) {
 			socket.destroy();
 			return true;
@@ -319,6 +330,8 @@ var VoiceRealtimeRuntime = class {
 		let ready = false;
 		let seq = 0;
 		let audioSeq = 0;
+		let outputMediaTimestampMs = 0;
+		const inputSequences = /* @__PURE__ */ new Map();
 		let closed = false;
 		let lastActivityAt = Date.now();
 		const abortController = new AbortController();
@@ -326,10 +339,11 @@ var VoiceRealtimeRuntime = class {
 		let context;
 		let unsubscribeMemory;
 		let unsubscribeSession;
+		let inputMutationTail = Promise.resolve();
 		const send = (type, payload) => {
 			if (!claim || socket.readyState !== WebSocketState.OPEN) return;
 			const event = {
-				protocolVersion: 2,
+				protocolVersion: 3,
 				eventId: crypto.randomUUID(),
 				seq: ++seq,
 				type,
@@ -434,11 +448,20 @@ var VoiceRealtimeRuntime = class {
 				setupStage = "engine";
 				const sendAudio = (responseId, bytes) => {
 					if (socket.bufferedAmount > 1024 * 1024) throw new Error("Voice client audio backpressure limit exceeded");
-					if (!closed && socket.readyState === WebSocketState.OPEN) socket.send(encodeVoiceAudioFrame({
-						responseId,
-						seq: ++audioSeq,
-						audio: bytes
-					}), { binary: true });
+					if (closed || socket.readyState !== WebSocketState.OPEN) return;
+					for (let offset = 0; offset < bytes.byteLength; offset += 960) {
+						const audio = bytes.subarray(offset, offset + 960);
+						if (audio.byteLength !== 960) throw new Error("Realtime output must align to 20 ms PCM frames");
+						socket.send(encodeVoiceAudioFrame({
+							connectionEpoch: consumed.connectionEpoch,
+							responseId,
+							seq: ++audioSeq,
+							mediaTimestampMs: outputMediaTimestampMs,
+							durationMs: 20,
+							audio
+						}), { binary: true });
+						outputMediaTimestampMs += 20;
+					}
 				};
 				engine = consumed.omni ? createOmniVoiceEngine({
 					callId: consumed.sessionId,
@@ -469,12 +492,19 @@ var VoiceRealtimeRuntime = class {
 				}, "Realtime voice session ready");
 				send("session.ready", {
 					purpose: consumed.request.purpose,
+					...consumed.mode ? { mode: consumed.mode } : {},
+					connectionEpoch: consumed.connectionEpoch,
 					inputMode: consumed.inputMode,
 					inputFormat: {
 						encoding: "pcm_s16le",
 						sampleRate: 16e3,
 						channels: 1
 					},
+					media: {
+						transport: "websocket-pcm",
+						codec: "pcm_s16le",
+						frameDurationMs: 20
+					},
 					route: consumed.omni ? {
 						engine: "omni",
 						omni: consumed.omni.route
@@ -512,7 +542,19 @@ var VoiceRealtimeRuntime = class {
 					return;
 				}
 				const bytes = data instanceof ArrayBuffer ? new Uint8Array(data) : Array.isArray(data) ? Buffer.concat(data) : new Uint8Array(data.buffer, data.byteOffset, data.byteLength);
-				if (bytes.byteLength === 0 || bytes.byteLength % 2 !== 0 || bytes.byteLength > 65536) {
+				let frame;
+				try {
+					frame = decodeVoiceUplinkAudioFrame(bytes);
+				} catch {
+					send("session.error", {
+						code: "INVALID_AUDIO",
+						message: "Invalid PCM audio frame",
+						recoverable: false
+					});
+					shutdown("invalid_audio", true);
+					return;
+				}
+				if (frame.connectionEpoch !== claim.connectionEpoch || frame.audio.byteLength !== 640) {
 					send("session.error", {
 						code: "INVALID_AUDIO",
 						message: "Invalid PCM audio frame",
@@ -521,12 +563,24 @@ var VoiceRealtimeRuntime = class {
 					shutdown("invalid_audio", true);
 					return;
 				}
+				const previous = inputSequences.get(frame.utteranceId) ?? 0;
+				if (frame.audioSeq <= previous) return;
+				if (frame.audioSeq !== previous + 1 || inputSequences.size >= 256) {
+					send("session.error", {
+						code: "INVALID_AUDIO",
+						message: "Invalid audio sequence",
+						recoverable: false
+					});
+					shutdown("invalid_audio", true);
+					return;
+				}
+				inputSequences.set(frame.utteranceId, frame.audioSeq);
 				if (!ready || !engine) {
 					socket.close(4401, "Voice session is not ready");
 					return;
 				}
 				try {
-					engine.appendAudio(bytes);
+					engine.appendAudio(frame.audio);
 				} catch (error) {
 					log.warn({
 						err: error,
@@ -574,23 +628,45 @@ var VoiceRealtimeRuntime = class {
 						metric,
 						durationMs,
 						source: "client",
-						engine: claim.request.engine
+						mode: claim.mode
 					}, "Voice client timing sample");
 				}
-			} else if (message.type === "response.cancel") {
+			} else if (message.type === "response.stop_playback") {
 				if (!engine?.cancel(message.payload.responseId, "client_cancelled")) send("session.error", {
 					code: "NO_ACTIVE_RESPONSE",
 					message: "No matching response is active",
 					recoverable: true
 				});
-			} else if (message.type === "response.audio.played") try {
-				engine?.acknowledge(message.payload.responseId, message.payload.playedBytes);
+			} else if (message.type === "task.cancel") engine?.cancelTask(message.payload.taskId).then((cancelled) => {
+				if (!cancelled) send("session.error", {
+					code: "NO_ACTIVE_TASK",
+					message: "No matching task is active",
+					recoverable: true
+				});
+			}).catch((error) => {
+				log.warn({
+					err: error,
+					sessionId: claim?.sessionId,
+					taskId: message.payload.taskId
+				}, "Voice task cancellation failed");
+				send("session.error", {
+					code: "TASK_CANCEL_FAILED",
+					message: "Could not cancel the task",
+					recoverable: true
+				});
+			});
+			else if (message.type === "response.audio.played") try {
+				engine?.acknowledge(message.payload.responseId, message.payload.playedDurationMs);
 			} catch {
 				socket.close(4400, "Invalid playback acknowledgement");
 			}
 			else if (message.type === "input.mute") {
 				if (!ready || !engine || claim.request.purpose !== "conversation") return;
-				Promise.resolve().then(() => engine.setInputMuted(message.payload.muted)).catch((error) => {
+				const muted = message.payload.muted;
+				inputMutationTail = inputMutationTail.then(async () => {
+					if (closed || !ready || !engine) return;
+					await engine.setInputMuted(muted);
+				}).catch((error) => {
 					log.warn({
 						err: error,
 						sessionId: claim?.sessionId

package/dist/src/voice/realtime/runtime.types.d.ts

@@ -1,4 +1,4 @@
-import type { CreateVoiceSessionRequest, VoiceProviderRoute } from '@xopcai/realtime-protocol/voice';
+import type { CreateVoiceSessionRequest, VoiceMode, VoiceProviderRoute } from '@xopcai/realtime-protocol/voice';
 import type { Config } from '../../config/schema.js';
 import type { MediaUnderstandingProvider } from '../../media-understanding/types.js';
 import type { ResolvedSpeechProvider } from '../tts/factory.js';
@@ -6,6 +6,7 @@ import type { TTSConfig } from '../tts/types.js';
 import type { VoiceConversationContext } from './conversation-context.js';
 import type { OmniTranscript } from './omniEngine.js';
 import type { OmniRoute } from './omniRoute.js';
+import type { VoiceAgentBroker } from './agentBroker.js';
 export interface ResolvedStreamingStt {
     plugin: MediaUnderstandingProvider & Required<Pick<MediaUnderstandingProvider, 'openAudioStream' | 'streamingAudio'>>;
     model: string;
@@ -18,7 +19,9 @@ export interface ResolvedStreamingStt {
 }
 export interface VoiceTicketClaim {
     sessionId: string;
+    connectionEpoch: number;
     principalId: string;
+    mode?: VoiceMode;
     request: CreateVoiceSessionRequest;
     inputMode: 'server_vad';
     idleTimeoutMs: number;
@@ -37,24 +40,6 @@ export interface ResolvedStreamingTts {
     config: TTSConfig;
     route: VoiceProviderRoute;
 }
-interface VoiceAgentEvent {
-    type: string;
-    payload?: {
-        delta?: unknown;
-        message?: unknown;
-        status?: unknown;
-        toolCallId?: unknown;
-        toolName?: unknown;
-        requestId?: unknown;
-        kind?: unknown;
-        question?: unknown;
-        choices?: unknown;
-        suggestedAnswer?: unknown;
-        version?: unknown;
-        createdAt?: unknown;
-        expiresAt?: unknown;
-    };
-}
 export interface VoiceRealtimeRuntimeOptions {
     recordOmniTranscript?: (sessionKey: string, callId: string, entry: OmniTranscript, expectedSessionId: string) => Promise<void>;
     getConversationContext?: (sessionKey: string, expectedSessionId: string) => Promise<VoiceConversationContext>;
@@ -62,7 +47,7 @@ export interface VoiceRealtimeRuntimeOptions {
     getConfig: () => Config;
     sessionExists: (sessionKey: string) => Promise<boolean>;
     sessionBusy: (sessionKey: string) => boolean;
-    runAgent: (text: string, sessionKey: string, signal: AbortSignal) => AsyncIterable<VoiceAgentEvent>;
+    agentBroker: VoiceAgentBroker;
     recordInterruption: (entry: {
         sessionKey: string;
         responseId: string;
@@ -71,4 +56,3 @@ export interface VoiceRealtimeRuntimeOptions {
         interruptedDuring: 'thinking' | 'speaking';
     }) => Promise<void>;
 }
-export {};

package/dist/src/voice/realtime/turnPolicy.d.ts

@@ -0,0 +1,36 @@
+export type TurnDisposition = 'complete' | 'incomplete' | 'backchannel' | 'wait';
+export interface TurnSnapshot {
+    text: string;
+    silenceDurationMs: number;
+}
+export interface TurnDecision {
+    disposition: TurnDisposition;
+    confidence: number;
+    holdMs: number;
+    source: 'provider' | 'semantic' | 'heuristic';
+}
+export interface TurnPolicy {
+    decide(snapshot: TurnSnapshot): TurnDecision | Promise<TurnDecision>;
+}
+export declare function hasContinuationHint(text: string): boolean;
+export declare const heuristicTurnPolicy: TurnPolicy;
+/** Accumulates provider utterances and commits only after the selected policy settles. */
+export declare class TurnCoordinator {
+    private readonly silenceDurationMs;
+    private readonly onCommit;
+    private readonly policy;
+    private readonly parts;
+    private timer;
+    private stoppedAt;
+    private decisionGeneration;
+    constructor(silenceDurationMs: number, onCommit: (text: string, decision: TurnDecision, turnId: string) => void, policy?: TurnPolicy);
+    start(id: string): void;
+    stop(id: string): void;
+    final(id: string, text: string): void;
+    reset(): void;
+    restore(id: string, text: string): void;
+    private text;
+    private invalidatePendingDecision;
+    private evaluate;
+    private schedule;
+}

package/dist/src/voice/realtime/turnPolicy.js

@@ -0,0 +1,134 @@
+//#region src/voice/realtime/turnPolicy.ts
+const MIN_TURN_SILENCE_MS = 1200;
+const FINAL_SETTLE_MS = 350;
+const INCOMPLETE_HOLD_MS = 1800;
+const DECISION_TIMEOUT_MS = 750;
+const MAX_TRANSCRIPT_CHARACTERS = 32e3;
+const MAX_UTTERANCES = 256;
+function isPromise(value) {
+	return typeof value.then === "function";
+}
+function hasContinuationHint(text) {
+	const tail = text.trim().replace(/[\s，。！？、；：,.!?;:]+$/u, "");
+	return /(?:…|\.\.\.)[\s，。！？,.!?]*$/u.test(text) || /(?:因为|但是|然后|而且|如果|所以|比如|或者|还有|我想|我要|我觉得|帮我|帮我查一下|帮我查查|请帮我|就是说|那个|这个|呃|嗯)$/u.test(tail) || /\b(?:because|but|and|or|if|so|then|um|uh|i want to|i would like to|can you|could you|let me)\s*$/iu.test(tail);
+}
+const heuristicTurnPolicy = { decide({ text }) {
+	const incomplete = hasContinuationHint(text);
+	return {
+		disposition: incomplete ? "incomplete" : "complete",
+		confidence: incomplete ? .6 : .5,
+		holdMs: incomplete ? INCOMPLETE_HOLD_MS : 0,
+		source: "heuristic"
+	};
+} };
+/** Accumulates provider utterances and commits only after the selected policy settles. */
+var TurnCoordinator = class {
+	parts = /* @__PURE__ */ new Map();
+	timer;
+	stoppedAt = 0;
+	decisionGeneration = 0;
+	constructor(silenceDurationMs, onCommit, policy = heuristicTurnPolicy) {
+		this.silenceDurationMs = silenceDurationMs;
+		this.onCommit = onCommit;
+		this.policy = policy;
+	}
+	start(id) {
+		if (this.parts.has(id)) return;
+		this.invalidatePendingDecision();
+		this.parts.set(id, { stopped: false });
+	}
+	stop(id) {
+		const part = this.parts.get(id);
+		if (part?.stopped) return;
+		this.parts.set(id, {
+			...part,
+			stopped: true
+		});
+		this.stoppedAt = Date.now();
+		this.evaluate();
+	}
+	final(id, text) {
+		const part = this.parts.get(id);
+		if (part?.text !== void 0) return;
+		if (!part?.stopped) this.stoppedAt = Date.now();
+		this.parts.set(id, {
+			text: text.trim(),
+			stopped: true
+		});
+		if (this.parts.size > MAX_UTTERANCES || this.text().length > MAX_TRANSCRIPT_CHARACTERS) {
+			this.reset();
+			throw new Error("Voice turn input limit reached");
+		}
+		this.evaluate();
+	}
+	reset() {
+		this.invalidatePendingDecision();
+		this.parts.clear();
+	}
+	restore(id, text) {
+		this.invalidatePendingDecision();
+		this.parts.set(id, {
+			text,
+			stopped: true
+		});
+	}
+	text() {
+		return [...this.parts.values()].map((part) => part.text ?? "").filter(Boolean).join(" ");
+	}
+	invalidatePendingDecision() {
+		this.decisionGeneration += 1;
+		clearTimeout(this.timer);
+		this.timer = void 0;
+	}
+	evaluate() {
+		this.invalidatePendingDecision();
+		if ([...this.parts.values()].some((part) => !part.stopped || part.text === void 0)) return;
+		const text = this.text();
+		if (!text) {
+			this.reset();
+			return;
+		}
+		const generation = this.decisionGeneration;
+		const snapshot = {
+			text,
+			silenceDurationMs: Math.max(0, Date.now() - this.stoppedAt)
+		};
+		let result;
+		try {
+			result = this.policy.decide(snapshot);
+		} catch {
+			this.schedule(text, heuristicTurnPolicy.decide(snapshot), generation);
+			return;
+		}
+		if (isPromise(result)) {
+			let settled = false;
+			const finish = (decision) => {
+				if (settled || generation !== this.decisionGeneration) return;
+				settled = true;
+				clearTimeout(timeout);
+				this.schedule(text, decision, generation);
+			};
+			const fallback = () => finish(heuristicTurnPolicy.decide(snapshot));
+			const timeout = setTimeout(fallback, DECISION_TIMEOUT_MS);
+			result.then(finish).catch(fallback);
+			return;
+		}
+		this.schedule(text, result, generation);
+	}
+	schedule(text, decision, generation) {
+		if (generation !== this.decisionGeneration) return;
+		const holdMs = Math.max(FINAL_SETTLE_MS, MIN_TURN_SILENCE_MS - this.silenceDurationMs, Number.isFinite(decision.holdMs) ? Math.max(0, decision.holdMs) : 0);
+		this.timer = setTimeout(() => {
+			if (generation !== this.decisionGeneration) return;
+			const turnId = [...this.parts.keys()][0];
+			if (decision.disposition === "wait") {
+				this.evaluate();
+				return;
+			}
+			this.reset();
+			if (decision.disposition !== "backchannel") this.onCommit(text, decision, turnId);
+		}, Math.max(FINAL_SETTLE_MS, this.stoppedAt + holdMs - Date.now()));
+	}
+};
+//#endregion
+export { TurnCoordinator, hasContinuationHint, heuristicTurnPolicy };

package/dist/src/work-discovery/service.js

@@ -6,12 +6,12 @@ import { getAgentDefaultModelRef, init_schema } from "../config/schema.js";
 import { buildSessionKey, init_session_key } from "../routing/session-key.js";
 import { getDefaultAgentId, init_resolve_route } from "../routing/resolve-route.js";
 import { init_providers, resolveModel } from "../providers/index.js";
+import { isLocalModelBaseUrl } from "../providers/model-call.js";
 import { writeKnowledgeItem } from "../knowledge-memory/repository.js";
 import "../knowledge-memory/index.js";
 import { createPriorityWindow, createUserGoal } from "../user-model/goals.js";
 import { getAssertionSlot, getUserAssertion, linkAssertionEvidence, reconcileAssertion, setAssertionStatus } from "../user-model/repository.js";
 import "../user-model/index.js";
-import { isLocalModelBaseUrl } from "../providers/model-call.js";
 import { allowsRemoteSourceProcessing } from "../user-context/sources/processing-policy.js";
 import { analyzeUnderstandingSources, analyzeWorkContext, workDiscoveryResultMarkdown } from "./analyzer.js";
 import { createUnderstandingSourceRun, getUnderstandingSourceRun, updateUnderstandingSourceGrantCheckpoint, updateUnderstandingSourceGrantPolicies, updateUnderstandingSourceRun, upsertUnderstandingSourceGrant } from "../user-context/sources/repository.js";

package/dist/src/workflows/service/workflow-run-service.js

@@ -1,7 +1,7 @@
 import { TaskRunRepository } from "../../tasks/task-run-repository.js";
 import { getDefaultAgentId, init_resolve_route } from "../../routing/resolve-route.js";
-import { extractProfileAgentId, resolveEffectiveAgentProfileForSession } from "../../config/agent-profile.js";
 import { init_providers, resolveModel } from "../../providers/index.js";
+import { extractProfileAgentId, resolveEffectiveAgentProfileForSession } from "../../config/agent-profile.js";
 import { TaskRepository } from "../../tasks/task-repository.js";
 import { TaskConversationRepository } from "../../tasks/task-conversation-repository.js";
 import { getProjectWorkspacePathForSession } from "../../projects/workspace.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xopcai/xopc",
-  "version": "0.0.264",
+  "version": "0.0.266",
   "description": "Local-first personal AI assistant with reviewable user understanding, durable tasks, workflows, automations, and local or cloud models.",
   "type": "module",
   "main": "dist/src/index.js",
@@ -163,9 +163,9 @@
     "vitepress": "^1.6.4",
     "vitest": "4.1.5",
     "vue": "^3.5.35",
+    "@xopcai/browser-control-contract": "0.1.0",
     "@xopcai/endpoint-tools-protocol": "0.0.0",
     "@xopcai/realtime-client": "0.0.0",
-    "@xopcai/browser-control-contract": "0.1.0",
     "@xopcai/realtime-protocol": "0.0.0",
     "@xopcai/gateway-contract": "0.0.0"
   },