@xopcai/xopc 0.0.248 → 0.0.250

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

@@ -1,34 +1,48 @@
-import { USER_FACING_UNDERSTANDING_WRITING_GUIDANCE } from "../../user-context/understanding-writing.js";
 //#region src/agent/background-review/prompts.ts
-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.";
+const USER_MODEL_INTERPRETER_SYSTEM_PROMPT = `You are xopc's user-model interpreter. You do not chat with the user and cannot write storage. Distinguish explicit memory commands, corrections, forgetting, durable user assertions, durable goals, collaboration rules, and ordinary task requests. Return strict JSON only. Assistant text is never evidence about the user.`;
+function buildUserModelInterpreterPrompt(options) {
+	const targets = options.availableTargets?.length ? `\nThese assertion IDs may be targeted for confirm, correction, or forgetting:\n${options.availableTargets.map((item) => `- ${item.id}: ${item.statement}`).join("\n")}` : "\nNo existing assertion IDs are available to target.";
 	return `Interpret the evidence-tagged conversation above for ${options.mode === "turn" ? "the latest user turn" : "durable transcript synthesis"}.
 
-Return exactly this JSON shape:
-{"intent":"none","candidates":[],"targetUnderstandingIds":[],"abstentionReason":"..."}
+Evidence time: ${options.evidenceTimestamp}
+User timezone: ${options.timezone}
 
-Allowed intents: memory_create, memory_query, memory_confirm, memory_correct, memory_forget, user_assertion, task_request, none.
+Return exactly this top-level shape:
+{"intent":"none","candidates":[],"goals":[],"collaborationRules":[],"targetAssertionIds":[],"abstentionReason":"..."}
 
 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":[]}
+{"subject":{"type":"user","id":"self"},"predicate":"preference.response.detail","cardinality":"single","scope":{"type":"global"},"kind":"preference","value":"concise","normalizedValue":"concise","statement":"The user prefers concise answers.","authority":"user_observed","confidence":0.9,"declaredImportance":0.8,"inferredImportance":0.6,"consequence":"medium","actionability":1,"volatility":"stable","sensitivity":"normal","disclosurePolicy":"referenceable","applicability":{"operation":"response"},"temporalResolution":"exact","evidence":[{"ref":"entry-id","quote":"exact quote"}],"selfContained":true,"unresolvedReferences":[]}
 
-Allowed kinds: preference, boundary, relationship, routine, current_state, long_term_goal, project_context, task_lesson, derived_insight.
+Goal shape:
+{"title":"Ship Atlas","desiredOutcome":"Atlas is released with all acceptance checks passing.","scope":{"type":"project","id":"exact-project-id"},"declaredImportance":0.9,"targetAt":"2026-09-30T18:00:00+08:00","evidence":[{"ref":"entry-id","quote":"exact quote"}],"selfContained":true,"unresolvedReferences":[]}
+
+Collaboration rule shape:
+{"category":"communication","priority":10,"scope":{"type":"global"},"conditions":{"enforcementLevel":"prompt"},"statement":"Keep status updates concise.","evidence":[{"ref":"entry-id","quote":"exact quote"}],"selfContained":true,"unresolvedReferences":[]}
+
+Allowed intents: remember, query, confirm, correct, forget, user_assertion, task, none.
+Allowed subject types: user, person, goal, project, topic.
+Allowed kinds: identity, preference, value, routine, capability, relationship, current_state, derived_insight.
+Allowed scopes: global without id; agent, workspace, project, or session with the exact supplied id.
 
 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 它.
+- A question about what is remembered uses query and creates no candidate.
+- A request to create, summarize, update, investigate, or track work uses task, not a user assertion.
+- Every candidate needs an exact quote from a user message. Assistant messages can resolve context but are never evidence.
+- Extract zero to eight independent candidates. Each candidate represents one stable predicate and one value.
+- Extract a goal only when the user explicitly describes a durable desired outcome, not a one-off task request.
+- Extract a collaboration rule only when the user explicitly states an ongoing way the assistant should communicate, execute, or respect a boundary.
+- Use only prompt enforcement for inferred collaboration rules. Never invent tool gates or deny effects.
+- predicate is a stable language-neutral lowercase identifier. The value is excluded from predicate identity.
+- Preserve importance stated by the user in declaredImportance; estimate inferredImportance separately.
+- Use current_state or event volatility only with a bounded validTo. If relative time cannot be resolved, use temporalResolution=unresolved and omit resolved time fields.
+- Resolve relative time using the evidence time and timezone. Put ISO 8601 timestamps with offsets in validFrom, validTo, and reviewAt.
+- For an explicit correction, set correctionOfAssertionId on the replacement candidate.
+- Set selfContained=false and list unresolvedReferences for unresolved pronouns or references.
 - 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.
+- In transcript mode, use system_inferred unless a quoted user message is itself an explicit memory command.
 - If evidence is insufficient, return candidates=[] and explain abstentionReason.
-
-${USER_FACING_UNDERSTANDING_WRITING_GUIDANCE}
 ${targets}`;
 }
 //#endregion
-export { UNDERSTANDING_INTERPRETER_SYSTEM_PROMPT, buildUnderstandingInterpreterPrompt };
+export { USER_MODEL_INTERPRETER_SYSTEM_PROMPT, buildUserModelInterpreterPrompt };

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

@@ -1,19 +1,18 @@
 import { Agent } from '@earendil-works/pi-agent-core';
 import type { Config } from '../../config/schema.js';
-import type { MemoryManager } from '../memory/manager.js';
-import type { UnderstandingReviewResult } from '../memory/understanding/types.js';
+import { type UserModelCaptureResult } from '../../user-model/capture/index.js';
 import type { BackgroundReviewSettings } from './settings.js';
-export interface RunBackgroundReviewParams {
+export interface RunUserModelReviewParams {
     sessionKey: string;
     mainAgent: Agent;
     settings: BackgroundReviewSettings;
-    memoryManager: MemoryManager;
+    workspaceId: string;
     getConfig: () => Config | undefined;
 }
-export interface RunTurnUnderstandingParams extends Omit<RunBackgroundReviewParams, 'settings'> {
+export interface RunTurnUserModelCaptureParams extends Omit<RunUserModelReviewParams, 'settings'> {
     turnId: string;
     userText: string;
     maxHistoryMessages?: number;
 }
-export declare function runTurnUnderstandingReview(params: RunTurnUnderstandingParams): Promise<UnderstandingReviewResult>;
-export declare function runBackgroundReviewTurn(params: RunBackgroundReviewParams): Promise<void>;
+export declare function runTurnUserModelCapture(params: RunTurnUserModelCaptureParams): Promise<UserModelCaptureResult>;
+export declare function runBackgroundUserModelReview(params: RunUserModelReviewParams): Promise<void>;

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

@@ -1,7 +1,7 @@
 import { createLogger } from "../../utils/logger/index.js";
 import { init_logger } from "../../utils/logger.js";
 import { finishContextExtractionRun } from "../../storage/sqlite/context-extraction-repository.js";
-import { getTurnPersonalization } from "../../storage/sqlite/user-context-repository.js";
+import { getSessionMetadata } from "../../storage/sqlite/session-repository.js";
 import { loadCompactionSourceSnapshot } from "../../storage/sqlite/transcript-repository.js";
 import "../../storage/sqlite/index.js";
 import { extractProfileAgentId } from "../../config/agent-profile.js";
@@ -9,20 +9,22 @@ import { init_sync_provider_auth, resolveProviderApiKeySync } from "../../auth/s
 import { getApiKeySync, init_providers, resolveModel } from "../../providers/index.js";
 import { createExtensionAwareStreamFn } from "../../providers/extension-stream-bridge.js";
 import { extractTextContent } from "../context/workspace.js";
+import { listUserAssertions } from "../../user-model/repository.js";
 import { readAgentMessageContent } from "../memory/agent-message-access.js";
 import { isAssistantTurnAborted, isAssistantTurnFailed } from "../orchestration/llm-turn-retry.js";
 import { resolveAgentTurnTimeoutMs, runAgentTurnWithTimeout } from "../orchestration/run-agent-turn-with-timeout.js";
-import { claimRegisteredExtraction } from "../../user-context/extraction/registry.js";
 import { resolveModelIntentRef } from "../../config/agent-model-intents.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 { claimRegisteredExtraction } from "../../user-context/extraction/registry.js";
+import { emptyUserModelCaptureResult, executeUserModelInterpretation } from "../../user-model/capture/executor.js";
+import { parseUserModelInterpretation } from "../../user-model/capture/semantic.js";
+import "../../user-model/capture/index.js";
+import { USER_MODEL_INTERPRETER_SYSTEM_PROMPT, buildUserModelInterpreterPrompt } 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("UnderstandingInterpreter");
+const log = createLogger("UserModelInterpreter");
 function isReviewMessage(value) {
 	if (!value || typeof value !== "object") return false;
 	const role = value.role;
@@ -91,7 +93,7 @@ function isLocalModel(model) {
 }
 function resolveInterpreterRuntime(params) {
 	const config = params.getConfig();
-	const processingPolicy = config?.userContext.understanding.processingPolicy ?? "remote_allowed";
+	const processingPolicy = config?.userContext.userModel.processingPolicy ?? "remote_allowed";
 	let model;
 	if (config) {
 		const agentId = extractProfileAgentId(params.sessionKey, config);
@@ -124,7 +126,7 @@ function resolveInterpreterRuntime(params) {
 async function interpret(params) {
 	const reviewAgent = new Agent({
 		initialState: {
-			systemPrompt: UNDERSTANDING_INTERPRETER_SYSTEM_PROMPT,
+			systemPrompt: USER_MODEL_INTERPRETER_SYSTEM_PROMPT,
 			model: params.model,
 			thinkingLevel: "off",
 			tools: [],
@@ -136,11 +138,14 @@ async function interpret(params) {
 	reviewAgent.state.messages = params.evidence.map(tagMessage);
 	try {
 		await runAgentTurnWithTimeout(reviewAgent, async () => {
+			const timezone = params.getConfig()?.userContext.userModel.maintenance.timezone ?? Intl.DateTimeFormat().resolvedOptions().timeZone ?? "UTC";
 			await reviewAgent.prompt({
 				role: "user",
-				content: buildUnderstandingInterpreterPrompt({
+				content: buildUserModelInterpreterPrompt({
 					mode: params.mode,
-					availableTargets: params.availableTargets
+					availableTargets: params.availableTargets,
+					evidenceTimestamp: new Date(params.evidence.at(-1)?.createdAt ?? Date.now()).toISOString(),
+					timezone
 				}),
 				timestamp: Date.now()
 			});
@@ -156,11 +161,11 @@ async function interpret(params) {
 		return null;
 	}
 	if (isAssistantTurnAborted(reviewAgent) || isAssistantTurnFailed(reviewAgent)) return null;
-	return parseSemanticUnderstanding(lastAssistantText(reviewAgent), params.evidence, params.availableTargets.map((item) => item.id));
+	return parseUserModelInterpretation(lastAssistantText(reviewAgent), params.evidence, params.availableTargets.map((item) => item.id));
 }
 async function executeReview(params) {
 	const runtime = resolveInterpreterRuntime(params);
-	if (!runtime) return emptyUnderstandingReview();
+	if (!runtime) return emptyUserModelCaptureResult();
 	const extraction = claimRegisteredExtraction({
 		extractorId: params.extractorId,
 		sourceRef: params.sourceRef,
@@ -168,7 +173,7 @@ async function executeReview(params) {
 		processingPolicy: runtime.processingPolicy,
 		destination: runtime.destination
 	});
-	if (!extraction.shouldExecute) return emptyUnderstandingReview();
+	if (!extraction.shouldExecute) return emptyUserModelCaptureResult();
 	const interpretation = await interpret({
 		...params,
 		model: runtime.model
@@ -179,32 +184,36 @@ async function executeReview(params) {
 			status: "failed",
 			errorCode: "model_or_schema_failed"
 		});
-		return emptyUnderstandingReview();
+		return emptyUserModelCaptureResult();
 	}
 	try {
-		const result = await executeUnderstandingInterpretation({
+		const config = params.getConfig();
+		const agentId = config ? extractProfileAgentId(params.sessionKey, config) : "main";
+		const write = config?.userContext.userModel.writePolicy ?? "deny";
+		const result = executeUserModelInterpretation({
 			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
+			scopeContext: {
+				sessionId: params.sessionKey,
+				agentId,
+				workspaceId: params.workspaceId,
+				...getSessionMetadata(params.sessionKey)?.projectId ? { projectId: getSessionMetadata(params.sessionKey).projectId } : {}
+			},
+			policy: {
+				write,
+				sensitiveWrite: config?.userContext.userModel.sensitiveWritePolicy ?? "confirm",
+				processing: runtime.processingPolicy
+			},
+			...params.turnId ? { turnId: params.turnId } : {}
 		});
 		finishContextExtractionRun({
 			runId: extraction.run.id,
 			status: "completed",
-			outputs: result.writeOutputs?.map((output) => ({
+			outputs: result.outputs.map((output) => ({
 				candidateKey: output.candidateKey,
-				...output.objectId ? {
-					objectType: "understanding",
-					objectId: output.objectId
-				} : {},
-				...output.versionId ? { versionId: output.versionId } : {},
-				outcome: output.outcome
+				outcome: output.outcome === "deduplicated" ? "deduplicated" : output.outcome === "rejected" ? "rejected" : "created"
 			}))
 		});
 		return result;
@@ -217,20 +226,17 @@ async function executeReview(params) {
 		throw err;
 	}
 }
-async function runTurnUnderstandingReview(params) {
+async function runTurnUserModelCapture(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
-		}];
-	}) ?? [];
+	if (!evidence.length) return emptyUserModelCaptureResult();
+	const availableTargets = listUserAssertions({ limit: 200 }).map((item) => ({
+		id: item.id,
+		statement: item.statement
+	}));
 	return executeReview({
 		sessionKey: params.sessionKey,
 		mainAgent: params.mainAgent,
-		memoryManager: params.memoryManager,
+		workspaceId: params.workspaceId,
 		getConfig: params.getConfig,
 		evidence,
 		mode: "turn",
@@ -242,7 +248,7 @@ async function runTurnUnderstandingReview(params) {
 		turnId: params.turnId
 	});
 }
-async function runBackgroundReviewTurn(params) {
+async function runBackgroundUserModelReview(params) {
 	const evidence = loadEvidenceMessages(params.sessionKey, params.settings.maxHistoryMessages);
 	if (!evidence.length) return;
 	const first = evidence[0];
@@ -250,7 +256,7 @@ async function runBackgroundReviewTurn(params) {
 	await executeReview({
 		sessionKey: params.sessionKey,
 		mainAgent: params.mainAgent,
-		memoryManager: params.memoryManager,
+		workspaceId: params.workspaceId,
 		getConfig: params.getConfig,
 		evidence,
 		mode: "transcript",
@@ -262,4 +268,4 @@ async function runBackgroundReviewTurn(params) {
 	});
 }
 //#endregion
-export { runBackgroundReviewTurn, runTurnUnderstandingReview };
+export { runBackgroundUserModelReview, runTurnUserModelCapture };

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

@@ -1,7 +1,6 @@
 import type { Config } from '../../config/schema.js';
 export interface BackgroundReviewSettings {
     enabled: boolean;
-    adaptiveCadence: boolean;
     reviewIntervalTurns: number;
     maxHistoryMessages: number;
     maxDurationMs: number;

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

@@ -1,20 +1,19 @@
 //#region src/agent/background-review/settings.ts
 const DEFAULT_SETTINGS = {
 	enabled: false,
-	adaptiveCadence: true,
 	reviewIntervalTurns: 10,
 	maxHistoryMessages: 80,
 	maxDurationMs: 12e4
 };
 function resolveBackgroundReviewSettings(config) {
 	if (!config) return DEFAULT_SETTINGS;
-	const { understanding } = config.userContext;
+	const userModel = config.userContext.userModel;
+	const extraction = userModel.extraction;
 	return {
-		enabled: config.userContext.enabled && understanding.enabled,
-		adaptiveCadence: understanding.adaptiveCadence,
-		reviewIntervalTurns: understanding.reviewIntervalTurns,
-		maxHistoryMessages: understanding.maxHistoryMessages,
-		maxDurationMs: understanding.maxDurationMs
+		enabled: config.userContext.enabled && userModel.enabled,
+		reviewIntervalTurns: extraction.reviewIntervalTurns,
+		maxHistoryMessages: extraction.maxHistoryMessages,
+		maxDurationMs: extraction.maxDurationMs
 	};
 }
 //#endregion

package/dist/src/agent/context/audit.d.ts

@@ -0,0 +1,38 @@
+import type { ExecutionContext } from './execution-context.types.js';
+export interface ExecutionContextBudget {
+    maxAssertions: number;
+    maxKnowledge: number;
+    maxChars: number;
+}
+export interface ExecutionContextAudit {
+    runId: string;
+    principalId: string;
+    turnId: string;
+    sessionId: string;
+    queryHash: string;
+    asOf: number;
+    budget: ExecutionContextBudget;
+    metrics: Record<string, number>;
+    items: Array<{
+        objectType: 'rule' | 'assertion' | 'goal' | 'priority' | 'knowledge';
+        objectId: string;
+        score?: number;
+        reasons: string[];
+        included: boolean;
+    }>;
+    createdAt: number;
+}
+export declare function recordExecutionContext(context: ExecutionContext, input: {
+    turnId: string;
+    sessionId: string;
+    budget: ExecutionContextBudget;
+    renderedChars: number;
+    includedContext?: ExecutionContext;
+}): void;
+export declare function getExecutionContextAudit(turnId: string): ExecutionContextAudit | undefined;
+export declare function recordExecutionContextFeedback(input: {
+    turnId: string;
+    rating: 'helpful' | 'irrelevant';
+    reason?: string;
+}): boolean;
+export declare function getExecutionContextFeedbackScores(): Map<string, number>;

package/dist/src/agent/context/audit.js

@@ -0,0 +1,123 @@
+import { getSqliteDatabase, runSqliteWriteTransaction } from "../../storage/sqlite/transaction.js";
+import { createHash } from "node:crypto";
+//#region src/agent/context/audit.ts
+function recordExecutionContext(context, input) {
+	const createdAt = Date.now();
+	const included = /* @__PURE__ */ new Set();
+	const selected = input.includedContext ?? context;
+	for (const item of selected.rules) included.add(`rule:${item.id}`);
+	for (const item of selected.assertions) included.add(`assertion:${item.assertion.id}`);
+	for (const item of selected.goals) included.add(`goal:${item.id}`);
+	for (const item of selected.priorities) included.add(`priority:${item.id}`);
+	for (const item of selected.knowledge) included.add(`knowledge:${item.id}`);
+	const items = [
+		...context.rules.map((item) => ({
+			objectType: "rule",
+			objectId: item.id,
+			reasons: [`${item.enforcementLevel}_rule`],
+			included: included.has(`rule:${item.id}`)
+		})),
+		...context.assertions.map((item) => ({
+			objectType: "assertion",
+			objectId: item.assertion.id,
+			score: item.score,
+			reasons: item.reasons,
+			included: included.has(`assertion:${item.assertion.id}`)
+		})),
+		...context.goals.map((item) => ({
+			objectType: "goal",
+			objectId: item.id,
+			reasons: ["active_goal"],
+			included: included.has(`goal:${item.id}`)
+		})),
+		...context.priorities.map((item) => ({
+			objectType: "priority",
+			objectId: item.id,
+			score: item.urgency,
+			reasons: [`${item.rank}_priority`],
+			included: included.has(`priority:${item.id}`)
+		})),
+		...context.knowledge.map((item) => ({
+			objectType: "knowledge",
+			objectId: item.id,
+			score: item.importance,
+			reasons: ["task_relevant_knowledge"],
+			included: included.has(`knowledge:${item.id}`)
+		}))
+	];
+	const metrics = {
+		rules: context.rules.length,
+		assertions: context.assertions.length,
+		goals: context.goals.length,
+		priorities: context.priorities.length,
+		knowledge: context.knowledge.length,
+		includedRules: selected.rules.length,
+		includedAssertions: selected.assertions.length,
+		includedGoals: selected.goals.length,
+		includedPriorities: selected.priorities.length,
+		includedKnowledge: selected.knowledge.length,
+		renderedChars: input.renderedChars
+	};
+	runSqliteWriteTransaction((db) => {
+		if (db.prepare("SELECT 1 FROM execution_context_runs WHERE turn_id = ?").get(input.turnId)) return;
+		db.prepare(`INSERT INTO execution_context_runs (
+      run_id, principal_id, turn_id, session_id, query_hash, as_of,
+      budget_json, metrics_json, created_at
+    ) VALUES (?, 'local-owner', ?, ?, ?, ?, ?, ?, ?)`).run(context.traceId, input.turnId, input.sessionId, createHash("sha256").update(context.query).digest("hex"), context.asOf, JSON.stringify(input.budget), JSON.stringify(metrics), createdAt);
+		const insert = db.prepare(`INSERT INTO execution_context_items (
+      run_id, object_type, object_id, score, reasons_json, included, created_at
+    ) VALUES (?, ?, ?, ?, ?, ?, ?)`);
+		for (const item of items) insert.run(context.traceId, item.objectType, item.objectId, item.score ?? null, JSON.stringify(item.reasons), item.included ? 1 : 0, createdAt);
+	});
+}
+function getExecutionContextAudit(turnId) {
+	const db = getSqliteDatabase();
+	const run = db.prepare("SELECT * FROM execution_context_runs WHERE turn_id = ?").get(turnId);
+	if (!run) return void 0;
+	const rows = db.prepare(`SELECT object_type, object_id, score, reasons_json, included
+    FROM execution_context_items WHERE run_id = ? ORDER BY rowid`).all(run.run_id);
+	return {
+		runId: run.run_id,
+		principalId: run.principal_id,
+		turnId: run.turn_id,
+		sessionId: run.session_id,
+		queryHash: run.query_hash,
+		asOf: run.as_of,
+		budget: JSON.parse(run.budget_json),
+		metrics: JSON.parse(run.metrics_json),
+		items: rows.map((row) => ({
+			objectType: row.object_type,
+			objectId: row.object_id,
+			...row.score === null ? {} : { score: row.score },
+			reasons: JSON.parse(row.reasons_json),
+			included: row.included === 1
+		})),
+		createdAt: run.created_at
+	};
+}
+function recordExecutionContextFeedback(input) {
+	const now = Date.now();
+	const result = getSqliteDatabase().prepare(`INSERT INTO execution_context_feedback (
+    turn_id, rating, reason, created_at, updated_at
+  ) SELECT ?, ?, ?, ?, ? WHERE EXISTS (
+    SELECT 1 FROM execution_context_runs WHERE turn_id = ?
+  ) ON CONFLICT(turn_id) DO UPDATE SET
+    rating = excluded.rating, reason = excluded.reason, updated_at = excluded.updated_at`).run(input.turnId, input.rating, input.reason ?? null, now, now, input.turnId);
+	return Number(result.changes) > 0;
+}
+function getExecutionContextFeedbackScores() {
+	const rows = getSqliteDatabase().prepare(`SELECT i.object_type, i.object_id,
+      COUNT(*) AS samples,
+      SUM(CASE f.rating WHEN 'helpful' THEN 1 ELSE -1 END) AS balance
+    FROM execution_context_items i
+    JOIN execution_context_runs r ON r.run_id = i.run_id
+    JOIN (
+      SELECT turn_id, rating FROM execution_context_feedback
+      ORDER BY updated_at DESC LIMIT 500
+    ) f ON f.turn_id = r.turn_id
+    WHERE i.included = 1
+    GROUP BY i.object_type, i.object_id`).all();
+	return new Map(rows.flatMap((row) => row.samples < 2 ? [] : [[`${row.object_type}:${row.object_id}`, Math.max(-.1, Math.min(.1, row.balance / row.samples * .1))]]));
+}
+//#endregion
+export { getExecutionContextAudit, getExecutionContextFeedbackScores, recordExecutionContext, recordExecutionContextFeedback };

package/dist/src/agent/context/coordinator.d.ts

@@ -0,0 +1,31 @@
+import type { AgentMessage } from '@earendil-works/pi-agent-core';
+import type { Config } from '../../config/schema.js';
+import type { KnowledgeSource } from '../../knowledge-memory/index.js';
+import { type ExecutionContext } from './execution-context.js';
+export interface ExecutionContextPlan {
+    traceId: string;
+    modelMessage: AgentMessage;
+    executionContext?: ExecutionContext;
+    estimatedTokens: number;
+    contextChars: number;
+    contextItemCount: number;
+}
+export interface ExecutionContextCoordinatorOptions {
+    getConfig: () => Config | undefined;
+    getAccessForSession: (sessionKey: string) => {
+        userModel: boolean;
+        knowledge: boolean;
+        knowledgeSources: readonly KnowledgeSource[];
+    };
+    getWorkspaceIdForSession: (sessionKey: string) => string;
+    getProjectIdForSession: (sessionKey: string) => string | undefined;
+}
+export declare class ExecutionContextCoordinator {
+    private readonly options;
+    private readonly currentBySession;
+    constructor(options: ExecutionContextCoordinatorOptions);
+    forgetSession(sessionKey: string): void;
+    clear(): void;
+    getCurrent(sessionKey: string): ExecutionContext | undefined;
+    prepare(userMessage: AgentMessage, sessionKey: string, turnId: string): Promise<ExecutionContextPlan>;
+}

package/dist/src/agent/context/coordinator.js

@@ -0,0 +1,73 @@
+import { extractProfileAgentId } from "../../config/agent-profile.js";
+import { assembleTaskContext } from "../../tasks/task-context-assembler.js";
+import { recordExecutionContext } from "./audit.js";
+import { prependAgentContext } from "./prepend.js";
+import { extractAgentUserPlainText } from "../memory/user-message-text.js";
+import { buildExecutionContext, fitExecutionContextToChars } from "./execution-context.js";
+//#region src/agent/context/coordinator.ts
+var ExecutionContextCoordinator = class {
+	currentBySession = /* @__PURE__ */ new Map();
+	constructor(options) {
+		this.options = options;
+	}
+	forgetSession(sessionKey) {
+		this.currentBySession.delete(sessionKey);
+	}
+	clear() {
+		this.currentBySession.clear();
+	}
+	getCurrent(sessionKey) {
+		return this.currentBySession.get(sessionKey);
+	}
+	async prepare(userMessage, sessionKey, turnId) {
+		const empty = () => ({
+			traceId: "",
+			modelMessage: userMessage,
+			estimatedTokens: 0,
+			contextChars: 0,
+			contextItemCount: 0
+		});
+		const config = this.options.getConfig();
+		const access = this.options.getAccessForSession(sessionKey);
+		if (!config || !config.userContext.contextPlanning.enabled || !access.userModel && !access.knowledge) return empty();
+		const task = assembleTaskContext(sessionKey, extractAgentUserPlainText(userMessage));
+		const context = buildExecutionContext({
+			query: task.retrievalQuery,
+			agentId: extractProfileAgentId(sessionKey, config),
+			workspaceId: this.options.getWorkspaceIdForSession(sessionKey),
+			projectId: this.options.getProjectIdForSession(sessionKey),
+			sessionId: sessionKey,
+			maxAssertions: Math.min(config.userContext.contextPlanning.maxAssertions, task.allocation.maxResults),
+			maxKnowledge: Math.min(config.userContext.contextPlanning.maxKnowledge, task.allocation.maxResults),
+			includeUserModel: access.userModel,
+			includeKnowledge: access.knowledge,
+			knowledgeSources: access.knowledgeSources
+		});
+		this.currentBySession.set(sessionKey, context);
+		const maxChars = Math.min(config.userContext.contextPlanning.maxChars, task.allocation.maxChars);
+		const fitted = fitExecutionContextToChars(context, maxChars);
+		const rendered = fitted.rendered;
+		const contextItemCount = fitted.context.rules.length + fitted.context.assertions.length + fitted.context.goals.length + fitted.context.priorities.length + fitted.context.knowledge.length;
+		recordExecutionContext(context, {
+			turnId,
+			sessionId: sessionKey,
+			budget: {
+				maxAssertions: Math.min(config.userContext.contextPlanning.maxAssertions, task.allocation.maxResults),
+				maxKnowledge: Math.min(config.userContext.contextPlanning.maxKnowledge, task.allocation.maxResults),
+				maxChars
+			},
+			renderedChars: rendered.length,
+			includedContext: fitted.context
+		});
+		return {
+			traceId: context.traceId,
+			modelMessage: prependAgentContext(userMessage, rendered),
+			executionContext: context,
+			estimatedTokens: Math.ceil(rendered.length / 4),
+			contextChars: rendered.length,
+			contextItemCount
+		};
+	}
+};
+//#endregion
+export { ExecutionContextCoordinator };

package/dist/src/agent/context/execution-context.d.ts

@@ -0,0 +1,13 @@
+import type { ExecutionContext, ExecutionContextRequest, ExecutionRule } from './execution-context.types.js';
+export type { ExecutionContext, ExecutionContextRequest, ExecutionGoal, ExecutionPriority, ExecutionRule, RankedExecutionAssertion, RuleEnforcementLevel, } from './execution-context.types.js';
+export declare function buildExecutionContext(request: ExecutionContextRequest): ExecutionContext;
+export declare function renderExecutionContext(context: ExecutionContext): string;
+export declare function fitExecutionContextToChars(context: ExecutionContext, maxChars: number): {
+    context: ExecutionContext;
+    rendered: string;
+};
+export declare function evaluateToolGate(context: ExecutionContext, operation: string): {
+    allowed: boolean;
+    rule?: ExecutionRule;
+    reason?: string;
+};