@xopcai/xopc 0.0.373 → 0.0.374

package/dist/src/tasks/task-main-update-decision-service.js

@@ -1,9 +1,9 @@
 import { TaskRepository, init_task_repository } from "./task-repository.js";
 import { TaskRunRepository, init_task_run_repository } from "./task-run-repository.js";
-import { extractAssistantText, getAssistantMessageErrorReason, stripCodeFences } from "../providers/model-response.js";
 import { init_providers, resolveModel } from "../providers/index.js";
-import { completeWithResolvedCredentials } from "../providers/model-call.js";
 import { getPersonalAgentByConversation } from "../personal-agent/repository.js";
+import { completeWithResolvedCredentials } from "../providers/model-call.js";
+import { extractAssistantText, getAssistantMessageErrorReason, stripCodeFences } from "../providers/model-response.js";
 import { TaskCollaborationRepository } from "./task-collaboration-repository.js";
 //#region src/tasks/task-main-update-decision-service.ts
 init_providers();

package/dist/src/tui/backends/embedded-backend.js

@@ -11,8 +11,8 @@ import { init_sqlite } from "../../storage/sqlite/index.js";
 import { normalizeAgentId } from "../../agent-catalog/id.js";
 import { init_agent_scope, listAgentEntries } from "../../agent/agent-scope.js";
 import { AgentCatalogService } from "../../agent-catalog/service.js";
-import { getAgentDefaultModelRef, init_schema } from "../../config/schema.js";
 import { init_paths } from "../../config/paths.js";
+import { getAgentDefaultModelRef, init_schema } from "../../config/schema.js";
 import { init_agent_session_key, resolveAgentIdFromConversationId } from "../../routing/agent-session-key.js";
 import { resolveEffectiveAgentProfile } from "../../config/agent-profile.js";
 import { effectiveWorkspacePathForSession } from "../../session/session-workspace.js";

package/dist/src/tui/tui.js

@@ -2,8 +2,8 @@ import { version } from "../../package.js";
 import { resolveStateDir, resolveXopcDatabasePath } from "../config/paths-state.js";
 import { init_paths } from "../config/paths.js";
 import { init_agent_session_key, normalizeAgentId } from "../routing/agent-session-key.js";
-import { getAllModels, getAllProviders, getApiKey, init_providers, isProviderConfiguredSync } from "../providers/index.js";
 import { resolveEffectiveAgentProfile } from "../config/agent-profile.js";
+import { getAllModels, getAllProviders, getApiKey, init_providers, isProviderConfiguredSync } from "../providers/index.js";
 import { isTerminalWorkflowRunStatus } from "../workflows/domain/run.js";
 import "../workflows/domain/index.js";
 import { ProjectTrustStore, hasTrustRequiringProjectResources } from "../project-trust/trust-store.js";

package/dist/src/tunnel/broker-client.js

@@ -29,6 +29,8 @@ const registrationResponseSchema = z.object({
 var TunnelBrokerClient = class {
 	constructor(baseUrl) {
 		this.baseUrl = baseUrl;
+		const url = new URL(baseUrl);
+		if (url.protocol !== "https:" || url.username || url.password) throw new Error("Tunnel broker requires HTTPS without URL credentials");
 	}
 	apiUrl(path) {
 		return `${this.baseUrl.replace(/\/+$/, "")}${path.startsWith("/") ? path : `/${path}`}`;

package/dist/src/tunnel/tunnel-config.js

@@ -1,4 +1,4 @@
-import { TunnelConfigSchema, TunnelConsentSchema, init_schema } from "../config/schema.js";
+import { TunnelBrokerUrlSchema, TunnelConfigSchema, TunnelConsentSchema, init_schema } from "../config/schema.js";
 import { getTunnelRegistrationSecretMeta, isMaskedTunnelSecretPatchValue } from "./env.js";
 import { assertTunnelAutoStartAllowed, buildTunnelConsentRecord, hasValidTunnelConsent } from "./consent.js";
 import { z } from "zod";
@@ -6,7 +6,7 @@ import { z } from "zod";
 init_schema();
 const TunnelConfigPatchSchema = z.object({
 	enabled: z.boolean().optional(),
-	brokerUrl: z.string().url().optional(),
+	brokerUrl: TunnelBrokerUrlSchema.optional(),
 	registrationSecret: z.union([z.string(), z.null()]).optional(),
 	autoStart: z.boolean().optional(),
 	subdomain: z.string().optional(),

package/dist/src/tunnel/tunnel-rate-limit.js

@@ -1,9 +1,10 @@
 import { createLogger } from "../utils/logger/index.js";
 import { init_logger } from "../utils/logger.js";
 import { buckets } from "../gateway/rate-limit/buckets.js";
-import "../gateway/rate-limit/index.js";
+import { init_rate_limit } from "../gateway/rate-limit/index.js";
 import { createHash } from "node:crypto";
 //#region src/tunnel/tunnel-rate-limit.ts
+init_rate_limit();
 init_logger();
 const log = createLogger("TunnelRateLimit");
 function tokenKey(token) {

package/dist/src/utils/logger/redact.js

@@ -62,8 +62,9 @@ var init_redact = __esmMin((() => {
 	KEEP_PREFIX_LENGTH = 6;
 	KEEP_SUFFIX_LENGTH = 4;
 	DEFAULT_REDACT_PATTERNS = [
+		/X-Xopc-Proof\s*[:=]\s*([A-Za-z0-9._-]+)/gi,
 		/\b[A-Z0-9_]*(?:KEY|TOKEN|SECRET|PASSWORD|PASSWD)\b\s*[=:]\s*((?:\\?["'])?)([^\s"'\\]+)\1/gi,
-		/"(?:apiKey|token|secret|password|passwd|accessToken|refreshToken|privateKey)"\s*:\s*"([^"]+)"/gi,
+		/"(?:apiKey|token|secret|password|passwd|accessToken|refreshToken|privateKey|signature|x-xopc-proof)"\s*:\s*"([^"]+)"/gi,
 		/(?:__Host-xopc-session|xopc-local-session)=([A-Za-z0-9_-]{43})/g,
 		/Authorization\s*[:=]\s*Bearer\s+([A-Za-z0-9._\-+=]+)/gi,
 		/\b(sk-[A-Za-z0-9_-]{8,})\b/gi,
@@ -88,6 +89,8 @@ var init_redact = __esmMin((() => {
 		"cookie",
 		"set-cookie",
 		"signedpayload",
+		"signature",
+		"x-xopc-proof",
 		"credential",
 		"credentials"
 	]);

package/dist/src/voice/platform-streams.d.ts

@@ -1,5 +1,11 @@
 import type { StreamingSttOpenRequest, StreamingSttSession } from '../media-understanding/types.js';
 import type { SpeechSynthesisStreamResult } from './tts/speech-provider-types.js';
+export declare class PlatformVoiceError extends Error {
+    readonly status?: number;
+    readonly code?: string;
+    constructor(message: string, status?: number, code?: string);
+    get clientMessage(): string;
+}
 export declare function openPlatformStt(request: StreamingSttOpenRequest): Promise<StreamingSttSession>;
 export declare function openPlatformTts(request: {
     baseUrl: string;

package/dist/src/voice/platform-streams.js

@@ -1,6 +1,22 @@
 import WebSocket from "ws";
 //#region src/voice/platform-streams.ts
 const MAX_BUFFERED_BYTES = 512 * 1024;
+const MAX_ERROR_BODY_BYTES = 16 * 1024;
+var PlatformVoiceError = class extends Error {
+	constructor(message, status, code) {
+		super(message);
+		this.status = status;
+		this.code = code;
+		this.name = "PlatformVoiceError";
+	}
+	get clientMessage() {
+		if (this.code === "realtime_quota_workspace_budget") return "XOPC Cloud voice workspace budget is exhausted. Increase the workspace budget or choose another voice provider.";
+		if (this.status === 402 || this.code === "realtime_quota_user_credits") return "XOPC Cloud voice has insufficient Credit or quota. Check your Cloud balance and workspace budget, or choose another voice provider.";
+		if (this.status === 401 || this.status === 403) return "XOPC Cloud voice authorization failed. Sign in again and check your access to this voice model.";
+		if (this.status === 429 || this.code?.startsWith("realtime_quota_")) return "XOPC Cloud voice quota or rate limit reached. Try again later or choose another voice provider.";
+		return "XOPC Cloud voice is unavailable. Try again later or choose another voice provider.";
+	}
+};
 function connect(url, token, signal, onEvent, onFailure) {
 	signal.throwIfAborted();
 	const socket = new WebSocket(url, {
@@ -30,15 +46,38 @@ function connect(url, token, signal, onEvent, onFailure) {
 			if (binary) throw new Error("Unexpected platform binary event");
 			const event = JSON.parse(raw.toString());
 			if (!event || typeof event.type !== "string") throw new Error("Invalid platform voice event");
-			if (event.type === "error") throw new Error(event.error?.message ?? "Platform voice failed");
+			if (event.type === "error") throw new PlatformVoiceError(event.error?.message ?? "Platform voice failed", void 0, event.error?.code);
 			onEvent(event);
 		} catch (error) {
 			fail(error instanceof Error ? error : /* @__PURE__ */ new Error("Invalid platform voice event"));
 		}
 	});
 	socket.on("unexpected-response", (_request, response) => {
-		response.resume();
-		fail(/* @__PURE__ */ new Error(`Platform voice rejected connection (${response.statusCode})`));
+		const fallback = `Platform voice rejected connection (${response.statusCode})`;
+		let bytes = 0;
+		const chunks = [];
+		const reject = () => {
+			let detail;
+			try {
+				detail = JSON.parse(Buffer.concat(chunks).toString("utf8"))?.error;
+			} catch {}
+			const code = typeof detail?.code === "string" && /^[a-zA-Z0-9_-]{1,128}$/.test(detail.code) ? detail.code : void 0;
+			const message = typeof detail?.message === "string" ? detail.message.slice(0, 1e3) : void 0;
+			fail(new PlatformVoiceError(`${fallback}${code ? `: ${code}` : ""}${message ? `: ${message}` : ""}`, response.statusCode, code));
+		};
+		response.on("data", (chunk) => {
+			bytes += chunk.length;
+			if (bytes > MAX_ERROR_BODY_BYTES) {
+				chunks.length = 0;
+				reject();
+				response.destroy();
+				return;
+			}
+			chunks.push(chunk);
+		});
+		response.once("end", reject);
+		response.once("error", reject);
+		response.once("aborted", reject);
 	});
 	socket.on("error", fail);
 	socket.on("close", () => fail(/* @__PURE__ */ new Error("Platform voice disconnected before completion")));
@@ -265,4 +304,4 @@ async function openPlatformTts(request) {
 	};
 }
 //#endregion
-export { openPlatformStt, openPlatformTts };
+export { PlatformVoiceError, openPlatformStt, openPlatformTts };

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