@xopcai/xopc 0.0.188 → 0.0.190

package/dist/src/user-context/manual-understanding.d.ts

@@ -1,19 +1,12 @@
-import type { MemoryKind, MemoryRecord } from '../agent/memory/types.js';
-export type ManualUnderstandingScope = {
-    type: 'global';
-} | {
-    type: 'session';
-    sessionKey: string;
-};
+import type { UnderstandingKind, UserContextScope, UserUnderstanding } from './domain.js';
 export declare function createManualUnderstanding(input: {
-    agentId: string;
     content: string;
-    kind: MemoryKind;
-    scope: ManualUnderstandingScope;
-    sensitivity: NonNullable<MemoryRecord['sensitivity']>;
-    durability: MemoryRecord['durability'];
-    disclosurePolicy: MemoryRecord['disclosurePolicy'];
+    kind: UnderstandingKind;
+    scope: UserContextScope;
+    sensitivity: UserUnderstanding['sensitivity'];
+    durability: UserUnderstanding['durability'];
+    disclosurePolicy: UserUnderstanding['disclosurePolicy'];
 }): {
-    record: MemoryRecord;
+    understanding: UserUnderstanding;
     created: boolean;
 };

package/dist/src/user-context/manual-understanding.js

@@ -1,66 +1,36 @@
-import { listMemoryRecords, upsertMemoryRecord } from "../storage/sqlite/memory-records-repository.js";
+import { createUnderstanding, listUnderstandings } from "../storage/sqlite/user-context-repository.js";
 import "../storage/sqlite/index.js";
-import { nextMemoryReviewAt } from "../agent/memory/lifecycle.js";
-import { isUserContextRecord } from "./projection.js";
+import { createHash } from "node:crypto";
 //#region src/user-context/manual-understanding.ts
-const STATUSES = [
-	"candidate",
-	"active",
-	"needs_review",
-	"stale",
-	"archived",
-	"rejected"
-];
-function sameScope(record, scope) {
-	if (scope.type === "session") return record.scope.sessionKey === scope.sessionKey;
-	return !record.scope.sessionKey && !record.scope.projectId && !record.scope.workspaceId;
+function canonicalKey(kind, statement) {
+	const normalized = statement.toLocaleLowerCase().replace(/[^\p{L}\p{N}]+/gu, " ").trim();
+	return `${kind}:${createHash("sha256").update(normalized).digest("hex").slice(0, 20)}`;
 }
-function findDuplicate(content, scope) {
-	const normalized = content.toLocaleLowerCase();
-	for (const status of STATUSES) {
-		let offset = 0;
-		while (true) {
-			const page = listMemoryRecords({
-				status,
-				limit: 500,
-				offset
-			});
-			const duplicate = page.find((record) => isUserContextRecord(record) && sameScope(record, scope) && record.content.trim().toLocaleLowerCase() === normalized);
-			if (duplicate) return duplicate;
-			if (page.length < 500) break;
-			offset += page.length;
-		}
-	}
+function sameScope(left, right) {
+	return left.type === right.type && left.id === right.id;
 }
 function createManualUnderstanding(input) {
-	const duplicate = findDuplicate(input.content, input.scope);
+	const statement = input.content.trim();
+	const key = canonicalKey(input.kind, statement);
+	const duplicate = listUnderstandings().find((item) => item.canonicalKey === key && item.status !== "archived" && item.status !== "rejected" && sameScope(item.scope, input.scope));
 	if (duplicate) return {
-		record: duplicate,
+		understanding: duplicate,
 		created: false
 	};
 	return {
-		record: upsertMemoryRecord({
-			providerId: "local",
+		understanding: createUnderstanding({
 			kind: input.kind,
-			sourceAgentId: input.agentId,
-			...input.scope.type === "session" ? { sessionKey: input.scope.sessionKey } : {},
-			content: input.content,
-			source: {
-				provider: "local",
-				path: "you://manual"
-			},
-			confidence: 1,
-			tags: ["user-understanding", "explicit-user-memory"],
+			canonicalKey: key,
 			status: "active",
-			sensitivity: input.sensitivity,
+			scope: input.scope,
 			explicitness: "explicit",
 			durability: input.durability,
-			importance: .8,
+			sensitivity: input.sensitivity,
 			disclosurePolicy: input.disclosurePolicy,
-			reviewAfter: nextMemoryReviewAt({
-				durability: input.durability,
-				explicitness: "explicit"
-			})
+			confidence: 1,
+			statement,
+			createdBy: "user",
+			changeReason: "Created with /remember"
 		}),
 		created: true
 	};

package/dist/src/{agent/memory/context → user-context}/planner.d.ts

@@ -1,17 +1,16 @@
 import type { AgentMessage } from '@earendil-works/pi-agent-core';
-import type { MemoryManager } from '../manager.js';
-import type { UserContextPlan } from './types.js';
-export declare function isUserSelfSummaryQuery(query: string): boolean;
+import type { UserContextPlan } from '../agent/memory/context/types.js';
 export declare function prependAgentContext(message: AgentMessage, block: string): AgentMessage;
 export declare class UserContextPlanner {
     plan(params: {
-        memoryManager: MemoryManager;
-        agentId: string;
         sessionKey: string;
+        workspaceId: string;
+        projectId?: string;
+        channel?: string;
         turnId: string;
         query: string;
         userMessage: AgentMessage;
         excludedRecordIds?: string[];
         allocation?: UserContextPlan['allocation'];
-    }): Promise<UserContextPlan>;
+    }): UserContextPlan;
 }

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

@@ -0,0 +1,311 @@
+import { consumeContextConsent, ensureContextConsent, getUserProfile, listCollaborationRules, listUnderstandings, recordContextRun } from "../storage/sqlite/user-context-repository.js";
+import "../storage/sqlite/index.js";
+import { readAgentMessageContent } from "../agent/memory/agent-message-access.js";
+import { buildUserContextBlock } from "../agent/memory/context-fence.js";
+import { listUserFocuses } from "./sources/repository.js";
+import { randomUUID } from "node:crypto";
+//#region src/user-context/planner.ts
+const DEFAULT_MAX_CONTEXT_CHARS = 6e3;
+const DEFAULT_MAX_RESULTS = 12;
+function prependAgentContext(message, block) {
+	if (!block) return message;
+	const prefix = `${block}\n\n`;
+	const content = readAgentMessageContent(message);
+	if (typeof content === "string") return {
+		...message,
+		content: prefix + content
+	};
+	if (Array.isArray(content)) {
+		const copy = [...content];
+		const first = copy[0];
+		if (first?.type === "text" && typeof first.text === "string") copy[0] = {
+			type: "text",
+			text: prefix + first.text
+		};
+		else copy.unshift({
+			type: "text",
+			text: prefix
+		});
+		return {
+			...message,
+			content: copy
+		};
+	}
+	return message;
+}
+function scopeMatches(scope, input) {
+	if (scope.type === "global") return true;
+	if (scope.type === "session") return scope.id === input.sessionKey;
+	if (scope.type === "workspace") return scope.id === input.workspaceId;
+	return Boolean(input.projectId && scope.id === input.projectId);
+}
+function terms(value) {
+	const normalized = value.toLocaleLowerCase().replace(/[^\p{L}\p{N}]+/gu, " ").trim();
+	const words = normalized.split(/\s+/).filter((word) => word.length > 1);
+	const cjk = [...normalized.replace(/[^\p{Script=Han}]/gu, "")];
+	for (let index = 0; index < cjk.length - 1; index += 1) words.push(`${cjk[index]}${cjk[index + 1]}`);
+	return new Set(words);
+}
+function relevance(query, item) {
+	const queryTerms = terms(query);
+	const itemTerms = terms(item.statement);
+	const shared = [...queryTerms].filter((term) => itemTerms.has(term)).length;
+	const lexical = queryTerms.size ? shared / queryTerms.size : 0;
+	const baseline = item.kind === "boundary" && item.explicitness === "explicit" ? .8 : item.kind === "preference" && item.explicitness === "explicit" ? .35 : 0;
+	const explicitness = item.explicitness === "explicit" ? .1 : item.explicitness === "observed" ? .05 : 0;
+	return Math.min(1, Math.max(baseline, lexical * .75 + item.confidence * .15 + explicitness));
+}
+function sectionFor(item) {
+	if (item.kind === "boundary") return "safety";
+	if ([
+		"preference",
+		"relationship",
+		"routine"
+	].includes(item.kind)) return "interaction";
+	return "task";
+}
+function originFor(item) {
+	if (item.explicitness === "explicit") return "told_by_user";
+	if (item.explicitness === "observed") return "observed";
+	return "inferred";
+}
+function sourceLabel(item) {
+	if (item.explicitness === "explicit") return "You told xopc";
+	if (item.explicitness === "observed") return "Observed across prior work";
+	return "An inference that may be wrong";
+}
+function rejectionReason(item, input, now) {
+	if (item.status === "needs_review" || item.status === "stale" || item.status === "candidate") return "needs_review";
+	if (item.status === "archived" || item.status === "rejected") return "disabled";
+	if (!scopeMatches(item.scope, input)) return "scope_mismatch";
+	if (item.validFrom && item.validFrom > now) return "not_yet_valid";
+	if (item.validTo && item.validTo < now || item.expiresAt && item.expiresAt < now) return "expired";
+	if (item.sensitivity === "secret" || item.sensitivity === "regulated") return "sensitive";
+	if (item.conflictGroupId) return "conflict";
+}
+function ruleMatches(rule, input) {
+	if (rule.status !== "active" || !scopeMatches(rule.scope, input)) return false;
+	const channel = typeof rule.conditions.channel === "string" ? rule.conditions.channel : void 0;
+	return !channel || channel === input.channel;
+}
+var UserContextPlanner = class {
+	plan(params) {
+		const traceId = randomUUID();
+		const query = params.query.trim();
+		if (!query) return {
+			traceId,
+			modelMessage: params.userMessage,
+			items: [],
+			rejected: [],
+			consentRequests: [],
+			estimatedTokens: 0,
+			allocation: params.allocation
+		};
+		const started = Date.now();
+		const now = Date.now();
+		const maxResults = params.allocation?.maxResults ?? DEFAULT_MAX_RESULTS;
+		const maxChars = params.allocation?.maxChars ?? DEFAULT_MAX_CONTEXT_CHARS;
+		const scopeInput = {
+			sessionKey: params.sessionKey,
+			workspaceId: params.workspaceId,
+			...params.projectId ? { projectId: params.projectId } : {}
+		};
+		const excluded = new Set(params.excludedRecordIds ?? []);
+		const rejected = [];
+		const consentRequests = [];
+		const traceItems = [];
+		const items = [];
+		let usedChars = 0;
+		const profile = getUserProfile();
+		const profileLines = [
+			profile.callName ? `Preferred name: ${profile.callName}` : "",
+			profile.role ? `Primary role: ${profile.role}` : "",
+			profile.primaryGoal ? `Primary goal for xopc: ${profile.primaryGoal}` : "",
+			profile.pronouns ? `Pronouns: ${profile.pronouns}` : "",
+			profile.timezone ? `Timezone: ${profile.timezone}` : "",
+			profile.locale ? `Language/locale: ${profile.locale}` : ""
+		].filter(Boolean);
+		if (profileLines.length) {
+			const content = profileLines.join("\n");
+			traceItems.push({
+				objectType: "profile",
+				objectId: "profile",
+				decision: "selected",
+				reason: "User-provided profile",
+				content,
+				sourceLabel: "You provided this directly",
+				rank: 0,
+				score: 1,
+				injectedChars: content.length
+			});
+			usedChars += content.length;
+		}
+		const activeFocusLines = listUserFocuses(["active"]).slice(0, 5).map((focus) => `- ${focus.title}: ${focus.summary} (${focus.horizon})`);
+		if (activeFocusLines.length) usedChars += activeFocusLines.join("\n").length;
+		const rules = listCollaborationRules().filter((rule) => ruleMatches(rule, {
+			...scopeInput,
+			channel: params.channel
+		}));
+		const selectedRules = [];
+		for (const [index, rule] of rules.entries()) {
+			if (usedChars + rule.statement.length > maxChars) {
+				traceItems.push({
+					objectType: "rule",
+					objectId: rule.id,
+					versionId: rule.revisionId,
+					decision: "budget_exceeded",
+					reason: "Context budget reached",
+					content: rule.statement,
+					sourceLabel: "Your collaboration rule",
+					injectedChars: 0
+				});
+				continue;
+			}
+			usedChars += rule.statement.length;
+			selectedRules.push(rule);
+			traceItems.push({
+				objectType: "rule",
+				objectId: rule.id,
+				versionId: rule.revisionId,
+				decision: "selected",
+				reason: "Active collaboration rule",
+				content: rule.statement,
+				sourceLabel: "Your collaboration rule",
+				rank: index + 1,
+				score: 1,
+				injectedChars: rule.statement.length
+			});
+		}
+		const ranked = listUnderstandings([
+			"active",
+			"candidate",
+			"needs_review",
+			"stale"
+		]).filter((item) => !excluded.has(item.id)).map((item) => ({
+			item,
+			score: relevance(query, item)
+		})).sort((left, right) => right.score - left.score).slice(0, Math.max(maxResults * 5, 50));
+		for (const { item, score } of ranked) {
+			if (items.length >= maxResults) {
+				rejected.push({
+					recordId: item.id,
+					reason: "budget"
+				});
+				traceItems.push({
+					objectType: "understanding",
+					objectId: item.id,
+					versionId: item.versionId,
+					decision: "budget_exceeded",
+					reason: "Maximum result count reached",
+					content: item.statement,
+					sourceLabel: sourceLabel(item),
+					score,
+					injectedChars: 0
+				});
+				continue;
+			}
+			let reason = rejectionReason(item, scopeInput, now);
+			if (!reason && score < .25) reason = "low_score";
+			if (!reason && item.disclosurePolicy === "ask_before_reference") {
+				const consentStatus = consumeContextConsent(item.id, params.sessionKey);
+				if (consentStatus !== "granted") {
+					reason = consentStatus === "denied" ? "disabled" : "requires_consent";
+					if (consentStatus === "missing") {
+						const consent = ensureContextConsent(item.id, params.sessionKey, query);
+						consentRequests.push({
+							id: consent.id,
+							recordId: item.id,
+							statement: item.statement,
+							purpose: consent.purpose
+						});
+					}
+				}
+			}
+			if (reason) {
+				rejected.push({
+					recordId: item.id,
+					reason
+				});
+				traceItems.push({
+					objectType: "understanding",
+					objectId: item.id,
+					versionId: item.versionId,
+					decision: reason === "budget" ? "budget_exceeded" : reason === "requires_consent" ? "needs_consent" : reason === "conflict" ? "conflicted" : reason === "expired" ? "expired" : reason === "sensitive" ? "sensitive" : reason === "scope_mismatch" ? "scope_mismatch" : reason === "disabled" ? "disabled" : "irrelevant",
+					reason,
+					content: item.statement,
+					sourceLabel: sourceLabel(item),
+					score,
+					injectedChars: 0
+				});
+				continue;
+			}
+			if (usedChars + item.statement.length > maxChars) {
+				rejected.push({
+					recordId: item.id,
+					reason: "budget"
+				});
+				traceItems.push({
+					objectType: "understanding",
+					objectId: item.id,
+					versionId: item.versionId,
+					decision: "budget_exceeded",
+					reason: "Context budget reached",
+					content: item.statement,
+					sourceLabel: sourceLabel(item),
+					score,
+					injectedChars: 0
+				});
+				continue;
+			}
+			usedChars += item.statement.length;
+			items.push({
+				recordId: item.id,
+				objectType: "understanding",
+				versionId: item.versionId,
+				content: item.statement,
+				score,
+				section: sectionFor(item),
+				citation: `user-context://${item.id}`,
+				origin: originFor(item),
+				stability: item.confidence
+			});
+			traceItems.push({
+				objectType: "understanding",
+				objectId: item.id,
+				versionId: item.versionId,
+				decision: "selected",
+				reason: "Relevant to this request",
+				content: item.statement,
+				sourceLabel: sourceLabel(item),
+				rank: items.length,
+				score,
+				injectedChars: item.statement.length
+			});
+		}
+		const block = [
+			profileLines.length ? `<user-profile>\n${profileLines.join("\n")}\n</user-profile>` : "",
+			activeFocusLines.length ? `<active-focuses>\n${activeFocusLines.join("\n")}\n</active-focuses>` : "",
+			selectedRules.length ? `<collaboration-contract>\n${selectedRules.map((rule) => `- ${rule.statement}`).join("\n")}\n</collaboration-contract>` : "",
+			items.length ? buildUserContextBlock(items.map((item) => `- ${item.content}\n  Evidence: ${traceItems.find((trace) => trace.objectId === item.recordId)?.sourceLabel}`).join("\n")) : ""
+		].filter(Boolean).join("\n\n");
+		recordContextRun({
+			turnId: params.turnId,
+			sessionKey: params.sessionKey,
+			query,
+			budget: maxChars,
+			durationMs: Date.now() - started,
+			items: traceItems
+		});
+		return {
+			traceId,
+			modelMessage: prependAgentContext(params.userMessage, block),
+			items,
+			rejected,
+			consentRequests,
+			estimatedTokens: Math.ceil(block.length / 4),
+			allocation: params.allocation
+		};
+	}
+};
+//#endregion
+export { UserContextPlanner, prependAgentContext };

package/dist/src/user-context/relationship-continuity.d.ts

@@ -1,14 +1,11 @@
-import type { MemoryRecord } from '../agent/memory/types.js';
-export declare const RELATIONSHIP_FOLLOW_UP_TAG = "relationship:follow-up";
+import type { UserUnderstanding } from './domain.js';
 export interface RelationshipFollowUpRequest {
     subject: string;
-    reviewAfter?: string;
+    validFrom?: number;
 }
 export declare function extractExplicitRelationshipFollowUp(message: string, nowMs?: number): RelationshipFollowUpRequest | null;
 export declare function recordExplicitRelationshipFollowUp(input: {
     sessionKey: string;
-    sourceAgentId: string;
     message: string;
     nowMs?: number;
-}): MemoryRecord | null;
-export declare function buildRelationshipContinuityPrompt(records: MemoryRecord[], nowMs?: number): string;
+}): UserUnderstanding | null;

package/dist/src/user-context/relationship-continuity.js

@@ -1,51 +1,58 @@
-import { listMemoryRecords, upsertMemoryRecord } from "../storage/sqlite/memory-records-repository.js";
+import { createContextEvidence, createUnderstanding, linkUnderstandingEvidence, listUnderstandings } from "../storage/sqlite/user-context-repository.js";
 import "../storage/sqlite/index.js";
+import { createHash } from "node:crypto";
 //#region src/user-context/relationship-continuity.ts
-const RELATIONSHIP_FOLLOW_UP_TAG = "relationship:follow-up";
+const CHINESE_FOLLOW_UP_PATTERN = /^(?:请|记得|麻烦|帮我)?\s*(?:明天|下周|之后|到时候)?\s*(?:提醒我|问问我|跟进一下|跟进)(?:关于)?[：:，,\s]*(.+)$/;
+const ENGLISH_FOLLOW_UP_PATTERN = /^(?:please\s+)?(?:remember to\s+)?(?:(?:tomorrow|next week|later)\s+)?(?:follow up with me|check in with me|ask me)(?: about)?[,\s:]+(.+)$/i;
+function normalizeFollowUpSubject(value) {
+	const subject = value?.trim();
+	if (!subject || subject.length > 240) return null;
+	if (/^(?:的|地|得|以及|并且|和|与|、|，|。|；|：)/.test(subject)) return null;
+	return subject;
+}
+function hash(value) {
+	return createHash("sha256").update(value).digest("hex").slice(0, 20);
+}
 function extractExplicitRelationshipFollowUp(message, nowMs = Date.now()) {
 	const text = message.trim();
-	const subject = (text.match(/(?:请|记得)?(?:明天|下周|之后|到时候)?(?:提醒我|问问我|跟进一下|跟进)(?:关于)?[：:，,\s]*(.+)/) ?? text.match(/(?:remember to )?(?:follow up with me|check in with me|ask me)(?: about)?[,:\s]+(.+)/i))?.[1]?.trim();
-	if (!subject || subject.length > 240) return null;
-	const delayMs = /明天|tomorrow/i.test(text) ? 1440 * 60 * 1e3 : /下周|next week/i.test(text) ? 10080 * 60 * 1e3 : 0;
+	const subject = normalizeFollowUpSubject((text.match(CHINESE_FOLLOW_UP_PATTERN) ?? text.match(ENGLISH_FOLLOW_UP_PATTERN))?.[1]);
+	if (!subject) return null;
+	const delayMs = /明天|tomorrow/i.test(text) ? 864e5 : /下周|next week/i.test(text) ? 7 * 864e5 : 0;
 	return {
 		subject,
-		...delayMs ? { reviewAfter: new Date(nowMs + delayMs).toISOString() } : {}
+		...delayMs ? { validFrom: nowMs + delayMs } : {}
 	};
 }
 function recordExplicitRelationshipFollowUp(input) {
 	const request = extractExplicitRelationshipFollowUp(input.message, input.nowMs);
 	if (!request) return null;
-	const existing = listMemoryRecords({
-		kind: "commitment",
-		status: "active",
-		limit: 200
-	}).find((record) => record.tags?.includes("relationship:follow-up") && record.content === request.subject);
+	const canonicalKey = `relationship-follow-up:${hash(request.subject.toLocaleLowerCase())}`;
+	const existing = listUnderstandings().find((item) => item.canonicalKey === canonicalKey && item.scope.type === "global" && item.status !== "rejected" && item.status !== "archived");
 	if (existing) return existing;
-	return upsertMemoryRecord({
-		providerId: "builtin",
-		kind: "commitment",
-		sourceAgentId: input.sourceAgentId,
-		sessionKey: input.sessionKey,
-		content: request.subject,
-		source: { provider: "builtin" },
-		tags: [RELATIONSHIP_FOLLOW_UP_TAG],
+	const understanding = createUnderstanding({
+		kind: "relationship",
+		canonicalKey,
 		status: "active",
+		scope: { type: "global" },
 		explicitness: "explicit",
 		durability: "recurring",
-		importance: .8,
+		sensitivity: "normal",
 		disclosurePolicy: "referenceable",
-		...request.reviewAfter ? { reviewAfter: request.reviewAfter } : {},
-		nowMs: input.nowMs
+		confidence: 1,
+		statement: request.subject,
+		...request.validFrom ? { validFrom: request.validFrom } : {},
+		createdBy: "user",
+		changeReason: "Explicit follow-up request"
 	});
-}
-function buildRelationshipContinuityPrompt(records, nowMs = Date.now()) {
-	const due = records.filter((record) => record.status === "active").filter((record) => record.tags?.includes(RELATIONSHIP_FOLLOW_UP_TAG)).filter((record) => !record.reviewAfter || Date.parse(record.reviewAfter) <= nowMs).slice(0, 3);
-	if (!due.length) return "";
-	return [
-		"## Relationship continuity",
-		"The user explicitly asked for these follow-ups. Check in naturally when relevant; do not pretend to know an task.",
-		...due.map((record) => `- ${record.content}`)
-	].join("\n");
+	const evidence = createContextEvidence({
+		sourceType: "conversation",
+		sourceRef: `session:${input.sessionKey}:follow-up:${hash(input.message)}`,
+		redactedExcerpt: input.message.slice(0, 600),
+		trustLevel: "owner",
+		observedAt: input.nowMs ?? Date.now()
+	});
+	linkUnderstandingEvidence(understanding.versionId, evidence.id, "supports", 1);
+	return understanding;
 }
 //#endregion
-export { RELATIONSHIP_FOLLOW_UP_TAG, buildRelationshipContinuityPrompt, extractExplicitRelationshipFollowUp, recordExplicitRelationshipFollowUp };
+export { extractExplicitRelationshipFollowUp, recordExplicitRelationshipFollowUp };

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

@@ -0,0 +1,2 @@
+import type { UnderstandingSourceDefinition, UnderstandingSourcePlatform } from './types.js';
+export declare function listUnderstandingSourceDefinitions(platform?: Exclude<UnderstandingSourcePlatform, 'all'>): UnderstandingSourceDefinition[];