@xopcai/xopc 0.0.210 → 0.0.211

package/dist/src/voice/local/runtime-worker.js

@@ -1,6 +1,5 @@
 import { getLocalVoiceModel, resolveLocalVoiceModelDir } from "./models.js";
 import { downloadLocalVoiceModelFiles } from "./model-files.js";
-import { createRuntimeDispatcher } from "./runtime-dispatcher.js";
 import { join, resolve, sep } from "node:path";
 import { mkdir, rm } from "node:fs/promises";
 import { EnvHttpProxyAgent, RetryAgent, setGlobalDispatcher } from "undici";
@@ -230,17 +229,6 @@ async function handle(request) {
 	throw new Error(`Unknown local voice runtime method: ${request.method}`);
 }
 const lines = createInterface({ input: process.stdin });
-const dispatch = createRuntimeDispatcher({
-	execute: handle,
-	sendResult: (request, result) => send({
-		id: request.id,
-		result
-	}),
-	sendError: (request, error) => send({
-		id: request.id,
-		error: serializeError(error)
-	})
-});
 lines.on("line", (line) => {
 	let request;
 	try {
@@ -248,7 +236,13 @@ lines.on("line", (line) => {
 	} catch {
 		return;
 	}
-	dispatch(request);
+	handle(request).then((result) => send({
+		id: request.id,
+		result
+	}), (error) => send({
+		id: request.id,
+		error: serializeError(error)
+	}));
 });
 lines.once("close", () => {
 	networkAgent.close().finally(() => process.exit(0));

package/dist/src/voice/local/wav.js

@@ -17,7 +17,7 @@ function resampleLinear(input, sourceRate, targetRate) {
 	return output;
 }
 function decodeWavToMonoFloat32(buffer, targetRate = 16e3) {
-	if (buffer.length < 44 || readChunkId(buffer, 0) !== "RIFF" || readChunkId(buffer, 8) !== "WAVE") throw new Error("Local STT currently requires PCM WAV audio");
+	if (buffer.length < 44 || readChunkId(buffer, 0) !== "RIFF" || readChunkId(buffer, 8) !== "WAVE") throw new Error("Unsupported or corrupt WAV audio");
 	let offset = 12;
 	let format;
 	let dataOffset = -1;

package/dist/src/voice/stt/availability.d.ts

@@ -1,8 +1,5 @@
 import type { STTConfig } from './types.js';
 /**
- * Lightweight availability check for channel routing. Do not import the STT
- * factory/provider registry here; channel plugins call this at startup and the
- * provider registry pulls optional SDKs (e.g. openai) into Electron's dynamic
- * extension runtime path.
+ * Runtime-truth availability check shared by channels and the gateway.
  */
 export declare function isSTTAvailable(config?: STTConfig): boolean;

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

@@ -1,23 +1,11 @@
-import { getVoiceProviderMetadata } from "../metadata/registry.js";
-import "../metadata/index.js";
+import { resolveSTTProviderChain } from "./factory.js";
 //#region src/voice/stt/availability.ts
-function providerHasConfig(config, providerId) {
-	const provider = config.providers?.[providerId];
-	if (provider && Object.keys(provider).length > 0) return true;
-	if ([...config.models ?? [], ...config.sharedModels ?? []].some((entry) => entry.provider === providerId && entry.capabilities?.includes("audio"))) return true;
-	return getVoiceProviderMetadata("stt", providerId)?.diagnostics.requiresApiKey === false;
-}
 /**
-* Lightweight availability check for channel routing. Do not import the STT
-* factory/provider registry here; channel plugins call this at startup and the
-* provider registry pulls optional SDKs (e.g. openai) into Electron's dynamic
-* extension runtime path.
+* Runtime-truth availability check shared by channels and the gateway.
 */
 function isSTTAvailable(config) {
 	if (!config?.enabled) return false;
-	if (providerHasConfig(config, config.provider)) return true;
-	if (config.fallback?.enabled) return config.fallback.order.some((providerId) => providerHasConfig(config, providerId));
-	return false;
+	return resolveSTTProviderChain(config).length > 0;
 }
 //#endregion
 export { isSTTAvailable };

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

@@ -14,6 +14,7 @@ function mergeSttConfigFromAppConfig(stt, toolsMedia) {
 	return {
 		...DEFAULT_STT_CONFIG,
 		...patch,
+		managedAuto: stt === void 0,
 		providers: mergeSttProviders(DEFAULT_STT_CONFIG.providers, patch.providers),
 		fallback: {
 			...DEFAULT_STT_CONFIG.fallback,

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

@@ -1,11 +1,14 @@
 import { createLogger } from "../../utils/logger/index.js";
 import { init_logger } from "../../utils/logger.js";
+import { getModelCatalogStore, init_model_catalog_store } from "../../providers/model-catalog-store.js";
+import { compareCatalogModels } from "../../providers/model-catalog-ranking.js";
 import { getMediaUnderstandingProvider, listMediaUnderstandingProviders } from "../../media-understanding/registry.js";
 import "./providers/index.js";
 import { resolveModelEntries } from "../../media-understanding/resolve-entries.js";
 import { readSttProviderFields, resolveSttProviderConfigSlice } from "./config-slice.js";
 //#region src/voice/stt/factory.ts
 init_logger();
+init_model_catalog_store();
 const log = createLogger("STT:Factory");
 function resolveApiKey(providerId, fields, envKey) {
 	return fields.apiKey ?? (envKey ? process.env[envKey] : void 0);
@@ -54,6 +57,7 @@ function resolveSTTProviderOrder(primary, fallback, config) {
 		for (const providerId of fallback.order) if (providerId !== primary && !order.includes(providerId)) order.push(providerId);
 		return order;
 	}
+	if (!config.managedAuto) return [primary];
 	const configured = sortAudioProvidersByAutoPriority(listMediaUnderstandingProviders()).filter((providerId) => resolveSTTProviderConfig(providerId, config) !== null);
 	const order = [primary];
 	for (const providerId of configured) if (providerId !== primary && !order.includes(providerId)) order.push(providerId);
@@ -72,8 +76,23 @@ function resolveModelEntryChain(config) {
 		const resolved = resolveSTTProviderConfig(providerId, config, entry);
 		if (resolved) chain.push(resolved);
 	}
+	if (chain.some((entry) => entry.id === "xopc-cloud")) appendManagedCloudModels(chain, config);
 	return chain;
 }
+function appendManagedCloudModels(chain, config) {
+	const seen = new Set(chain.filter((entry) => entry.id === "xopc-cloud" && entry.model).map((entry) => entry.model));
+	const source = getModelCatalogStore().getSource("xopc-cloud");
+	const models = [...source?.models ?? []].sort((left, right) => compareCatalogModels(left, right, source?.recommended?.stt));
+	for (const model of models) {
+		if (model.availability !== "available" || model.kind !== "stt" || !model.operations.includes("audio.transcription") || seen.has(model.id)) continue;
+		const resolved = resolveSTTProviderConfig("xopc-cloud", config, {
+			provider: "xopc-cloud",
+			model: model.id,
+			capabilities: ["audio"]
+		});
+		if (resolved) chain.push(resolved);
+	}
+}
 /** Build the full chain of resolved provider configs in priority order. */
 function resolveSTTProviderChain(config) {
 	if (!config.enabled) return [];
@@ -82,6 +101,10 @@ function resolveSTTProviderChain(config) {
 	const order = resolveSTTProviderOrder(config.provider, config.fallback, config);
 	const chain = [];
 	for (const providerId of order) {
+		if (providerId === "xopc-cloud") {
+			appendManagedCloudModels(chain, config);
+			continue;
+		}
 		const resolved = resolveSTTProviderConfig(providerId, config);
 		if (resolved) chain.push(resolved);
 	}

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

@@ -7,6 +7,7 @@
 import './providers/index.js';
 import type { STTConfig, STTOptions, STTResult } from './types.js';
 export { transcribe } from './transcribe-core.js';
+export { STTTranscriptionError } from './transcribe-core.js';
 export { isSTTAvailable } from './availability.js';
 export { mergeSttConfigFromAppConfig } from './config.js';
 /**

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

@@ -2,7 +2,7 @@ import { openAiTranscriptionProvider } from "./providers/openai-transcription.js
 import { alibabaTranscriptionProvider } from "./providers/alibaba-transcription.js";
 import "./providers/index.js";
 import { resolveSTTProviderChain, resolveSTTProviderConfig, resolveSTTProviderOrder } from "./factory.js";
-import { transcribe } from "./transcribe-core.js";
+import { STTTranscriptionError, transcribe } from "./transcribe-core.js";
 import { isSTTAvailable } from "./availability.js";
 import { mergeSttConfigFromAppConfig } from "./config.js";
 import { checkMentionInTranscription } from "./mention.js";
@@ -29,4 +29,4 @@ async function transcribeWithProvider(audioBuffer, providerName, config, options
 	};
 }
 //#endregion
-export { alibabaTranscriptionProvider, audioPreflightTranscribe, checkMentionInTranscription, isSTTAvailable, mergeSttConfigFromAppConfig, openAiTranscriptionProvider, resolveSTTProviderChain, resolveSTTProviderConfig, resolveSTTProviderOrder, transcribe, transcribeWithProvider };
+export { STTTranscriptionError, alibabaTranscriptionProvider, audioPreflightTranscribe, checkMentionInTranscription, isSTTAvailable, mergeSttConfigFromAppConfig, openAiTranscriptionProvider, resolveSTTProviderChain, resolveSTTProviderConfig, resolveSTTProviderOrder, transcribe, transcribeWithProvider };

package/dist/src/voice/stt/list-providers.js

@@ -1,8 +1,8 @@
 import { listMediaUnderstandingProviders } from "../../media-understanding/registry.js";
 import { resolveSTTProviderConfig } from "./factory.js";
+import { mergeSttConfigFromAppConfig } from "./config.js";
 import { getVoiceProviderMetadata } from "../metadata/registry.js";
 import "../metadata/index.js";
-import { mergeSttConfigFromAppConfig } from "./config.js";
 //#region src/voice/stt/list-providers.ts
 function fallbackMetadata(providerId, aliases) {
 	return {

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

@@ -1,16 +1,19 @@
 import { createLogger } from "../../../utils/logger/index.js";
 import { init_logger } from "../../../utils/logger.js";
-import { registerMediaUnderstandingProvider } from "../../../media-understanding/registry.js";
 import { DEFAULT_LOCAL_VOICE_MODEL_ID, getLocalVoiceModel, hasInstalledLocalVoiceModel, isLocalVoiceModelInstalled } from "../../local/models.js";
+import { registerMediaUnderstandingProvider } from "../../../media-understanding/registry.js";
 import { getLocalVoiceRuntimeClient } from "../../local/runtime-client.js";
-import { decodeWavToMonoFloat32 } from "../../local/wav.js";
+import { decodeAudioToMonoFloat32 } from "../../audio/normalize.js";
 //#region src/voice/stt/providers/local-transcription.ts
 init_logger();
 const log = createLogger("STT:Local");
 async function transcribeAudio(req) {
 	const model = getLocalVoiceModel(req.model);
 	if (!isLocalVoiceModelInstalled(model.id)) throw new Error(`Local voice model "${model.id}" is not installed`);
-	const decoded = decodeWavToMonoFloat32(req.buffer);
+	const decoded = await decodeAudioToMonoFloat32({
+		buffer: req.buffer,
+		signal: req.signal
+	});
 	const audioBytes = Buffer.from(decoded.samples.buffer, decoded.samples.byteOffset, decoded.samples.byteLength);
 	const startedAt = Date.now();
 	const result = await getLocalVoiceRuntimeClient().request("transcribe", {
@@ -25,6 +28,7 @@ async function transcribeAudio(req) {
 		model: model.id,
 		audioDurationSeconds: decoded.durationSeconds,
 		latencyMs: Date.now() - startedAt,
+		realTimeFactor: decoded.durationSeconds > 0 ? (Date.now() - startedAt) / 1e3 / decoded.durationSeconds : void 0,
 		textLength: result.text.length
 	}, "Local transcription completed");
 	return {

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

@@ -1,13 +1,15 @@
 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 { compareCatalogModels } from "../../../providers/model-catalog-ranking.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 source = getModelCatalogStore().getSource("xopc-cloud");
+	return source?.models.filter((model) => model.availability === "available" && model.kind === "stt").sort((left, right) => compareCatalogModels(left, right, source.recommended?.stt))[0]?.id;
 }
 const xopcCloudTranscriptionProvider = {
 	id: "xopc-cloud",

package/dist/src/voice/stt/transcribe-core.d.ts

@@ -11,5 +11,9 @@
  * wrap the input as a single CapabilityAttachmentInput and unpack the first
  * output. Multi-attachment cases go through `runAudioTranscription` directly.
  */
-import type { STTConfig, STTOptions, STTResultWithTracking } from './types.js';
+import type { STTConfig, STTOptions, STTProviderFailureReason, STTResultWithTracking } from './types.js';
+export declare class STTTranscriptionError extends Error {
+    readonly reasonCode: STTProviderFailureReason;
+    constructor(message: string, reasonCode: STTProviderFailureReason);
+}
 export declare function transcribe(audioBuffer: Buffer, config: STTConfig, options?: STTOptions): Promise<STTResultWithTracking>;

package/dist/src/voice/stt/transcribe-core.js

@@ -10,9 +10,16 @@ function classifyFailureReason(reason) {
 	const lower = reason.toLowerCase();
 	if (lower.includes("not configured") || lower.includes("api key") || lower.includes("missing")) return "not_configured";
 	if (lower.includes("timeout") || lower.includes("timed out") || lower.includes("aborted")) return "timeout";
-	if (lower.includes("unsupported") || lower.includes("format")) return "unsupported_format";
+	if (lower.includes("unsupported") || lower.includes("format") || lower.includes("audio decoder")) return "unsupported_format";
 	return "provider_error";
 }
+var STTTranscriptionError = class extends Error {
+	constructor(message, reasonCode) {
+		super(message);
+		this.reasonCode = reasonCode;
+		this.name = "STTTranscriptionError";
+	}
+};
 function toAttempt(attempt) {
 	return {
 		provider: attempt.provider ?? "unknown",
@@ -49,8 +56,8 @@ async function transcribe(audioBuffer, config, options) {
 			attempts,
 			attemptedProviders
 		}, "All STT providers failed");
-		const lastError = attempts.find((a) => a.task === "failed")?.error;
-		throw new Error(lastError ?? "All STT providers failed");
+		const lastFailure = attempts.findLast((attempt) => attempt.task === "failed");
+		throw new STTTranscriptionError(lastFailure?.error ?? "All STT providers failed", lastFailure?.reasonCode ?? "unknown");
 	}
 	const chosen = attachmentDecision.chosen;
 	const output = result.outputs[0];
@@ -60,11 +67,12 @@ async function transcribe(audioBuffer, config, options) {
 	return {
 		text: output.text,
 		provider: chosen.provider ?? "unknown",
-		...chosen.model ? { language: options?.language } : {},
+		...output.durationSeconds !== void 0 ? { duration: output.durationSeconds } : {},
+		...output.language || options?.language ? { language: output.language ?? options?.language } : {},
 		attempts,
 		...fallbackFrom ? { fallbackFrom } : {},
 		attemptedProviders
 	};
 }
 //#endregion
-export { transcribe };
+export { STTTranscriptionError, transcribe };

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

@@ -31,6 +31,8 @@ import type { MediaUnderstandingModelEntry } from '../../media-understanding/typ
 export interface STTConfig {
     enabled: boolean;
     provider: string;
+    /** Runtime-only flag: absent app config enables managed provider selection. */
+    managedAuto?: boolean;
     /** Capability-local model chain (`tools.media.audio.models`). */
     models?: MediaUnderstandingModelEntry[];
     /** Shared model entries merged from `tools.media.models` at runtime. */

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

@@ -23,7 +23,7 @@ export interface ResolvedSpeechProvider {
     timeoutMs: number;
 }
 /** Resolve a single provider id → plugin + per-call config, or null if unavailable. */
-export declare function resolveSpeechProvider(providerId: TTSProvider, config: TTSConfig): ResolvedSpeechProvider | null;
+export declare function resolveSpeechProvider(providerId: TTSProvider, config: TTSConfig, providerOverride?: Record<string, unknown>): ResolvedSpeechProvider | null;
 /** Order providers: explicit fallback when enabled, otherwise auto-select by registry order. */
 export declare function resolveProviderOrder(primary: TTSProvider, fallback: TTSConfig['fallback'] | undefined, config: TTSConfig): TTSProvider[];
 /** Resolve the full provider chain in priority order; only configured plugins included. */

package/dist/src/voice/tts/factory.js

@@ -1,19 +1,26 @@
 import { createLogger } from "../../utils/logger/index.js";
 import { init_logger } from "../../utils/logger.js";
+import { getModelCatalogStore, init_model_catalog_store } from "../../providers/model-catalog-store.js";
+import { compareCatalogModels } from "../../providers/model-catalog-ranking.js";
 import { getSpeechProvider, listSpeechProviders } from "./speech-registry.js";
 import "./providers/index.js";
 import { buildTtsResolveRawConfig } from "./config-slice.js";
 //#region src/voice/tts/factory.ts
 init_logger();
+init_model_catalog_store();
 const log = createLogger("TTS:Factory");
 /** Resolve a single provider id → plugin + per-call config, or null if unavailable. */
-function resolveSpeechProvider(providerId, config) {
+function resolveSpeechProvider(providerId, config, providerOverride) {
 	const plugin = getSpeechProvider(providerId);
 	if (!plugin) {
 		log.warn({ providerId }, `Unknown TTS provider "${providerId}" (not registered)`);
 		return null;
 	}
 	const rawConfig = buildTtsResolveRawConfig(providerId, config);
+	if (providerOverride) rawConfig[providerId] = {
+		...rawConfig[providerId] ?? {},
+		...providerOverride
+	};
 	const timeoutMs = config.timeoutMs ?? 3e4;
 	const providerConfig = plugin.resolveConfig({
 		cfg: void 0,
@@ -41,6 +48,7 @@ function resolveProviderOrder(primary, fallback, config) {
 		for (const provider of fallback.order) if (provider !== primary && !order.includes(provider)) order.push(provider);
 		return order;
 	}
+	if (!config.managedAuto) return [primary];
 	const configured = listSpeechProviders().map((plugin) => {
 		return resolveSpeechProvider(plugin.id, config) ? plugin : null;
 	}).filter((plugin) => plugin !== null).sort((left, right) => {
@@ -59,6 +67,20 @@ function resolveSpeechProviderChain(config) {
 	const order = resolveProviderOrder(config.provider, config.fallback, config);
 	const chain = [];
 	for (const providerId of order) {
+		if (providerId === "xopc-cloud") {
+			const configuredModel = typeof config.providers?.["xopc-cloud"]?.model === "string" ? config.providers["xopc-cloud"].model : void 0;
+			const source = getModelCatalogStore().getSource("xopc-cloud");
+			const models = source?.models.filter((model) => model.availability === "available" && model.kind === "tts" && model.operations.includes("audio.speech") && Boolean(model.tts?.defaultVoice)).sort((left, right) => {
+				if (left.id === configuredModel) return -1;
+				if (right.id === configuredModel) return 1;
+				return compareCatalogModels(left, right, source.recommended?.tts);
+			}) ?? [];
+			for (const model of models) {
+				const resolved = resolveSpeechProvider(providerId, config, { model: model.id });
+				if (resolved) chain.push(resolved);
+			}
+			continue;
+		}
 		const resolved = resolveSpeechProvider(providerId, config);
 		if (resolved) chain.push(resolved);
 	}

package/dist/src/voice/tts/merge-config.js

@@ -24,15 +24,17 @@ function mergeProviderEntries(base, patch) {
 }
 function mergeTtsConfigFromAppConfig(tts) {
 	const p = tts ?? {};
+	const managedAuto = tts === void 0;
 	return {
 		...DEFAULT_TTS_CONFIG,
 		...p,
+		managedAuto,
 		enabled: p.enabled ?? DEFAULT_TTS_CONFIG.enabled,
 		provider: normalizeTtsProvider(p.provider),
 		trigger: normalizeTtsTrigger(p.trigger ?? DEFAULT_TTS_CONFIG.trigger),
-		fallback: {
-			...DEFAULT_TTS_CONFIG.fallback,
-			...p.fallback
+		fallback: managedAuto ? { ...DEFAULT_TTS_CONFIG.fallback } : p.fallback ? { ...p.fallback } : {
+			enabled: false,
+			order: []
 		},
 		modelOverrides: {
 			...DEFAULT_TTS_CONFIG.modelOverrides,

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

@@ -1,13 +1,15 @@
 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 { compareCatalogModels } from "../../../providers/model-catalog-ranking.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") ?? [];
+	const source = getModelCatalogStore().getSource("xopc-cloud");
+	return source?.models.filter((model) => model.availability === "available" && model.kind === "tts").sort((left, right) => compareCatalogModels(left, right, source.recommended?.tts)) ?? [];
 }
 function readConfig(config) {
 	return config;

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

@@ -57,6 +57,8 @@ export interface TTSModelOverrideConfig {
 export interface TTSConfig {
     enabled: boolean;
     provider: TTSProvider;
+    /** Runtime-only flag: absent app config enables managed provider selection. */
+    managedAuto?: boolean;
     /** Trigger mode for automatic voice replies. */
     trigger: TTSAutoMode;
     /** Fallback configuration */

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

@@ -1,11 +1,12 @@
 //#region src/voice/tts/types.ts
 const DEFAULT_TTS_CONFIG = {
 	enabled: true,
-	provider: "edge",
-	trigger: "inbound",
+	provider: "xopc-cloud",
+	trigger: "off",
 	fallback: {
 		enabled: true,
 		order: [
+			"xopc-cloud",
 			"openai",
 			"alibaba",
 			"minimax",
@@ -26,6 +27,7 @@ const DEFAULT_TTS_CONFIG = {
 		allowSeed: false
 	},
 	providers: {
+		"xopc-cloud": {},
 		alibaba: {
 			model: "qwen-tts",
 			voice: "Cherry"

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

@@ -9,3 +9,26 @@ export declare function evaluateWorkUnderstandingCase(input: WorkUnderstandingEv
     evidenceCoverage: number;
     f1: number;
 };
+export interface QuickUnderstandingEvaluationCase extends WorkUnderstandingEvaluationCase {
+    expectedSourceIds: string[];
+    observedSourceIds: string[];
+    startedAtMs: number;
+    firstCandidateAtMs?: number;
+    timeBudgetMs: number;
+}
+export type QuickUnderstandingGate = {
+    minPrecision: number;
+    minRecall: number;
+    minEvidenceCoverage: number;
+    minSourceCoverage: number;
+};
+export declare function evaluateQuickUnderstandingCase(input: QuickUnderstandingEvaluationCase): {
+    sourceCoverage: number;
+    timeToFirstCandidateMs: number;
+    withinTimeBudget: boolean;
+    precision: number;
+    recall: number;
+    evidenceCoverage: number;
+    f1: number;
+};
+export declare function meetsQuickUnderstandingGate(metrics: ReturnType<typeof evaluateQuickUnderstandingCase>, gate: QuickUnderstandingGate): boolean;

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

@@ -13,5 +13,22 @@ function evaluateWorkUnderstandingCase(input) {
 		f1: precision + recall ? 2 * precision * recall / (precision + recall) : 0
 	};
 }
+function evaluateQuickUnderstandingCase(input) {
+	const topic = evaluateWorkUnderstandingCase(input);
+	const expectedSources = new Set(input.expectedSourceIds);
+	const observedSources = new Set(input.observedSourceIds);
+	const coveredSources = [...expectedSources].filter((sourceId) => observedSources.has(sourceId)).length;
+	const sourceCoverage = expectedSources.size ? coveredSources / expectedSources.size : 1;
+	const timeToFirstCandidateMs = input.firstCandidateAtMs === void 0 ? null : Math.max(0, input.firstCandidateAtMs - input.startedAtMs);
+	return {
+		...topic,
+		sourceCoverage,
+		timeToFirstCandidateMs,
+		withinTimeBudget: timeToFirstCandidateMs !== null && timeToFirstCandidateMs <= input.timeBudgetMs
+	};
+}
+function meetsQuickUnderstandingGate(metrics, gate) {
+	return metrics.precision >= gate.minPrecision && metrics.recall >= gate.minRecall && metrics.evidenceCoverage >= gate.minEvidenceCoverage && metrics.sourceCoverage >= gate.minSourceCoverage && metrics.withinTimeBudget;
+}
 //#endregion
-export { evaluateWorkUnderstandingCase };
+export { evaluateQuickUnderstandingCase, evaluateWorkUnderstandingCase, meetsQuickUnderstandingGate };

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

@@ -9,5 +9,5 @@ import { DEFAULT_WORK_INVESTIGATION_BUDGET, investigateWorkContext } from "./inv
 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, resolvePersonalWorkRoots, revokeWorkDiscoveryDirectorySource, searchWorkDiscoveryText, setWorkDiscoveryFeedback, setWorkDiscoveryOnboardingState, summarizeWorkContextSnapshot, updateWorkDiscoveryRun, updateWorkDiscoverySourceRefreshForRun, updateWorkUnderstandingEvidenceObservation, updateWorkUnderstandingInvestigation, upsertWorkDiscoveryDirectorySource, workDiscoveryFingerprintsEqual, workDiscoveryResultMarkdown };
+import { evaluateQuickUnderstandingCase, evaluateWorkUnderstandingCase, meetsQuickUnderstandingGate } from "./evaluation.js";
+export { DEFAULT_WORK_INVESTIGATION_BUDGET, WORK_DISCOVERY_SCAN_POLICY_VERSION, WorkDiscoveryService, analyzeUnderstandingSources, analyzeWorkContext, appendWorkUnderstandingEvidence, canonicalWorkDiscoveryRoot, createWorkDiscoveryRun, createWorkUnderstandingInvestigation, discoverWorkCandidates, evaluateQuickUnderstandingCase, evaluateWorkUnderstandingCase, findActiveWorkDiscoverySourceRefresh, getWorkDiscoveryDirectorySource, getWorkDiscoveryOnboardingState, getWorkDiscoveryRun, getWorkDiscoveryRunByIdempotencyKey, getWorkUnderstandingInvestigation, getWorkUnderstandingInvestigationForRun, investigateWorkContext, listWorkDiscoveryDirectorySources, listWorkDiscoverySourceRefreshes, listWorkUnderstandingEvidence, meetsQuickUnderstandingGate, persistWorkThreadsFromDiscovery, previewWorkDiscoveryRoot, probeWorkDiscoveryRoot, readWorkDiscoveryTextExcerpt, recordWorkDiscoverySourceRefresh, resetWorkUnderstandingInvestigation, resolvePersonalWorkRoots, revokeWorkDiscoveryDirectorySource, searchWorkDiscoveryText, setWorkDiscoveryFeedback, setWorkDiscoveryOnboardingState, summarizeWorkContextSnapshot, updateWorkDiscoveryRun, updateWorkDiscoverySourceRefreshForRun, updateWorkUnderstandingEvidenceObservation, updateWorkUnderstandingInvestigation, upsertWorkDiscoveryDirectorySource, workDiscoveryFingerprintsEqual, workDiscoveryResultMarkdown };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xopcai/xopc",
-  "version": "0.0.210",
+  "version": "0.0.211",
   "description": "Local-first AI system that remembers context, coordinates AI, and sustains long-term progress.",
   "type": "module",
   "main": "dist/src/index.js",
@@ -165,8 +165,8 @@
     "vue": "^3.5.35",
     "@xopcai/endpoint-tools-protocol": "0.0.0",
     "@xopcai/gateway-contract": "0.0.0",
-    "@xopcai/realtime-client": "0.0.0",
-    "@xopcai/realtime-protocol": "0.0.0"
+    "@xopcai/realtime-protocol": "0.0.0",
+    "@xopcai/realtime-client": "0.0.0"
   },
   "scripts": {
     "assets:brand": "node scripts/generate-brand-assets.mjs",
@@ -198,6 +198,7 @@
     "dev:gateway": "sh -c 'mkdir -p \"$HOME/.xopc-dev\" && XOPC_STATE_DIR=\"$HOME/.xopc-dev\" XOPC_CONFIG_PATH=\"$HOME/.xopc-dev/xopc.json\" XOPC_CONFIG=\"$HOME/.xopc-dev/xopc.json\" XOPC_LOG_DIR=\"$HOME/.xopc-dev/logs\" XOPC_LOG_LEVEL=info tsx src/cli/bin.ts gateway \"$@\"' --",
     "start": "node dist/src/cli/bin.js",
     "test": "vitest run src extensions/telegram/src extensions/feishu/src extensions/weixin/src",
+    "test:quick-understanding": "XOPC_LOG_LEVEL=fatal vitest run src/work-discovery/__tests__/evaluation.test.ts src/user-context/sources/__tests__/activity-clustering.test.ts src/knowledge/__tests__/quick-understanding.e2e.test.ts src/connectors/__tests__/content-enrichment.test.ts src/connectors/__tests__/connected-source-ingestion.test.ts",
     "test:skills": "vitest run src/agent/skills/__tests__",
     "test:skills:regression": "./scripts/test-skills.sh",
     "test:skills:all": "npm run test:skills && npm run test:skills:regression",