@xopcai/xopc 0.0.190 → 0.0.192

package/dist/src/voice/stt/providers/alibaba-transcription.js

@@ -1,159 +1,86 @@
 import { createLogger } from "../../../utils/logger/index.js";
 import { init_logger } from "../../../utils/logger.js";
-import { ProviderHttpError } from "../../../media-shared/http/provider-http-errors.js";
-import { fetchWithTimeoutGuarded, postJsonRequest, waitProviderOperationPollInterval } from "../../../media-shared/http/provider-http.js";
+import { postJsonRequest } from "../../../media-shared/http/provider-http.js";
 import "../../../media-shared/http/index.js";
 import { registerMediaUnderstandingProvider } from "../../../media-understanding/registry.js";
 //#region src/voice/stt/providers/alibaba-transcription.ts
-/**
-* Alibaba DashScope Paraformer STT — implements MediaUnderstandingProvider.transcribeAudio.
-*
-* DashScope's async API is a 4-step dance:
-*   1. POST /api/v1/services/audio/asr/transcription with `X-DashScope-Async: enable`
-*      and `input.file_urls = [data:audio/ogg;base64,...]` → returns task_id
-*   2. Poll GET /api/v1/tasks/{task_id} until task_status === 'SUCCEEDED'
-*   3. The success result contains `transcription_url` pointing at a JSON document
-*   4. Fetch that JSON to extract the actual `transcripts[].text`
-*
-* All HTTP calls go through `fetchWithTimeoutGuarded` so the SSRF guard catches
-* malicious config injection. The transcription_url is a public OSS URL
-* (CDN-hosted); we keep `allowPrivateNetwork: false` so a malicious tenant
-* cannot redirect to an internal address.
-*
-* Polling caps at 60s by default (60 * 1s). The runner's `timeoutMs` controls
-* HTTP timeouts on each individual submit/poll/fetch call, not the overall
-* poll loop ceiling.
-*/
 init_logger();
 const log = createLogger("STT:Alibaba");
-const DEFAULT_MODEL = "paraformer-v2";
-const DEFAULT_BASE_URL = "https://dashscope.aliyuncs.com/api/v1/services/audio/asr/transcription";
-const TASKS_BASE_URL = "https://dashscope.aliyuncs.com/api/v1/tasks";
-const POLL_INTERVAL_MS = 1e3;
-const MAX_POLL_MS = 6e4;
-async function submitTask(params) {
-	const data = await (await postJsonRequest(params.baseUrl, {
-		timeoutMs: params.timeoutMs,
-		label: "Alibaba STT submit",
-		headers: {
-			Authorization: `Bearer ${params.apiKey}`,
-			"X-DashScope-Async": "enable"
-		},
-		body: {
-			model: params.model,
-			input: { file_urls: [params.audioDataUrl] },
-			...params.language ? { parameters: { language_hint: params.language } } : {}
-		},
-		signal: params.signal
-	})).json();
-	if (data.code) throw new Error(`Alibaba STT API error: ${data.code} - ${data.message}`);
-	if (!data.output?.task_id) {
-		log.error({ response: data }, "Alibaba STT API response missing task_id");
-		throw new Error(`No task_id returned from Alibaba STT API: ${JSON.stringify(data)}`);
-	}
-	log.debug({ taskId: data.output.task_id }, "Task submitted");
-	return data.output.task_id;
-}
-async function pollTask(params) {
-	const startTime = Date.now();
-	const url = `${TASKS_BASE_URL}/${params.taskId}`;
-	while (Date.now() - startTime < MAX_POLL_MS) {
-		const response = await fetchWithTimeoutGuarded(url, {
-			timeoutMs: params.timeoutMs,
-			label: "Alibaba STT poll",
-			signal: params.signal,
-			init: {
-				method: "GET",
-				headers: { Authorization: `Bearer ${params.apiKey}` }
-			}
-		});
-		if (!response.ok) {
-			const errorText = await response.text().catch(() => "");
-			throw new ProviderHttpError({
-				label: "Alibaba STT poll",
-				status: response.status,
-				detail: errorText.slice(0, 220) || response.statusText
-			});
-		}
-		const data = await response.json();
-		const status = data.output?.task_status;
-		if (status === "SUCCEEDED") {
-			const result = data.output?.results?.[0];
-			if (!result) throw new Error("Alibaba STT task succeeded but no results found");
-			return { text: (await fetchTranscription(result.transcription_url, params.timeoutMs, params.signal)).transcripts.map((t) => t.text).join("\n") };
-		}
-		if (status === "FAILED") throw new Error("Alibaba STT task failed");
-		await waitProviderOperationPollInterval(POLL_INTERVAL_MS, params.signal);
-	}
-	throw new Error(`Alibaba STT task did not complete within ${MAX_POLL_MS}ms`);
+const DEFAULT_MODEL = "qwen-audio-3.0-asr-flash";
+const DEFAULT_BASE_URL = "https://dashscope.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation";
+function audioFormat(request) {
+	const extension = request.fileName.split(".").pop()?.toLowerCase();
+	if (extension === "mpeg" || extension === "mpga") return "mp3";
+	if (extension === "m4a") return "mp4";
+	return extension || "wav";
 }
-async function fetchTranscription(url, timeoutMs, signal) {
-	const response = await fetchWithTimeoutGuarded(url, {
-		timeoutMs,
-		label: "Alibaba STT transcription fetch",
-		signal
+async function transcribeAudio(request) {
+	if (!request.apiKey) throw new Error("Alibaba STT API key is unavailable");
+	const startedAt = Date.now();
+	const model = request.model ?? DEFAULT_MODEL;
+	const audio = `data:${request.mime ?? "application/octet-stream"};base64,${request.buffer.toString("base64")}`;
+	const messages = [];
+	if (request.prompt) messages.push({
+		role: "user",
+		content: [{
+			type: "input_text",
+			text: request.prompt
+		}]
 	});
-	if (!response.ok) throw new ProviderHttpError({
-		label: "Alibaba STT transcription fetch",
-		status: response.status,
-		detail: response.statusText
+	messages.push({
+		role: "user",
+		content: [{
+			type: "input_audio",
+			input_audio: { data: audio }
+		}]
 	});
-	return await response.json();
-}
-async function transcribeAudio(req) {
-	const startTime = Date.now();
-	const model = req.model ?? DEFAULT_MODEL;
-	const baseUrl = req.baseUrl ?? DEFAULT_BASE_URL;
-	const base64Audio = req.buffer.toString("base64");
-	const audioDataUrl = `data:${req.mime ?? "audio/ogg"};base64,${base64Audio}`;
-	log.debug({
-		model,
-		bufferSize: req.buffer.length,
-		language: req.language,
-		fileName: req.fileName
-	}, "Sending to Alibaba Paraformer");
 	try {
-		const taskId = await submitTask({
-			apiKey: req.apiKey,
-			baseUrl,
-			model,
-			audioDataUrl,
-			...req.language ? { language: req.language } : {},
-			timeoutMs: req.timeoutMs,
-			signal: req.signal
-		});
-		const result = await pollTask({
-			apiKey: req.apiKey,
-			taskId,
-			timeoutMs: req.timeoutMs,
-			signal: req.signal
-		});
-		const durationSeconds = (Date.now() - startTime) / 1e3;
+		const data = await (await postJsonRequest(request.baseUrl ?? DEFAULT_BASE_URL, {
+			timeoutMs: request.timeoutMs,
+			label: "Alibaba STT",
+			headers: {
+				Authorization: `Bearer ${request.apiKey}`,
+				"X-DashScope-SSE": "disable"
+			},
+			body: {
+				model,
+				input: { messages },
+				parameters: {
+					format: audioFormat(request),
+					...request.language && request.language !== "auto" ? { language_hints: [request.language] } : {}
+				}
+			},
+			signal: request.signal
+		})).json();
+		const text = data.output?.text;
+		if (typeof text !== "string") throw new Error("Alibaba STT returned an invalid response");
 		log.info({
 			provider: "alibaba",
-			durationSeconds,
-			textLength: result.text.length
+			model,
+			latencyMs: Date.now() - startedAt,
+			textLength: text.length
 		}, "Transcription completed");
+		const durationSeconds = Number(data.usage?.duration);
 		return {
-			text: result.text,
+			text,
 			model,
-			...req.language ? { language: req.language } : {},
-			durationSeconds
+			...request.language ? { language: request.language } : {},
+			...Number.isFinite(durationSeconds) && durationSeconds >= 0 ? { durationSeconds } : {}
 		};
 	} catch (error) {
-		if (req.signal?.aborted) throw error;
-		const errorMsg = error instanceof Error ? error.message : String(error);
+		if (request.signal?.aborted) throw error;
+		const message = error instanceof Error ? error.message : String(error);
 		log.error({
 			err: error,
-			bufferSize: req.buffer.length,
-			model
-		}, `Alibaba transcription failed: ${errorMsg}`);
-		throw new Error(`Alibaba STT failed: ${errorMsg}`);
+			model,
+			bufferSize: request.buffer.length
+		}, `Alibaba transcription failed: ${message}`);
+		throw new Error(`Alibaba STT failed: ${message}`);
 	}
 }
 const alibabaTranscriptionProvider = {
 	id: "alibaba",
-	aliases: ["dashscope", "paraformer"],
+	aliases: ["dashscope"],
 	capabilities: ["audio"],
 	envKey: "DASHSCOPE_API_KEY",
 	defaultModels: { audio: DEFAULT_MODEL },

package/dist/src/voice/stt/providers/index.d.ts

@@ -13,3 +13,4 @@
 export { openAiTranscriptionProvider } from './openai-transcription.js';
 export { alibabaTranscriptionProvider } from './alibaba-transcription.js';
 export { localTranscriptionProvider } from './local-transcription.js';
+export { xopcCloudTranscriptionProvider } from './xopc-cloud-transcription.js';

package/dist/src/voice/stt/providers/index.js

@@ -1,4 +1,5 @@
 import { openAiTranscriptionProvider } from "./openai-transcription.js";
 import { alibabaTranscriptionProvider } from "./alibaba-transcription.js";
 import { localTranscriptionProvider } from "./local-transcription.js";
-export { alibabaTranscriptionProvider, localTranscriptionProvider, openAiTranscriptionProvider };
+import { xopcCloudTranscriptionProvider } from "./xopc-cloud-transcription.js";
+export { alibabaTranscriptionProvider, localTranscriptionProvider, openAiTranscriptionProvider, xopcCloudTranscriptionProvider };

package/dist/src/voice/stt/providers/openai-transcription.d.ts

@@ -1,5 +1,5 @@
 /**
- * OpenAI Whisper STT — implements MediaUnderstandingProvider.transcribeAudio.
+ * OpenAI transcription provider — implements MediaUnderstandingProvider.transcribeAudio.
  *
  * Uses the official `openai` SDK rather than the raw HTTP path because the SDK
  * already handles multipart/form-data encoding (`file` field), streaming
@@ -8,7 +8,7 @@
  * keep parity with the SDK's own fetch (proxy support, retries, etc.); the
  * only egress is api.openai.com which is HTTPS-only and public.
  *
- * Streaming transcription is not implemented (Whisper returns a final text
+ * Streaming transcription is not implemented (the API returns a final text
  * blob). Self-registers with `capabilities: ['audio']` only — the registry's
  * `listProvidersForCapability` filter skips this provider for image/video.
  */

package/dist/src/voice/stt/providers/openai-transcription.js

@@ -4,7 +4,7 @@ import { registerMediaUnderstandingProvider } from "../../../media-understanding
 import OpenAI from "openai";
 //#region src/voice/stt/providers/openai-transcription.ts
 /**
-* OpenAI Whisper STT — implements MediaUnderstandingProvider.transcribeAudio.
+* OpenAI transcription provider — implements MediaUnderstandingProvider.transcribeAudio.
 *
 * Uses the official `openai` SDK rather than the raw HTTP path because the SDK
 * already handles multipart/form-data encoding (`file` field), streaming
@@ -13,13 +13,13 @@ import OpenAI from "openai";
 * keep parity with the SDK's own fetch (proxy support, retries, etc.); the
 * only egress is api.openai.com which is HTTPS-only and public.
 *
-* Streaming transcription is not implemented (Whisper returns a final text
+* Streaming transcription is not implemented (the API returns a final text
 * blob). Self-registers with `capabilities: ['audio']` only — the registry's
 * `listProvidersForCapability` filter skips this provider for image/video.
 */
 init_logger();
 const log = createLogger("STT:OpenAI");
-const DEFAULT_MODEL = "whisper-1";
+const DEFAULT_MODEL = "gpt-4o-mini-transcribe";
 async function transcribeAudio(req) {
 	const startTime = Date.now();
 	const model = req.model ?? DEFAULT_MODEL;
@@ -36,7 +36,7 @@ async function transcribeAudio(req) {
 		bufferSize: req.buffer.length,
 		language: req.language,
 		fileName: req.fileName
-	}, "Sending to OpenAI Whisper");
+	}, "Sending to OpenAI transcription");
 	try {
 		const result = await client.audio.transcriptions.create({
 			file,

package/dist/src/voice/stt/providers/xopc-cloud-transcription.d.ts

@@ -0,0 +1,2 @@
+import type { MediaUnderstandingProvider } from '../../../media-understanding/types.js';
+export declare const xopcCloudTranscriptionProvider: MediaUnderstandingProvider;

package/dist/src/voice/stt/providers/xopc-cloud-transcription.js

@@ -0,0 +1,49 @@
+import { getModelCatalogStore, init_model_catalog_store } from "../../../providers/model-catalog-store.js";
+import { init_xopc_cloud_config, resolveXopcModelRouterUrl } from "../../../providers/xopc-cloud-config.js";
+import { getProviderAuthService, init_provider_auth_service } from "../../../providers/provider-auth-service.js";
+import { registerMediaUnderstandingProvider } from "../../../media-understanding/registry.js";
+//#region src/voice/stt/providers/xopc-cloud-transcription.ts
+init_model_catalog_store();
+init_provider_auth_service();
+init_xopc_cloud_config();
+function defaultModel() {
+	return getModelCatalogStore().getSource("xopc-cloud")?.models.find((model) => model.availability === "available" && model.kind === "stt")?.id;
+}
+const xopcCloudTranscriptionProvider = {
+	id: "xopc-cloud",
+	capabilities: ["audio"],
+	requiresApiKey: false,
+	autoPriority: { audio: 5 },
+	isConfigured: () => Boolean(defaultModel()),
+	transcribeAudio: async (request) => {
+		const model = request.model ?? defaultModel();
+		if (!model) throw new Error("No XOPC Cloud speech-to-text model is available");
+		const accessToken = await getProviderAuthService().resolveApiKey("xopc-cloud", request.signal);
+		if (!accessToken) throw new Error("XOPC Cloud authorization is unavailable");
+		const source = getModelCatalogStore().getSource("xopc-cloud");
+		const baseUrl = (request.baseUrl ?? source?.baseUrl ?? resolveXopcModelRouterUrl()).replace(/\/+$/, "");
+		const form = new FormData();
+		form.append("model", model);
+		form.append("file", new File([Uint8Array.from(request.buffer)], request.fileName, { type: request.mime ?? "application/octet-stream" }));
+		if (request.language) form.append("language", request.language);
+		if (request.prompt) form.append("prompt", request.prompt);
+		const response = await fetch(`${baseUrl}/audio/transcriptions`, {
+			method: "POST",
+			headers: { authorization: `Bearer ${accessToken}` },
+			body: form,
+			signal: request.signal ?? AbortSignal.timeout(request.timeoutMs),
+			redirect: "error"
+		});
+		const body = await response.json().catch(() => null);
+		if (!response.ok) throw new Error(typeof body?.error?.message === "string" ? body.error.message : `XOPC Cloud STT failed (${response.status})`);
+		if (typeof body?.text !== "string") throw new Error("XOPC Cloud STT returned an invalid response");
+		return {
+			text: body.text,
+			model,
+			...request.language ? { language: request.language } : {}
+		};
+	}
+};
+registerMediaUnderstandingProvider(xopcCloudTranscriptionProvider);
+//#endregion
+export { xopcCloudTranscriptionProvider };

package/dist/src/voice/stt/types.js

@@ -4,8 +4,8 @@ const DEFAULT_STT_CONFIG = {
 	provider: "xopc-local",
 	providers: {
 		"xopc-local": { model: "sensevoice-small" },
-		alibaba: { model: "paraformer-v2" },
-		openai: { model: "whisper-1" }
+		alibaba: { model: "qwen-audio-3.0-asr-flash" },
+		openai: { model: "gpt-4o-mini-transcribe" }
 	},
 	fallback: {
 		enabled: false,

package/dist/src/voice/tts/providers/index.d.ts

@@ -14,4 +14,5 @@
 export { openAiSpeechProvider, OPENAI_TTS_MODELS, OPENAI_TTS_VOICES } from './openai-speech.js';
 export { alibabaSpeechProvider } from './alibaba-speech.js';
 export { edgeSpeechProvider } from './edge-speech.js';
+export { xopcCloudSpeechProvider } from './xopc-cloud-speech.js';
 export { minimaxSpeechProvider, MINIMAX_TTS_MODELS, MINIMAX_TTS_VOICES, } from './minimax-speech.js';

package/dist/src/voice/tts/providers/index.js

@@ -1,5 +1,6 @@
 import { OPENAI_TTS_MODELS, OPENAI_TTS_VOICES, openAiSpeechProvider } from "./openai-speech.js";
 import { alibabaSpeechProvider } from "./alibaba-speech.js";
 import { edgeSpeechProvider } from "./edge-speech.js";
+import { xopcCloudSpeechProvider } from "./xopc-cloud-speech.js";
 import { MINIMAX_TTS_MODELS, MINIMAX_TTS_VOICES, minimaxSpeechProvider } from "./minimax-speech.js";
-export { MINIMAX_TTS_MODELS, MINIMAX_TTS_VOICES, OPENAI_TTS_MODELS, OPENAI_TTS_VOICES, alibabaSpeechProvider, edgeSpeechProvider, minimaxSpeechProvider, openAiSpeechProvider };
+export { MINIMAX_TTS_MODELS, MINIMAX_TTS_VOICES, OPENAI_TTS_MODELS, OPENAI_TTS_VOICES, alibabaSpeechProvider, edgeSpeechProvider, minimaxSpeechProvider, openAiSpeechProvider, xopcCloudSpeechProvider };

package/dist/src/voice/tts/providers/xopc-cloud-speech.d.ts

@@ -0,0 +1,2 @@
+import type { SpeechProviderPlugin } from '../speech-provider-types.js';
+export declare const xopcCloudSpeechProvider: SpeechProviderPlugin;

package/dist/src/voice/tts/providers/xopc-cloud-speech.js

@@ -0,0 +1,113 @@
+import { getModelCatalogStore, init_model_catalog_store } from "../../../providers/model-catalog-store.js";
+import { init_xopc_cloud_config, resolveXopcModelRouterUrl } from "../../../providers/xopc-cloud-config.js";
+import { getProviderAuthService, init_provider_auth_service } from "../../../providers/provider-auth-service.js";
+import { registerSpeechProvider } from "../speech-registry.js";
+//#region src/voice/tts/providers/xopc-cloud-speech.ts
+init_model_catalog_store();
+init_provider_auth_service();
+init_xopc_cloud_config();
+function availableModels() {
+	return getModelCatalogStore().getSource("xopc-cloud")?.models.filter((model) => model.availability === "available" && model.kind === "tts") ?? [];
+}
+function readConfig(config) {
+	return config;
+}
+function readSpeed(value) {
+	if (value === void 0 || value === null || value === "") return void 0;
+	if (typeof value !== "number" || !Number.isFinite(value) || value < .25 || value > 4) throw new Error("XOPC Cloud TTS speed must be between 0.25 and 4");
+	return value;
+}
+function extension(contentType, fallback) {
+	return {
+		"audio/mpeg": "mp3",
+		"audio/opus": "opus",
+		"audio/ogg": "ogg",
+		"audio/wav": "wav",
+		"audio/flac": "flac",
+		"audio/aac": "aac",
+		"audio/pcm": "pcm"
+	}[contentType?.split(";")[0] ?? ""] ?? fallback;
+}
+const xopcCloudSpeechProvider = {
+	id: "xopc-cloud",
+	autoSelectOrder: 5,
+	resolveConfig: ({ rawConfig }) => {
+		const raw = rawConfig["xopc-cloud"];
+		const slice = raw && typeof raw === "object" && !Array.isArray(raw) ? raw : {};
+		const model = typeof slice.model === "string" ? slice.model : availableModels()[0]?.id;
+		const catalogModel = availableModels().find((entry) => entry.id === model);
+		return {
+			model,
+			voice: typeof slice.voice === "string" ? slice.voice : catalogModel?.tts?.defaultVoice,
+			speed: readSpeed(slice.speed),
+			instructions: typeof slice.instructions === "string" && slice.instructions.trim() ? slice.instructions.trim() : void 0,
+			baseUrl: typeof slice.baseUrl === "string" ? slice.baseUrl : getModelCatalogStore().getSource("xopc-cloud")?.baseUrl ?? resolveXopcModelRouterUrl()
+		};
+	},
+	isConfigured: ({ providerConfig }) => {
+		const config = readConfig(providerConfig);
+		return Boolean(config.model && config.voice && availableModels().some((model) => model.id === config.model));
+	},
+	listVoices: async ({ providerConfig }) => {
+		const config = readConfig(providerConfig ?? {});
+		if (!config.model) return [];
+		const token = await getProviderAuthService().resolveApiKey("xopc-cloud");
+		if (!token) return [];
+		const response = await fetch(`${config.baseUrl.replace(/\/+$/, "")}/audio/voices?model=${encodeURIComponent(config.model)}`, {
+			headers: { authorization: `Bearer ${token}` },
+			signal: AbortSignal.timeout(3e4),
+			redirect: "error"
+		});
+		if (!response.ok) return [];
+		return ((await response.json().catch(() => null))?.data ?? []).filter((voice) => typeof voice.id === "string").map((voice) => ({
+			id: voice.id,
+			...typeof voice.name === "string" ? { name: voice.name } : {}
+		}));
+	},
+	synthesize: async (request) => {
+		const config = readConfig(request.providerConfig);
+		const model = typeof request.providerOverrides?.model === "string" ? request.providerOverrides.model : config.model;
+		const voice = typeof request.providerOverrides?.voice === "string" ? request.providerOverrides.voice : config.voice;
+		if (!model || !voice) throw new Error("XOPC Cloud TTS model or voice is unavailable");
+		const catalogModel = availableModels().find((entry) => entry.id === model);
+		if (!catalogModel) throw new Error(`XOPC Cloud TTS model is unavailable: ${model}`);
+		const speed = readSpeed(request.providerOverrides?.speed ?? config.speed);
+		const instructions = typeof request.providerOverrides?.instructions === "string" ? request.providerOverrides.instructions.trim() : config.instructions;
+		const outputFormat = request.target === "voice-note" && catalogModel.tts?.outputFormats.includes("opus") ? "opus" : catalogModel.tts?.outputFormats.includes("mp3") ? "mp3" : catalogModel.tts?.outputFormats[0] ?? "wav";
+		const token = await getProviderAuthService().resolveApiKey("xopc-cloud");
+		if (!token) throw new Error("XOPC Cloud authorization is unavailable");
+		const response = await fetch(`${config.baseUrl.replace(/\/+$/, "")}/audio/speech`, {
+			method: "POST",
+			headers: {
+				authorization: `Bearer ${token}`,
+				"content-type": "application/json"
+			},
+			body: JSON.stringify({
+				model,
+				input: request.text,
+				voice,
+				response_format: outputFormat,
+				...speed !== void 0 && catalogModel.tts?.speed ? { speed } : {},
+				...instructions && catalogModel.tts?.instructions ? { instructions } : {}
+			}),
+			signal: AbortSignal.timeout(request.timeoutMs),
+			redirect: "error"
+		});
+		if (!response.ok) {
+			const body = await response.json().catch(() => null);
+			throw new Error(typeof body?.error?.message === "string" ? body.error.message : `XOPC Cloud TTS failed (${response.status})`);
+		}
+		const audioBuffer = Buffer.from(await response.arrayBuffer());
+		if (audioBuffer.length === 0) throw new Error("XOPC Cloud TTS returned empty audio");
+		const fileExtension = extension(response.headers.get("content-type"), outputFormat);
+		return {
+			audioBuffer,
+			outputFormat: fileExtension,
+			fileExtension,
+			voiceCompatible: fileExtension === "opus" || fileExtension === "ogg"
+		};
+	}
+};
+registerSpeechProvider(xopcCloudSpeechProvider);
+//#endregion
+export { xopcCloudSpeechProvider };

package/dist/src/voice/tts/types.d.ts

@@ -57,7 +57,7 @@ export interface TTSModelOverrideConfig {
 export interface TTSConfig {
     enabled: boolean;
     provider: TTSProvider;
-    /** Trigger mode: auto = reply with voice when user sends voice */
+    /** Trigger mode for automatic voice replies. */
     trigger: TTSAutoMode;
     /** Fallback configuration */
     fallback?: {

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

@@ -76,7 +76,7 @@ function validateSuggestion(value, allowedPaths) {
 		verification: strings(item.verification, 4).map((entry) => entry.slice(0, 300))
 	};
 }
-function validateProfileCandidate(value) {
+function validateProfileCandidate(value, allowedRefs) {
 	if (!value || typeof value !== "object") return null;
 	const item = value;
 	const category = item.category === "role" || item.category === "focus" || item.category === "technology" || item.category === "workflow" || item.category === "preference" ? item.category : void 0;
@@ -84,12 +84,15 @@ function validateProfileCandidate(value) {
 	const statement = item.statement.trim().slice(0, 500);
 	if (statement.length < 4) return null;
 	const confidence = item.confidence === "high" || item.confidence === "low" ? item.confidence : "medium";
+	const evidenceRefs = allowedRefs ? strings(item.evidenceRefs, 12).filter((ref) => allowedRefs.has(ref)) : void 0;
+	if (allowedRefs && !evidenceRefs?.length) return null;
 	return {
 		id: randomUUID(),
 		category,
 		statement,
 		confidence,
 		evidence: strings(item.evidence, 4).map((entry) => entry.slice(0, 300)),
+		...evidenceRefs?.length ? { evidenceRefs } : {},
 		status: "pending"
 	};
 }
@@ -216,7 +219,7 @@ async function analyzeWorkContext(input) {
 		result: lowConfidenceResult(input.snapshot)
 	};
 	const primarySuggestion = [...suggestions].sort((a, b) => suggestionScore(b) - suggestionScore(a))[0];
-	const profileCandidates = input.candidateContext?.length && Array.isArray(parsed.profileCandidates) ? parsed.profileCandidates.map(validateProfileCandidate).filter((value) => Boolean(value)).slice(0, 6) : [];
+	const profileCandidates = input.candidateContext?.length && Array.isArray(parsed.profileCandidates) ? parsed.profileCandidates.map((value) => validateProfileCandidate(value)).filter((value) => Boolean(value)).slice(0, 6) : [];
 	const workThreadCandidates = Array.isArray(parsed.workThreads) ? parsed.workThreads.map((value) => validateWorkThreadCandidate(value, allowedThreadRefs)).filter((value) => Boolean(value)).slice(0, 3) : [];
 	const projectSummary = typeof parsed.projectSummary === "string" ? parsed.projectSummary.trim() : "";
 	const currentState = typeof parsed.currentState === "string" ? parsed.currentState.trim() : "";
@@ -254,6 +257,7 @@ async function analyzeUnderstandingSources(input) {
 			endsAt: item.endsAt,
 			ownerAttribution: item.ownerAttribution,
 			sensitivity: item.sensitivity,
+			resourceUri: item.resourceUri,
 			text
 		}];
 	});
@@ -266,7 +270,8 @@ async function analyzeUnderstandingSources(input) {
 		"Analyze bounded context from sources the user explicitly chose to connect.",
 		"Return only one JSON object with profileCandidates and workThreads.",
 		"profileCandidates contains at most 6 stable, useful work-related facts.",
-		"Each item has category (role, focus, technology, workflow, or preference), statement, confidence, and evidence.",
+		"Each item has category (role, focus, technology, workflow, or preference), statement, confidence, evidence, and evidenceRefs.",
+		"profileCandidates evidenceRefs must contain only supplied refs. Do not create a candidate without direct support.",
 		"workThreads contains at most 3 evidence-backed current, ongoing, or long-term work streams.",
 		"Each work thread has topicKey, title, summary, status, horizon, confidence, and evidenceRefs.",
 		"evidenceRefs must contain only supplied refs. Do not create a thread without direct support.",
@@ -294,7 +299,7 @@ async function analyzeUnderstandingSources(input) {
 	const raw = extractText(response.content);
 	const parsed = parseJson(raw);
 	if (!parsed) throw invalidJsonError("Understanding source analysis", response, raw);
-	const profileCandidates = Array.isArray(parsed.profileCandidates) ? parsed.profileCandidates.map(validateProfileCandidate).filter((value) => Boolean(value)).slice(0, 6) : [];
+	const profileCandidates = Array.isArray(parsed.profileCandidates) ? parsed.profileCandidates.map((value) => validateProfileCandidate(value, allowedRefs)).filter((value) => Boolean(value)).slice(0, 6) : [];
 	const allowedRefs = new Set(items.map((item) => item.ref));
 	return {
 		modelRef,

package/dist/src/work-discovery/candidate-discovery.d.ts

@@ -14,4 +14,5 @@ export interface DiscoverWorkCandidatesOptions {
     platform?: NodeJS.Platform;
     environment?: NodeJS.ProcessEnv;
 }
+export declare function resolvePersonalWorkRoots(homeDirectory: string, platform: NodeJS.Platform, environment: NodeJS.ProcessEnv): Promise<string[]>;
 export declare function discoverWorkCandidates(options?: DiscoverWorkCandidatesOptions): Promise<WorkDiscoveryCandidate[]>;

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

@@ -187,7 +187,7 @@ function resolveXdgPath(value, homeDirectory) {
 	const expanded = value.trim().replace(/^"|"$/g, "").replace(/^\$HOME(?=\/|$)|^\$\{HOME\}(?=\/|$)/, homeDirectory);
 	return isAbsolute(expanded) ? resolve(expanded) : null;
 }
-async function personalWorkRoots(homeDirectory, platform, environment) {
+async function resolvePersonalWorkRoots(homeDirectory, platform, environment) {
 	const roots = PERSONAL_WORK_ROOT_NAMES.map((name) => join(homeDirectory, name));
 	if (platform === "win32") for (const oneDrive of [
 		environment.OneDrive,
@@ -253,7 +253,7 @@ async function discoverWorkCandidates(options = {}) {
 		rootPath: source.rootPath,
 		source: "approved_directory"
 	}));
-	const [commonInputs, personalInputs] = await Promise.all([commonRootInputs(homeDirectory, options.signal), personalWorkRoots(homeDirectory, options.platform ?? process.platform, options.environment ?? process.env).then((roots) => personalRootInputs(roots, nowMs, options.signal))]);
+	const [commonInputs, personalInputs] = await Promise.all([commonRootInputs(homeDirectory, options.signal), resolvePersonalWorkRoots(homeDirectory, options.platform ?? process.platform, options.environment ?? process.env).then((roots) => personalRootInputs(roots, nowMs, options.signal))]);
 	const uniqueInputs = /* @__PURE__ */ new Map();
 	for (const input of [
 		...existingInputs,
@@ -276,4 +276,4 @@ async function discoverWorkCandidates(options = {}) {
 	return [...canonicalCandidates.values()].sort((a, b) => b.score - a.score || (b.lastActiveAt ?? 0) - (a.lastActiveAt ?? 0) || a.rootPath.localeCompare(b.rootPath)).slice(0, 8);
 }
 //#endregion
-export { discoverWorkCandidates };
+export { discoverWorkCandidates, resolvePersonalWorkRoots };

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

@@ -1,6 +1,6 @@
 import { WORK_DISCOVERY_SCAN_POLICY_VERSION, canonicalWorkDiscoveryRoot, previewWorkDiscoveryRoot, probeWorkDiscoveryRoot, readWorkDiscoveryTextExcerpt, searchWorkDiscoveryText, summarizeWorkContextSnapshot } from "./probe.js";
 import { analyzeUnderstandingSources, analyzeWorkContext, workDiscoveryResultMarkdown } from "./analyzer.js";
-import { discoverWorkCandidates } from "./candidate-discovery.js";
+import { discoverWorkCandidates, resolvePersonalWorkRoots } from "./candidate-discovery.js";
 import { workDiscoveryFingerprintsEqual } from "./incremental.js";
 import { createWorkDiscoveryRun, getWorkDiscoveryOnboardingState, getWorkDiscoveryRun, getWorkDiscoveryRunByIdempotencyKey, setWorkDiscoveryFeedback, setWorkDiscoveryOnboardingState, updateWorkDiscoveryRun } from "./repository.js";
 import { findActiveWorkDiscoverySourceRefresh, listWorkDiscoverySourceRefreshes, recordWorkDiscoverySourceRefresh, updateWorkDiscoverySourceRefreshForRun } from "./incremental-repository.js";
@@ -10,4 +10,4 @@ import { persistWorkThreadsFromDiscovery } from "./thread-service.js";
 import { getWorkDiscoveryDirectorySource, listWorkDiscoveryDirectorySources, revokeWorkDiscoveryDirectorySource, upsertWorkDiscoveryDirectorySource } from "./source-repository.js";
 import { WorkDiscoveryService } from "./service.js";
 import { evaluateWorkUnderstandingCase } from "./evaluation.js";
-export { DEFAULT_WORK_INVESTIGATION_BUDGET, WORK_DISCOVERY_SCAN_POLICY_VERSION, WorkDiscoveryService, analyzeUnderstandingSources, analyzeWorkContext, appendWorkUnderstandingEvidence, canonicalWorkDiscoveryRoot, createWorkDiscoveryRun, createWorkUnderstandingInvestigation, discoverWorkCandidates, evaluateWorkUnderstandingCase, findActiveWorkDiscoverySourceRefresh, getWorkDiscoveryDirectorySource, getWorkDiscoveryOnboardingState, getWorkDiscoveryRun, getWorkDiscoveryRunByIdempotencyKey, getWorkUnderstandingInvestigation, getWorkUnderstandingInvestigationForRun, investigateWorkContext, listWorkDiscoveryDirectorySources, listWorkDiscoverySourceRefreshes, listWorkUnderstandingEvidence, persistWorkThreadsFromDiscovery, previewWorkDiscoveryRoot, probeWorkDiscoveryRoot, readWorkDiscoveryTextExcerpt, recordWorkDiscoverySourceRefresh, resetWorkUnderstandingInvestigation, revokeWorkDiscoveryDirectorySource, searchWorkDiscoveryText, setWorkDiscoveryFeedback, setWorkDiscoveryOnboardingState, summarizeWorkContextSnapshot, updateWorkDiscoveryRun, updateWorkDiscoverySourceRefreshForRun, updateWorkUnderstandingEvidenceObservation, updateWorkUnderstandingInvestigation, upsertWorkDiscoveryDirectorySource, workDiscoveryFingerprintsEqual, workDiscoveryResultMarkdown };
+export { DEFAULT_WORK_INVESTIGATION_BUDGET, WORK_DISCOVERY_SCAN_POLICY_VERSION, WorkDiscoveryService, analyzeUnderstandingSources, analyzeWorkContext, appendWorkUnderstandingEvidence, canonicalWorkDiscoveryRoot, createWorkDiscoveryRun, createWorkUnderstandingInvestigation, discoverWorkCandidates, evaluateWorkUnderstandingCase, findActiveWorkDiscoverySourceRefresh, getWorkDiscoveryDirectorySource, getWorkDiscoveryOnboardingState, getWorkDiscoveryRun, getWorkDiscoveryRunByIdempotencyKey, getWorkUnderstandingInvestigation, getWorkUnderstandingInvestigationForRun, investigateWorkContext, listWorkDiscoveryDirectorySources, listWorkDiscoverySourceRefreshes, listWorkUnderstandingEvidence, persistWorkThreadsFromDiscovery, previewWorkDiscoveryRoot, probeWorkDiscoveryRoot, readWorkDiscoveryTextExcerpt, recordWorkDiscoverySourceRefresh, resetWorkUnderstandingInvestigation, resolvePersonalWorkRoots, revokeWorkDiscoveryDirectorySource, searchWorkDiscoveryText, setWorkDiscoveryFeedback, setWorkDiscoveryOnboardingState, summarizeWorkContextSnapshot, updateWorkDiscoveryRun, updateWorkDiscoverySourceRefreshForRun, updateWorkUnderstandingEvidenceObservation, updateWorkUnderstandingInvestigation, upsertWorkDiscoveryDirectorySource, workDiscoveryFingerprintsEqual, workDiscoveryResultMarkdown };

package/dist/src/work-discovery/service.d.ts

@@ -46,7 +46,7 @@ export declare class WorkDiscoveryService {
         reused?: undefined;
     }>;
     revokeDirectorySource(id: string): import("./types.js").WorkDiscoveryDirectorySource;
-    importUnderstandingSources(rawItems: unknown[], signal?: AbortSignal, runId?: string): Promise<{
+    importUnderstandingSources(rawItems: unknown[], signal?: AbortSignal, runId?: string, rawCheckpoints?: Record<string, unknown>): Promise<{
         profileCandidates: {
             status: "rejected" | "pending";
             understandingId: string;
@@ -55,6 +55,7 @@ export declare class WorkDiscoveryService {
             statement: string;
             confidence: "high" | "medium" | "low";
             evidence: string[];
+            evidenceRefs?: string[];
         }[];
         workThreads: import("./types.js").WorkUnderstandingThread[];
         focuses: import("../user-context/sources/types.js").UserFocus[];