@xopcai/xopc 0.0.373 → 0.0.375

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

@@ -1,5 +1,6 @@
 import { createLogger } from "../../utils/logger/index.js";
 import { init_logger } from "../../utils/logger.js";
+import { PlatformVoiceError } from "../platform-streams.js";
 import { prepareSpeechStreamSession, speakStream } from "../tts/speak-core.js";
 import { AudioPlaybackWindow } from "./audio-playback-window.js";
 import { TurnCoordinator } from "./turnPolicy.js";
@@ -43,6 +44,7 @@ function createAgentVoiceEngine(options) {
 	let turnReceivedAtMs;
 	let taskUpdateQueued = false;
 	let lastUserSpeechAt = 0;
+	let openingInputSeen = false;
 	const turn = new TurnCoordinator(claim.silenceDurationMs, (text, decision, turnId) => {
 		if (closed || muted) return;
 		const receivedAtMs = turnReceivedAtMs ?? Date.now();
@@ -103,13 +105,15 @@ function createAgentVoiceEngine(options) {
 		};
 		activeResponse = void 0;
 		clearTimeout(response.firstPhraseTimer);
+		clearTimeout(response.openingTimer);
+		if (response.opening && response.opening.result !== "expired") response.opening.result = "interrupted";
 		response.abortController.abort(reason);
 		send("response.cancelled", {
 			responseId: response.id,
 			reason
 		});
 		const conversationId = claim.request.conversationId;
-		if (conversationId && reason !== "session_closed") interruptionWrites = interruptionWrites.then(() => options.runtime.recordInterruption({
+		if (conversationId && !response.opening && reason !== "session_closed") interruptionWrites = interruptionWrites.then(() => options.runtime.recordInterruption({
 			conversationId,
 			responseId: response.id,
 			reason,
@@ -221,6 +225,12 @@ function createAgentVoiceEngine(options) {
 				for (const frame of response.pcm.push(item.value)) {
 					await response.playback.reserve(frame.byteLength, response.abortController.signal);
 					if (activeResponse !== response || closed) return;
+					if (response.opening && options.runtime.sessionBusy(claim.request.conversationId)) {
+						cancelActiveResponse("barge_in");
+						return;
+					}
+					response.firstFrameSent = true;
+					clearTimeout(response.openingTimer);
 					options.sendAudio(response.id, frame);
 				}
 			}
@@ -304,17 +314,19 @@ function createAgentVoiceEngine(options) {
 		if (response.speechWorker) prefetchNextSpeech(response);
 		else startSpeechWorker(response);
 	}
-	async function runAssistantTurn(text, turnId, updateClientMessageId, receivedAtMs = Date.now(), committedAtMs = receivedAtMs) {
+	async function runAssistantTurn(text, turnId, updateClientMessageId, receivedAtMs = Date.now(), committedAtMs = receivedAtMs, opening) {
 		if (!claim.tts || !claim.request.conversationId || !text.trim() || closed) return false;
 		cancelActiveResponse("barge_in");
 		const response = {
-			id: `resp_${crypto.randomUUID()}`,
+			id: opening?.responseId ?? `resp_${crypto.randomUUID()}`,
+			...opening ? { opening } : {},
 			playback: new AudioPlaybackWindow(),
 			abortController: new AbortController(),
 			segmenter: new SpeakableSegmenter(AGENT_TTS_MAX_SEGMENT_CHARACTERS, AGENT_TTS_MIN_SEGMENT_CHARACTERS, 0),
 			text: "",
 			audibleText: "",
 			audioStarted: false,
+			firstFrameSent: false,
 			speechQueue: [],
 			queuedSpeechCharacters: 0,
 			startedAt: Date.now(),
@@ -328,13 +340,19 @@ function createAgentVoiceEngine(options) {
 		const taskUpdateExposed = () => Boolean(updateClientMessageId && response.text.trim());
 		activeResponse = response;
 		send("response.created", { responseId: response.id });
+		if (opening) response.openingTimer = setTimeout(() => {
+			if (activeResponse === response) {
+				opening.result = "expired";
+				cancelActiveResponse("client_cancelled");
+			}
+		}, Math.max(0, opening.deadlineAt - Date.now()));
 		try {
-			const opening = prepareSpeechStreamSession(claim.tts.config, {
+			const speechOpening = prepareSpeechStreamSession(claim.tts.config, {
 				appConfig: claim.config,
 				signal: response.abortController.signal,
 				allowFallback: false
 			});
-			if (opening) response.preparedSpeech = opening.then((session) => {
+			if (speechOpening) response.preparedSpeech = speechOpening.then((session) => {
 				log.info({
 					sessionId: claim.sessionId,
 					responseId: response.id,
@@ -346,86 +364,96 @@ function createAgentVoiceEngine(options) {
 			}, (error) => ({ error }));
 			await interruptionWrites;
 			if (response.abortController.signal.aborted || closed) return taskUpdateExposed();
-			if (!claim.conversationSessionId) throw new Error("Conversation identity is unavailable");
-			const task = await options.runtime.agentBroker.delegate({
-				text,
-				turnId,
-				conversationId: claim.request.conversationId,
-				expectedTranscriptId: claim.conversationSessionId,
-				signal: response.abortController.signal,
-				clientMessageId: updateClientMessageId ?? `voice:${claim.conversationSessionId}:${claim.sessionId}:${inputGeneration}:${turnId}`,
-				...updateClientMessageId ? { origin: {
-					type: "system",
-					source: "task_update"
-				} } : {}
-			});
-			response.taskId = task.taskId;
-			send("task.created", {
-				responseId: response.id,
-				taskId: task.taskId
-			});
-			for await (const event of task.events) {
-				if (activeResponse !== response || response.abortController.signal.aborted) return taskUpdateExposed();
-				if (event.type === "assistant_delta" || event.type === "tool_end" && event.payload?.toolName !== "clarify") response.awaitingClarification = false;
-				if (event.type === "assistant_delta" && typeof event.payload?.delta === "string") {
-					if (response.text.length + event.payload.delta.length > 32e3) throw new Error("Voice response text limit reached");
-					if (!response.firstTextSeen && event.payload.delta.trim()) {
-						response.firstTextSeen = true;
-						response.firstTextAtMs = Date.now();
-						log.info({
-							sessionId: claim.sessionId,
+			if (opening) {
+				response.text = text;
+				response.firstTextAtMs = Date.now();
+				send("response.text.delta", {
+					responseId: response.id,
+					delta: text
+				});
+				queuePhrases(response, [text]);
+			} else {
+				if (!claim.conversationSessionId) throw new Error("Conversation identity is unavailable");
+				const task = await options.runtime.agentBroker.delegate({
+					text,
+					turnId,
+					conversationId: claim.request.conversationId,
+					expectedTranscriptId: claim.conversationSessionId,
+					signal: response.abortController.signal,
+					clientMessageId: updateClientMessageId ?? `voice:${claim.conversationSessionId}:${claim.sessionId}:${inputGeneration}:${turnId}`,
+					...updateClientMessageId ? { origin: {
+						type: "system",
+						source: "task_update"
+					} } : {}
+				});
+				response.taskId = task.taskId;
+				send("task.created", {
+					responseId: response.id,
+					taskId: task.taskId
+				});
+				for await (const event of task.events) {
+					if (activeResponse !== response || response.abortController.signal.aborted) return taskUpdateExposed();
+					if (event.type === "assistant_delta" || event.type === "tool_end" && event.payload?.toolName !== "clarify") response.awaitingClarification = false;
+					if (event.type === "assistant_delta" && typeof event.payload?.delta === "string") {
+						if (response.text.length + event.payload.delta.length > 32e3) throw new Error("Voice response text limit reached");
+						if (!response.firstTextSeen && event.payload.delta.trim()) {
+							response.firstTextSeen = true;
+							response.firstTextAtMs = Date.now();
+							log.info({
+								sessionId: claim.sessionId,
+								responseId: response.id,
+								conversationId: claim.request.conversationId,
+								phase: "first_response_text",
+								latencyMs: Date.now() - response.startedAt,
+								inputToTextMs: Date.now() - response.inputReceivedAtMs,
+								turnDecisionMs: Math.max(0, response.turnCommittedAtMs - response.inputReceivedAtMs),
+								queueMs: Math.max(0, response.startedAt - response.turnCommittedAtMs)
+							}, "Realtime voice first response text ready");
+						}
+						response.text += event.payload.delta;
+						send("response.text.delta", {
 							responseId: response.id,
-							conversationId: claim.request.conversationId,
-							phase: "first_response_text",
-							latencyMs: Date.now() - response.startedAt,
-							inputToTextMs: Date.now() - response.inputReceivedAtMs,
-							turnDecisionMs: Math.max(0, response.turnCommittedAtMs - response.inputReceivedAtMs),
-							queueMs: Math.max(0, response.startedAt - response.turnCommittedAtMs)
-						}, "Realtime voice first response text ready");
+							delta: event.payload.delta
+						});
+						queuePhrases(response, response.segmenter.push(event.payload.delta));
+						if (response.firstPhraseAtMs === void 0 && response.firstPhraseTimer === void 0) response.firstPhraseTimer = setTimeout(() => {
+							response.firstPhraseTimer = void 0;
+							if (activeResponse === response && !response.abortController.signal.aborted) queuePhrases(response, response.segmenter.flushFirstPhrase());
+						}, FIRST_PHRASE_WAIT_MS);
 					}
-					response.text += event.payload.delta;
-					send("response.text.delta", {
-						responseId: response.id,
-						delta: event.payload.delta
+					if (event.type === "tool_start") queuePhrases(response, response.segmenter.flush());
+					if ((event.type === "tool_start" || event.type === "tool_end") && typeof event.payload?.toolCallId === "string" && typeof event.payload?.toolName === "string") send("task.activity", {
+						taskId: task.taskId,
+						toolCallId: event.payload.toolCallId.slice(0, 160),
+						toolName: event.payload.toolName.slice(0, 256),
+						status: event.type === "tool_start" ? "running" : event.payload.status === "error" ? "failed" : "completed"
 					});
-					queuePhrases(response, response.segmenter.push(event.payload.delta));
-					if (response.firstPhraseAtMs === void 0 && response.firstPhraseTimer === void 0) response.firstPhraseTimer = setTimeout(() => {
-						response.firstPhraseTimer = void 0;
-						if (activeResponse === response && !response.abortController.signal.aborted) queuePhrases(response, response.segmenter.flushFirstPhrase());
-					}, FIRST_PHRASE_WAIT_MS);
-				}
-				if (event.type === "tool_start") queuePhrases(response, response.segmenter.flush());
-				if ((event.type === "tool_start" || event.type === "tool_end") && typeof event.payload?.toolCallId === "string" && typeof event.payload?.toolName === "string") send("task.activity", {
-					taskId: task.taskId,
-					toolCallId: event.payload.toolCallId.slice(0, 160),
-					toolName: event.payload.toolName.slice(0, 256),
-					status: event.type === "tool_start" ? "running" : event.payload.status === "error" ? "failed" : "completed"
-				});
-				if (event.type === "run_end" || event.type === "stream_end") {
-					const status = event.payload?.status;
-					if (!response.taskDone) {
-						response.taskDone = true;
-						send("task.done", {
-							taskId: task.taskId,
-							status: status === "cancelled" ? "cancelled" : status === "suspended" ? "suspended" : status === "error" ? "failed" : "completed"
+					if (event.type === "run_end" || event.type === "stream_end") {
+						const status = event.payload?.status;
+						if (!response.taskDone) {
+							response.taskDone = true;
+							send("task.done", {
+								taskId: task.taskId,
+								status: status === "cancelled" ? "cancelled" : status === "suspended" ? "suspended" : status === "error" ? "failed" : "completed"
+							});
+						}
+					}
+					if (event.type === "clarify_request" && typeof event.payload?.requestId === "string" && typeof event.payload?.question === "string") {
+						response.awaitingClarification = true;
+						send("response.clarification", {
+							responseId: response.id,
+							requestId: event.payload.requestId.slice(0, 160),
+							kind: event.payload.kind === "approval" ? "approval" : "input",
+							question: event.payload.question.slice(0, 8e3),
+							...Array.isArray(event.payload.choices) ? { choices: event.payload.choices.filter((choice) => typeof choice === "string").slice(0, 20).map((choice) => choice.slice(0, 1e3)) } : {},
+							...typeof event.payload.suggestedAnswer === "string" ? { suggestedAnswer: event.payload.suggestedAnswer.slice(0, 1e3) } : {},
+							version: typeof event.payload.version === "number" ? event.payload.version : 1,
+							createdAt: typeof event.payload.createdAt === "number" ? event.payload.createdAt : Date.now(),
+							...typeof event.payload.expiresAt === "number" ? { expiresAt: event.payload.expiresAt } : {}
 						});
 					}
+					if (event.type === "error") throw new Error(typeof event.payload?.message === "string" ? event.payload.message : "Agent response failed");
 				}
-				if (event.type === "clarify_request" && typeof event.payload?.requestId === "string" && typeof event.payload?.question === "string") {
-					response.awaitingClarification = true;
-					send("response.clarification", {
-						responseId: response.id,
-						requestId: event.payload.requestId.slice(0, 160),
-						kind: event.payload.kind === "approval" ? "approval" : "input",
-						question: event.payload.question.slice(0, 8e3),
-						...Array.isArray(event.payload.choices) ? { choices: event.payload.choices.filter((choice) => typeof choice === "string").slice(0, 20).map((choice) => choice.slice(0, 1e3)) } : {},
-						...typeof event.payload.suggestedAnswer === "string" ? { suggestedAnswer: event.payload.suggestedAnswer.slice(0, 1e3) } : {},
-						version: typeof event.payload.version === "number" ? event.payload.version : 1,
-						createdAt: typeof event.payload.createdAt === "number" ? event.payload.createdAt : Date.now(),
-						...typeof event.payload.expiresAt === "number" ? { expiresAt: event.payload.expiresAt } : {}
-					});
-				}
-				if (event.type === "error") throw new Error(typeof event.payload?.message === "string" ? event.payload.message : "Agent response failed");
 			}
 			if (activeResponse !== response || response.abortController.signal.aborted || closed) return taskUpdateExposed();
 			queuePhrases(response, response.segmenter.flush());
@@ -436,6 +464,12 @@ function createAgentVoiceEngine(options) {
 			if (finalFrame) {
 				await response.playback.reserve(finalFrame.byteLength, response.abortController.signal);
 				if (activeResponse !== response || closed) return taskUpdateExposed();
+				if (response.opening && options.runtime.sessionBusy(claim.request.conversationId)) {
+					cancelActiveResponse("barge_in");
+					return false;
+				}
+				response.firstFrameSent = true;
+				clearTimeout(response.openingTimer);
 				options.sendAudio(response.id, finalFrame);
 			}
 			await response.playback.drain(response.abortController.signal);
@@ -451,6 +485,7 @@ function createAgentVoiceEngine(options) {
 				finishReason: response.audioStarted ? "completed" : "text_only",
 				audio: response.audioStarted
 			});
+			if (opening) opening.result = response.audioStarted ? "completed" : "failed";
 			activeResponse = void 0;
 			return !updateClientMessageId || taskUpdateExposed();
 		} catch (error) {
@@ -461,7 +496,7 @@ function createAgentVoiceEngine(options) {
 				responseId: response.id,
 				...updateClientMessageId ? { clientMessageId: updateClientMessageId } : {}
 			}, updateClientMessageId ? "Proactive voice task update deferred" : "Realtime voice response failed");
-			if (!updateClientMessageId) send("session.error", {
+			if (!updateClientMessageId && !opening) send("session.error", {
 				code: "RESPONSE_FAILED",
 				message: "Voice response failed",
 				recoverable: true
@@ -483,6 +518,7 @@ function createAgentVoiceEngine(options) {
 			if (activeResponse === response) activeResponse = void 0;
 			return taskUpdateExposed();
 		} finally {
+			clearTimeout(response.openingTimer);
 			clearTimeout(response.firstPhraseTimer);
 			await waitForSpeech(response);
 			response.abortController.abort("response_finished");
@@ -538,14 +574,15 @@ function createAgentVoiceEngine(options) {
 		if (event.type === "error") {
 			turn.reset();
 			echoCandidates.clear();
+			const message = event.error instanceof PlatformVoiceError ? event.error.clientMessage : "Streaming transcription failed";
 			log.warn({
 				err: event.error,
 				sessionId: claim.sessionId,
 				provider: stt.route.provider
-			}, "Realtime STT failed");
+			}, `Realtime STT failed: ${message}`);
 			send("session.error", {
 				code: "PROVIDER_ERROR",
-				message: "Streaming transcription failed",
+				message,
 				recoverable: false
 			});
 			options.onClose("provider_error", true);
@@ -553,6 +590,8 @@ function createAgentVoiceEngine(options) {
 		}
 		if (muted || finalizedUtterances.has(event.utteranceId)) return;
 		if (event.type === "speech_started") {
+			openingInputSeen = true;
+			if (activeResponse?.opening && !activeResponse.firstFrameSent) cancelActiveResponse("barge_in");
 			lastUserSpeechAt = Date.now();
 			echoCandidates.remember(event.utteranceId, activeResponse?.audioStarted ? activeResponse.audibleText : recentPlayback && recentPlayback.expiresAt >= Date.now() ? recentPlayback.text : void 0);
 			if (claim.request.purpose === "conversation") {
@@ -578,6 +617,7 @@ function createAgentVoiceEngine(options) {
 		if (event.type === "transcript_final") {
 			lastUserSpeechAt = Date.now();
 			const text = event.text.trim();
+			if (text) openingInputSeen = true;
 			if (!text) {
 				if (claim.request.purpose === "conversation") bufferFinal(event.utteranceId, "");
 				return;
@@ -613,7 +653,7 @@ function createAgentVoiceEngine(options) {
 					turn.reset();
 					return;
 				}
-				if (claim.config.voice?.realtime?.bargeIn) cancelActiveResponse("barge_in");
+				if (activeResponse?.opening || claim.config.voice?.realtime?.bargeIn) cancelActiveResponse("barge_in");
 				bufferFinal(event.utteranceId, text);
 			}
 		}
@@ -654,6 +694,21 @@ function createAgentVoiceEngine(options) {
 	}
 	return {
 		isConversationIdle,
+		async offerOpeningGreeting(input) {
+			if (openingInputSeen || !canOfferTaskUpdateInput() || options.runtime.sessionBusy(claim.request.conversationId)) return "skipped";
+			const opening = {
+				...input,
+				result: "failed"
+			};
+			const attempt = conversationTail.then(async () => {
+				if (Date.now() >= input.deadlineAt) return "expired";
+				if (openingInputSeen || !canOfferTaskUpdateInput() || options.runtime.sessionBusy(claim.request.conversationId)) return "skipped";
+				await runAssistantTurn(input.text, input.responseId, void 0, input.deadlineAt - 2e3, Date.now(), opening);
+				return opening.result;
+			});
+			conversationTail = attempt.then(() => {}, () => {});
+			return attempt;
+		},
 		canOfferTaskUpdate() {
 			return !taskUpdateQueued && canOfferTaskUpdateInput();
 		},

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

@@ -1,9 +1,15 @@
+import type { OpeningGreetingResult } from './opening-greeting.js';
 import type { VoiceServerEvent } from '@xopcai/realtime-protocol/voice';
 export type VoiceEventSink = <T extends VoiceServerEvent['type']>(type: T, payload: Extract<VoiceServerEvent, {
     type: T;
 }>['payload']) => void;
 export interface VoiceEngine {
     start(): Promise<void>;
+    offerOpeningGreeting?(input: {
+        responseId: string;
+        text: string;
+        deadlineAt: number;
+    }): Promise<OpeningGreetingResult>;
     appendAudio(bytes: Uint8Array): void;
     setInputMuted(muted: boolean): void | Promise<void>;
     commit(): Promise<void>;

package/dist/src/voice/realtime/memory-context.js

@@ -3,16 +3,20 @@ import { init_logger } from "../../utils/logger.js";
 import { getSessionMetadata } from "../../storage/sqlite/session-read-repository.js";
 import { init_session_repository } from "../../storage/sqlite/session-repository.js";
 import { getSessionConfig, init_config_repository } from "../../storage/sqlite/config-repository.js";
+import { canUseKnowledge } from "../../knowledge-memory/usage-policy.js";
+import { getKnowledgeItem } from "../../knowledge-memory/repository.js";
+import { init_config, resolveKnowledgeReadPolicy } from "../../user-context/config.js";
 import { getConversationRouting } from "../../storage/sqlite/conversation-repository.js";
 import { getConversation } from "../../routing/agent-session-key.js";
 import { init_session_key } from "../../routing/session-key.js";
-import { getKnowledgeItem } from "../../knowledge-memory/repository.js";
+import { resolveUserContextSessionAccess } from "../../user-context/access-policy.js";
 import "../../knowledge-memory/index.js";
+import { stripRuntimeContextFromUserMessage } from "../../session/user-message-display.js";
 import { getUserAssertion } from "../../user-model/repository.js";
 import "../../user-model/index.js";
-import { stripRuntimeContextFromUserMessage } from "../../session/user-message-display.js";
 import { buildExecutionContext } from "../../agent/context/execution-context.js";
 //#region src/voice/realtime/memory-context.ts
+init_config();
 init_session_key();
 init_config_repository();
 init_session_repository();
@@ -35,7 +39,7 @@ function buildVoiceMemoryContext(input) {
 	const started = performance.now();
 	try {
 		const config = input.getConfig();
-		if (!voiceMemoryEnabled(config, input.conversationId) || input.maxChars < 128) return;
+		if (!resolveUserContextSessionAccess(config, input.conversationId).userModel || !voiceMemoryEnabled(config, input.conversationId) || input.maxChars < 128) return;
 		const session = getSessionMetadata(input.conversationId);
 		const context = buildExecutionContext({
 			query: voiceMemoryQuery(input.history),
@@ -44,7 +48,9 @@ function buildVoiceMemoryContext(input) {
 			projectId: input.projectId,
 			conversationId: input.conversationId,
 			maxAssertions: 6,
-			maxKnowledge: 3
+			maxKnowledge: 3,
+			includeKnowledge: resolveUserContextSessionAccess(config, input.conversationId).knowledge,
+			knowledgePolicy: resolveKnowledgeReadPolicy(config.userContext.knowledgeMemory)
 		});
 		const block = JSON.stringify({ backgroundMemory: {
 			userFacts: context.assertions.map((item) => item.assertion.statement),
@@ -64,7 +70,15 @@ function buildVoiceMemoryContext(input) {
 		const configVersion = JSON.stringify(config.userContext);
 		const isCurrent = () => {
 			if (!voiceMemoryEnabled(input.getConfig(), input.conversationId) || JSON.stringify(input.getConfig().userContext) !== configVersion) return false;
-			return references.every((reference) => reference.kind === "assertion" ? getUserAssertion(reference.id)?.recordedAt === reference.updatedAt : getKnowledgeItem(reference.id)?.updatedAt === reference.updatedAt);
+			return references.every((reference) => reference.kind === "assertion" ? getUserAssertion(reference.id)?.recordedAt === reference.updatedAt : (() => {
+				const item = getKnowledgeItem(reference.id);
+				return Boolean(item && item.updatedAt === reference.updatedAt && canUseKnowledge(item, {
+					agentId: session?.routing?.agentId ?? "main",
+					workspaceId: input.workspaceId,
+					projectId: input.projectId,
+					conversationId: input.conversationId
+				}, resolveKnowledgeReadPolicy(input.getConfig().userContext.knowledgeMemory)));
+			})());
 		};
 		log.debug({
 			conversationId: input.conversationId,

package/dist/src/voice/realtime/opening-greeting.d.ts

@@ -0,0 +1,12 @@
+export type OpeningGreetingResult = 'completed' | 'skipped' | 'interrupted' | 'failed' | 'expired';
+export interface OpeningGreetingIdentity {
+    principalId: string;
+    conversationId: string;
+    logicalCallId: string;
+    responseId: string;
+}
+/** Only an explicitly provided name is used; never infer identity from an account ID. */
+export declare function openingGreetingText(callName: string | null | undefined, language: 'zh' | 'en'): string;
+/** Claim before output: crashes and interrupted calls must never replay the greeting. */
+export declare function claimOpeningGreeting(identity: OpeningGreetingIdentity, now?: number): boolean;
+export declare function finishOpeningGreeting(identity: OpeningGreetingIdentity, state: OpeningGreetingResult, reason?: string): void;

package/dist/src/voice/realtime/opening-greeting.js

@@ -0,0 +1,22 @@
+import { getSqliteDatabase, init_transaction } from "../../storage/sqlite/transaction.js";
+//#region src/voice/realtime/opening-greeting.ts
+init_transaction();
+/** Only an explicitly provided name is used; never infer identity from an account ID. */
+function openingGreetingText(callName, language) {
+	const name = callName?.replace(/[\p{Cc}\p{Cf}]/gu, "").replace(/\s+/g, " ").trim().slice(0, 40);
+	return language === "en" ? name ? `Hi, ${name}. I'm here.` : "Hi, I'm here." : name ? `嗨，${name}，我在。` : "嗨，我在。";
+}
+/** Claim before output: crashes and interrupted calls must never replay the greeting. */
+function claimOpeningGreeting(identity, now = Date.now()) {
+	const db = getSqliteDatabase();
+	db.prepare("DELETE FROM voice_opening_greetings WHERE created_at < ?").run(now - 864e5);
+	return db.prepare(`INSERT OR IGNORE INTO voice_opening_greetings
+    (principal_id, conversation_id, logical_call_id, response_id, state, created_at, updated_at)
+    VALUES (?, ?, ?, ?, 'claimed', ?, ?)`).run(identity.principalId, identity.conversationId, identity.logicalCallId, identity.responseId, now, now).changes === 1;
+}
+function finishOpeningGreeting(identity, state, reason) {
+	getSqliteDatabase().prepare(`UPDATE voice_opening_greetings SET state = ?, reason = ?, updated_at = ?
+    WHERE principal_id = ? AND conversation_id = ? AND logical_call_id = ? AND state = 'claimed'`).run(state, reason ?? null, Date.now(), identity.principalId, identity.conversationId, identity.logicalCallId);
+}
+//#endregion
+export { claimOpeningGreeting, finishOpeningGreeting, openingGreetingText };

package/dist/src/voice/realtime/persona-context.js

@@ -1,6 +1,6 @@
 import { init_agent_scope, resolveAgentProfileDir } from "../../agent/agent-scope.js";
-import { DEFAULT_SOUL_FILENAME } from "../../agent/context/workspace.js";
 import { resolveEffectiveAgentProfileForSession } from "../../config/agent-profile.js";
+import { DEFAULT_SOUL_FILENAME } from "../../agent/context/workspace.js";
 import { loadProfileBootstrapFiles } from "../../agent/bootstrap/load-bootstrap-files.js";
 import { join } from "node:path";
 import { statSync } from "node:fs";

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

@@ -12,7 +12,9 @@ import { ALIBABA_REALTIME_TTS_MODEL } from "../tts/providers/alibaba-speech.js";
 import { resolveSpeechProviderChain } from "../tts/factory.js";
 import { mergeTtsConfigFromAppConfig } from "../tts/merge-config.js";
 import { voiceConversationInstructions } from "./conversation-context.js";
+import { verifyDeviceConnectionProof } from "../../gateway/security/device-request-proof.js";
 import { createPreauthConnectionBudget } from "../../gateway/security/preauth-connection-budget.js";
+import { claimOpeningGreeting, finishOpeningGreeting, openingGreetingText } from "./opening-greeting.js";
 import { createAgentVoiceEngine } from "./agentEngine.js";
 import { resolveOmniRoute } from "./omniRoute.js";
 import { createOmniVoiceEngine } from "./omniEngine.js";
@@ -225,12 +227,18 @@ var VoiceRealtimeRuntime = class {
 	async createSession(request, principalId, now = Date.now()) {
 		const { request: resolvedRequest, config, omni, conversationSessionId, stt, tts, inputMode } = await this.prepareSession(request, now);
 		request = resolvedRequest;
+		const personal = request.conversationId ? getPersonalAgentByConversation(request.conversationId) : null;
+		const openingGreeting = request.openingGreeting && request.openingGreeting.initiation === "user" && request.purpose === "conversation" && request.mode === "assistant" && personal?.state === "ready" && personal.voiceCallPreferences.openingGreetingEnabled ? {
+			responseId: `greeting_${crypto.randomUUID()}`,
+			text: openingGreetingText(personal.userCallName, request.language ?? "zh")
+		} : void 0;
 		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?.maxSessionSeconds ? omni.maxSessionSeconds * 1e3 : Number.MAX_SAFE_INTEGER) : config.voice.realtime.maxDictationMs;
 		const claim = {
 			conversationSessionId,
+			openingGreeting,
 			sessionId,
 			connectionEpoch,
 			principalId,
@@ -250,6 +258,10 @@ var VoiceRealtimeRuntime = class {
 		this.tickets.set(ticketKey(ticket), claim);
 		if (request.purpose === "conversation" && request.conversationId) this.conversationReservations.set(request.conversationId, sessionId);
 		return {
+			...request.openingGreeting ? { openingGreeting: {
+				accepted: Boolean(openingGreeting),
+				...openingGreeting ? { greetingResponseId: openingGreeting.responseId } : {}
+			} } : {},
 			sessionId,
 			ticket,
 			ticketExpiresAt: new Date(claim.expiresAt).toISOString(),
@@ -394,6 +406,20 @@ var VoiceRealtimeRuntime = class {
 		let context;
 		let unsubscribeMemory;
 		let unsubscribeSession;
+		let openingTimer;
+		let outputReady = false;
+		let pendingGreeting;
+		const finishGreeting = (identity, result, reason) => {
+			try {
+				finishOpeningGreeting(identity, result, reason);
+			} catch (err) {
+				log.warn({
+					err,
+					...identity,
+					phase: "opening_greeting_audit"
+				}, "Opening greeting audit failed");
+			}
+		};
 		let inputMutationTail = Promise.resolve();
 		const send = (type, payload) => {
 			if (!claim || socket.readyState !== WebSocketState.OPEN) return;
@@ -423,6 +449,11 @@ var VoiceRealtimeRuntime = class {
 			if (shutdownCompletion) return shutdownCompletion;
 			if (closed) return Promise.resolve();
 			closed = true;
+			clearTimeout(openingTimer);
+			if (pendingGreeting) {
+				finishGreeting(pendingGreeting, "skipped", "session_closed");
+				pendingGreeting = void 0;
+			}
 			shutdownCompletion = (async () => {
 				unsubscribeMemory?.();
 				unsubscribeSession?.();
@@ -476,6 +507,11 @@ var VoiceRealtimeRuntime = class {
 			shutdown("context_changed", true);
 		};
 		const authenticate = async (message) => {
+			const pendingClaim = this.tickets.get(ticketKey(message.payload.ticket));
+			if (pendingClaim && !verifyDeviceConnectionProof(pendingClaim.principalId, message.payload.ticket, new URL(request.url, "http://localhost").pathname + new URL(request.url, "http://localhost").search, typeof request.headers["x-xopc-proof"] === "string" ? request.headers["x-xopc-proof"] : void 0)) {
+				socket.close(4401, "Invalid voice session proof");
+				return;
+			}
 			const consumed = this.consumeTicket(message.payload.ticket, message.payload.sessionId);
 			if (!consumed || this.options.isPrincipalActive?.(consumed.principalId) === false) {
 				if (consumed) this.releaseConversationReservation(consumed);
@@ -697,7 +733,60 @@ var VoiceRealtimeRuntime = class {
 				return;
 			}
 			if (message.type === "session.ping") send("session.pong", {});
-			else if (message.type === "session.stop") shutdown(message.payload.reason, true);
+			else if (message.type === "session.output_ready") {
+				if (!ready || !claim.request.openingGreeting || message.payload.connectionEpoch !== claim.connectionEpoch) {
+					socket.close(4400, "Invalid output readiness");
+					return;
+				}
+				if (outputReady) return;
+				outputReady = true;
+				const greeting = claim.openingGreeting;
+				if (!greeting || !engine?.offerOpeningGreeting) return;
+				const identity = {
+					principalId: claim.principalId,
+					conversationId: claim.request.conversationId,
+					logicalCallId: claim.request.openingGreeting.logicalCallId,
+					responseId: greeting.responseId
+				};
+				try {
+					if (!claimOpeningGreeting(identity)) return;
+				} catch (err) {
+					log.warn({
+						err,
+						sessionId: claim.sessionId
+					}, "Opening greeting claim failed");
+					return;
+				}
+				const deadlineAt = Date.now() + 2e3;
+				pendingGreeting = identity;
+				openingTimer = setTimeout(() => {
+					openingTimer = void 0;
+					pendingGreeting = void 0;
+					if (closed) {
+						finishGreeting(identity, "skipped", "session_closed");
+						return;
+					}
+					engine.offerOpeningGreeting({
+						...greeting,
+						deadlineAt
+					}).then((result) => {
+						finishGreeting(identity, result);
+						log.info({
+							...identity,
+							sessionId: claim?.sessionId,
+							phase: "opening_greeting",
+							result
+						}, "Opening greeting finished");
+					}).catch((err) => {
+						finishGreeting(identity, "failed");
+						log.warn({
+							err,
+							...identity,
+							phase: "opening_greeting"
+						}, "Opening greeting failed");
+					});
+				}, 300);
+			} else if (message.type === "session.stop") shutdown(message.payload.reason, true);
 			else if (message.type === "session.metric") {
 				const { responseId, metric, durationMs } = message.payload;
 				const key = `${responseId}:${metric}`;

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

@@ -18,6 +18,10 @@ export interface ResolvedStreamingStt {
     route: VoiceProviderRoute;
 }
 export interface VoiceTicketClaim {
+    openingGreeting?: {
+        responseId: string;
+        text: string;
+    };
     sessionId: string;
     connectionEpoch: number;
     principalId: string;

package/dist/src/work-discovery/incremental-repository.js

@@ -1,5 +1,5 @@
-import { getWorkDiscoveryRun } from "./repository.js";
 import { createUnderstandingSourceRun, listUnderstandingSourceGrants, listUnderstandingSourceRuns, updateUnderstandingSourceRun } from "../user-context/sources/repository.js";
+import { getWorkDiscoveryRun } from "./repository.js";
 import { workDiscoveryFingerprintsEqual } from "./incremental.js";
 //#region src/work-discovery/incremental-repository.ts
 function refreshFromRun(run) {