@xopcai/xopc 0.0.247 → 0.0.249

package/dist/src/user-model/repository.js

@@ -0,0 +1,268 @@
+import { getSqliteDatabase, runSqliteWriteTransaction } from "../storage/sqlite/transaction.js";
+import { USER_MODEL_PRINCIPAL_ID, validateCandidate, validateScope } from "./domain.js";
+import { defaultReviewAt, requiresBoundedValidity } from "./temporal.js";
+import { randomUUID } from "node:crypto";
+//#region src/user-model/repository.ts
+function slotFromRow(row) {
+	return {
+		id: row.slot_id,
+		principalId: row.principal_id,
+		subject: {
+			type: row.subject_type,
+			id: row.subject_id
+		},
+		predicate: row.predicate,
+		cardinality: row.cardinality,
+		scope: {
+			type: row.scope_type,
+			...row.scope_id ? { id: row.scope_id } : {}
+		},
+		createdAt: row.created_at
+	};
+}
+function assertionFromRow(row) {
+	return {
+		id: row.assertion_id,
+		slotId: row.slot_id,
+		kind: row.kind,
+		value: JSON.parse(row.value_json),
+		normalizedValue: row.normalized_value,
+		statement: row.statement,
+		authority: row.authority,
+		status: row.status,
+		confidence: row.confidence,
+		...row.declared_importance === null ? {} : { declaredImportance: row.declared_importance },
+		inferredImportance: row.inferred_importance,
+		consequence: row.consequence,
+		actionability: row.actionability,
+		volatility: row.volatility,
+		sensitivity: row.sensitivity,
+		disclosurePolicy: row.disclosure_policy,
+		applicability: JSON.parse(row.applicability_json),
+		...row.valid_from === null ? {} : { validFrom: row.valid_from },
+		...row.valid_to === null ? {} : { validTo: row.valid_to },
+		observedAt: row.observed_at,
+		recordedAt: row.recorded_at,
+		...row.review_at === null ? {} : { reviewAt: row.review_at },
+		...row.supersedes_assertion_id === null ? {} : { supersedesAssertionId: row.supersedes_assertion_id },
+		createdBy: row.created_by,
+		createdAt: row.created_at
+	};
+}
+function findOrCreateSlot(db, candidate, now) {
+	const principalId = candidate.principalId ?? "local-owner";
+	const scopeId = candidate.scope.id?.trim() ?? null;
+	const existing = db.prepare(`SELECT * FROM user_assertion_slots
+    WHERE principal_id = ? AND subject_type = ? AND subject_id = ? AND predicate = ?
+      AND scope_type = ? AND COALESCE(scope_id, '') = COALESCE(?, '')`).get(principalId, candidate.subject.type, candidate.subject.id.trim(), candidate.predicate.trim(), candidate.scope.type, scopeId);
+	if (existing) {
+		if (existing.cardinality !== candidate.cardinality) throw new Error(`Assertion slot cardinality mismatch for ${candidate.predicate}.`);
+		return slotFromRow(existing);
+	}
+	const id = randomUUID();
+	db.prepare(`INSERT INTO user_assertion_slots (
+    slot_id, principal_id, subject_type, subject_id, predicate, cardinality,
+    scope_type, scope_id, created_at
+  ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(id, principalId, candidate.subject.type, candidate.subject.id.trim(), candidate.predicate.trim(), candidate.cardinality, candidate.scope.type, scopeId, now);
+	return slotFromRow(db.prepare("SELECT * FROM user_assertion_slots WHERE slot_id = ?").get(id));
+}
+function intervalsOverlap(left, candidate) {
+	const leftStart = left.validFrom ?? Number.NEGATIVE_INFINITY;
+	const leftEnd = left.validTo ?? Number.POSITIVE_INFINITY;
+	const rightStart = candidate.validFrom ?? Number.NEGATIVE_INFINITY;
+	return leftStart <= (candidate.validTo ?? Number.POSITIVE_INFINITY) && rightStart <= leftEnd;
+}
+function listReconcilableAssertions(db, slotId) {
+	return db.prepare(`SELECT * FROM user_assertions WHERE slot_id = ?
+    AND status NOT IN ('rejected', 'archived') ORDER BY recorded_at DESC`).all(slotId).map(assertionFromRow);
+}
+function sortByAuthorityAndRecorded(assertions) {
+	return assertions.sort((left, right) => authorityRank(right.authority) - authorityRank(left.authority) || right.recordedAt - left.recordedAt);
+}
+function initialStatus(candidate) {
+	if (requiresBoundedValidity(candidate.kind, candidate.volatility) && candidate.validTo === void 0) return "needs_review";
+	return candidate.authority === "user_explicit" ? "active" : "candidate";
+}
+function insertAssertion(db, slotId, candidate, status, now, supersedesAssertionId) {
+	const id = randomUUID();
+	const reviewAt = candidate.reviewAt ?? defaultReviewAt(candidate.volatility, candidate.observedAt) ?? null;
+	db.prepare(`INSERT INTO user_assertions (
+    assertion_id, slot_id, kind, value_json, normalized_value, statement, authority, status,
+    confidence, declared_importance, inferred_importance, consequence, actionability,
+    volatility, sensitivity, disclosure_policy, applicability_json, valid_from, valid_to,
+    observed_at, recorded_at, review_at, supersedes_assertion_id, created_by, created_at
+  ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(id, slotId, candidate.kind, JSON.stringify(candidate.value), candidate.normalizedValue.trim(), candidate.statement.trim(), candidate.authority, status, candidate.confidence, candidate.declaredImportance ?? null, candidate.inferredImportance, candidate.consequence, candidate.actionability, candidate.volatility, candidate.sensitivity, candidate.disclosurePolicy, JSON.stringify(candidate.applicability ?? {}), candidate.validFrom ?? null, candidate.validTo ?? null, candidate.observedAt, now, reviewAt, supersedesAssertionId ?? null, candidate.createdBy, now);
+	db.prepare(`INSERT INTO user_assertions_fts(statement, assertion_id, slot_id) VALUES (?, ?, ?)`).run(candidate.statement.trim(), id, slotId);
+	recordStatusEvent(db, id, null, status, candidate.createdBy === "connector" ? "runtime" : candidate.createdBy, "Assertion admitted.", now);
+	if (candidate.evidenceId) db.prepare(`INSERT INTO user_assertion_evidence (
+      assertion_id, evidence_id, relation, confidence, created_at
+    ) VALUES (?, ?, 'supports', ?, ?)
+    ON CONFLICT(assertion_id, evidence_id, relation) DO UPDATE SET confidence = excluded.confidence`).run(id, candidate.evidenceId, candidate.evidenceConfidence ?? candidate.confidence, now);
+	return assertionFromRow(db.prepare("SELECT * FROM user_assertions WHERE assertion_id = ?").get(id));
+}
+function recordStatusEvent(db, assertionId, fromStatus, toStatus, actor, reason, now) {
+	db.prepare(`INSERT INTO user_assertion_status_events (
+    event_id, assertion_id, from_status, to_status, actor_type, reason, created_at
+  ) VALUES (?, ?, ?, ?, ?, ?, ?)`).run(randomUUID(), assertionId, fromStatus, toStatus, actor, reason, now);
+}
+function attachEvidence(db, assertionId, candidate, now) {
+	if (!candidate.evidenceId) return;
+	db.prepare(`INSERT INTO user_assertion_evidence (
+    assertion_id, evidence_id, relation, confidence, created_at
+  ) VALUES (?, ?, 'supports', ?, ?)
+  ON CONFLICT(assertion_id, evidence_id, relation) DO UPDATE SET confidence = excluded.confidence`).run(assertionId, candidate.evidenceId, candidate.evidenceConfidence ?? candidate.confidence, now);
+}
+function closeValidity(db, assertion, boundary, now) {
+	if (assertion.validFrom !== void 0 && boundary <= assertion.validFrom) {
+		updateStatus(db, assertion, "archived", "Superseded before its validity began.", now);
+		return;
+	}
+	const end = boundary - 1;
+	db.prepare(`UPDATE user_assertions SET valid_to = ?
+    WHERE assertion_id = ? AND (valid_to IS NULL OR valid_to >= ?)`).run(end, assertion.id, boundary);
+}
+function updateStatus(db, assertion, status, reason, now) {
+	if (assertion.status === status) return;
+	db.prepare("UPDATE user_assertions SET status = ? WHERE assertion_id = ?").run(status, assertion.id);
+	recordStatusEvent(db, assertion.id, assertion.status, status, "runtime", reason, now);
+}
+function authorityRank(authority) {
+	return {
+		external_untrusted: 0,
+		system_inferred: 1,
+		user_observed: 2,
+		user_explicit: 3
+	}[authority];
+}
+function reconcileAssertion(candidate, now = Date.now()) {
+	validateCandidate(candidate);
+	return runSqliteWriteTransaction((db) => {
+		const slot = findOrCreateSlot(db, candidate, now);
+		const existing = listReconcilableAssertions(db, slot.id);
+		if (candidate.correctionOfAssertionId) {
+			if (candidate.authority !== "user_explicit") throw new Error("Only an explicit user assertion can correct an existing assertion.");
+			const target = existing.find((item) => item.id === candidate.correctionOfAssertionId);
+			if (!target) throw new Error("Correction target does not belong to the resolved assertion slot.");
+			if (target.normalizedValue === candidate.normalizedValue.trim()) {
+				attachEvidence(db, target.id, candidate, now);
+				return {
+					action: "deduplicated",
+					assertion: target
+				};
+			}
+			const assertion = insertAssertion(db, slot.id, candidate, "active", now, target.id);
+			closeValidity(db, target, candidate.validFrom ?? candidate.observedAt, now);
+			return {
+				action: "superseded",
+				assertion,
+				previousAssertion: getUserAssertion(target.id)
+			};
+		}
+		const overlapping = sortByAuthorityAndRecorded(existing.filter((item) => intervalsOverlap(item, candidate)));
+		const duplicate = overlapping.find((item) => item.normalizedValue === candidate.normalizedValue.trim());
+		if (duplicate) {
+			attachEvidence(db, duplicate.id, candidate, now);
+			return {
+				action: "deduplicated",
+				assertion: duplicate
+			};
+		}
+		const status = initialStatus(candidate);
+		if (slot.cardinality === "multiple" || !overlapping.length) return {
+			action: "created",
+			assertion: insertAssertion(db, slot.id, candidate, status, now)
+		};
+		const current = overlapping[0];
+		if (candidate.authority === "user_explicit" && authorityRank(candidate.authority) > authorityRank(current.authority)) {
+			const assertion = insertAssertion(db, slot.id, candidate, status, now, current.id);
+			closeValidity(db, current, candidate.validFrom ?? candidate.observedAt, now);
+			return {
+				action: "superseded",
+				assertion,
+				previousAssertion: getUserAssertion(current.id)
+			};
+		}
+		const assertion = insertAssertion(db, slot.id, candidate, candidate.authority === "user_explicit" ? "needs_review" : "conflicted", now);
+		if (current.authority !== "user_explicit" && candidate.authority !== "user_explicit") updateStatus(db, current, "conflicted", "Overlapping assertion has a different value.", now);
+		return {
+			action: "conflicted",
+			assertion,
+			previousAssertion: getUserAssertion(current.id)
+		};
+	});
+}
+function getUserAssertion(id) {
+	const row = getSqliteDatabase().prepare("SELECT * FROM user_assertions WHERE assertion_id = ?").get(id);
+	return row ? assertionFromRow(row) : void 0;
+}
+function getAssertionSlot(id) {
+	const row = getSqliteDatabase().prepare("SELECT * FROM user_assertion_slots WHERE slot_id = ?").get(id);
+	return row ? slotFromRow(row) : void 0;
+}
+function listSlotAssertions(slotId) {
+	return getSqliteDatabase().prepare(`SELECT * FROM user_assertions
+    WHERE slot_id = ? ORDER BY recorded_at DESC`).all(slotId).map(assertionFromRow);
+}
+function listUserAssertions(input = {}) {
+	const principalId = input.principalId ?? "local-owner";
+	const statuses = input.statuses ?? [
+		"active",
+		"candidate",
+		"needs_review",
+		"conflicted"
+	];
+	if (!statuses.length) return [];
+	const placeholders = statuses.map(() => "?").join(", ");
+	const limit = Math.max(1, Math.min(2e3, input.limit ?? 200));
+	return getSqliteDatabase().prepare(`SELECT a.* FROM user_assertions a
+    JOIN user_assertion_slots s ON s.slot_id = a.slot_id
+    WHERE s.principal_id = ? AND a.status IN (${placeholders})
+    ORDER BY a.recorded_at DESC LIMIT ?`).all(principalId, ...statuses, limit).map(assertionFromRow);
+}
+function getActiveAssertionByPredicate(predicate) {
+	const row = getSqliteDatabase().prepare(`SELECT a.* FROM user_assertions a
+    JOIN user_assertion_slots s ON s.slot_id = a.slot_id
+    WHERE s.principal_id = ? AND s.predicate = ? AND a.status = 'active'
+      AND (a.valid_from IS NULL OR a.valid_from <= ?)
+      AND (a.valid_to IS NULL OR a.valid_to >= ?)
+    ORDER BY CASE a.authority WHEN 'user_explicit' THEN 0 WHEN 'user_observed' THEN 1
+      WHEN 'system_inferred' THEN 2 ELSE 3 END, a.recorded_at DESC LIMIT 1`).get(USER_MODEL_PRINCIPAL_ID, predicate, Date.now(), Date.now());
+	return row ? assertionFromRow(row) : void 0;
+}
+function getActiveAssertionForSlot(input) {
+	validateScope(input.scope);
+	const row = getSqliteDatabase().prepare(`SELECT a.* FROM user_assertions a
+    JOIN user_assertion_slots s ON s.slot_id = a.slot_id
+    WHERE s.principal_id = ? AND s.subject_type = ? AND s.subject_id = ?
+      AND s.predicate = ? AND s.scope_type = ?
+      AND COALESCE(s.scope_id, '') = COALESCE(?, '') AND a.status = 'active'
+      AND (a.valid_from IS NULL OR a.valid_from <= ?)
+      AND (a.valid_to IS NULL OR a.valid_to >= ?)
+    ORDER BY CASE a.authority WHEN 'user_explicit' THEN 0 WHEN 'user_observed' THEN 1
+      WHEN 'system_inferred' THEN 2 ELSE 3 END, a.recorded_at DESC LIMIT 1`).get(USER_MODEL_PRINCIPAL_ID, input.subject.type, input.subject.id.trim(), input.predicate.trim(), input.scope.type, input.scope.id?.trim() ?? null, Date.now(), Date.now());
+	return row ? assertionFromRow(row) : void 0;
+}
+function getUserTimezone() {
+	const value = getActiveAssertionByPredicate("preference.timezone")?.value;
+	return typeof value === "string" && value.trim() ? value.trim() : void 0;
+}
+function linkAssertionEvidence(assertionId, evidenceId, relation, confidence, now = Date.now()) {
+	if (!Number.isFinite(confidence) || confidence < 0 || confidence > 1) throw new Error("Evidence confidence must be between 0 and 1.");
+	getSqliteDatabase().prepare(`INSERT INTO user_assertion_evidence (
+    assertion_id, evidence_id, relation, confidence, created_at
+  ) VALUES (?, ?, ?, ?, ?)
+  ON CONFLICT(assertion_id, evidence_id, relation) DO UPDATE SET confidence = excluded.confidence`).run(assertionId, evidenceId, relation, confidence, now);
+}
+function setAssertionStatus(assertionId, status, input) {
+	const current = getUserAssertion(assertionId);
+	if (!current) throw new Error(`User assertion not found: ${assertionId}`);
+	if (current.status === status) return current;
+	const now = input.now ?? Date.now();
+	runSqliteWriteTransaction((db) => {
+		db.prepare("UPDATE user_assertions SET status = ? WHERE assertion_id = ?").run(status, assertionId);
+		recordStatusEvent(db, assertionId, current.status, status, input.actor, input.reason, now);
+	});
+	return getUserAssertion(assertionId);
+}
+//#endregion
+export { getActiveAssertionByPredicate, getActiveAssertionForSlot, getAssertionSlot, getUserAssertion, getUserTimezone, linkAssertionEvidence, listSlotAssertions, listUserAssertions, reconcileAssertion, setAssertionStatus };

package/dist/src/user-model/temporal.d.ts

@@ -0,0 +1,10 @@
+import type { AssertionKind, AssertionVolatility, UserAssertion } from './domain.js';
+export declare function defaultReviewAt(volatility: AssertionVolatility, observedAt: number): number | undefined;
+export declare function requiresBoundedValidity(kind: AssertionKind, volatility: AssertionVolatility): boolean;
+export declare function isAssertionValidAt(assertion: UserAssertion, asOf: number): boolean;
+export interface CurrentAssertionResolution {
+    assertion?: UserAssertion;
+    conflict: boolean;
+    contenders: UserAssertion[];
+}
+export declare function resolveCurrentAssertion(assertions: UserAssertion[], asOf?: number): CurrentAssertionResolution;

package/dist/src/user-model/temporal.js

@@ -0,0 +1,44 @@
+//#region src/user-model/temporal.ts
+const REVIEW_INTERVAL_MS = {
+	stable: void 0,
+	slow: 4320 * 60 * 60 * 1e3,
+	dynamic: 720 * 60 * 60 * 1e3,
+	event: 10080 * 60 * 1e3
+};
+function defaultReviewAt(volatility, observedAt) {
+	const interval = REVIEW_INTERVAL_MS[volatility];
+	return interval === void 0 ? void 0 : observedAt + interval;
+}
+function requiresBoundedValidity(kind, volatility) {
+	return kind === "current_state" || volatility === "event";
+}
+function isAssertionValidAt(assertion, asOf) {
+	return assertion.status === "active" && (assertion.validFrom === void 0 || assertion.validFrom <= asOf) && (assertion.validTo === void 0 || assertion.validTo >= asOf);
+}
+const AUTHORITY_RANK = {
+	external_untrusted: 0,
+	system_inferred: 1,
+	user_observed: 2,
+	user_explicit: 3
+};
+function resolveCurrentAssertion(assertions, asOf = Date.now()) {
+	const contenders = assertions.filter((item) => isAssertionValidAt(item, asOf));
+	if (!contenders.length) return {
+		conflict: false,
+		contenders: []
+	};
+	contenders.sort((left, right) => AUTHORITY_RANK[right.authority] - AUTHORITY_RANK[left.authority] || right.recordedAt - left.recordedAt);
+	const best = contenders[0];
+	if (contenders.filter((item) => AUTHORITY_RANK[item.authority] === AUTHORITY_RANK[best.authority] && item.normalizedValue !== best.normalizedValue).length) return {
+		assertion: void 0,
+		conflict: true,
+		contenders
+	};
+	return {
+		assertion: best,
+		conflict: false,
+		contenders
+	};
+}
+//#endregion
+export { defaultReviewAt, isAssertionValidAt, requiresBoundedValidity, resolveCurrentAssertion };

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

@@ -2,6 +2,7 @@ import { createLogger } from "../../utils/logger/index.js";
 import { init_logger } from "../../utils/logger.js";
 import { speakStream } from "../tts/speak-core.js";
 import { AudioPlaybackWindow } from "./audio-playback-window.js";
+import { ConversationTurn } from "./conversationTurn.js";
 import { SpeakableSegmenter } from "./speakable-segmenter.js";
 import crypto from "node:crypto";
 //#region src/voice/realtime/agentEngine.ts
@@ -29,6 +30,32 @@ function createAgentVoiceEngine(options) {
 	let finalCount = 0;
 	let committing = false;
 	const finalizedUtterances = /* @__PURE__ */ new Set();
+	let pendingTurn;
+	const turn = new ConversationTurn(claim.silenceDurationMs, (text) => {
+		if (closed || muted) return;
+		if (queuedTurns >= 8) {
+			send("session.error", {
+				code: "INPUT_BACKPRESSURE",
+				message: "Too many queued voice turns",
+				recoverable: false
+			});
+			options.onClose("input_backpressure", true);
+			return;
+		}
+		queuedTurns += 1;
+		const generation = inputGeneration;
+		const pending = {
+			text,
+			cancelled: false
+		};
+		pendingTurn = pending;
+		conversationTail = conversationTail.then(() => {
+			if (pendingTurn === pending) pendingTurn = void 0;
+			if (generation === inputGeneration && !pending.cancelled) return runConversationTurn(text);
+		}).finally(() => {
+			if (generation === inputGeneration) queuedTurns -= 1;
+		});
+	});
 	function cancelActiveResponse(reason) {
 		const response = activeResponse;
 		if (!response) return false;
@@ -238,10 +265,23 @@ function createAgentVoiceEngine(options) {
 			}
 		});
 	}
+	function bufferFinal(utteranceId, text) {
+		try {
+			turn.final(utteranceId, text);
+		} catch {
+			send("session.error", {
+				code: "INPUT_BACKPRESSURE",
+				message: "Voice turn input limit reached",
+				recoverable: false
+			});
+			options.onClose("input_backpressure", true);
+		}
+	}
 	function onSttEvent(event) {
 		if (closed) return;
 		if (event.type === "ready" || event.type === "usage") return;
 		if (event.type === "error") {
+			turn.reset();
 			log.warn({
 				err: event.error,
 				sessionId: claim.sessionId,
@@ -257,10 +297,21 @@ function createAgentVoiceEngine(options) {
 		}
 		if (muted || finalizedUtterances.has(event.utteranceId)) return;
 		if (event.type === "speech_started") {
+			if (claim.request.purpose === "conversation") {
+				if (pendingTurn) {
+					pendingTurn.cancelled = true;
+					turn.restore(pendingTurn.text);
+					pendingTurn = void 0;
+				}
+				turn.start(event.utteranceId);
+			}
 			if (claim.request.purpose === "conversation" && claim.config.voice?.realtime?.bargeIn && !activeResponse?.awaitingClarification) cancelActiveResponse("barge_in");
 			send("input.speech_started", { utteranceId: event.utteranceId });
 		}
-		if (event.type === "speech_stopped") send("input.speech_stopped", { utteranceId: event.utteranceId });
+		if (event.type === "speech_stopped") {
+			if (claim.request.purpose === "conversation") turn.stop(event.utteranceId);
+			send("input.speech_stopped", { utteranceId: event.utteranceId });
+		}
 		if (event.type === "transcript_delta") send("input.transcript.delta", {
 			utteranceId: event.utteranceId,
 			revision: event.revision,
@@ -268,7 +319,10 @@ function createAgentVoiceEngine(options) {
 		});
 		if (event.type === "transcript_final") {
 			const text = event.text.trim();
-			if (!text) return;
+			if (!text) {
+				if (claim.request.purpose === "conversation") bufferFinal(event.utteranceId, "");
+				return;
+			}
 			if (finalizedUtterances.size >= 1e4) {
 				options.onClose("utterance_limit", true);
 				return;
@@ -282,28 +336,18 @@ function createAgentVoiceEngine(options) {
 				...event.language === "zh" || event.language === "en" ? { language: event.language } : {}
 			});
 			if (claim.request.purpose === "conversation") {
-				if (activeResponse?.awaitingClarification) return;
-				if (claim.config.voice?.realtime?.bargeIn) cancelActiveResponse("barge_in");
-				if (queuedTurns >= 8) {
-					send("session.error", {
-						code: "INPUT_BACKPRESSURE",
-						message: "Too many queued voice turns",
-						recoverable: false
-					});
-					options.onClose("input_backpressure", true);
+				if (activeResponse?.awaitingClarification) {
+					turn.reset();
 					return;
 				}
-				queuedTurns += 1;
-				const generation = inputGeneration;
-				conversationTail = conversationTail.then(() => {
-					if (generation === inputGeneration) return runConversationTurn(text);
-				}).finally(() => {
-					if (generation === inputGeneration) queuedTurns -= 1;
-				});
+				if (claim.config.voice?.realtime?.bargeIn) cancelActiveResponse("barge_in");
+				bufferFinal(event.utteranceId, text);
 			}
 		}
 	}
 	function discardInput() {
+		turn.reset();
+		pendingTurn = void 0;
 		inputGeneration += 1;
 		queuedTurns = 0;
 		bufferedAudio = [];
@@ -387,6 +431,7 @@ function createAgentVoiceEngine(options) {
 		close() {
 			if (closing) return closing;
 			closed = true;
+			turn.reset();
 			cancelActiveResponse("session_closed");
 			sttAbort.abort("session_closed");
 			sttSession?.abort("session_closed");

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

@@ -0,0 +1,20 @@
+/** Conservative continuation hints, not a semantic model or punctuation-based endpoint detector. */
+export declare function needsContinuation(text: string): boolean;
+/** Joins provider utterances until both transcription and the continuation window have settled. */
+export declare class ConversationTurn {
+    private readonly silenceDurationMs;
+    private readonly onTurn;
+    private readonly parts;
+    private timer;
+    private stoppedAt;
+    constructor(silenceDurationMs: number, onTurn: (text: string) => void);
+    start(id: string): void;
+    stop(id: string): void;
+    final(id: string, text: string): void;
+    reset(): void;
+    /** Restore a settled turn if generation was still queued when the user resumed. */
+    restore(text: string): void;
+    private text;
+    private clearTimer;
+    private schedule;
+}

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

@@ -0,0 +1,83 @@
+//#region src/voice/realtime/conversationTurn.ts
+const MIN_TURN_SILENCE_MS = 1200;
+const FINAL_SETTLE_MS = 350;
+const INCOMPLETE_HOLD_MS = 1800;
+/** Conservative continuation hints, not a semantic model or punctuation-based endpoint detector. */
+function needsContinuation(text) {
+	const tail = text.trim().replace(/[\s，。！？、；：,.!?;:]+$/u, "");
+	return /(?:…|\.\.\.)[\s，。！？,.!?]*$/u.test(text) || /(?:因为|但是|然后|而且|如果|所以|比如|或者|还有|我想|我要|我觉得|帮我|帮我查一下|帮我查查|请帮我|就是说|那个|这个|呃|嗯)$/u.test(tail) || /\b(?:because|but|and|or|if|so|then|um|uh|i want to|i would like to|can you|could you|let me)\s*$/iu.test(tail);
+}
+/** Joins provider utterances until both transcription and the continuation window have settled. */
+var ConversationTurn = class {
+	parts = /* @__PURE__ */ new Map();
+	timer;
+	stoppedAt = 0;
+	constructor(silenceDurationMs, onTurn) {
+		this.silenceDurationMs = silenceDurationMs;
+		this.onTurn = onTurn;
+	}
+	start(id) {
+		if (this.parts.has(id)) return;
+		this.clearTimer();
+		this.parts.set(id, { stopped: false });
+	}
+	stop(id) {
+		const part = this.parts.get(id);
+		if (part?.stopped) return;
+		this.parts.set(id, {
+			...part,
+			stopped: true
+		});
+		this.stoppedAt = Date.now();
+		this.schedule();
+	}
+	final(id, text) {
+		const part = this.parts.get(id);
+		if (part?.text !== void 0) return;
+		if (!part?.stopped) this.stoppedAt = Date.now();
+		this.parts.set(id, {
+			text: text.trim(),
+			stopped: true
+		});
+		if (this.parts.size > 256 || this.text().length > 32e3) {
+			this.reset();
+			throw new Error("Voice turn input limit reached");
+		}
+		this.schedule();
+	}
+	reset() {
+		this.clearTimer();
+		this.parts.clear();
+	}
+	/** Restore a settled turn if generation was still queued when the user resumed. */
+	restore(text) {
+		this.parts.set("queued-turn", {
+			text,
+			stopped: true
+		});
+		this.clearTimer();
+	}
+	text() {
+		return [...this.parts.values()].map((part) => part.text ?? "").filter(Boolean).join(" ");
+	}
+	clearTimer() {
+		clearTimeout(this.timer);
+		this.timer = void 0;
+	}
+	schedule() {
+		this.clearTimer();
+		if ([...this.parts.values()].some((part) => !part.stopped || part.text === void 0)) return;
+		const text = this.text();
+		if (!text) {
+			this.reset();
+			return;
+		}
+		const holdMs = Math.max(FINAL_SETTLE_MS, MIN_TURN_SILENCE_MS - this.silenceDurationMs, needsContinuation(text) ? INCOMPLETE_HOLD_MS : 0);
+		this.timer = setTimeout(() => {
+			this.reset();
+			this.onTurn(text);
+		}, Math.max(FINAL_SETTLE_MS, this.stoppedAt + holdMs - Date.now()));
+	}
+};
+//#endregion
+export { ConversationTurn, needsContinuation };

package/dist/src/voice/realtime/memory-context.d.ts

@@ -1,7 +1,12 @@
 import type { AgentMessage } from '@earendil-works/pi-agent-core';
 import type { Config } from '../../config/schema.js';
-import { type AutomaticContextSelection } from '../../user-context/automatic-context.js';
-export interface VoiceMemorySnapshot extends AutomaticContextSelection {
+export interface VoiceMemorySnapshot {
+    block: string;
+    references: Array<{
+        kind: 'assertion' | 'knowledge';
+        id: string;
+        updatedAt: number;
+    }>;
     isCurrent: () => boolean;
     subscribe: (invalidate: () => void) => () => void;
 }