@xopcai/xopc 0.0.228 → 0.0.229

package/dist/src/agent/agent-instance-gateway.d.ts

@@ -44,7 +44,7 @@ export interface AgentInstanceGateway {
     /** Build the bounded, policy-filtered context used for this model turn. */
     prepareUserTurnContext(userMessage: AgentMessage, sessionKey: string, turnId: string): Promise<import('./memory/context/types.js').UserContextPlan>;
     /** Post-turn: sync external memory providers, queue next prefetch. */
-    afterAgentTurn(sessionKey: string, userPlainText: string): Promise<import('./memory/understanding/types.js').UnderstandingReviewResult | undefined>;
+    afterAgentTurn(sessionKey: string, userPlainText: string, turnId: string): Promise<import('./memory/understanding/types.js').UnderstandingReviewResult | undefined>;
     /** Bump the per-session "turns since memory review" counter. */
     beginBackgroundReviewUserTurn(sessionKey: string): void;
     /** Fire-and-forget review (memory + skill nudges) once the main turn finishes. */

package/dist/src/agent/agent-manager.d.ts

@@ -206,7 +206,7 @@ export declare class AgentManager implements AgentInstanceGateway {
      * After a completed turn: sync external providers and queue next-turn prefetch.
      * Delegates to {@link UserContextCoordinator}.
      */
-    afterAgentTurn(sessionKey: string, userPlainText: string): Promise<import('./memory/understanding/types.js').UnderstandingReviewResult | undefined>;
+    afterAgentTurn(sessionKey: string, userPlainText: string, turnId: string): Promise<import('./memory/understanding/types.js').UnderstandingReviewResult | undefined>;
     /**
      * Call once per user turn before the main embedded agent turn.
      * Delegates to {@link BackgroundReviewCoordinator}.

package/dist/src/agent/agent-manager.js

@@ -8,6 +8,7 @@ import { getAgentDefaultModelRef, init_schema } from "../config/schema.js";
 import { applyConfigOverrides } from "../config/runtime-overrides.js";
 import { expandWorkspacePathString, init_workspace_path } from "../config/workspace-path.js";
 import { init_agent_scope, resolveAgentProfileDir } from "./agent-scope.js";
+import { init_session_key, parseSessionKey } from "../routing/session-key.js";
 import { resolveEffectiveAgentProfile, resolveEffectiveAgentProfileForSession } from "../config/agent-profile.js";
 import { init_paths, resolveBundledSkillsDir } from "../config/paths.js";
 import { init_sync_provider_auth, resolveProviderApiKeySync } from "../auth/sync-provider-auth.js";
@@ -36,6 +37,7 @@ import { evictAllEmbeddedSessionRunners, evictEmbeddedSessionRunner } from "./em
 import { isMemorySubsystemEnabled } from "./memory/memory-config.js";
 import { UserContextCoordinator } from "./memory/user-context-coordinator.js";
 import { WorkspaceRuntimeRegistry } from "./workspace-runtime/registry.js";
+import { runTurnUnderstandingReview } from "./background-review/run-background-review.js";
 import { BackgroundReviewCoordinator } from "./background-review/coordinator.js";
 import { maybeRequestChannelExecApproval } from "../channels/exec-approval-runtime.js";
 import { checkBoundary } from "../agent-runtime/boundary-guard.js";
@@ -59,6 +61,7 @@ init_sync_provider_auth();
 init_providers();
 init_credentials();
 init_paths();
+init_session_key();
 const log = createLogger("AgentManager");
 var AgentManager = class {
 	agents = /* @__PURE__ */ new Map();
@@ -131,7 +134,6 @@ var AgentManager = class {
 		this.userContext = new UserContextCoordinator({
 			getConfig: () => this.config.config,
 			isEnabledForSession: (sessionKey) => this.isUserContextEnabledForSession(sessionKey),
-			getAgentIdForSession: (sk) => this.agents.get(sk)?.effectiveProfile.agentId ?? "main",
 			getWorkspaceIdForSession: (sk) => this.getResolvedWorkspaceForSession(sk),
 			getProjectIdForSession: (sk) => getSessionMetadata(sk)?.projectId,
 			getMemoryManagerForSession: (sk) => this.getMemoryManagerForSession(sk),
@@ -299,8 +301,21 @@ var AgentManager = class {
 	* After a completed turn: sync external providers and queue next-turn prefetch.
 	* Delegates to {@link UserContextCoordinator}.
 	*/
-	afterAgentTurn(sessionKey, userPlainText) {
-		return this.userContext.afterTurn(sessionKey, userPlainText);
+	async afterAgentTurn(sessionKey, userPlainText, turnId) {
+		await this.userContext.afterTurn(sessionKey, userPlainText);
+		if (!this.isUserContextEnabledForSession(sessionKey)) return void 0;
+		const parsed = parseSessionKey(sessionKey);
+		if (parsed && parsed.peerKind !== "direct") return void 0;
+		const instance = this.agents.get(sessionKey);
+		if (!instance) return void 0;
+		return runTurnUnderstandingReview({
+			sessionKey,
+			turnId,
+			userText: userPlainText,
+			mainAgent: instance.agent,
+			memoryManager: this.getMemoryManagerForSession(sessionKey),
+			getConfig: () => this.mergedConfig()
+		});
 	}
 	/**
 	* Call once per user turn before the main embedded agent turn.

package/dist/src/agent/background-review/prompts.d.ts

@@ -1,2 +1,8 @@
-export declare const MEMORY_REVIEW_USER_PROMPT = "Review the conversation above and identify durable user-understanding candidates.\n\nFocus on:\n1. Has the user revealed things about themselves \u2014 persona, desires, preferences, or personal details worth remembering?\n2. Has the user expressed expectations about how you should behave, their work style, emotional-support preferences, boundaries, or how they want you to communicate?\n3. Has the user explicitly corrected a prior assumption? Prefer the correction and do not preserve the contradicted interpretation.\n\nReturn JSON only, with this shape:\n{\"candidates\":[{\"kind\":\"preference\",\"content\":\"...\",\"confidence\":0.8,\"importance\":0.7,\"durability\":\"durable\",\"sensitivity\":\"normal\",\"disclosurePolicy\":\"referenceable\",\"evidenceRefs\":[\"entry-id\"]}]}\n\nAllowed kinds: preference, boundary, relationship, routine, current_state, long_term_goal, project_context, task_lesson, derived_insight.\nEvery reviewed message is prefixed with an evidence_ref. Every candidate must list the exact one or more evidence_ref values that support it. Omit a candidate when no exact message supports it. Only include facts supported by the conversation and likely to matter in a future session. A temporary mood or one-off reaction is current context, not durable identity; omit it unless the user describes a recurring pattern that will matter later. Never include passwords, tokens, credentials, or speculative diagnoses. Use {\"candidates\":[]} when nothing qualifies.\n\nWrite each understanding as concise, neutral profile copy that can be shown directly to the person described, not as an internal note about \"the user\". Prefer a subject-omitted predicate or noun phrase. For example, write \u201C\u503E\u5411\u4F7F\u7528 pnpm \u4F5C\u4E3A\u5305\u7BA1\u7406\u5668\u201D or \u201Cxopc \u9879\u76EE\u7684\u6838\u5FC3\u5F00\u53D1\u8005\u201D, not \u201C\u7528\u6237\u503E\u5411\u4E8E\u4F7F\u7528 pnpm\u201D or \u201C\u7528\u6237\u662F xopc \u9879\u76EE\u7684\u5F00\u53D1\u8005\u201D; write \u201CPrefers pnpm as the package manager\u201D or \u201CCore maintainer of xopc\u201D, not \u201CThe user prefers pnpm\u201D or \u201CThe user is a maintainer of xopc\u201D. Do not begin with generic subject labels or pronouns such as \u201C\u7528\u6237\u201D, \u201C\u8BE5\u7528\u6237\u201D, \u201C\u6B64\u7528\u6237\u201D, \u201C\u4F60\u201D, \u201C\u6211\u201D, \u201Cthe user\u201D, \u201Cuser\u201D, \u201Cyou\u201D, or \u201CI\u201D.\n\nDo not turn a request about the current task into user understanding. Exclude requested outputs, follow-up instructions, project-note edits, investigations, and other one-off work. Every candidate must be a complete standalone profile statement or enduring pattern; never return a clause fragment beginning with a connector such as \"and\", \"also\", \"\u5E76\u4E14\", \"\u4EE5\u53CA\", or \"\u7684\u4E8B\u9879\". Use long_term_goal only when the person states an enduring personal goal, not when they ask the assistant to create, update, investigate, summarize, or track something.";
-export declare const UNDERSTANDING_REVIEW_SYSTEM_PROMPT = "You are the user-understanding synthesis stage for the same session. You do not chat with the user and cannot write storage directly. Extract only evidence-backed, durable candidates and return strict JSON matching the requested schema.";
+export declare const UNDERSTANDING_INTERPRETER_SYSTEM_PROMPT = "You are xopc's user-understanding interpreter. You do not chat with the user and cannot write storage. Distinguish memory commands, memory questions, corrections, forgetting, durable user assertions, and ordinary task requests. Return strict JSON only. Never treat assistant text as evidence of a fact about the user.";
+export declare function buildUnderstandingInterpreterPrompt(options: {
+    mode: 'turn' | 'transcript';
+    availableTargets?: Array<{
+        id: string;
+        statement: string;
+    }>;
+}): string;

package/dist/src/agent/background-review/prompts.js

@@ -1,21 +1,34 @@
 import { USER_FACING_UNDERSTANDING_WRITING_GUIDANCE } from "../../user-context/understanding-writing.js";
 //#region src/agent/background-review/prompts.ts
-const MEMORY_REVIEW_USER_PROMPT = `Review the conversation above and identify durable user-understanding candidates.
+const UNDERSTANDING_INTERPRETER_SYSTEM_PROMPT = `You are xopc's user-understanding interpreter. You do not chat with the user and cannot write storage. Distinguish memory commands, memory questions, corrections, forgetting, durable user assertions, and ordinary task requests. Return strict JSON only. Never treat assistant text as evidence of a fact about the user.`;
+function buildUnderstandingInterpreterPrompt(options) {
+	const targets = options.availableTargets?.length ? `\nOnly these understanding IDs may be targeted for confirm, correction, or forgetting:\n${options.availableTargets.map((item) => `- ${item.id}: ${item.statement}`).join("\n")}` : "\nNo existing understanding IDs are available to target.";
+	return `Interpret the evidence-tagged conversation above for ${options.mode === "turn" ? "the latest user turn" : "durable transcript synthesis"}.
 
-Focus on:
-1. Has the user revealed things about themselves — persona, desires, preferences, or personal details worth remembering?
-2. Has the user expressed expectations about how you should behave, their work style, emotional-support preferences, boundaries, or how they want you to communicate?
-3. Has the user explicitly corrected a prior assumption? Prefer the correction and do not preserve the contradicted interpretation.
+Return exactly this JSON shape:
+{"intent":"none","candidates":[],"targetUnderstandingIds":[],"abstentionReason":"..."}
 
-Return JSON only, with this shape:
-{"candidates":[{"kind":"preference","content":"...","confidence":0.8,"importance":0.7,"durability":"durable","sensitivity":"normal","disclosurePolicy":"referenceable","evidenceRefs":["entry-id"]}]}
+Allowed intents: memory_create, memory_query, memory_confirm, memory_correct, memory_forget, user_assertion, task_request, none.
+
+Candidate shape:
+{"factKey":"communication:concise","statement":"...","kind":"preference","explicitness":"observed","durability":"durable","scopeHint":"global","confidence":0.8,"importance":0.7,"sensitivity":"normal","disclosurePolicy":"referenceable","evidence":[{"ref":"entry-id","quote":"exact quote from that user message"}],"selfContained":true,"unresolvedReferences":[]}
 
 Allowed kinds: preference, boundary, relationship, routine, current_state, long_term_goal, project_context, task_lesson, derived_insight.
-Every reviewed message is prefixed with an evidence_ref. Every candidate must list the exact one or more evidence_ref values that support it. Omit a candidate when no exact message supports it. Only include facts supported by the conversation and likely to matter in a future session. A temporary mood or one-off reaction is current context, not durable identity; omit it unless the user describes a recurring pattern that will matter later. Never include passwords, tokens, credentials, or speculative diagnoses. Use {"candidates":[]} when nothing qualifies.
 
-${USER_FACING_UNDERSTANDING_WRITING_GUIDANCE}
+Rules:
+- A question such as “Do you remember this goal?” is memory_query and creates no candidate.
+- A request to create, summarize, update, investigate, or track a goal is task_request, not a user goal.
+- Every candidate needs an exact quote from one or more user messages. Assistant messages may resolve context but never count as evidence.
+- Extract zero to eight independent candidates; do not collapse multiple facts into one.
+- factKey must be a stable language-neutral lowercase identifier using letters, digits, colons, or hyphens. Equivalent facts in different languages must use the same factKey.
+- Set selfContained=false and list unresolvedReferences for unresolved words such as this, that, it, 这个, 那个, or 它.
+- Omit temporary reactions and one-off task instructions.
+- Never include passwords, credentials, regulated identifiers, or speculative diagnoses.
+- For transcript mode, use explicitness=inferred unless the latest user message is itself an explicit memory command or correction.
+- If evidence is insufficient, return candidates=[] and explain abstentionReason.
 
-Do not turn a request about the current task into user understanding. Exclude requested outputs, follow-up instructions, project-note edits, investigations, and other one-off work. Every candidate must be a complete standalone profile statement or enduring pattern; never return a clause fragment beginning with a connector such as "and", "also", "并且", "以及", or "的事项". Use long_term_goal only when the person states an enduring personal goal, not when they ask the assistant to create, update, investigate, summarize, or track something.`;
-const UNDERSTANDING_REVIEW_SYSTEM_PROMPT = `You are the user-understanding synthesis stage for the same session. You do not chat with the user and cannot write storage directly. Extract only evidence-backed, durable candidates and return strict JSON matching the requested schema.`;
+${USER_FACING_UNDERSTANDING_WRITING_GUIDANCE}
+${targets}`;
+}
 //#endregion
-export { MEMORY_REVIEW_USER_PROMPT, UNDERSTANDING_REVIEW_SYSTEM_PROMPT };
+export { UNDERSTANDING_INTERPRETER_SYSTEM_PROMPT, buildUnderstandingInterpreterPrompt };

package/dist/src/agent/background-review/run-background-review.d.ts

@@ -1,7 +1,7 @@
 import { Agent } from '@earendil-works/pi-agent-core';
 import type { Config } from '../../config/schema.js';
 import type { MemoryManager } from '../memory/manager.js';
-import type { UnderstandingCandidate } from '../memory/understanding/types.js';
+import type { UnderstandingReviewResult } from '../memory/understanding/types.js';
 import type { BackgroundReviewSettings } from './settings.js';
 export interface RunBackgroundReviewParams {
     sessionKey: string;
@@ -10,5 +10,10 @@ export interface RunBackgroundReviewParams {
     memoryManager: MemoryManager;
     getConfig: () => Config | undefined;
 }
-export declare function parseUnderstandingCandidates(raw: string): UnderstandingCandidate[];
+export interface RunTurnUnderstandingParams extends Omit<RunBackgroundReviewParams, 'settings'> {
+    turnId: string;
+    userText: string;
+    maxHistoryMessages?: number;
+}
+export declare function runTurnUnderstandingReview(params: RunTurnUnderstandingParams): Promise<UnderstandingReviewResult>;
 export declare function runBackgroundReviewTurn(params: RunBackgroundReviewParams): Promise<void>;

package/dist/src/agent/background-review/run-background-review.js

@@ -1,54 +1,60 @@
 import { createLogger } from "../../utils/logger/index.js";
 import { init_logger } from "../../utils/logger.js";
-import { UNDERSTANDING_KINDS } from "../../user-context/domain.js";
 import { finishContextExtractionRun } from "../../storage/sqlite/context-extraction-repository.js";
-import { createContextEvidence } from "../../storage/sqlite/user-context-repository.js";
-import { getSessionMetadata } from "../../storage/sqlite/session-repository.js";
+import { getTurnPersonalization } from "../../storage/sqlite/user-context-repository.js";
 import { loadCompactionSourceSnapshot } from "../../storage/sqlite/transcript-repository.js";
 import "../../storage/sqlite/index.js";
+import { extractProfileAgentId } from "../../config/agent-profile.js";
 import { init_sync_provider_auth, resolveProviderApiKeySync } from "../../auth/sync-provider-auth.js";
-import { getApiKeySync, init_providers } from "../../providers/index.js";
+import { getApiKeySync, init_providers, resolveModel } from "../../providers/index.js";
 import { createExtensionAwareStreamFn } from "../../providers/extension-stream-bridge.js";
 import { extractTextContent } from "../context/workspace.js";
 import { readAgentMessageContent } from "../memory/agent-message-access.js";
 import { resolveAgentTurnTimeoutMs, runAgentTurnWithTimeout } from "../orchestration/run-agent-turn-with-timeout.js";
-import { claimRegisteredExtraction, extractionInputHash } from "../../user-context/extraction/registry.js";
-import { isDurableUnderstandingCandidate } from "../../user-context/understandingQuality.js";
+import { resolveTypedModelRef } from "../../config/agent-typed-models.js";
+import { claimRegisteredExtraction } from "../../user-context/extraction/registry.js";
 import { isAssistantTurnAborted, isAssistantTurnFailed } from "../orchestration/llm-turn-retry.js";
-import { MEMORY_REVIEW_USER_PROMPT, UNDERSTANDING_REVIEW_SYSTEM_PROMPT } from "./prompts.js";
+import { emptyUnderstandingReview, executeUnderstandingInterpretation } from "../../user-context/extraction/executor.js";
+import { parseSemanticUnderstanding } from "../../user-context/extraction/semantic.js";
+import { UNDERSTANDING_INTERPRETER_SYSTEM_PROMPT, buildUnderstandingInterpreterPrompt } from "./prompts.js";
 import { Agent } from "@earendil-works/pi-agent-core";
 //#region src/agent/background-review/run-background-review.ts
 init_sync_provider_auth();
 init_providers();
 init_logger();
-const log = createLogger("BackgroundReview");
+const log = createLogger("UnderstandingInterpreter");
 function isReviewMessage(value) {
 	if (!value || typeof value !== "object") return false;
 	const role = value.role;
 	return role === "user" || role === "assistant";
 }
-function tagMessage(message, entryId) {
-	const copy = JSON.parse(JSON.stringify(message));
-	const tag = `[evidence_ref:${entryId}]\n`;
-	const messageContent = readAgentMessageContent(copy);
-	if (typeof messageContent === "string") return {
+function messageText(message) {
+	const content = readAgentMessageContent(message);
+	if (typeof content === "string") return content;
+	return Array.isArray(content) ? extractTextContent(content) : "";
+}
+function tagMessage(entry) {
+	const copy = JSON.parse(JSON.stringify(entry.message));
+	const tag = `[evidence_ref:${entry.ref}] [role:${entry.role}]\n`;
+	const content = readAgentMessageContent(copy);
+	if (typeof content === "string") return {
 		...copy,
-		content: `${tag}${messageContent}`
+		content: `${tag}${content}`
 	};
-	if (Array.isArray(messageContent)) {
-		const content = [...messageContent];
-		const first = content[0];
-		if (first?.type === "text") content[0] = {
+	if (Array.isArray(content)) {
+		const parts = [...content];
+		const first = parts[0];
+		if (first?.type === "text") parts[0] = {
 			...first,
 			text: `${tag}${first.text ?? ""}`
 		};
-		else content.unshift({
+		else parts.unshift({
 			type: "text",
 			text: tag
 		});
 		return {
 			...copy,
-			content
+			content: parts
 		};
 	}
 	return copy;
@@ -56,89 +62,75 @@ function tagMessage(message, entryId) {
 function loadEvidenceMessages(sessionKey, max) {
 	const snapshot = loadCompactionSourceSnapshot(sessionKey);
 	if (!snapshot) return [];
-	return snapshot.entries.filter((entry) => isReviewMessage(entry.row)).slice(-max).map((entry) => ({
-		entryId: entry.entryId,
-		createdAt: entry.createdAt,
-		message: entry.row
-	}));
+	return snapshot.entries.filter((entry) => isReviewMessage(entry.row)).slice(-max).map((entry) => {
+		const message = entry.row;
+		return {
+			ref: entry.entryId,
+			role: message.role,
+			text: messageText(message),
+			createdAt: entry.createdAt,
+			message
+		};
+	});
 }
-const ALLOWED_UNDERSTANDING_KINDS = new Set(UNDERSTANDING_KINDS);
-const ALLOWED_SENSITIVITIES = new Set([
-	"normal",
-	"personal",
-	"secret",
-	"regulated"
-]);
 function lastAssistantText(agent) {
-	for (let i = agent.state.messages.length - 1; i >= 0; i--) {
+	for (let i = agent.state.messages.length - 1; i >= 0; i -= 1) {
 		const message = agent.state.messages[i];
-		if (message.role !== "assistant") continue;
-		return Array.isArray(message.content) ? extractTextContent(message.content) : String(message.content);
+		if (message.role === "assistant") return messageText(message);
 	}
 	return "";
 }
-function parseBackgroundCandidates(raw) {
-	const fenced = /```(?:json)?\s*([\s\S]*?)```/i.exec(raw)?.[1];
-	const start = raw.indexOf("{");
-	const end = raw.lastIndexOf("}");
-	const candidateJson = fenced ?? (start >= 0 && end > start ? raw.slice(start, end + 1) : raw);
+function isLocalModel(model) {
+	if (["ollama", "lmstudio"].includes(model.provider)) return true;
 	try {
-		const parsed = JSON.parse(candidateJson);
-		if (!Array.isArray(parsed.candidates)) return [];
-		const output = [];
-		for (const value of parsed.candidates.slice(0, 8)) {
-			if (!value || typeof value !== "object") continue;
-			const item = value;
-			if (!ALLOWED_UNDERSTANDING_KINDS.has(item.kind)) continue;
-			if (typeof item.content !== "string" || item.content.trim().length < 4) continue;
-			const kind = item.kind;
-			if (!isDurableUnderstandingCandidate(kind, item.content)) continue;
-			const confidence = typeof item.confidence === "number" ? item.confidence : .65;
-			const importance = typeof item.importance === "number" ? item.importance : .5;
-			const durability = item.durability === "ephemeral" || item.durability === "recurring" ? item.durability : "durable";
-			const sensitivity = ALLOWED_SENSITIVITIES.has(item.sensitivity) ? item.sensitivity : "personal";
-			const disclosurePolicy = item.disclosurePolicy === "silent" || item.disclosurePolicy === "ask_before_reference" ? item.disclosurePolicy : "referenceable";
-			const evidenceRefs = Array.isArray(item.evidenceRefs) ? [...new Set(item.evidenceRefs.filter((value) => typeof value === "string" && value.trim().length > 0))] : [];
-			output.push({
-				kind,
-				content: item.content.trim(),
-				confidence: Math.max(0, Math.min(1, confidence)),
-				importance: Math.max(0, Math.min(1, importance)),
-				explicitness: "inferred",
-				durability,
-				sensitivity,
-				disclosurePolicy,
-				evidenceRefs
-			});
-		}
-		return output;
+		const hostname = new URL(model.baseUrl).hostname;
+		return hostname === "localhost" || hostname === "127.0.0.1" || hostname === "::1";
 	} catch {
-		return [];
+		return false;
 	}
 }
-function parseUnderstandingCandidates(raw) {
-	return parseBackgroundCandidates(raw).map(({ evidenceRefs: _evidenceRefs, ...candidate }) => candidate);
-}
-async function runUnderstandingReview(params) {
-	const { sessionKey, mainAgent, settings, memoryManager, getConfig } = params;
-	const evidenceMessages = loadEvidenceMessages(sessionKey, settings.maxHistoryMessages);
-	if (!evidenceMessages.length) {
-		log.debug({ sessionKey }, "User-understanding review skipped because no persisted evidence was available");
-		return;
+function resolveInterpreterRuntime(params) {
+	const config = params.getConfig();
+	const processingPolicy = config?.userContext.understanding.processingPolicy ?? "remote_allowed";
+	let model;
+	if (config) {
+		const agentId = extractProfileAgentId(params.sessionKey, config);
+		for (const role of ["understanding", "small"]) {
+			const ref = resolveTypedModelRef(config, agentId, role);
+			if (!ref) continue;
+			try {
+				model = resolveModel(ref);
+				break;
+			} catch (err) {
+				log.debug({
+					err,
+					agentId,
+					role,
+					modelRef: ref
+				}, "Configured understanding model could not be resolved");
+			}
+		}
 	}
-	const lastEvidence = evidenceMessages[evidenceMessages.length - 1];
-	const extraction = claimRegisteredExtraction({
-		extractorId: "transcript-synthesis",
-		sourceRef: `session:${sessionKey}:window:${evidenceMessages[0].entryId}:${lastEvidence.entryId}`,
-		contentForHash: evidenceMessages.map((entry) => entry.entryId).join("\n"),
-		processingPolicy: "remote_allowed",
-		destination: "remote_model"
-	});
-	if (!extraction.shouldExecute) return;
+	model ??= params.mainAgent.state.model;
+	if (processingPolicy === "local_only" && !isLocalModel(model)) {
+		log.debug({
+			sessionKey: params.sessionKey,
+			provider: model.provider,
+			modelId: model.id
+		}, "Understanding interpretation skipped because no local model is configured");
+		return null;
+	}
+	return {
+		model,
+		processingPolicy,
+		destination: isLocalModel(model) ? "local_model" : "remote_model"
+	};
+}
+async function interpret(params) {
 	const reviewAgent = new Agent({
 		initialState: {
-			systemPrompt: UNDERSTANDING_REVIEW_SYSTEM_PROMPT,
-			model: mainAgent.state.model,
+			systemPrompt: UNDERSTANDING_INTERPRETER_SYSTEM_PROMPT,
+			model: params.model,
 			thinkingLevel: "off",
 			tools: [],
 			messages: []
@@ -146,79 +138,71 @@ async function runUnderstandingReview(params) {
 		streamFn: createExtensionAwareStreamFn(),
 		getApiKey: (provider) => resolveProviderApiKeySync(provider) ?? getApiKeySync(provider) ?? ""
 	});
-	reviewAgent.state.messages = evidenceMessages.map((entry) => tagMessage(entry.message, entry.entryId));
-	const timeoutMs = Math.min(settings.maxDurationMs, resolveAgentTurnTimeoutMs(getConfig()));
+	reviewAgent.state.messages = params.evidence.map(tagMessage);
 	try {
 		await runAgentTurnWithTimeout(reviewAgent, async () => {
 			await reviewAgent.prompt({
 				role: "user",
-				content: MEMORY_REVIEW_USER_PROMPT,
+				content: buildUnderstandingInterpreterPrompt({
+					mode: params.mode,
+					availableTargets: params.availableTargets
+				}),
 				timestamp: Date.now()
 			});
 			await reviewAgent.waitForIdle();
-		}, timeoutMs);
+		}, Math.min(params.timeoutMs, resolveAgentTurnTimeoutMs(params.getConfig())));
 	} catch (err) {
 		log.warn({
 			err,
-			sessionKey
-		}, "User-understanding review failed or timed out");
+			sessionKey: params.sessionKey
+		}, "User-understanding interpretation failed or timed out");
 		reviewAgent.abort();
 		await reviewAgent.waitForIdle().catch(() => {});
-		finishContextExtractionRun({
-			runId: extraction.run.id,
-			status: "failed",
-			errorCode: "model_failed"
-		});
-		return;
+		return null;
 	}
-	if (isAssistantTurnAborted(reviewAgent) || isAssistantTurnFailed(reviewAgent)) {
+	if (isAssistantTurnAborted(reviewAgent) || isAssistantTurnFailed(reviewAgent)) return null;
+	return parseSemanticUnderstanding(lastAssistantText(reviewAgent), params.evidence, params.availableTargets.map((item) => item.id));
+}
+async function executeReview(params) {
+	const runtime = resolveInterpreterRuntime(params);
+	if (!runtime) return emptyUnderstandingReview();
+	const extraction = claimRegisteredExtraction({
+		extractorId: params.extractorId,
+		sourceRef: params.sourceRef,
+		contentForHash: params.contentForHash,
+		processingPolicy: runtime.processingPolicy,
+		destination: runtime.destination
+	});
+	if (!extraction.shouldExecute) return emptyUnderstandingReview();
+	const interpretation = await interpret({
+		...params,
+		model: runtime.model
+	});
+	if (!interpretation) {
 		finishContextExtractionRun({
 			runId: extraction.run.id,
 			status: "failed",
-			errorCode: "model_failed"
+			errorCode: "model_or_schema_failed"
 		});
-		return;
+		return emptyUnderstandingReview();
 	}
-	const candidates = parseBackgroundCandidates(lastAssistantText(reviewAgent));
-	let applied = 0;
 	try {
-		const evidenceByRef = new Map(evidenceMessages.map((entry) => [entry.entryId, entry]));
-		const projectId = getSessionMetadata(sessionKey)?.projectId;
-		const outputs = [];
-		for (const { evidenceRefs, ...candidate } of candidates) {
-			const referenced = evidenceRefs.flatMap((ref) => {
-				const entry = evidenceByRef.get(ref);
-				return entry ? [entry] : [];
-			});
-			if (!referenced.length) {
-				outputs.push({
-					candidateKey: `${candidate.kind}:${candidate.content}`,
-					outcome: "rejected"
-				});
-				continue;
-			}
-			const evidenceIds = referenced.map((entry) => createContextEvidence({
-				sourceType: "conversation",
-				sourceRef: `session:${sessionKey}:entry:${entry.entryId}`,
-				sourceRunId: extraction.run.id,
-				sessionId: sessionKey,
-				messageId: entry.entryId,
-				contentHash: extractionInputHash(JSON.stringify(entry.message)),
-				retentionPolicy: "derived_only",
-				processingPolicy: "remote_allowed",
-				extractorId: "transcript-synthesis",
-				extractorVersion: "1",
-				trustLevel: "owner",
-				observedAt: entry.createdAt
-			}).id);
-			const result = await memoryManager.applyUnderstandingCandidates([candidate], {
-				sessionKey,
-				...projectId ? { projectId } : {},
-				evidenceIds,
-				reviewSource: "background",
-				extractionRunId: extraction.run.id
-			});
-			outputs.push(...(result.writeOutputs ?? []).map((output) => ({
+		const result = await executeUnderstandingInterpretation({
+			interpretation,
+			evidence: params.evidence,
+			extractionRunId: extraction.run.id,
+			extractorId: params.extractorId,
+			sessionKey: params.sessionKey,
+			...params.turnId ? { turnId: params.turnId } : {},
+			memoryManager: params.memoryManager,
+			getConfig: params.getConfig,
+			reviewSource: params.mode === "turn" ? "turn" : "background",
+			processingPolicy: runtime.processingPolicy
+		});
+		finishContextExtractionRun({
+			runId: extraction.run.id,
+			status: "completed",
+			outputs: result.writeOutputs?.map((output) => ({
 				candidateKey: output.candidateKey,
 				...output.objectId ? {
 					objectType: "understanding",
@@ -226,30 +210,61 @@ async function runUnderstandingReview(params) {
 				} : {},
 				...output.versionId ? { versionId: output.versionId } : {},
 				outcome: output.outcome
-			})));
-			applied += 1;
-		}
-		finishContextExtractionRun({
-			runId: extraction.run.id,
-			status: "completed",
-			outputs
+			}))
 		});
-	} catch (error) {
+		return result;
+	} catch (err) {
 		finishContextExtractionRun({
 			runId: extraction.run.id,
 			status: "failed",
 			errorCode: "write_failed"
 		});
-		throw error;
+		throw err;
 	}
-	log.debug({
-		sessionKey,
-		candidateCount: candidates.length,
-		applied
-	}, "User-understanding review completed");
+}
+async function runTurnUnderstandingReview(params) {
+	const evidence = loadEvidenceMessages(params.sessionKey, params.maxHistoryMessages ?? 12);
+	if (!evidence.length) return emptyUnderstandingReview();
+	const availableTargets = getTurnPersonalization(params.turnId)?.items.flatMap((item) => {
+		if (item.objectType !== "understanding" || item.decision !== "selected") return [];
+		return [{
+			id: item.objectId,
+			statement: item.content
+		}];
+	}) ?? [];
+	return executeReview({
+		sessionKey: params.sessionKey,
+		mainAgent: params.mainAgent,
+		memoryManager: params.memoryManager,
+		getConfig: params.getConfig,
+		evidence,
+		mode: "turn",
+		extractorId: "turn-semantics",
+		sourceRef: `session:${params.sessionKey}:turn:${params.turnId}`,
+		contentForHash: params.userText,
+		availableTargets,
+		timeoutMs: 3e4,
+		turnId: params.turnId
+	});
 }
 async function runBackgroundReviewTurn(params) {
-	await runUnderstandingReview(params);
+	const evidence = loadEvidenceMessages(params.sessionKey, params.settings.maxHistoryMessages);
+	if (!evidence.length) return;
+	const first = evidence[0];
+	const last = evidence[evidence.length - 1];
+	await executeReview({
+		sessionKey: params.sessionKey,
+		mainAgent: params.mainAgent,
+		memoryManager: params.memoryManager,
+		getConfig: params.getConfig,
+		evidence,
+		mode: "transcript",
+		extractorId: "transcript-synthesis",
+		sourceRef: `session:${params.sessionKey}:window:${first.ref}:${last.ref}`,
+		contentForHash: evidence.map((entry) => entry.ref).join("\n"),
+		availableTargets: [],
+		timeoutMs: params.settings.maxDurationMs
+	});
 }
 //#endregion
-export { parseUnderstandingCandidates, runBackgroundReviewTurn };
+export { runBackgroundReviewTurn, runTurnUnderstandingReview };

package/dist/src/agent/memory/index.d.ts

@@ -5,7 +5,7 @@ export type { UserContextPlan } from './context/types.js';
 export { createMemoryManagerFromConfig } from './create-memory-manager.js';
 export { isMemorySubsystemEnabled, shouldPlanUserContextThisTurn, } from './memory-config.js';
 export { MemoryManager } from './manager.js';
-export { UserUnderstandingService, extractExplicitUnderstandingCandidates } from './understanding/service.js';
+export { UserUnderstandingService } from './understanding/service.js';
 export type { UnderstandingCandidate, UnderstandingReviewResult } from './understanding/types.js';
 export { discoverMemoryPlugins } from './plugin-discovery.js';
 export type { MemoryPluginMetadata } from './plugin-discovery.js';

package/dist/src/agent/memory/index.js

@@ -3,9 +3,9 @@ import { buildUserContextBlock, sanitizeUserContextFenceEscapes } from "./contex
 import { UserContextPlanner } from "../../user-context/planner.js";
 import { extractAgentUserPlainText } from "./user-message-text.js";
 import { BuiltinMemoryProvider } from "./builtin-provider.js";
-import { UserUnderstandingService, extractExplicitUnderstandingCandidates } from "./understanding/service.js";
+import { UserUnderstandingService } from "./understanding/service.js";
 import { MemoryManager } from "./manager.js";
 import { discoverMemoryPlugins } from "./plugin-discovery.js";
 import { createMemoryManagerFromConfig } from "./create-memory-manager.js";
 import { StubMemoryProvider } from "./stub-memory-provider.js";
-export { BuiltinMemoryProvider, MemoryManager, StubMemoryProvider, UserContextPlanner, UserUnderstandingService, buildUserContextBlock, createMemoryManagerFromConfig, discoverMemoryPlugins, extractAgentUserPlainText, extractExplicitUnderstandingCandidates, isMemorySubsystemEnabled, sanitizeUserContextFenceEscapes, shouldPlanUserContextThisTurn };
+export { BuiltinMemoryProvider, MemoryManager, StubMemoryProvider, UserContextPlanner, UserUnderstandingService, buildUserContextBlock, createMemoryManagerFromConfig, discoverMemoryPlugins, extractAgentUserPlainText, isMemorySubsystemEnabled, sanitizeUserContextFenceEscapes, shouldPlanUserContextThisTurn };