@xopcai/xopc 0.0.208 → 0.0.211

package/dist/src/user-context/retriever.js

@@ -0,0 +1,65 @@
+import { summarizeUnderstandingFeedback } from "../storage/sqlite/user-context-quality-repository.js";
+import { listUnderstandings, searchActiveUnderstandings } from "../storage/sqlite/user-context-repository.js";
+import { normalizeRetrievalText, retrievalLexicalSimilarity } from "../retrieval/textFeatures.js";
+import { buildRetrievalQueryProfile } from "../retrieval/queryProfile.js";
+import "../storage/sqlite/index.js";
+import { matchesUserContextScope } from "./scope.js";
+//#region src/user-context/retriever.ts
+function authorityBonus(item) {
+	if (item.explicitness === "explicit") return .1;
+	if (item.explicitness === "observed") return .05;
+	return 0;
+}
+function baseline(item) {
+	if (item.kind === "boundary" && item.explicitness === "explicit") return .8;
+	if (item.kind === "preference" && item.explicitness === "explicit") return .35;
+	return 0;
+}
+function feedbackAdjustment(summary) {
+	if (!summary || summary.total < 3) return 0;
+	const helpfulRate = (summary.helpful + 1) / (summary.total + 2);
+	const relevancePenalty = summary.irrelevant >= 3 ? .05 : 0;
+	return Math.max(-.1, Math.min(.05, (helpfulRate - .5) * .1 - relevancePenalty));
+}
+var UserUnderstandingRetriever = class {
+	retrieve(params) {
+		const profile = buildRetrievalQueryProfile(params.query, {
+			sessionKey: params.sessionKey,
+			workspaceId: params.workspaceId,
+			...params.projectId ? { projectId: params.projectId } : {}
+		});
+		if (!profile.normalized) return [];
+		const maxCandidates = Math.max(1, Math.min(200, Math.floor(params.maxCandidates)));
+		const fts = searchActiveUnderstandings(profile.normalized, Math.max(50, maxCandidates));
+		const ftsScores = new Map(fts.map((result) => [result.understanding.id, result.score]));
+		const recentLimit = Math.max(200, Math.min(500, maxCandidates * 5));
+		const recent = listUnderstandings(["active"]).slice(0, recentLimit);
+		const candidates = /* @__PURE__ */ new Map();
+		for (const result of fts) candidates.set(result.understanding.id, result.understanding);
+		for (const item of recent) candidates.set(item.id, item);
+		const feedback = new Map(summarizeUnderstandingFeedback([...candidates.keys()]).map((summary) => [summary.understandingId, summary]));
+		return [...candidates.values()].map((item) => {
+			const lexical = retrievalLexicalSimilarity(profile.normalized, item.statement);
+			const ftsScore = ftsScores.get(item.id) ?? 0;
+			const textScore = Math.max(lexical, ftsScore);
+			const kindMatched = profile.intentKinds.includes(item.kind);
+			const normalizedStatement = normalizeRetrievalText(item.statement);
+			const identifierMatched = profile.identifiers.some((identifier) => normalizedStatement.includes(identifier));
+			const feedbackScore = feedbackAdjustment(feedback.get(item.id));
+			return {
+				understanding: item,
+				score: Math.min(1, Math.max(0, Math.max(baseline(item), textScore * .7 + lexical * .1 + item.confidence * .1 + authorityBonus(item) + (kindMatched ? .08 : 0) + (identifierMatched ? .12 : 0) + (matchesUserContextScope(item.scope, params) && item.scope.type !== "global" ? .05 : 0)) + feedbackScore)),
+				reasons: [
+					ftsScore > 0 ? "fts" : "",
+					lexical > 0 ? "lexical" : "",
+					identifierMatched ? "identifier" : "",
+					kindMatched ? "kind" : "",
+					item.explicitness === "explicit" ? "explicit" : "",
+					feedbackScore !== 0 ? "feedback" : ""
+				].filter(Boolean)
+			};
+		}).sort((left, right) => Number(matchesUserContextScope(right.understanding.scope, params)) - Number(matchesUserContextScope(left.understanding.scope, params)) || right.score - left.score || right.understanding.updatedAt - left.understanding.updatedAt).slice(0, maxCandidates);
+	}
+};
+//#endregion
+export { UserUnderstandingRetriever };

package/dist/src/user-context/scope.d.ts

@@ -0,0 +1,7 @@
+import type { UserContextScope } from './domain.js';
+export interface UserContextScopeTarget {
+    sessionKey: string;
+    workspaceId: string;
+    projectId?: string;
+}
+export declare function matchesUserContextScope(scope: UserContextScope, target: UserContextScopeTarget): boolean;

package/dist/src/user-context/scope.js

@@ -0,0 +1,9 @@
+//#region src/user-context/scope.ts
+function matchesUserContextScope(scope, target) {
+	if (scope.type === "global") return true;
+	if (scope.type === "session") return scope.id === target.sessionKey;
+	if (scope.type === "workspace") return scope.id === target.workspaceId;
+	return Boolean(target.projectId && scope.id === target.projectId);
+}
+//#endregion
+export { matchesUserContextScope };

package/dist/src/user-context/sources/activity-clustering.js

@@ -1,130 +1,43 @@
-import { createHash } from "node:crypto";
+import { clusterUnderstandingSignals } from "./signal-clustering.js";
 //#region src/user-context/sources/activity-clustering.ts
-const STOP_WORDS = new Set([
-	"about",
-	"and",
-	"bookmark",
-	"bookmarks",
-	"desktop",
-	"document",
-	"documents",
-	"download",
-	"downloads",
-	"file",
-	"files",
-	"from",
-	"guide",
-	"home",
-	"index",
-	"into",
-	"latest",
-	"new",
-	"notes",
-	"official",
-	"overview",
-	"page",
-	"plan",
-	"profile",
-	"project",
-	"recent",
-	"roadmap",
-	"the",
-	"this",
-	"with",
-	"www"
-]);
 function activityTimestamp(item) {
 	return item.modifiedAt ?? item.occurredAt ?? item.startsAt ?? 0;
 }
-function tokenize(value) {
-	const normalized = value.replace(/([a-z0-9])([A-Z])/g, "$1 $2").toLocaleLowerCase().replace(/\.[a-z0-9]{1,8}$/i, "").replace(/https?:\/\//g, " ");
-	const tokens = /* @__PURE__ */ new Set();
-	for (const token of normalized.match(/[a-z0-9][a-z0-9-]{2,}|[\p{Script=Han}]{2,}/gu) ?? []) {
-		if (/^[\p{Script=Han}]+$/u.test(token)) {
-			if (token.length <= 4) tokens.add(token);
-			else for (let index = 0; index < token.length - 1; index += 1) tokens.add(token.slice(index, index + 2));
-			continue;
-		}
-		const clean = token.replace(/^-+|-+$/g, "");
-		if (clean.length >= 3 && !STOP_WORDS.has(clean) && !/^\d+$/.test(clean)) tokens.add(clean);
+function resourceHost(item) {
+	if (!item.resourceUri) return void 0;
+	try {
+		return new URL(item.resourceUri).hostname.replace(/^www\./, "") || void 0;
+	} catch {
+		return;
 	}
-	return tokens;
-}
-function itemTokens(item) {
-	let host = "";
-	if (item.resourceUri) try {
-		host = new URL(item.resourceUri).hostname.replace(/^www\./, "");
-	} catch {}
-	return tokenize([
-		item.title,
-		item.group ?? "",
-		host
-	].join(" "));
-}
-function overlap(left, right) {
-	let count = 0;
-	for (const token of left) if (right.has(token)) count += 1;
-	return count;
-}
-function related(left, right) {
-	const shared = overlap(left.tokens, right.tokens);
-	if (shared >= 2) return true;
-	const smallest = Math.min(left.tokens.size, right.tokens.size);
-	if (shared === 1 && smallest <= 2) return true;
-	return Boolean(shared === 1 && left.item.group && left.item.group === right.item.group);
-}
-function displayTitle(cluster) {
-	const frequency = /* @__PURE__ */ new Map();
-	for (const entry of cluster) for (const token of entry.tokens) frequency.set(token, (frequency.get(token) ?? 0) + 1);
-	const shared = [...frequency.entries()].filter(([, count]) => count >= 2).sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0])).slice(0, 3).map(([token]) => token);
-	if (shared.length && shared.every((token) => /^[\p{Script=Han}]+$/u.test(token))) return cluster[0].item.title.replace(/\.[a-z0-9]{1,8}$/i, "").slice(0, 80);
-	if (shared.length) return shared.map((token) => token.charAt(0).toUpperCase() + token.slice(1)).join(" ");
-	return cluster[0].item.title.replace(/\.[a-z0-9]{1,8}$/i, "").slice(0, 80);
 }
 function clusterActivityTopics(items, now = Date.now()) {
-	const prepared = items.filter((item) => item.type === "document" || item.type === "bookmark").map((item) => ({
-		item,
-		tokens: itemTokens(item),
-		timestamp: activityTimestamp(item)
-	})).filter((entry) => entry.tokens.size > 0);
-	const parent = prepared.map((_, index) => index);
-	const find = (index) => parent[index] === index ? index : parent[index] = find(parent[index]);
-	const union = (left, right) => {
-		const leftRoot = find(left);
-		const rightRoot = find(right);
-		if (leftRoot !== rightRoot) parent[rightRoot] = leftRoot;
-	};
-	for (let left = 0; left < prepared.length; left += 1) for (let right = left + 1; right < prepared.length; right += 1) if (related(prepared[left], prepared[right])) union(left, right);
-	const clusters = /* @__PURE__ */ new Map();
-	prepared.forEach((entry, index) => clusters.set(find(index), [...clusters.get(find(index)) ?? [], entry]));
-	return [...clusters.values()].flatMap((cluster) => {
-		if (cluster.length < 2) return [];
-		const sourceIds = [...new Set(cluster.map(({ item }) => item.sourceId))];
-		const types = new Set(cluster.map(({ item }) => item.type));
-		if (types.size === 1 && types.has("bookmark") && cluster.length < 3) return [];
-		const newestAt = Math.max(...cluster.map(({ timestamp }) => timestamp));
-		const ageDays = newestAt ? Math.max(0, (now - newestAt) / 864e5) : 90;
-		const recency = Math.max(0, 1 - ageDays / 90);
-		const confidence = Math.min(.92, .48 + Math.min(cluster.length, 5) * .06 + Math.min(sourceIds.length, 3) * .09 + recency * .08);
-		const title = displayTitle(cluster);
-		const fileCount = cluster.filter(({ item }) => item.type === "document").length;
-		const bookmarkCount = cluster.length - fileCount;
-		const evidenceRefs = cluster.map(({ item }) => item.evidenceRef);
-		const sharedTokens = /* @__PURE__ */ new Map();
-		for (const entry of cluster) for (const token of entry.tokens) sharedTokens.set(token, (sharedTokens.get(token) ?? 0) + 1);
-		const stableTopicTokens = [...sharedTokens.entries()].filter(([, count]) => count >= 2).map(([token]) => token).sort();
-		const key = createHash("sha256").update(stableTopicTokens.join("|")).digest("hex").slice(0, 16);
-		const signals = [fileCount ? `${fileCount} recent file${fileCount === 1 ? "" : "s"}` : "", bookmarkCount ? `${bookmarkCount} bookmark${bookmarkCount === 1 ? "" : "s"}` : ""].filter(Boolean).join(" and ");
+	const eligible = items.filter((item) => item.type === "document" || item.type === "bookmark");
+	const byEvidenceRef = new Map(eligible.map((item) => [item.evidenceRef, item]));
+	return clusterUnderstandingSignals(eligible.map((item) => ({
+		evidenceRef: item.evidenceRef,
+		sourceId: item.sourceId,
+		title: item.title,
+		group: [item.group, resourceHost(item)].filter(Boolean).join(" ") || void 0,
+		occurredAt: activityTimestamp(item)
+	})), now).flatMap((cluster) => {
+		const sourceItems = cluster.signals.map((signal) => byEvidenceRef.get(signal.evidenceRef)).filter((item) => Boolean(item));
+		const types = new Set(sourceItems.map((item) => item.type));
+		if (types.size === 1 && types.has("bookmark") && sourceItems.length < 3) return [];
+		const fileCount = sourceItems.filter((item) => item.type === "document").length;
+		const bookmarkCount = sourceItems.length - fileCount;
+		const evidenceRefs = cluster.signals.map((signal) => signal.evidenceRef);
+		const evidenceSummary = [fileCount ? `${fileCount} recent file${fileCount === 1 ? "" : "s"}` : "", bookmarkCount ? `${bookmarkCount} bookmark${bookmarkCount === 1 ? "" : "s"}` : ""].filter(Boolean).join(" and ");
 		return [{
-			canonicalKey: `activity-focus:${key}`,
-			title,
-			summary: `${signals} suggest sustained attention to ${title}.`,
-			horizon: ageDays <= 14 ? "current" : "ongoing",
-			confidence,
+			canonicalKey: `activity-focus:${cluster.key}`,
+			title: cluster.title,
+			summary: `${evidenceSummary} suggest sustained attention to ${cluster.title}.`,
+			horizon: cluster.horizon,
+			confidence: cluster.confidence,
 			evidenceRefs,
-			sourceIds
+			sourceIds: cluster.sourceIds
 		}];
-	}).sort((left, right) => right.confidence - left.confidence);
+	});
 }
 //#endregion
 export { clusterActivityTopics };

package/dist/src/user-context/sources/index.d.ts

@@ -1,3 +1,4 @@
 export * from './catalog.js';
 export * from './repository.js';
+export * from './signal-clustering.js';
 export * from './types.js';

package/dist/src/user-context/sources/index.js

@@ -1,3 +1,4 @@
 import { createUnderstandingSourceRun, deleteUserFocus, getUnderstandingSourceGrant, getUnderstandingSourceRun, listUnderstandingSourceGrants, listUnderstandingSourceRuns, listUserFocuses, revokeUnderstandingSourceGrant, setUserFocusStatus, updateUnderstandingSourceGrantCheckpoint, updateUnderstandingSourceRun, upsertUnderstandingSourceGrant, upsertUserFocus } from "./repository.js";
+import { clusterUnderstandingSignals, tokenizeUnderstandingSignal } from "./signal-clustering.js";
 import { listUnderstandingSourceDefinitions } from "./catalog.js";
-export { createUnderstandingSourceRun, deleteUserFocus, getUnderstandingSourceGrant, getUnderstandingSourceRun, listUnderstandingSourceDefinitions, listUnderstandingSourceGrants, listUnderstandingSourceRuns, listUserFocuses, revokeUnderstandingSourceGrant, setUserFocusStatus, updateUnderstandingSourceGrantCheckpoint, updateUnderstandingSourceRun, upsertUnderstandingSourceGrant, upsertUserFocus };
+export { clusterUnderstandingSignals, createUnderstandingSourceRun, deleteUserFocus, getUnderstandingSourceGrant, getUnderstandingSourceRun, listUnderstandingSourceDefinitions, listUnderstandingSourceGrants, listUnderstandingSourceRuns, listUserFocuses, revokeUnderstandingSourceGrant, setUserFocusStatus, tokenizeUnderstandingSignal, updateUnderstandingSourceGrantCheckpoint, updateUnderstandingSourceRun, upsertUnderstandingSourceGrant, upsertUserFocus };

package/dist/src/user-context/sources/signal-clustering.d.ts

@@ -0,0 +1,18 @@
+export type UnderstandingSignal = {
+    evidenceRef: string;
+    sourceId: string;
+    title: string;
+    group?: string;
+    subjectKey?: string;
+    occurredAt?: number;
+};
+export type UnderstandingSignalCluster = {
+    key: string;
+    title: string;
+    confidence: number;
+    horizon: 'current' | 'ongoing';
+    signals: UnderstandingSignal[];
+    sourceIds: string[];
+};
+export declare function tokenizeUnderstandingSignal(value: string): Set<string>;
+export declare function clusterUnderstandingSignals(signals: UnderstandingSignal[], now?: number): UnderstandingSignalCluster[];

package/dist/src/user-context/sources/signal-clustering.js

@@ -0,0 +1,131 @@
+import { createHash } from "node:crypto";
+//#region src/user-context/sources/signal-clustering.ts
+const STOP_WORDS = new Set([
+	"about",
+	"and",
+	"bookmark",
+	"bookmarks",
+	"desktop",
+	"document",
+	"documents",
+	"download",
+	"downloads",
+	"file",
+	"files",
+	"from",
+	"fwd",
+	"guide",
+	"home",
+	"index",
+	"into",
+	"latest",
+	"new",
+	"notes",
+	"official",
+	"overview",
+	"page",
+	"plan",
+	"profile",
+	"project",
+	"recent",
+	"reply",
+	"roadmap",
+	"the",
+	"this",
+	"with",
+	"www"
+]);
+function normalizeKey(value) {
+	return value?.trim().toLocaleLowerCase() || void 0;
+}
+function tokenizeUnderstandingSignal(value) {
+	const normalized = value.replace(/([a-z0-9])([A-Z])/g, "$1 $2").toLocaleLowerCase().replace(/\.[a-z0-9]{1,8}$/i, "").replace(/https?:\/\//g, " ");
+	const tokens = /* @__PURE__ */ new Set();
+	for (const token of normalized.match(/[a-z0-9][a-z0-9-]{2,}|[\p{Script=Han}]{2,}/gu) ?? []) {
+		if (/^[\p{Script=Han}]+$/u.test(token)) {
+			if (token.length <= 4) tokens.add(token);
+			else for (let index = 0; index < token.length - 1; index += 1) tokens.add(token.slice(index, index + 2));
+			continue;
+		}
+		const clean = token.replace(/^-+|-+$/g, "");
+		if (clean.length >= 3 && !STOP_WORDS.has(clean) && !/^\d+$/.test(clean)) tokens.add(clean);
+	}
+	return tokens;
+}
+function signalTokens(signal) {
+	return tokenizeUnderstandingSignal([signal.title, signal.group ?? ""].join(" "));
+}
+function overlap(left, right) {
+	let count = 0;
+	for (const token of left) if (right.has(token)) count += 1;
+	return count;
+}
+function related(left, right) {
+	const leftSubject = normalizeKey(left.signal.subjectKey);
+	const rightSubject = normalizeKey(right.signal.subjectKey);
+	if (leftSubject && leftSubject === rightSubject) return true;
+	const shared = overlap(left.tokens, right.tokens);
+	if (shared >= 2) return true;
+	const smallest = Math.min(left.tokens.size, right.tokens.size);
+	if (shared === 1 && smallest <= 2) return true;
+	return Boolean(shared === 1 && left.signal.group && normalizeKey(left.signal.group) === normalizeKey(right.signal.group));
+}
+function displayTitle(cluster) {
+	const subjects = /* @__PURE__ */ new Map();
+	for (const { signal } of cluster) {
+		const key = normalizeKey(signal.subjectKey);
+		if (!key) continue;
+		const current = subjects.get(key);
+		subjects.set(key, {
+			count: (current?.count ?? 0) + 1,
+			label: signal.subjectKey
+		});
+	}
+	const repeatedSubject = [...subjects.values()].sort((left, right) => right.count - left.count)[0];
+	if (repeatedSubject && repeatedSubject.count >= 2) return repeatedSubject.label.slice(0, 80);
+	const frequency = /* @__PURE__ */ new Map();
+	for (const entry of cluster) for (const token of entry.tokens) frequency.set(token, (frequency.get(token) ?? 0) + 1);
+	const shared = [...frequency.entries()].filter(([, count]) => count >= 2).sort((left, right) => right[1] - left[1] || left[0].localeCompare(right[0])).slice(0, 3).map(([token]) => token);
+	if (shared.length && !shared.every((token) => /^[\p{Script=Han}]+$/u.test(token))) return shared.map((token) => token.charAt(0).toUpperCase() + token.slice(1)).join(" ");
+	return cluster[0].signal.title.replace(/\.[a-z0-9]{1,8}$/i, "").slice(0, 80);
+}
+function clusterUnderstandingSignals(signals, now = Date.now()) {
+	const prepared = signals.map((signal) => ({
+		signal,
+		tokens: signalTokens(signal)
+	})).filter((entry) => entry.tokens.size > 0 || entry.signal.subjectKey);
+	const parent = prepared.map((_, index) => index);
+	const find = (index) => parent[index] === index ? index : parent[index] = find(parent[index]);
+	const union = (left, right) => {
+		const leftRoot = find(left);
+		const rightRoot = find(right);
+		if (leftRoot !== rightRoot) parent[rightRoot] = leftRoot;
+	};
+	for (let left = 0; left < prepared.length; left += 1) for (let right = left + 1; right < prepared.length; right += 1) if (related(prepared[left], prepared[right])) union(left, right);
+	const clusters = /* @__PURE__ */ new Map();
+	prepared.forEach((entry, index) => clusters.set(find(index), [...clusters.get(find(index)) ?? [], entry]));
+	return [...clusters.values()].flatMap((cluster) => {
+		if (cluster.length < 2) return [];
+		const sourceIds = [...new Set(cluster.map(({ signal }) => signal.sourceId))];
+		const timestamps = cluster.map(({ signal }) => signal.occurredAt ?? 0).filter(Boolean);
+		const newestAt = timestamps.length ? Math.max(...timestamps) : 0;
+		const ageDays = newestAt ? Math.max(0, (now - newestAt) / 864e5) : 90;
+		const recency = Math.max(0, 1 - ageDays / 90);
+		const confidence = Math.min(.92, .48 + Math.min(cluster.length, 5) * .06 + Math.min(sourceIds.length, 3) * .09 + recency * .08);
+		const tokenFrequency = /* @__PURE__ */ new Map();
+		for (const entry of cluster) for (const token of entry.tokens) tokenFrequency.set(token, (tokenFrequency.get(token) ?? 0) + 1);
+		const stableTokens = [...tokenFrequency.entries()].filter(([, count]) => count >= 2).map(([token]) => token).sort();
+		const stableSubjects = cluster.map(({ signal }) => normalizeKey(signal.subjectKey)).filter((value) => Boolean(value)).sort();
+		const keyMaterial = stableTokens.length ? stableTokens : stableSubjects;
+		return [{
+			key: createHash("sha256").update((keyMaterial.length ? keyMaterial : cluster.map(({ signal }) => signal.evidenceRef).sort()).join("|")).digest("hex").slice(0, 16),
+			title: displayTitle(cluster),
+			confidence,
+			horizon: ageDays <= 14 ? "current" : "ongoing",
+			signals: cluster.map(({ signal }) => signal),
+			sourceIds
+		}];
+	}).sort((left, right) => right.confidence - left.confidence);
+}
+//#endregion
+export { clusterUnderstandingSignals, tokenizeUnderstandingSignal };

package/dist/src/voice/audio/normalize.d.ts

@@ -0,0 +1,17 @@
+import { type DecodedPcmAudio } from '../local/wav.js';
+export type AudioFormat = 'wav' | 'webm' | 'ogg' | 'mp3' | 'mp4' | 'unknown';
+export declare class AudioNormalizationError extends Error {
+    readonly code = "unsupported_audio_codec";
+    constructor(message: string, options?: ErrorOptions);
+}
+export declare function detectAudioFormat(buffer: Buffer): AudioFormat;
+export declare function decodeAudioToMonoFloat32(input: {
+    buffer: Buffer;
+    signal?: AbortSignal;
+}): Promise<DecodedPcmAudio>;
+/** Decodes a recording into bounded PCM WAV files and removes all temporary files afterwards. */
+export declare function forEachNormalizedAudioSegment(input: {
+    filePath: string;
+    segmentSeconds?: number;
+    signal?: AbortSignal;
+}, consume: (buffer: Buffer, index: number) => Promise<void>): Promise<number>;

package/dist/src/voice/audio/normalize.js

@@ -0,0 +1,155 @@
+import { decodeWavToMonoFloat32 } from "../local/wav.js";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { spawn } from "node:child_process";
+import { mkdtemp, readFile, readdir, rm } from "node:fs/promises";
+//#region src/voice/audio/normalize.ts
+const TARGET_SAMPLE_RATE = 16e3;
+const MAX_DECODED_BYTES = TARGET_SAMPLE_RATE * 4 * 15 * 60;
+var AudioNormalizationError = class extends Error {
+	code = "unsupported_audio_codec";
+	constructor(message, options) {
+		super(message, options);
+		this.name = "AudioNormalizationError";
+	}
+};
+function detectAudioFormat(buffer) {
+	if (buffer.length >= 12 && buffer.toString("ascii", 0, 4) === "RIFF" && buffer.toString("ascii", 8, 12) === "WAVE") return "wav";
+	if (buffer.length >= 4 && buffer.subarray(0, 4).equals(Buffer.from([
+		26,
+		69,
+		223,
+		163
+	]))) return "webm";
+	if (buffer.length >= 4 && buffer.toString("ascii", 0, 4) === "OggS") return "ogg";
+	if (buffer.length >= 3 && buffer.toString("ascii", 0, 3) === "ID3") return "mp3";
+	if (buffer.length >= 2 && buffer[0] === 255 && (buffer[1] & 224) === 224) return "mp3";
+	if (buffer.length >= 12 && buffer.toString("ascii", 4, 8) === "ftyp") return "mp4";
+	return "unknown";
+}
+function runFfmpeg(args, options = {}) {
+	options.signal?.throwIfAborted();
+	return new Promise((resolve, reject) => {
+		const child = spawn("ffmpeg", [
+			"-hide_banner",
+			"-loglevel",
+			"error",
+			...args
+		], { stdio: [
+			options.input ? "pipe" : "ignore",
+			"pipe",
+			"pipe"
+		] });
+		const stdout = [];
+		const stderr = [];
+		let outputBytes = 0;
+		let errorBytes = 0;
+		let settled = false;
+		const finish = (error) => {
+			if (settled) return;
+			settled = true;
+			options.signal?.removeEventListener("abort", abort);
+			if (error) reject(error);
+			else resolve(Buffer.concat(stdout));
+		};
+		const abort = () => {
+			child.kill("SIGTERM");
+			finish(new AudioNormalizationError("Audio decoding was cancelled"));
+		};
+		options.signal?.addEventListener("abort", abort, { once: true });
+		child.stdout.on("data", (chunk) => {
+			outputBytes += chunk.length;
+			if (options.maxOutputBytes != null && outputBytes > options.maxOutputBytes) {
+				child.kill("SIGTERM");
+				finish(new AudioNormalizationError("Decoded audio exceeds the supported duration"));
+				return;
+			}
+			stdout.push(chunk);
+		});
+		child.stderr.on("data", (chunk) => {
+			if (errorBytes >= 8192) return;
+			const bounded = chunk.subarray(0, 8192 - errorBytes);
+			stderr.push(bounded);
+			errorBytes += bounded.length;
+		});
+		child.once("error", (error) => {
+			finish(new AudioNormalizationError(error.code === "ENOENT" ? "Audio decoder is unavailable; install ffmpeg to transcribe this format" : `Audio decoder failed to start: ${error.message}`, { cause: error }));
+		});
+		child.once("close", (code) => {
+			if (settled) return;
+			if (code === 0) finish();
+			else finish(new AudioNormalizationError(Buffer.concat(stderr).toString("utf8").trim() || `Unsupported or corrupt audio (decoder exit ${code})`));
+		});
+		if (options.input) {
+			child.stdin.on("error", () => void 0);
+			child.stdin.end(options.input);
+		}
+	});
+}
+async function decodeAudioToMonoFloat32(input) {
+	if (detectAudioFormat(input.buffer) === "wav") return decodeWavToMonoFloat32(input.buffer);
+	const bytes = await runFfmpeg([
+		"-i",
+		"pipe:0",
+		"-map",
+		"0:a:0",
+		"-vn",
+		"-ac",
+		"1",
+		"-ar",
+		String(TARGET_SAMPLE_RATE),
+		"-f",
+		"f32le",
+		"pipe:1"
+	], {
+		input: input.buffer,
+		signal: input.signal,
+		maxOutputBytes: MAX_DECODED_BYTES
+	});
+	if (bytes.length === 0 || bytes.length % 4 !== 0) throw new AudioNormalizationError("Audio decoder produced no usable samples");
+	const copied = Uint8Array.from(bytes);
+	const samples = new Float32Array(copied.buffer);
+	return {
+		samples,
+		sampleRate: TARGET_SAMPLE_RATE,
+		durationSeconds: samples.length / TARGET_SAMPLE_RATE
+	};
+}
+/** Decodes a recording into bounded PCM WAV files and removes all temporary files afterwards. */
+async function forEachNormalizedAudioSegment(input, consume) {
+	const directory = await mkdtemp(join(tmpdir(), "xopc-audio-"));
+	const outputPattern = join(directory, "segment-%05d.wav");
+	try {
+		await runFfmpeg([
+			"-i",
+			input.filePath,
+			"-map",
+			"0:a:0",
+			"-vn",
+			"-ac",
+			"1",
+			"-ar",
+			String(TARGET_SAMPLE_RATE),
+			"-c:a",
+			"pcm_s16le",
+			"-f",
+			"segment",
+			"-segment_time",
+			String(input.segmentSeconds ?? 20),
+			"-reset_timestamps",
+			"1",
+			outputPattern
+		], { signal: input.signal });
+		const files = (await readdir(directory)).filter((name) => name.endsWith(".wav")).sort();
+		if (files.length === 0) throw new AudioNormalizationError("Audio decoder produced no segments");
+		for (let index = 0; index < files.length; index += 1) await consume(await readFile(join(directory, files[index])), index);
+		return files.length;
+	} finally {
+		await rm(directory, {
+			recursive: true,
+			force: true
+		});
+	}
+}
+//#endregion
+export { AudioNormalizationError, decodeAudioToMonoFloat32, detectAudioFormat, forEachNormalizedAudioSegment };

package/dist/src/voice/language-profile.d.ts

@@ -9,10 +9,7 @@ export interface VoiceLanguageProfile {
 }
 export declare function resolveVoiceLanguageProfile(language: ProductLanguage): VoiceLanguageProfile;
 export declare function inferProductLanguageFromEnvironment(): ProductLanguage;
-/**
- * Install safe product defaults while preserving every explicit on/off choice.
- * Older configs with a persisted language or Edge voice are treated as manual.
- */
+/** Install safe product defaults while preserving every explicit on/off choice. */
 export declare function initializeVoiceDefaults(config: Config, language?: ProductLanguage): boolean;
 /** Apply product language only to providers whose language mapping is known. */
 export declare function applyAutomaticVoiceLanguage(config: Config, language: ProductLanguage): boolean;

package/dist/src/voice/language-profile.js

@@ -26,22 +26,14 @@ function inferProductLanguageFromEnvironment() {
 		Intl.DateTimeFormat().resolvedOptions().locale
 	].find((value) => typeof value === "string" && value.trim())?.trim().toLowerCase().startsWith("zh") ? "zh" : "en";
 }
-function hasLegacyManualLanguageSelection(config) {
-	const local = config.tools?.media?.audio?.providers?.["xopc-local"];
-	const edge = config.messages?.tts?.providers?.edge;
-	return typeof local?.language === "string" && local.language.trim().length > 0 || typeof edge?.voice === "string" && edge.voice.trim().length > 0 || typeof edge?.lang === "string" && edge.lang.trim().length > 0;
-}
-/**
-* Install safe product defaults while preserving every explicit on/off choice.
-* Older configs with a persisted language or Edge voice are treated as manual.
-*/
+/** Install safe product defaults while preserving every explicit on/off choice. */
 function initializeVoiceDefaults(config, language = inferProductLanguageFromEnvironment()) {
 	const before = JSON.stringify({
 		voice: config.voice,
 		tools: config.tools?.media?.audio,
 		tts: config.messages?.tts
 	});
-	const languageMode = config.voice?.languageMode ?? (hasLegacyManualLanguageSelection(config) ? "manual" : "auto");
+	const languageMode = config.voice?.languageMode ?? "auto";
 	config.voice = {
 		...config.voice,
 		languageMode,
@@ -66,21 +58,6 @@ function initializeVoiceDefaults(config, language = inferProductLanguageFromEnvi
 			}
 		}
 	};
-	config.messages = config.messages ?? {};
-	const tts = config.messages.tts;
-	config.messages.tts = {
-		...tts,
-		enabled: tts?.enabled ?? true,
-		provider: tts?.provider ?? "edge",
-		trigger: tts?.trigger ?? "inbound",
-		providers: {
-			...tts?.providers ?? {},
-			edge: {
-				enabled: true,
-				...tts?.providers?.edge ?? {}
-			}
-		}
-	};
 	if (languageMode === "auto") applyAutomaticVoiceLanguage(config, language);
 	return before !== JSON.stringify({
 		voice: config.voice,

package/dist/src/voice/local/runtime-client.d.ts

@@ -9,6 +9,7 @@ export declare class LocalVoiceRuntimeClient {
     private child;
     private nextId;
     private pending;
+    private requestTail;
     request<T>(method: string, params?: Record<string, unknown>, options?: {
         signal?: AbortSignal;
         timeoutMs?: number;
@@ -16,6 +17,7 @@ export declare class LocalVoiceRuntimeClient {
         stopOnTimeout?: boolean;
         onProgress?: (progress: LocalVoiceRuntimeProgress) => void;
     }): Promise<T>;
+    private executeRequest;
     stop(): void;
     private ensureStarted;
     private handleLine;