@xopcai/xopc 0.0.242 → 0.0.243

package/dist/src/media-understanding/types.d.ts

@@ -112,6 +112,65 @@ export interface AudioTranscriptionResult {
     /** Audio duration in seconds, when reported. */
     durationSeconds?: number;
 }
+export interface PcmAudioFormat {
+    encoding: 'pcm_s16le';
+    sampleRate: 16_000 | 24_000;
+    channels: 1;
+}
+export interface StreamingSttCapabilities {
+    inputSampleRates: readonly number[];
+    turnDetection: readonly 'server_vad'[];
+    defaultModel: string;
+    models: readonly string[];
+}
+export type StreamingSttEvent = {
+    type: 'ready';
+} | {
+    type: 'speech_started';
+    utteranceId: string;
+} | {
+    type: 'speech_stopped';
+    utteranceId: string;
+} | {
+    type: 'transcript_delta';
+    utteranceId: string;
+    revision: number;
+    text: string;
+} | {
+    type: 'transcript_final';
+    utteranceId: string;
+    revision: number;
+    text: string;
+    language?: string;
+} | {
+    type: 'usage';
+    inputAudioMs: number;
+} | {
+    type: 'error';
+    error: Error;
+};
+export interface StreamingSttOpenRequest {
+    model: string;
+    inputFormat: PcmAudioFormat;
+    apiKey?: string;
+    baseUrl?: string;
+    headers?: Record<string, string>;
+    language?: string;
+    prompt?: string;
+    turnDetection: {
+        mode: 'server_vad';
+        silenceDurationMs: number;
+    };
+    timeoutMs: number;
+    signal: AbortSignal;
+    onEvent: (event: StreamingSttEvent) => void;
+}
+export interface StreamingSttSession {
+    appendAudio(chunk: Uint8Array): void;
+    commit(): Promise<void>;
+    close(): Promise<void>;
+    abort(reason: string): void;
+}
 export interface ImageDescriptionRequest {
     buffer: Buffer;
     fileName: string;
@@ -170,6 +229,8 @@ export interface MediaUnderstandingProvider {
     /** True when the provider can natively ingest PDF (no OCR pre-step needed). */
     nativeDocumentInputs?: ReadonlyArray<'pdf'>;
     transcribeAudio?: (req: AudioTranscriptionRequest) => Promise<AudioTranscriptionResult>;
+    streamingAudio?: StreamingSttCapabilities;
+    openAudioStream?: (req: StreamingSttOpenRequest) => Promise<StreamingSttSession>;
     describeImage?: (req: ImageDescriptionRequest) => Promise<ImageDescriptionResult>;
     describeVideo?: (req: VideoDescriptionRequest) => Promise<VideoDescriptionResult>;
 }

package/dist/src/session/client-history.js

@@ -267,6 +267,18 @@ function customRowToClientHistory(row) {
 	if (r.role !== "custom" && r.type !== "custom_message") return null;
 	const customType = optionalString(r.customType)?.trim();
 	if (!customType) return null;
+	if (customType === "voice_omni_transcript") {
+		const details = r.details;
+		if (details?.role !== "user" && details?.role !== "assistant") return null;
+		const content = typeof r.content === "string" ? r.content : "";
+		return {
+			role: details.role,
+			kind: "message",
+			content,
+			rawContent: content,
+			timestamp: parseTimestampValue(typeof r.timestamp === "string" || typeof r.timestamp === "number" ? r.timestamp : void 0)
+		};
+	}
 	const content = Array.isArray(r.content) || typeof r.content === "string" ? flattenMessageContent(r.content) : "";
 	const timestamp = parseTimestampValue(typeof r.timestamp === "string" || typeof r.timestamp === "number" ? r.timestamp : void 0);
 	return {

package/dist/src/session/manager.d.ts

@@ -149,6 +149,7 @@ export declare class SessionIndex extends EventEmitter {
         data?: unknown;
     }): Promise<void>;
     appendTranscriptCustomMessageEntry(key: string, entry: {
+        expectedSessionId?: string;
         customType: string;
         content?: string | unknown[];
         display?: boolean;

package/dist/src/session/session-context-for-llm.js

@@ -1,3 +1,4 @@
+import { voiceTranscriptMessage } from "./voice-transcript.js";
 import { isCompactionAudit, isCompactionHandover } from "./compaction-types.js";
 //#region src/session/session-context-for-llm.ts
 function isTranscriptContextEntry(x) {
@@ -245,6 +246,12 @@ function buildSessionContextForLlm(rows) {
 			continue;
 		}
 		if (isTranscriptCustomMessageEntry(r)) {
+			if (r.customType === "voice_call") continue;
+			if (r.customType === "voice_omni_transcript") {
+				const message = voiceTranscriptMessage(r);
+				if (message) out.push(message);
+				continue;
+			}
 			out.push(customMessageRowToLlmMessage(r));
 			continue;
 		}
@@ -257,6 +264,7 @@ function buildSessionDisplayMessages(rows) {
 	const out = [];
 	for (const r of rows) {
 		if (isTranscriptCustomMessageEntry(r)) {
+			if (r.customType === "voice_call") continue;
 			if (r.display === false) continue;
 			out.push(customMessageRowToLlmMessage(r));
 			continue;

package/dist/src/session/store.d.ts

@@ -124,6 +124,7 @@ export declare class SessionStore {
         data?: unknown;
     }): Promise<void>;
     appendTranscriptCustomMessageEntry(key: string, entry: {
+        expectedSessionId?: string;
         customType: string;
         content?: string | unknown[];
         display?: boolean;

package/dist/src/session/store.js

@@ -386,6 +386,7 @@ var SessionStore = class {
 	async appendTranscriptCustomMessageEntry(key, entry) {
 		return this.runStoreMutation(async () => {
 			requireXopcDatabase();
+			if (entry.expectedSessionId && getSessionMetadata(key)?.sessionId !== entry.expectedSessionId) throw new Error("Voice conversation session changed");
 			ensureSessionRecord(key, this.resolveWorkspaceCwd(key));
 			appendTranscriptEntry(key, {
 				role: "custom",

package/dist/src/session/stored-rows-to-file-entries.js

@@ -1,3 +1,4 @@
+import { voiceTranscriptMessage } from "./voice-transcript.js";
 import { isTranscriptContextEntry, isTranscriptCustomMessageEntry, isTranscriptCustomStateEntry } from "./session-context-for-llm.js";
 import { randomUUID } from "node:crypto";
 import { CURRENT_SESSION_VERSION } from "@earendil-works/pi-coding-agent";
@@ -100,7 +101,10 @@ function storedRowsToFileEntries(params) {
 			continue;
 		}
 		if (isTranscriptCustomMessageEntry(row)) {
-			const entry = customMessageRowToEntry(row, parentId, byId);
+			if (row.customType === "voice_call") continue;
+			const voiceMessage = row.customType === "voice_omni_transcript" ? voiceTranscriptMessage(row) : null;
+			if (row.customType === "voice_omni_transcript" && !voiceMessage) continue;
+			const entry = voiceMessage ? agentMessageToEntry(voiceMessage, parentId, byId) : customMessageRowToEntry(row, parentId, byId);
 			byId.add(entry.id);
 			entries.push(entry);
 			parentId = entry.id;

package/dist/src/session/voice-transcript.d.ts

@@ -0,0 +1,9 @@
+import type { AgentMessage } from '@earendil-works/pi-agent-core';
+export declare const VOICE_CALL_TYPE = "voice_call";
+export declare const VOICE_TRANSCRIPT_TYPE = "voice_omni_transcript";
+/** One projection for both direct LLM loads and the embedded SessionManager. */
+export declare function voiceTranscriptMessage(row: {
+    content?: unknown;
+    details?: unknown;
+    timestamp?: string | number;
+}): AgentMessage | null;

package/dist/src/session/voice-transcript.js

@@ -0,0 +1,45 @@
+//#region src/session/voice-transcript.ts
+const VOICE_CALL_TYPE = "voice_call";
+const VOICE_TRANSCRIPT_TYPE = "voice_omni_transcript";
+/** One projection for both direct LLM loads and the embedded SessionManager. */
+function voiceTranscriptMessage(row) {
+	const details = row.details && typeof row.details === "object" ? row.details : {};
+	if (details.role !== "user" && details.role !== "assistant" || typeof row.content !== "string" || !row.content.trim()) return null;
+	const text = details.role === "assistant" && details.interrupted === true ? "[Voice reply was interrupted. Its generated text is omitted because the heard portion is unknown.]" : row.content;
+	const parsed = typeof row.timestamp === "number" ? row.timestamp : Date.parse(row.timestamp ?? "");
+	const timestamp = Number.isFinite(parsed) ? parsed : 0;
+	const content = [{
+		type: "text",
+		text
+	}];
+	if (details.role === "user") return {
+		role: "user",
+		content,
+		timestamp
+	};
+	return {
+		role: "assistant",
+		content,
+		timestamp,
+		api: "openai-completions",
+		provider: "xopc-voice",
+		model: "voice-transcript",
+		stopReason: "stop",
+		usage: {
+			input: 0,
+			output: 0,
+			cacheRead: 0,
+			cacheWrite: 0,
+			totalTokens: 0,
+			cost: {
+				input: 0,
+				output: 0,
+				cacheRead: 0,
+				cacheWrite: 0,
+				total: 0
+			}
+		}
+	};
+}
+//#endregion
+export { VOICE_CALL_TYPE, VOICE_TRANSCRIPT_TYPE, voiceTranscriptMessage };

package/dist/src/storage/sqlite/config-repository.js

@@ -1,4 +1,5 @@
 import { getSqliteDatabase, runSqliteWriteTransaction } from "./transaction.js";
+import { notifyUserContextChange } from "../../user-context/changes.js";
 import { sessionConfigRowToConfig } from "./row-mappers.js";
 import { ensureSessionInTransaction } from "./session-repository.js";
 //#region src/storage/sqlite/config-repository.ts
@@ -21,6 +22,10 @@ function listSessionWorkspaceOverrides() {
   `).all();
 }
 function setSessionConfig(sessionKey, config, cwd) {
+	notifyUserContextChange({
+		kind: "session",
+		id: sessionKey
+	});
 	return runSqliteWriteTransaction((db) => {
 		ensureSessionInTransaction(db, sessionKey, cwd);
 		const updatedAt = Math.max(Date.now(), (readConfigRow(db, sessionKey)?.updated_at ?? 0) + 1);
@@ -54,6 +59,10 @@ function updateSessionConfig(sessionKey, partial, cwd) {
 	}, cwd);
 }
 function deleteSessionConfig(sessionKey) {
+	notifyUserContextChange({
+		kind: "session",
+		id: sessionKey
+	});
 	runSqliteWriteTransaction((db) => {
 		db.prepare(`DELETE FROM session_config WHERE session_key = ?`).run(sessionKey);
 	});

package/dist/src/storage/sqlite/remote-context-repository.d.ts

@@ -0,0 +1,3 @@
+export type RemoteContextKind = 'understanding' | 'focus';
+/** Check all provenance, including older evidence, without loading private excerpts. */
+export declare function remoteContextEligibleIds(kind: RemoteContextKind, ids: string[]): Set<string>;

package/dist/src/storage/sqlite/remote-context-repository.js

@@ -0,0 +1,40 @@
+import { getSqliteDatabase } from "./transaction.js";
+import { USER_CONTEXT_PRINCIPAL_ID } from "../../user-context/domain.js";
+//#region src/storage/sqlite/remote-context-repository.ts
+/** Check all provenance, including older evidence, without loading private excerpts. */
+function remoteContextEligibleIds(kind, ids) {
+	if (!ids.length) return /* @__PURE__ */ new Set();
+	if (ids.length > 200) throw new Error("Context candidate limit exceeded");
+	const focus = kind === "focus";
+	const table = focus ? "user_focuses" : "user_understandings";
+	const versions = focus ? "user_focus_versions" : "user_understanding_versions";
+	const links = focus ? "user_focus_evidence_links" : "understanding_evidence_links";
+	const id = focus ? "focus_id" : "understanding_id";
+	const rows = getSqliteDatabase().prepare(`
+    SELECT u.${id} AS id, v.created_by, u.explicitness,
+      COUNT(e.evidence_id) AS evidence_count,
+      MAX(CASE WHEN e.evidence_id IS NOT NULL AND (
+        (e.processing_policy IS NOT NULL AND e.processing_policy <> 'remote_allowed')
+        OR e.trust_level = 'untrusted' OR e.principal_id <> u.principal_id
+        OR (e.source_run_id IS NOT NULL AND (g.grant_id IS NULL OR g.status <> 'active' OR g.processing_policy <> 'remote_allowed'))
+        OR (e.source_type = 'connector' AND (e.processing_policy IS NULL OR e.source_run_id IS NULL))
+        OR (e.processing_policy IS NULL AND e.source_type <> 'user' AND e.trust_level <> 'owner')
+      ) THEN 1 ELSE 0 END) AS blocked
+    FROM ${table} u
+    JOIN ${versions} v ON v.version_id = u.current_version_id
+    LEFT JOIN ${versions} history ON history.${id} = u.${id}
+    LEFT JOIN ${links} l ON l.version_id = history.version_id
+    LEFT JOIN context_evidence e ON e.evidence_id = l.evidence_id
+    LEFT JOIN understanding_source_runs r ON r.run_id = e.source_run_id
+    LEFT JOIN understanding_source_grants g ON g.grant_id = r.grant_id
+    WHERE u.principal_id = ? AND u.${id} IN (${ids.map(() => "?").join(",")})
+    ${focus ? `AND (u.source_run_id IS NULL OR EXISTS (
+      SELECT 1 FROM understanding_source_runs fr JOIN understanding_source_grants fg ON fg.grant_id = fr.grant_id
+      WHERE fr.run_id = u.source_run_id AND fg.status = 'active' AND fg.processing_policy = 'remote_allowed'
+    ))` : ""}
+    GROUP BY u.${id}
+  `).all(USER_CONTEXT_PRINCIPAL_ID, ...ids);
+	return new Set(rows.filter((row) => !row.blocked && (row.evidence_count > 0 || row.explicitness === "explicit" && row.created_by === "user")).map((row) => row.id));
+}
+//#endregion
+export { remoteContextEligibleIds };

package/dist/src/storage/sqlite/session-repository.js

@@ -1,4 +1,5 @@
 import { getSqliteDatabase, runSqliteWriteTransaction } from "./transaction.js";
+import { notifyUserContextChange } from "../../user-context/changes.js";
 import { buildFts5SearchQuery } from "./fts.js";
 import { validateSessionId } from "../../session/session-id.js";
 import { buildDefaultSessionMetadata } from "./session-metadata.js";
@@ -175,6 +176,10 @@ function sessionSortColumn(sortBy) {
 	}
 }
 function patchSessionMetadata(sessionKey, updates) {
+	if ("projectId" in updates) notifyUserContextChange({
+		kind: "session-reset",
+		id: sessionKey
+	});
 	return runSqliteWriteTransaction((db) => {
 		const existing = readSessionRow(db, sessionKey);
 		if (!existing) throw new Error(`Session not found: ${sessionKey}`);
@@ -242,6 +247,10 @@ function incrementSessionStatsOnAppend(sessionKey, tokenDelta = 0) {
 	});
 }
 function resetSessionRecord(sessionKey, cwd) {
+	notifyUserContextChange({
+		kind: "session-reset",
+		id: sessionKey
+	});
 	return runSqliteWriteTransaction((db) => {
 		const existing = readSessionRow(db, sessionKey);
 		if (!existing) return null;
@@ -267,6 +276,10 @@ function resetSessionRecord(sessionKey, cwd) {
 	});
 }
 function deleteSessionRecord(sessionKey) {
+	notifyUserContextChange({
+		kind: "session-reset",
+		id: sessionKey
+	});
 	return runSqliteWriteTransaction((db) => {
 		const existing = readSessionRow(db, sessionKey);
 		if (!existing) return false;

package/dist/src/storage/sqlite/user-context-repository.d.ts

@@ -18,7 +18,7 @@ export type CreateUnderstandingInput = Omit<UserUnderstanding, 'id' | 'versionId
 };
 export declare function createUnderstanding(input: CreateUnderstandingInput, principalId?: string): UserUnderstanding;
 export declare function getUnderstanding(id: string): UserUnderstanding | undefined;
-export declare function listUnderstandings(statuses?: UnderstandingStatus[], principalId?: string): UserUnderstanding[];
+export declare function listUnderstandings(statuses?: UnderstandingStatus[], principalId?: string, limit?: number): UserUnderstanding[];
 export declare function searchActiveUnderstandings(query: string, limit?: number): Array<{
     understanding: UserUnderstanding;
     score: number;
@@ -52,6 +52,8 @@ export declare function createContextEvidence(input: Omit<ContextEvidence, 'id'
 }, principalId?: string): ContextEvidence;
 export declare function linkUnderstandingEvidence(versionId: string, evidenceId: string, relation: 'supports' | 'contradicts' | 'supersedes', confidence: number): void;
 export declare function listUnderstandingEvidence(understandingId: string, relation?: 'supports' | 'contradicts' | 'supersedes'): ContextEvidence[];
+/** Latest source labels for ranking, without fetching evidence bodies per candidate. */
+export declare function understandingSourceBuckets(ids: string[]): Map<string, string>;
 export declare function recordContextRun(input: {
     turnId: string;
     sessionKey: string;

package/dist/src/storage/sqlite/user-context-repository.js

@@ -1,5 +1,6 @@
 import { getSqliteDatabase, runSqliteWriteTransaction } from "./transaction.js";
 import { USER_CONTEXT_PRINCIPAL_ID } from "../../user-context/domain.js";
+import { notifyUserContextChange } from "../../user-context/changes.js";
 import { retrievalQueryAuditValue } from "../../retrieval/audit.js";
 import { buildFts5SearchQuery, fts5RankToScore } from "./fts.js";
 import { createHash, randomUUID } from "node:crypto";
@@ -108,6 +109,10 @@ function getUserProfile(principalId = USER_CONTEXT_PRINCIPAL_ID) {
 	};
 }
 function updateUserProfile(patch, principalId = USER_CONTEXT_PRINCIPAL_ID) {
+	notifyUserContextChange({
+		kind: "profile",
+		id: "profile"
+	});
 	const current = getUserProfile(principalId);
 	const now = Date.now();
 	const next = {
@@ -163,11 +168,12 @@ function getUnderstanding(id) {
 	const row = getSqliteDatabase().prepare(`${UNDERSTANDING_SELECT} WHERE u.understanding_id = ?`).get(id);
 	return row ? understandingFromRow(row) : void 0;
 }
-function listUnderstandings(statuses, principalId = USER_CONTEXT_PRINCIPAL_ID) {
+function listUnderstandings(statuses, principalId = USER_CONTEXT_PRINCIPAL_ID, limit) {
 	const db = getSqliteDatabase();
-	if (!statuses?.length) return db.prepare(`${UNDERSTANDING_SELECT} WHERE u.principal_id = ? ORDER BY u.updated_at DESC`).all(principalId).map(understandingFromRow);
+	const maxRows = limit === void 0 ? -1 : Math.max(1, Math.min(500, Math.floor(limit)));
+	if (!statuses?.length) return db.prepare(`${UNDERSTANDING_SELECT} WHERE u.principal_id = ? ORDER BY u.updated_at DESC LIMIT ?`).all(principalId, maxRows).map(understandingFromRow);
 	const placeholders = statuses.map(() => "?").join(", ");
-	return db.prepare(`${UNDERSTANDING_SELECT} WHERE u.principal_id = ? AND u.status IN (${placeholders}) ORDER BY u.updated_at DESC`).all(principalId, ...statuses).map(understandingFromRow);
+	return db.prepare(`${UNDERSTANDING_SELECT} WHERE u.principal_id = ? AND u.status IN (${placeholders}) ORDER BY u.updated_at DESC LIMIT ?`).all(principalId, ...statuses, maxRows).map(understandingFromRow);
 }
 function searchActiveUnderstandings(query, limit = 50) {
 	const ftsQuery = buildFts5SearchQuery(query);
@@ -193,6 +199,10 @@ function searchActiveUnderstandings(query, limit = 50) {
 	}));
 }
 function reviseUnderstanding(id, statement, options) {
+	notifyUserContextChange({
+		kind: "understanding",
+		id
+	});
 	const current = getUnderstanding(id);
 	if (!current) throw new Error(`User understanding not found: ${id}`);
 	const versionId = randomUUID();
@@ -210,6 +220,10 @@ function reviseUnderstanding(id, statement, options) {
 	return getUnderstanding(id);
 }
 function setUnderstandingStatus(id, status, options) {
+	notifyUserContextChange({
+		kind: "understanding",
+		id
+	});
 	const current = getUnderstanding(id);
 	if (!current) throw new Error(`User understanding not found: ${id}`);
 	const now = Date.now();
@@ -237,6 +251,10 @@ function setUnderstandingStatus(id, status, options) {
 	return result;
 }
 function closeUnderstandingValidity(id, validTo = Date.now()) {
+	notifyUserContextChange({
+		kind: "understanding",
+		id
+	});
 	getSqliteDatabase().prepare(`UPDATE user_understandings SET valid_to = ?, updated_at = ?
     WHERE understanding_id = ?`).run(validTo, validTo, id);
 	const result = getUnderstanding(id);
@@ -244,6 +262,10 @@ function closeUnderstandingValidity(id, validTo = Date.now()) {
 	return result;
 }
 function rejectUnderstanding(id, reason, actorType = "runtime") {
+	notifyUserContextChange({
+		kind: "understanding",
+		id
+	});
 	const current = getUnderstanding(id);
 	if (!current) throw new Error(`User understanding not found: ${id}`);
 	const now = Date.now();
@@ -277,6 +299,10 @@ function listUnderstandingStatusEvents(id) {
 	}));
 }
 function deleteUnderstanding(id) {
+	notifyUserContextChange({
+		kind: "understanding",
+		id
+	});
 	return runSqliteWriteTransaction((db) => {
 		db.prepare("DELETE FROM user_understanding_fts WHERE understanding_id = ?").run(id);
 		return Number(db.prepare("DELETE FROM user_understandings WHERE understanding_id = ?").run(id).changes) > 0;
@@ -342,6 +368,7 @@ function createContextEvidence(input, principalId = USER_CONTEXT_PRINCIPAL_ID) {
       AND COALESCE(source_instance_id, '') = COALESCE(?, '') AND source_ref = ?`).get(principalId, input.sourceType, input.sourceInstanceId ?? null, input.sourceRef);
 	const derivedHash = input.contentHash ?? (input.redactedExcerpt ? createHash("sha256").update(input.redactedExcerpt).digest("hex") : void 0);
 	if (existing) {
+		notifyUserContextChange({ kind: "policy" });
 		getSqliteDatabase().prepare(`UPDATE context_evidence SET
       source_run_id = COALESCE(source_run_id, ?), source_item_id = COALESCE(source_item_id, ?),
       session_id = COALESCE(session_id, ?), turn_id = COALESCE(turn_id, ?),
@@ -373,6 +400,11 @@ function createContextEvidence(input, principalId = USER_CONTEXT_PRINCIPAL_ID) {
 	return evidence;
 }
 function linkUnderstandingEvidence(versionId, evidenceId, relation, confidence) {
+	const owner = getSqliteDatabase().prepare("SELECT understanding_id AS id FROM user_understanding_versions WHERE version_id = ?").get(versionId);
+	if (owner) notifyUserContextChange({
+		kind: "understanding",
+		id: owner.id
+	});
 	getSqliteDatabase().prepare(`INSERT INTO understanding_evidence_links (
     version_id, evidence_id, relation, confidence
   ) VALUES (?, ?, ?, ?)
@@ -385,6 +417,20 @@ function listUnderstandingEvidence(understandingId, relation) {
     WHERE v.understanding_id = ? AND (? IS NULL OR l.relation = ?)
     ORDER BY e.observed_at DESC`).all(understandingId, relation ?? null, relation ?? null).map(evidenceFromRow);
 }
+/** Latest source labels for ranking, without fetching evidence bodies per candidate. */
+function understandingSourceBuckets(ids) {
+	if (!ids.length) return /* @__PURE__ */ new Map();
+	const rows = getSqliteDatabase().prepare(`
+    SELECT understanding_id, source_type, source_instance_id, source_ref FROM (
+      SELECT v.understanding_id, e.source_type, e.source_instance_id, e.source_ref,
+        ROW_NUMBER() OVER (PARTITION BY v.understanding_id ORDER BY e.observed_at DESC) AS rank
+      FROM context_evidence e JOIN understanding_evidence_links l ON l.evidence_id = e.evidence_id
+      JOIN user_understanding_versions v ON v.version_id = l.version_id
+      WHERE v.understanding_id IN (${ids.map(() => "?").join(",")})
+    ) WHERE rank = 1
+  `).all(...ids);
+	return new Map(rows.map((row) => [row.understanding_id, `${row.source_type}:${row.source_instance_id ?? row.source_ref.split(":entry:")[0]}`]));
+}
 function recordContextRun(input) {
 	const auditedQuery = retrievalQueryAuditValue(input.query);
 	const existing = getSqliteDatabase().prepare("SELECT context_run_id FROM context_runs WHERE turn_id = ?").get(input.turnId);
@@ -486,4 +532,4 @@ function decideContextConsent(id, decision) {
 	return Number(result.changes) > 0;
 }
 //#endregion
-export { closeUnderstandingValidity, consumeContextConsent, createCollaborationRule, createContextEvidence, createUnderstanding, decideContextConsent, deleteCollaborationRule, deleteUnderstanding, ensureContextConsent, getCollaborationRule, getTurnPersonalization, getUnderstanding, getUserProfile, hasContextConsent, isUnderstandingSuppressed, linkUnderstandingEvidence, listCollaborationRules, listUnderstandingEvidence, listUnderstandingStatusEvents, listUnderstandings, recordContextFeedback, recordContextRun, rejectUnderstanding, reviseCollaborationRule, reviseUnderstanding, searchActiveUnderstandings, setCollaborationRuleStatus, setUnderstandingStatus, updateUserProfile };
+export { closeUnderstandingValidity, consumeContextConsent, createCollaborationRule, createContextEvidence, createUnderstanding, decideContextConsent, deleteCollaborationRule, deleteUnderstanding, ensureContextConsent, getCollaborationRule, getTurnPersonalization, getUnderstanding, getUserProfile, hasContextConsent, isUnderstandingSuppressed, linkUnderstandingEvidence, listCollaborationRules, listUnderstandingEvidence, listUnderstandingStatusEvents, listUnderstandings, recordContextFeedback, recordContextRun, rejectUnderstanding, reviseCollaborationRule, reviseUnderstanding, searchActiveUnderstandings, setCollaborationRuleStatus, setUnderstandingStatus, understandingSourceBuckets, updateUserProfile };

package/dist/src/tui/tui.js

@@ -477,7 +477,8 @@ async function runTui(opts) {
 			isHidden: () => hidden,
 			focus: () => tui.setFocus(component),
 			unfocus: () => tui.setFocus(editor),
-			isFocused: () => false
+			isFocused: () => false,
+			getBounds: () => void 0
 		};
 	};
 	const closeCommandOverlay = () => {

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

@@ -0,0 +1,17 @@
+import { type RemoteContextKind } from '../storage/sqlite/remote-context-repository.js';
+import type { UserContextScopeTarget } from './scope.js';
+export interface AutomaticContextReference {
+    kind: RemoteContextKind | 'profile';
+    id: string;
+    version: string;
+}
+export interface AutomaticContextSelection {
+    block: string;
+    references: AutomaticContextReference[];
+}
+/** Read-only background selection. Never consumes consent or starts a model turn. */
+export declare function selectAutomaticContext(input: UserContextScopeTarget & {
+    query: string;
+    maxChars: number;
+    deadline: number;
+}): AutomaticContextSelection;

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

@@ -0,0 +1,85 @@
+import { getUserProfile, listUnderstandings } from "../storage/sqlite/user-context-repository.js";
+import { listUserFocuses } from "./sources/repository.js";
+import { UserUnderstandingRetriever } from "./retriever.js";
+import { allowsAutomaticDisclosure, focusRejectionReason, focusScore, rejectionReason } from "./selection-policy.js";
+import { remoteContextEligibleIds } from "../storage/sqlite/remote-context-repository.js";
+//#region src/user-context/automatic-context.ts
+/** Read-only background selection. Never consumes consent or starts a model turn. */
+function selectAutomaticContext(input) {
+	const references = [];
+	const facts = [];
+	const profile = {};
+	const render = () => JSON.stringify({ backgroundMemory: {
+		profile,
+		facts
+	} });
+	const withinDeadline = () => performance.now() < input.deadline;
+	if (input.maxChars < 128 || !withinDeadline()) return {
+		block: "",
+		references
+	};
+	const user = getUserProfile();
+	for (const key of [
+		"callName",
+		"locale",
+		"timezone",
+		"pronouns",
+		"role",
+		"primaryGoal"
+	]) {
+		if (!user[key] || user[key].length > 300) continue;
+		profile[key] = user[key];
+		if (render().length > input.maxChars) delete profile[key];
+	}
+	if (Object.keys(profile).length) references.push({
+		kind: "profile",
+		id: "profile",
+		version: JSON.stringify(user)
+	});
+	const query = input.query.trim();
+	const candidates = !withinDeadline() ? [] : query ? new UserUnderstandingRetriever().retrieve({
+		...input,
+		maxCandidates: 50
+	}) : listUnderstandings(["active"], void 0, 200).filter((item) => item.explicitness === "explicit" && ["preference", "boundary"].includes(item.kind) && item.durability === "durable").map((understanding) => ({
+		understanding,
+		score: 1
+	}));
+	const now = Date.now();
+	const eligible = candidates.filter(({ understanding: item, score }) => item.status === "active" && allowsAutomaticDisclosure(item) && !rejectionReason(item, input, now, []) && score > .25);
+	const allowed = withinDeadline() ? remoteContextEligibleIds("understanding", eligible.map(({ understanding }) => understanding.id)) : /* @__PURE__ */ new Set();
+	const append = (text, origin, reference) => {
+		if (!withinDeadline() || facts.length >= 6 || !text.trim()) return;
+		facts.push({
+			text,
+			origin
+		});
+		if (render().length > input.maxChars) {
+			facts.pop();
+			return;
+		}
+		references.push(reference);
+	};
+	for (const { understanding: item } of eligible) if (allowed.has(item.id)) append(item.statement, item.explicitness, {
+		kind: "understanding",
+		id: item.id,
+		version: item.versionId
+	});
+	if (query && withinDeadline() && facts.length < 6) {
+		const focuses = listUserFocuses(["active"], 50).filter((item) => allowsAutomaticDisclosure(item) && !focusRejectionReason(item, input, now)).map((item) => ({
+			item,
+			score: focusScore(item, query, input)
+		})).filter(({ score }) => score > .25).sort((a, b) => b.score - a.score);
+		const allowedFocuses = remoteContextEligibleIds("focus", focuses.map(({ item }) => item.id));
+		for (const { item } of focuses) if (allowedFocuses.has(item.id)) append(`${item.title}: ${item.summary}`, item.explicitness, {
+			kind: "focus",
+			id: item.id,
+			version: item.versionId ?? String(item.updatedAt)
+		});
+	}
+	return {
+		block: references.length ? render() : "",
+		references
+	};
+}
+//#endregion
+export { selectAutomaticContext };

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

@@ -0,0 +1,7 @@
+export interface UserContextChange {
+    kind: 'profile' | 'understanding' | 'focus' | 'policy' | 'session' | 'session-reset';
+    id?: string;
+}
+export declare function onUserContextChange(listener: (change: UserContextChange) => void): () => void;
+/** Dispatch after the synchronous write/outer transaction has left the stack. */
+export declare function notifyUserContextChange(change: UserContextChange): void;

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

@@ -0,0 +1,28 @@
+import { createLogger } from "../utils/logger/index.js";
+import { init_logger } from "../utils/logger.js";
+//#region src/user-context/changes.ts
+init_logger();
+const listeners = /* @__PURE__ */ new Set();
+const log = createLogger("UserContextChanges");
+function onUserContextChange(listener) {
+	listeners.add(listener);
+	return () => {
+		listeners.delete(listener);
+	};
+}
+/** Dispatch after the synchronous write/outer transaction has left the stack. */
+function notifyUserContextChange(change) {
+	if (!listeners.size) return;
+	queueMicrotask(() => {
+		for (const listener of listeners) try {
+			listener(change);
+		} catch (err) {
+			log.error({
+				err,
+				kind: change.kind
+			}, "User context change listener failed");
+		}
+	});
+}
+//#endregion
+export { notifyUserContextChange, onUserContextChange };