@xopcai/xopc 0.0.247 → 0.0.249

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/commands/command-registry.d.ts

@@ -32,6 +32,7 @@ export declare class CommandRegistry {
     constructor(root?: string);
     private directory;
     private persist;
+    private receipts;
     start(input: {
         owner: string;
         command: string;

package/dist/src/agent/commands/command-registry.js

@@ -1,10 +1,11 @@
 import { resolveStateDir } from "../../config/paths-state.js";
 import { resolveGlobalSingleton } from "../../utils/global-singleton.js";
 import { init_paths } from "../../config/paths.js";
+import { DurableState } from "../../storage/sqlite/durable-state.js";
 import { isolatedCommand, removeCommandContainer } from "./command-isolation.js";
 import { readWorkspaceRevision } from "../coding/workspace-revision.js";
 import { join } from "node:path";
-import { appendFileSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { appendFileSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
 import { spawn } from "node:child_process";
 import { createHash, randomUUID } from "node:crypto";
 //#region src/agent/commands/command-registry.ts
@@ -46,9 +47,10 @@ var CommandRegistry = class {
 		return join(this.root, createHash("sha256").update(owner).digest("hex"));
 	}
 	persist(owner, result) {
-		const file = join(this.directory(owner), `${result.id}.json`);
-		writeFileSync(`${file}.tmp`, JSON.stringify(result), { mode: 384 });
-		renameSync(`${file}.tmp`, file);
+		this.receipts(owner).set(result.id, result);
+	}
+	receipts(owner) {
+		return new DurableState("command-receipts", owner);
 	}
 	async start(input) {
 		input.signal?.throwIfAborted();
@@ -174,16 +176,15 @@ var CommandRegistry = class {
 			...current.result,
 			durationMs: Date.now() - current.result.createdAtMs
 		} : void 0;
-		try {
-			const result = JSON.parse(readFileSync(join(this.directory(owner), `${id}.json`), "utf8"));
+		{
+			const result = this.receipts(owner).get(id);
+			if (!result) return void 0;
 			if (result.status === "running") {
 				result.status = "interrupted";
 				result.stderr += "\nRuntime ownership was lost. Process/container state is unknown; inspect before restarting.";
 				this.persist(owner, result);
 			}
 			return result;
-		} catch {
-			return;
 		}
 	}
 	async wait(owner, id, waitMs = 3e4, signal) {
@@ -225,27 +226,16 @@ var CommandRegistry = class {
 		if (Date.now() - (this.prunedAt.get(owner) ?? 0) < 6e4) return;
 		this.prunedAt.set(owner, Date.now());
 		const directory = this.directory(owner);
-		const completed = readdirSync(directory).filter((file) => file.endsWith(".json")).flatMap((file) => {
-			try {
-				const job = JSON.parse(readFileSync(join(directory, file), "utf8"));
-				return this.running.has(job.id) || job.status === "running" ? [] : [job];
-			} catch {
-				return [];
-			}
-		}).sort((a, b) => b.createdAtMs - a.createdAtMs);
+		const completed = this.receipts(owner).values().filter((job) => !this.running.has(job.id) && job.status !== "running").sort((a, b) => b.createdAtMs - a.createdAtMs);
 		for (const [index, job] of completed.entries()) {
 			if (index < 500 && Date.now() - job.createdAtMs < 10080 * 6e4) continue;
 			if (!/^[\da-f-]{36}$/.test(job.id)) continue;
-			rmSync(join(directory, `${job.id}.json`), { force: true });
+			this.receipts(owner).delete(job.id);
 			rmSync(join(directory, `${job.id}.log`), { force: true });
 		}
 	}
 	list(owner) {
-		try {
-			return readdirSync(this.directory(owner)).filter((file) => file.endsWith(".json")).map((file) => this.get(owner, file.slice(0, -5))).filter((job) => !!job).sort((a, b) => b.createdAtMs - a.createdAtMs).slice(0, 50);
-		} catch {
-			return [];
-		}
+		return this.receipts(owner).entries().map(([id]) => this.get(owner, id)).filter((job) => !!job).sort((a, b) => b.createdAtMs - a.createdAtMs).slice(0, 50);
 	}
 };
 function commandRegistry() {

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

@@ -0,0 +1,36 @@
+import type { ExecutionContext } from './execution-context.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;
+}): void;
+export declare function getExecutionContextAudit(turnId: string): ExecutionContextAudit | undefined;
+export declare function recordExecutionContextFeedback(input: {
+    turnId: string;
+    rating: 'helpful' | 'irrelevant';
+    reason?: string;
+}): boolean;

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

@@ -0,0 +1,97 @@
+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 items = [
+		...context.rules.map((item) => ({
+			objectType: "rule",
+			objectId: item.id,
+			reasons: [`${item.enforcementLevel}_rule`],
+			included: true
+		})),
+		...context.assertions.map((item) => ({
+			objectType: "assertion",
+			objectId: item.assertion.id,
+			score: item.score,
+			reasons: item.reasons,
+			included: true
+		})),
+		...context.goals.map((item) => ({
+			objectType: "goal",
+			objectId: item.id,
+			reasons: ["active_goal"],
+			included: true
+		})),
+		...context.priorities.map((item) => ({
+			objectType: "priority",
+			objectId: item.id,
+			score: item.urgency,
+			reasons: [`${item.rank}_priority`],
+			included: true
+		})),
+		...context.knowledge.map((item) => ({
+			objectType: "knowledge",
+			objectId: item.id,
+			score: item.importance,
+			reasons: ["task_relevant_knowledge"],
+			included: true
+		}))
+	];
+	const metrics = {
+		rules: context.rules.length,
+		assertions: context.assertions.length,
+		goals: context.goals.length,
+		priorities: context.priorities.length,
+		knowledge: context.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;
+}
+//#endregion
+export { getExecutionContextAudit, recordExecutionContext, recordExecutionContextFeedback };

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

@@ -0,0 +1,26 @@
+import type { AgentMessage } from '@earendil-works/pi-agent-core';
+import type { Config } from '../../config/schema.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;
+    isEnabledForSession: (sessionKey: string) => boolean;
+    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,72 @@
+import { init_session_key, parseSessionKey } from "../../routing/session-key.js";
+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, renderExecutionContext } from "./execution-context.js";
+//#region src/agent/context/coordinator.ts
+init_session_key();
+function isPrivateSession(sessionKey) {
+	const parsed = parseSessionKey(sessionKey);
+	return !parsed || parsed.peerKind === "direct";
+}
+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();
+		if (!config || !config.userContext.contextPlanning.enabled || !this.options.isEnabledForSession(sessionKey) || !isPrivateSession(sessionKey)) 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)
+		});
+		this.currentBySession.set(sessionKey, context);
+		const rendered = renderExecutionContext(context).slice(0, Math.min(config.userContext.contextPlanning.maxChars, task.allocation.maxChars));
+		const contextItemCount = context.rules.length + context.assertions.length + context.goals.length + context.priorities.length + 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: Math.min(config.userContext.contextPlanning.maxChars, task.allocation.maxChars)
+			},
+			renderedChars: rendered.length
+		});
+		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,54 @@
+import { type KnowledgeItem, type KnowledgeVisibilityContext } from '../../knowledge-memory/index.js';
+import type { UserAssertion } from '../../user-model/domain.js';
+export type RuleEnforcementLevel = 'prompt' | 'planner' | 'tool_gate';
+export interface ExecutionRule {
+    id: string;
+    statement: string;
+    priority: number;
+    enforcementLevel: RuleEnforcementLevel;
+    conditions: Record<string, unknown>;
+}
+export interface RankedExecutionAssertion {
+    assertion: UserAssertion;
+    score: number;
+    reasons: string[];
+}
+export interface ExecutionGoal {
+    id: string;
+    title: string;
+    desiredOutcome: string;
+    status: string;
+    declaredImportance?: number;
+    targetAt?: number;
+}
+export interface ExecutionPriority {
+    id: string;
+    targetType: string;
+    targetId: string;
+    rank: 'primary' | 'secondary' | 'background';
+    urgency: number;
+    validTo: number;
+}
+export interface ExecutionContext {
+    traceId: string;
+    asOf: number;
+    query: string;
+    rules: ExecutionRule[];
+    assertions: RankedExecutionAssertion[];
+    goals: ExecutionGoal[];
+    priorities: ExecutionPriority[];
+    knowledge: KnowledgeItem[];
+}
+export interface ExecutionContextRequest extends KnowledgeVisibilityContext {
+    query: string;
+    asOf?: number;
+    maxAssertions?: number;
+    maxKnowledge?: number;
+}
+export declare function buildExecutionContext(request: ExecutionContextRequest): ExecutionContext;
+export declare function renderExecutionContext(context: ExecutionContext): string;
+export declare function evaluateToolGate(context: ExecutionContext, operation: string): {
+    allowed: boolean;
+    rule?: ExecutionRule;
+    reason?: string;
+};