@xopcai/xopc 0.0.247 → 0.0.249

package/dist/src/agent/context/execution-context.js

@@ -0,0 +1,147 @@
+import { getSqliteDatabase } from "../../storage/sqlite/transaction.js";
+import { listCollaborationRules } from "../../storage/sqlite/collaboration-rule-repository.js";
+import { searchKnowledgeItems } from "../../knowledge-memory/repository.js";
+import "../../knowledge-memory/index.js";
+import { retrievalLexicalSimilarity } from "../../retrieval/textFeatures.js";
+import { calculateExecutionValue } from "../../user-model/importance.js";
+import { listUserAssertions } from "../../user-model/repository.js";
+import { randomUUID } from "node:crypto";
+//#region src/agent/context/execution-context.ts
+function scopeVisible(scope, context) {
+	if (scope.type === "global") return true;
+	return scope.id === {
+		agent: context.agentId,
+		workspace: context.workspaceId,
+		project: context.projectId,
+		session: context.sessionId
+	}[scope.type];
+}
+function urgency(assertion, asOf) {
+	const deadline = assertion.validTo ?? assertion.reviewAt;
+	if (deadline === void 0) return 0;
+	const remaining = deadline - asOf;
+	if (remaining <= 0) return 1;
+	return Math.max(0, 1 - remaining / (720 * 60 * 60 * 1e3));
+}
+function rankAssertion(assertion, query, asOf) {
+	const taskRelevance = retrievalLexicalSimilarity(query, `${assertion.statement} ${assertion.normalizedValue}`);
+	return {
+		assertion,
+		score: calculateExecutionValue({
+			declaredImportance: assertion.declaredImportance,
+			inferredImportance: assertion.inferredImportance,
+			consequence: assertion.consequence,
+			actionability: assertion.actionability,
+			taskRelevance,
+			urgency: urgency(assertion, asOf)
+		}),
+		reasons: [
+			taskRelevance >= .35 ? "task_relevant" : "",
+			assertion.declaredImportance !== void 0 ? "user_declared_importance" : "",
+			assertion.consequence === "critical" || assertion.consequence === "high" ? "high_consequence" : "",
+			assertion.kind === "identity" || assertion.kind === "preference" ? "stable_personalization" : ""
+		].filter(Boolean)
+	};
+}
+function ruleEnforcement(conditions) {
+	const value = conditions.enforcementLevel;
+	return value === "planner" || value === "tool_gate" ? value : "prompt";
+}
+function loadRules(context) {
+	return listCollaborationRules().filter((rule) => rule.status === "active" && scopeVisible(rule.scope, context)).map((rule) => ({
+		id: rule.id,
+		statement: rule.statement,
+		priority: rule.priority,
+		enforcementLevel: ruleEnforcement(rule.conditions),
+		conditions: rule.conditions
+	})).sort((left, right) => left.priority - right.priority);
+}
+function loadGoals(context, asOf) {
+	return getSqliteDatabase().prepare(`SELECT g.goal_id, g.status, g.declared_importance,
+      g.target_at, g.scope_type, g.scope_id, r.title, r.desired_outcome
+    FROM user_goals g JOIN user_goal_revisions r ON r.revision_id = g.current_revision_id
+    WHERE g.principal_id = 'local-owner' AND g.status IN ('active', 'proposed')
+      AND (g.valid_from IS NULL OR g.valid_from <= ?)
+      AND (g.valid_to IS NULL OR g.valid_to >= ?)
+    ORDER BY COALESCE(g.declared_importance, 0) DESC, g.updated_at DESC LIMIT 30`).all(asOf, asOf).filter((row) => scopeVisible({
+		type: row.scope_type,
+		...row.scope_id ? { id: row.scope_id } : {}
+	}, context)).map((row) => ({
+		id: row.goal_id,
+		title: row.title,
+		desiredOutcome: row.desired_outcome,
+		status: row.status,
+		...row.declared_importance === null ? {} : { declaredImportance: row.declared_importance },
+		...row.target_at === null ? {} : { targetAt: row.target_at }
+	}));
+}
+function loadPriorities(context, asOf) {
+	return getSqliteDatabase().prepare(`SELECT priority_id, target_type, target_id, rank, urgency,
+      valid_to, scope_type, scope_id FROM user_priority_windows
+    WHERE principal_id = 'local-owner' AND status = 'active' AND valid_from <= ? AND valid_to >= ?
+    ORDER BY CASE rank WHEN 'primary' THEN 0 WHEN 'secondary' THEN 1 ELSE 2 END, urgency DESC LIMIT 30`).all(asOf, asOf).filter((row) => scopeVisible({
+		type: row.scope_type,
+		...row.scope_id ? { id: row.scope_id } : {}
+	}, context)).map((row) => ({
+		id: row.priority_id,
+		targetType: row.target_type,
+		targetId: row.target_id,
+		rank: row.rank,
+		urgency: row.urgency,
+		validTo: row.valid_to
+	}));
+}
+function buildExecutionContext(request) {
+	const asOf = request.asOf ?? Date.now();
+	const assertions = listUserAssertions({
+		statuses: ["active"],
+		limit: 1e3
+	}).filter((item) => scopeVisible(getAssertionScope(item.slotId), request)).filter((item) => (item.validFrom === void 0 || item.validFrom <= asOf) && (item.validTo === void 0 || item.validTo >= asOf)).filter((item) => item.sensitivity !== "secret" && item.sensitivity !== "regulated" && item.disclosurePolicy !== "ask_before_reference").map((item) => rankAssertion(item, request.query, asOf)).filter((item) => item.score >= .12 || item.reasons.includes("high_consequence")).sort((left, right) => right.score - left.score).slice(0, Math.max(1, Math.min(100, request.maxAssertions ?? 20)));
+	return {
+		traceId: randomUUID(),
+		asOf,
+		query: request.query,
+		rules: loadRules(request),
+		assertions,
+		goals: loadGoals(request, asOf),
+		priorities: loadPriorities(request, asOf),
+		knowledge: searchKnowledgeItems({
+			query: request.query,
+			context: request,
+			asOf,
+			limit: request.maxKnowledge ?? 12
+		})
+	};
+}
+function getAssertionScope(slotId) {
+	const row = getSqliteDatabase().prepare(`SELECT scope_type, scope_id FROM user_assertion_slots
+    WHERE slot_id = ?`).get(slotId);
+	return {
+		type: row.scope_type,
+		...row.scope_id ? { id: row.scope_id } : {}
+	};
+}
+function renderExecutionContext(context) {
+	const sections = [];
+	if (context.rules.length) sections.push(`Collaboration rules:\n${context.rules.map((rule) => `- ${rule.statement}`).join("\n")}`);
+	if (context.assertions.length) sections.push(`Relevant user facts:\n${context.assertions.map((item) => `- ${item.assertion.statement}`).join("\n")}`);
+	if (context.goals.length) sections.push(`Active goals:\n${context.goals.map((goal) => `- ${goal.title}: ${goal.desiredOutcome}`).join("\n")}`);
+	if (context.priorities.length) sections.push(`Current priorities:\n${context.priorities.map((item) => `- ${item.rank}: ${item.targetType}/${item.targetId}`).join("\n")}`);
+	if (context.knowledge.length) sections.push(`Relevant knowledge:\n${context.knowledge.map((item) => `- ${item.content}`).join("\n")}`);
+	return sections.join("\n\n");
+}
+function evaluateToolGate(context, operation) {
+	for (const rule of context.rules) {
+		if (rule.enforcementLevel !== "tool_gate") continue;
+		const operations = Array.isArray(rule.conditions.operationTypes) ? rule.conditions.operationTypes.filter((item) => typeof item === "string") : [];
+		if (operations.length && !operations.includes(operation)) continue;
+		if (rule.conditions.effect === "deny") return {
+			allowed: false,
+			rule,
+			reason: rule.statement
+		};
+	}
+	return { allowed: true };
+}
+//#endregion
+export { buildExecutionContext, evaluateToolGate, renderExecutionContext };

package/dist/src/agent/context/execution-scope.js

@@ -79,7 +79,7 @@ function formatCurrentWorkForPrompt(scope) {
 }
 function buildExecutionScopeContextForPrompt(sessionKey) {
 	const scope = resolveExecutionScope(sessionKey);
-	return [buildActiveProjectContextForPrompt(sessionKey, { memoryQuery: scope.objective?.objective }), formatCurrentWorkForPrompt(scope)].filter((section) => Boolean(section?.trim())).join("\n\n") || void 0;
+	return [buildActiveProjectContextForPrompt(sessionKey, { knowledgeQuery: scope.objective?.objective }), formatCurrentWorkForPrompt(scope)].filter((section) => Boolean(section?.trim())).join("\n\n") || void 0;
 }
 //#endregion
 export { buildExecutionScopeContextForPrompt, formatCurrentWorkForPrompt, resolveExecutionScope };

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

@@ -0,0 +1,2 @@
+import type { AgentMessage } from '@earendil-works/pi-agent-core';
+export declare function prependAgentContext(message: AgentMessage, block: string): AgentMessage;

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

@@ -0,0 +1,28 @@
+import { readAgentMessageContent } from "../memory/agent-message-access.js";
+//#region src/agent/context/prepend.ts
+function prependAgentContext(message, block) {
+	if (!block) return message;
+	const prefix = `${block}\n\n`;
+	const content = readAgentMessageContent(message);
+	if (typeof content === "string") return {
+		...message,
+		content: prefix + content
+	};
+	if (!Array.isArray(content)) return message;
+	const copy = [...content];
+	const first = copy[0];
+	if (first?.type === "text" && typeof first.text === "string") copy[0] = {
+		type: "text",
+		text: prefix + first.text
+	};
+	else copy.unshift({
+		type: "text",
+		text: prefix
+	});
+	return {
+		...message,
+		content: copy
+	};
+}
+//#endregion
+export { prependAgentContext };

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

@@ -5,7 +5,7 @@ export interface ProjectTaskContext {
     priority: string;
 }
 export declare function buildActiveProjectContextForPrompt(sessionKey: string, options?: {
-    memoryQuery?: string;
+    knowledgeQuery?: string;
 }): string | undefined;
 export declare function formatActiveProjectContextForPrompt(input: {
     project: Project;
@@ -17,10 +17,10 @@ export declare function formatActiveProjectContextForPrompt(input: {
         updatedAt: string;
         agentId: string;
     }>;
-    memoryRecords?: Array<{
+    knowledgeItems?: Array<{
         kind: string;
         content: string;
-        updatedAt: string;
+        updatedAt: number;
     }>;
     localApp?: {
         extensionId: string;

package/dist/src/agent/context/project-context.js

@@ -1,18 +1,18 @@
-import { listMemoryRecords, searchMemoryRecords } from "../../storage/sqlite/memory-records-repository.js";
-import "../../storage/sqlite/index.js";
 import { sanitizeForPromptLiteral } from "../prompt/sanitize-for-prompt.js";
 import { TaskRepository } from "../../tasks/task-repository.js";
 import { TaskReadModelProjector } from "../../tasks/task-read-model-projector.js";
 import { LocalAppStore } from "../../local-apps/store.js";
 import { ProjectStore } from "../../projects/project-store.js";
 import { getProjectForSession, getProjectWorkspacePathForSession } from "../../projects/workspace.js";
+import { listKnowledgeItems, searchKnowledgeItems } from "../../knowledge-memory/repository.js";
+import "../../knowledge-memory/index.js";
 //#region src/agent/context/project-context.ts
 const MAX_TEXT = 1200;
 const MAX_TASKS = 5;
 const MAX_SESSIONS = 5;
-const MAX_RECENT_MEMORY = 5;
-const MAX_RELEVANT_MEMORY = 5;
-const MAX_MEMORY = 8;
+const MAX_RECENT_KNOWLEDGE = 5;
+const MAX_RELEVANT_KNOWLEDGE = 5;
+const MAX_KNOWLEDGE = 8;
 function truncateText(value, max = MAX_TEXT) {
 	const trimmed = value?.trim();
 	if (!trimmed) return void 0;
@@ -26,11 +26,11 @@ function formatTask(task) {
 		`priority=${task.priority}`
 	].join(" | ");
 }
-function selectProjectMemoryRecords(input) {
+function selectProjectKnowledge(input) {
 	const selected = /* @__PURE__ */ new Map();
 	for (const record of [...input.relevant, ...input.recent]) {
 		if (!selected.has(record.id)) selected.set(record.id, record);
-		if (selected.size >= MAX_MEMORY) break;
+		if (selected.size >= MAX_KNOWLEDGE) break;
 	}
 	return [...selected.values()];
 }
@@ -49,18 +49,21 @@ function buildActiveProjectContextForPrompt(sessionKey, options = {}) {
 			state: `${task.phase}/${new TaskReadModelProjector().project(task).operationalState}`
 		})),
 		recentSessions: new ProjectStore().getRecentSessions(project.id, MAX_SESSIONS),
-		memoryRecords: selectProjectMemoryRecords({
-			relevant: options.memoryQuery?.trim() ? searchMemoryRecords({
-				query: options.memoryQuery,
-				projectId: project.id,
+		knowledgeItems: selectProjectKnowledge({
+			relevant: options.knowledgeQuery?.trim() ? searchKnowledgeItems({
+				query: options.knowledgeQuery,
+				context: {
+					agentId: project.defaultAgentId ?? "main",
+					workspaceId: project.workspaceRoot ?? "",
+					projectId: project.id,
+					sessionId: sessionKey
+				},
+				limit: MAX_RELEVANT_KNOWLEDGE
+			}) : [],
+			recent: listKnowledgeItems({
 				statuses: ["active"],
-				maxResults: MAX_RELEVANT_MEMORY
-			}).map((result) => result.record) : [],
-			recent: listMemoryRecords({
-				projectId: project.id,
-				status: "active",
-				limit: MAX_RECENT_MEMORY
-			})
+				limit: 500
+			}).filter((item) => item.scope.type === "project" && item.scope.id === project.id).slice(0, MAX_RECENT_KNOWLEDGE)
 		}),
 		localApp: localApp ? {
 			extensionId: localApp.extensionId,
@@ -107,12 +110,12 @@ function formatActiveProjectContextForPrompt(input) {
 		const label = sanitizeForPromptLiteral(session.name?.trim() || session.key);
 		lines.push(`- ${label} | agent=${sanitizeForPromptLiteral(session.agentId)} | updated=${sanitizeForPromptLiteral(session.updatedAt)}`);
 	}
-	lines.push("", "## Project Memory");
-	const memoryRecords = input.memoryRecords ?? [];
-	if (memoryRecords.length === 0) lines.push("- None recorded.");
-	else for (const record of memoryRecords) {
+	lines.push("", "## Project Knowledge");
+	const knowledgeItems = input.knowledgeItems ?? [];
+	if (knowledgeItems.length === 0) lines.push("- None recorded.");
+	else for (const record of knowledgeItems) {
 		const content = sanitizeForPromptLiteral(truncateText(record.content, 240) ?? "");
-		lines.push(`- ${sanitizeForPromptLiteral(record.kind)} | updated=${sanitizeForPromptLiteral(record.updatedAt)} | ${content}`);
+		lines.push(`- ${sanitizeForPromptLiteral(record.kind)} | updated=${new Date(record.updatedAt).toISOString()} | ${content}`);
 	}
 	return lines.join("\n");
 }

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

@@ -1,3 +1,4 @@
+import { getEmbeddedExecutionSession, runWithEmbeddedExecutionSession } from "./execution-context.js";
 import { abortEmbeddedRun, getEmbeddedRunBySessionKey, queueEmbeddedSteer } from "./runs.js";
 import { DEFAULT_MAX_LIVE_TOOL_RESULT_CHARS, resolveLiveToolResultMaxChars, truncateToolResultMessage } from "./tool-result-truncation.js";
 import { getRawSessionAppendMessage, guardSessionManager, installSessionToolResultGuard } from "./session-tool-result-guard.js";
@@ -6,7 +7,6 @@ import { repairAssistantUsageInSessionManager } from "./session-manager-init.js"
 import { openSqliteHydratingSessionManager } from "./sqlite-hydrating-session-manager.js";
 import { InMemoryTranscriptRuntime, createSqliteTranscriptRuntime } from "./transcript-runtime.js";
 import { runXopcEmbeddedTurn } from "./run-turn.js";
-import { getEmbeddedExecutionSession, runWithEmbeddedExecutionSession } from "./execution-context.js";
 import { runEmbeddedTurnForSession } from "./run-for-session.js";
 import { CURRENT_SESSION_VERSION, PiTranscriptManager } from "./pi-transcript.js";
 export { CURRENT_SESSION_VERSION, DEFAULT_MAX_LIVE_TOOL_RESULT_CHARS, InMemoryTranscriptRuntime, PiTranscriptManager, abortEmbeddedRun, acquireEmbeddedSessionRunner, buildEmbeddedRunnerFingerprint, createSqliteTranscriptRuntime, evictAllEmbeddedSessionRunners, evictEmbeddedSessionRunner, getEmbeddedExecutionSession, getEmbeddedRunBySessionKey, getEmbeddedSessionRunnerIdleTtlMs, getEmbeddedSessionRunnerStats, getRawSessionAppendMessage, guardSessionManager, installSessionToolResultGuard, isEmbeddedSessionRunnerEnabled, openSqliteHydratingSessionManager, queueEmbeddedSteer, repairAssistantUsageInSessionManager, resetEmbeddedSessionRunnerForTest, resolveLiveToolResultMaxChars, runEmbeddedTurnForSession, runWithEmbeddedExecutionSession, runXopcEmbeddedTurn, truncateToolResultMessage };

package/dist/src/agent/embedded/run-for-session.js

@@ -27,6 +27,7 @@ async function runEmbeddedTurnForSession(params) {
 		parentSignal: params.abortSignal
 	});
 	const finish = async (result) => {
+		if (result.stopReason === "connection_required") return result;
 		try {
 			const rows = await sessionStore.loadTranscriptRows(sessionKey);
 			const hasTurn = rows.some((source) => {

package/dist/src/agent/embedded/run-turn.js

@@ -1,5 +1,6 @@
 import { createLogger } from "../../utils/logger/index.js";
 import { init_logger } from "../../utils/logger.js";
+import { getConnectionResumeInput, isConnectionSuspended } from "../../storage/sqlite/connection-wait-repository.js";
 import { EmbeddedRunConflictError, abortEmbeddedRun, acquireEmbeddedRunLease, queueEmbeddedSteer } from "./runs.js";
 import { lastAssistantPlainText, subscribeEmbeddedSessionEvents } from "./subscribe-session.js";
 import { isContextOverflowError } from "../orchestration/context-overflow.js";
@@ -233,8 +234,14 @@ async function runXopcEmbeddedTurn(params) {
 			...await verification.summary()
 		});
 		let policyStopped = false;
+		let connectionStopped = false;
 		params.turnPolicy?.reset();
 		session.agent.beforeToolCall = async (context, signal) => {
+			if (connectionStopped) return {
+				block: true,
+				reason: "Waiting for the user to connect an app.",
+				terminate: true
+			};
 			const decision = await params.turnPolicy?.beforeToolCall(context, signal);
 			if (decision?.block) {
 				policyStopped ||= decision.terminate === true;
@@ -251,6 +258,7 @@ async function runXopcEmbeddedTurn(params) {
 			return decision;
 		};
 		session.agent.afterToolCall = async (context) => {
+			connectionStopped ||= isConnectionSuspended(sessionKey, runId);
 			const scoped = context.toolCall.name === "read_file" ? await instructions.forTool(context.toolCall.name, context.args) : "";
 			const checked = await verification.afterTool(context);
 			if (scoped) checked.result.content.unshift({
@@ -265,7 +273,7 @@ async function runXopcEmbeddedTurn(params) {
 		};
 		session.agent.shouldStopAfterTurn = (context) => {
 			policyStopped ||= params.turnPolicy?.shouldStopAfterTurn(context) ?? false;
-			return policyStopped;
+			return policyStopped || connectionStopped;
 		};
 		unsubscribe = subscribeEmbeddedSessionEvents(session, (event) => {
 			if (event.type === "message_end" && event.message.role === "assistant") recordPromptCacheTouch(sessionKey, resolvedModel, event.message.usage);
@@ -281,13 +289,20 @@ async function runXopcEmbeddedTurn(params) {
 		runAbortSignal.addEventListener("abort", abortListener, { once: true });
 		try {
 			await runAgentTurnWithTimeout(session.agent, async () => {
-				if (params.resumeLastUserMessage) await session.agent.continue();
+				const connectionResume = getConnectionResumeInput(sessionKey, runId);
+				if (connectionResume) await session.sendCustomMessage({
+					customType: "connection_resume",
+					content: connectionResume.content,
+					display: false
+				}, { triggerTurn: true });
+				else if (params.resumeLastUserMessage) await session.agent.continue();
 				else {
 					const text = userMessageToPromptText(userMessage);
 					const images = params.images ?? [];
 					await session.prompt(text, images.length > 0 ? { images } : void 0);
 				}
 				await session.agent.waitForIdle();
+				if (connectionStopped) return;
 				await maybeRetryTurnAfterTransientLlmFailure(session.agent, {
 					sessionKey,
 					log,
@@ -311,6 +326,10 @@ async function runXopcEmbeddedTurn(params) {
 					await session.agent.waitForIdle();
 				}
 			}, timeoutMs);
+			if (connectionStopped) runner.piSm.appendCustomEntry("connection_required", {
+				runId,
+				sessionKey
+			});
 			runner.piSm.appendCustomEntry("coding_verification", {
 				runId,
 				workspace: workspaceDir,
@@ -337,6 +356,7 @@ async function runXopcEmbeddedTurn(params) {
 			});
 			return {
 				ok: true,
+				...connectionStopped ? { stopReason: "connection_required" } : {},
 				lastAssistantText: lastAssistantPlainText(session)
 			};
 		} finally {

package/dist/src/agent/embedded/types.d.ts

@@ -48,31 +48,6 @@ export type EmbeddedStreamEvent = {
     runId?: string;
     stage: string;
     message: string;
-} | {
-    type: 'memory_consent_required';
-    runId?: string;
-    requests: Array<{
-        id: string;
-        recordId: string;
-        statement: string;
-        purpose: string;
-    }>;
-} | {
-    type: 'memory_captured';
-    runId?: string;
-    records: Array<{
-        id: string;
-        content: string;
-        kind: string;
-    }>;
-} | {
-    type: 'memory_candidate';
-    runId?: string;
-    records: Array<{
-        id: string;
-        content: string;
-        kind: string;
-    }>;
 } | {
     type: 'error';
     runId?: string;
@@ -114,6 +89,7 @@ export type RunXopcEmbeddedTurnParams = {
 };
 export type RunXopcEmbeddedTurnResult = {
     ok: boolean;
+    stopReason?: 'connection_required';
     /** False for harness failures that must not trigger another model attempt. */
     retryable?: boolean;
     errorMessage?: string;