@xopcai/xopc 0.0.241 → 0.0.243

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 };

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

@@ -1,5 +1,4 @@
 import { consumeContextConsent, ensureContextConsent, getUserProfile, listCollaborationRules, listUnderstandingEvidence, listUnderstandings, recordContextRun } from "../storage/sqlite/user-context-repository.js";
-import { retrievalLexicalSimilarity } from "../retrieval/textFeatures.js";
 import { buildRetrievalQueryProfile } from "../retrieval/queryProfile.js";
 import "../storage/sqlite/index.js";
 import { init_session_key, parseSessionKey } from "../routing/session-key.js";
@@ -9,6 +8,7 @@ import { buildUserContextBlock } from "../agent/memory/context-fence.js";
 import { getUnderstandingSourceGrant, getUnderstandingSourceRun, listUserFocuses } from "./sources/repository.js";
 import { matchesUserContextScope } from "./scope.js";
 import { UserUnderstandingRetriever } from "./retriever.js";
+import { focusRejectionReason, focusScore, rejectionReason } from "./selection-policy.js";
 import { randomUUID } from "node:crypto";
 //#region src/user-context/planner.ts
 init_session_key();
@@ -103,35 +103,12 @@ function focusSourceDescription(focus) {
 		label: "Suggested from prior work"
 	};
 }
-function rejectionReason(item, input, now, timeHints) {
-	const historical = timeHints.includes("historical") && item.validTo !== void 0;
-	if (item.status === "needs_review" || item.status === "candidate" || item.status === "stale" && !historical) return "needs_review";
-	if (item.status === "rejected" || item.status === "archived" && !historical) return "disabled";
-	if (!matchesUserContextScope(item.scope, input)) return "scope_mismatch";
-	if (item.validFrom && item.validFrom > now && !timeHints.includes("future")) return "not_yet_valid";
-	if ((item.validTo && item.validTo < now || item.expiresAt && item.expiresAt < now) && !historical) return "expired";
-	if (item.sensitivity === "secret" || item.sensitivity === "regulated") return "sensitive";
-	if (item.conflictGroupId) return "conflict";
-}
 function ruleMatches(rule, input) {
 	if (rule.status !== "active" || !matchesUserContextScope(rule.scope, input)) return false;
 	const channel = typeof rule.conditions.channel === "string" ? rule.conditions.channel : void 0;
 	const agentId = typeof rule.conditions.agentId === "string" ? rule.conditions.agentId : void 0;
 	return (!channel || channel === input.channel) && (!agentId || agentId === input.agentId);
 }
-function focusRejectionReason(focus, input, now) {
-	if (focus.status !== "active") return "disabled";
-	if (!matchesUserContextScope(focus.scope, input)) return "scope_mismatch";
-	if (focus.validFrom && focus.validFrom > now) return "not_yet_valid";
-	if (focus.validTo && focus.validTo < now) return "expired";
-	if (focus.sensitivity === "secret" || focus.sensitivity === "regulated") return "sensitive";
-	if (focus.disclosurePolicy === "ask_before_reference") return "requires_consent";
-}
-function focusScore(focus, query, scopeInput) {
-	const lexical = retrievalLexicalSimilarity(buildRetrievalQueryProfile(query, scopeInput).normalized, `${focus.title} ${focus.summary}`);
-	const scoped = focus.scope.type !== "global" && matchesUserContextScope(focus.scope, scopeInput);
-	return Math.min(1, lexical * .75 + focus.confidence * .15 + (scoped ? .25 : 0));
-}
 function renderContextBlock(params) {
 	const understandingItems = params.items.filter((item) => item.objectType === "understanding");
 	return [

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

@@ -1,5 +1,5 @@
 import { summarizeUnderstandingFeedback } from "../storage/sqlite/user-context-quality-repository.js";
-import { listUnderstandingEvidence, listUnderstandings, searchActiveUnderstandings } from "../storage/sqlite/user-context-repository.js";
+import { listUnderstandings, searchActiveUnderstandings, understandingSourceBuckets } 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";
@@ -32,23 +32,18 @@ function temporalAdjustment(item, hints, now) {
 	}
 	return score;
 }
-function sourceBucket(item) {
-	if (item.explicitness === "explicit") return "user";
-	const evidence = listUnderstandingEvidence(item.id)[0];
-	if (!evidence) return `unknown:${item.id}`;
-	if (evidence.sourceInstanceId) return `${evidence.sourceType}:${evidence.sourceInstanceId}`;
-	return `${evidence.sourceType}:${evidence.sourceRef.split(":entry:")[0]}`;
-}
 function diversify(results, limit) {
 	const remaining = [...results];
 	const selected = [];
 	const sourceCounts = /* @__PURE__ */ new Map();
-	const sourceBuckets = new Map(results.map((result) => [result.understanding.id, sourceBucket(result.understanding)]));
+	const redundancies = /* @__PURE__ */ new Map();
+	const evidenceBuckets = understandingSourceBuckets(results.filter((result) => result.understanding.explicitness !== "explicit").map((result) => result.understanding.id));
+	const sourceBuckets = new Map(results.map(({ understanding: item }) => [item.id, item.explicitness === "explicit" ? "user" : evidenceBuckets.get(item.id) ?? `unknown:${item.id}`]));
 	while (remaining.length && selected.length < limit) {
 		let bestIndex = 0;
 		let bestScore = Number.NEGATIVE_INFINITY;
 		for (const [index, candidate] of remaining.entries()) {
-			const redundancy = selected.reduce((maximum, chosen) => Math.max(maximum, retrievalLexicalSimilarity(candidate.understanding.statement, chosen.understanding.statement)), 0);
+			const redundancy = redundancies.get(candidate.understanding.id) ?? 0;
 			const bucket = sourceBuckets.get(candidate.understanding.id);
 			const sourcePenalty = candidate.understanding.explicitness === "explicit" ? 0 : (sourceCounts.get(bucket) ?? 0) * .04;
 			const adjusted = candidate.score - redundancy * .18 - sourcePenalty;
@@ -65,6 +60,10 @@ function diversify(results, limit) {
 			score: Math.max(0, bestScore),
 			reasons: bestScore < candidate.score ? [...candidate.reasons, "diversified"] : candidate.reasons
 		});
+		if (selected.length < limit) for (const remainingItem of remaining) {
+			const id = remainingItem.understanding.id;
+			redundancies.set(id, Math.max(redundancies.get(id) ?? 0, retrievalLexicalSimilarity(remainingItem.understanding.statement, candidate.understanding.statement)));
+		}
 	}
 	return selected;
 }
@@ -90,7 +89,7 @@ var UserUnderstandingRetriever = class {
 			"active",
 			"archived",
 			"stale"
-		] : ["active"]]).slice(0, recentLimit);
+		] : ["active"]], void 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);

package/dist/src/user-context/selection-policy.d.ts

@@ -0,0 +1,20 @@
+import type { UserContextRejectionReason } from '../agent/memory/context/types.js';
+import type { UserUnderstanding } from './domain.js';
+import type { UserFocus } from './sources/types.js';
+/** Automatic remote context never uses sensitive, consent-gated or weakly inferred facts. */
+export declare function allowsAutomaticDisclosure(item: Pick<UserUnderstanding, 'sensitivity' | 'disclosurePolicy' | 'explicitness' | 'confidence'>): boolean;
+export declare function rejectionReason(item: UserUnderstanding, input: {
+    sessionKey: string;
+    workspaceId: string;
+    projectId?: string;
+}, now: number, timeHints: string[]): UserContextRejectionReason | undefined;
+export declare function focusRejectionReason(focus: UserFocus, input: {
+    sessionKey: string;
+    workspaceId: string;
+    projectId?: string;
+}, now: number): UserContextRejectionReason | undefined;
+export declare function focusScore(focus: UserFocus, query: string, scopeInput: {
+    sessionKey: string;
+    workspaceId: string;
+    projectId?: string;
+}): number;

package/dist/src/user-context/selection-policy.js

@@ -0,0 +1,33 @@
+import { retrievalLexicalSimilarity } from "../retrieval/textFeatures.js";
+import { buildRetrievalQueryProfile } from "../retrieval/queryProfile.js";
+import { matchesUserContextScope } from "./scope.js";
+//#region src/user-context/selection-policy.ts
+/** Automatic remote context never uses sensitive, consent-gated or weakly inferred facts. */
+function allowsAutomaticDisclosure(item) {
+	return item.sensitivity === "normal" && item.disclosurePolicy !== "ask_before_reference" && (item.explicitness !== "inferred" || item.confidence >= .8);
+}
+function rejectionReason(item, input, now, timeHints) {
+	const historical = timeHints.includes("historical") && item.validTo !== void 0;
+	if (item.status === "needs_review" || item.status === "candidate" || item.status === "stale" && !historical) return "needs_review";
+	if (item.status === "rejected" || item.status === "archived" && !historical) return "disabled";
+	if (!matchesUserContextScope(item.scope, input)) return "scope_mismatch";
+	if (item.validFrom && item.validFrom > now && !timeHints.includes("future")) return "not_yet_valid";
+	if ((item.validTo && item.validTo < now || item.expiresAt && item.expiresAt < now) && !historical) return "expired";
+	if (item.sensitivity === "secret" || item.sensitivity === "regulated") return "sensitive";
+	if (item.conflictGroupId) return "conflict";
+}
+function focusRejectionReason(focus, input, now) {
+	if (focus.status !== "active") return "disabled";
+	if (!matchesUserContextScope(focus.scope, input)) return "scope_mismatch";
+	if (focus.validFrom && focus.validFrom > now) return "not_yet_valid";
+	if (focus.validTo && focus.validTo < now) return "expired";
+	if (focus.sensitivity === "secret" || focus.sensitivity === "regulated") return "sensitive";
+	if (focus.disclosurePolicy === "ask_before_reference") return "requires_consent";
+}
+function focusScore(focus, query, scopeInput) {
+	const lexical = retrievalLexicalSimilarity(buildRetrievalQueryProfile(query, scopeInput).normalized, `${focus.title} ${focus.summary}`);
+	const scoped = focus.scope.type !== "global" && matchesUserContextScope(focus.scope, scopeInput);
+	return Math.min(1, lexical * .75 + focus.confidence * .15 + (scoped ? .25 : 0));
+}
+//#endregion
+export { allowsAutomaticDisclosure, focusRejectionReason, focusScore, rejectionReason };

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

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

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

@@ -54,7 +54,8 @@ export declare function updateUnderstandingSourceRun(id: string, patch: {
     nowMs?: number;
 }): UnderstandingSourceRun | null;
 export declare function upsertUserFocus(input: UserFocusInput): UserFocus;
-export declare function listUserFocuses(statuses?: UserFocus['status'][]): UserFocus[];
+export declare function listUserFocuses(statuses?: UserFocus['status'][], limit?: number): UserFocus[];
+export declare function getUserFocus(id: string): UserFocus | undefined;
 export declare function updateUserFocus(id: string, patch: Partial<Pick<UserFocus, 'title' | 'summary' | 'status' | 'validFrom' | 'validTo' | 'reviewAt'>>, nowMs?: number): UserFocus | null;
 export declare function deleteUserFocus(id: string): boolean;
 export {};