@xopcai/xopc 0.0.218 → 0.0.220

package/dist/src/agent/memory/understanding/service.js

@@ -1,6 +1,9 @@
-import { createContextEvidence, createUnderstanding, isUnderstandingSuppressed, linkUnderstandingEvidence, listUnderstandings, setUnderstandingStatus } from "../../../storage/sqlite/user-context-repository.js";
+import { finishContextExtractionRun, getContextExtractionRun, listContextExtractionOutputs } from "../../../storage/sqlite/context-extraction-repository.js";
+import { closeTemporalAssertions, createTemporalAssertion, linkContextObjects } from "../../../storage/sqlite/context-relation-repository.js";
+import { closeUnderstandingValidity, createContextEvidence, createUnderstanding, getUnderstanding, isUnderstandingSuppressed, linkUnderstandingEvidence, listUnderstandings, setUnderstandingStatus } from "../../../storage/sqlite/user-context-repository.js";
 import "../../../storage/sqlite/index.js";
 import { extractExplicitUnderstandingCorrectionContent } from "./correction.js";
+import { claimRegisteredExtraction, extractionInputHash, getRegisteredExtractorDefinition } from "../../../user-context/extraction/registry.js";
 import { canonicalUnderstandingKey, findContradictoryUnderstanding, findDuplicateUnderstanding } from "../../../user-context/understanding.js";
 import { inferMemorySensitivity, redactSensitiveMemoryText } from "../sensitivity.js";
 //#region src/agent/memory/understanding/service.ts
@@ -32,6 +35,11 @@ function effectiveSensitivity(declared, content) {
 function normalizeContent(raw) {
 	return raw.replace(/^["'“”‘’\s]+|["'“”‘’\s]+$/g, "").replace(/\s+/g, " ").trim().slice(0, MAX_CANDIDATE_CHARS);
 }
+function candidateTime(value) {
+	if (!value) return void 0;
+	const parsed = Date.parse(value);
+	return Number.isFinite(parsed) ? parsed : void 0;
+}
 function inferKind(content) {
 	if (/\b(don't|do not|never|avoid)\b/i.test(content) || /不要|不用|无需|别再|禁止|底线/.test(content)) return "boundary";
 	if (/\b(prefer|preference|like)\b/i.test(content) || /喜欢|偏好|习惯/.test(content)) return "preference";
@@ -96,39 +104,104 @@ var UserUnderstandingService = class {
 		params.assistantContent;
 		const explicitCandidates = extractExplicitUnderstandingCandidates(params.userContent);
 		const candidates = explicitCandidates.length > 0 ? explicitCandidates : extractHighSignalUnderstandingCandidates(params.userContent);
-		if (candidates.length === 0) return {
-			proposed: 0,
-			created: 0,
-			deduplicated: 0,
-			rejected: 0,
-			createdRecords: []
-		};
+		const turnRef = params.turnId ?? `untracked-${extractionInputHash(params.userContent).slice(0, 16)}`;
+		const extraction = claimRegisteredExtraction({
+			extractorId: explicitCandidates.length > 0 ? "explicit-command" : "deterministic-signal",
+			sourceRef: params.sessionKey ? `session:${params.sessionKey}:turn:${turnRef}` : `turn:${turnRef}`,
+			contentForHash: params.userContent,
+			processingPolicy: "local_only",
+			destination: "deterministic"
+		});
+		if (!extraction.shouldExecute) {
+			const previous = listContextExtractionOutputs(extraction.run.id);
+			return {
+				proposed: candidates.length,
+				created: 0,
+				deduplicated: previous.filter((output) => output.outcome !== "rejected").length,
+				rejected: previous.filter((output) => output.outcome === "rejected").length,
+				createdRecords: []
+			};
+		}
+		if (candidates.length === 0) {
+			finishContextExtractionRun({
+				runId: extraction.run.id,
+				status: "completed",
+				outputs: []
+			});
+			return {
+				proposed: 0,
+				created: 0,
+				deduplicated: 0,
+				rejected: 0,
+				createdRecords: []
+			};
+		}
 		const safeCandidates = candidates.filter((candidate) => {
 			const content = normalizeContent(candidate.content);
 			const sensitivity = effectiveSensitivity(candidate.sensitivity, content);
 			return sensitivity !== "secret" && sensitivity !== "regulated";
 		});
-		if (!safeCandidates.length) return {
-			proposed: candidates.length,
-			created: 0,
-			deduplicated: 0,
-			rejected: candidates.length,
-			createdRecords: []
-		};
+		if (!safeCandidates.length) {
+			finishContextExtractionRun({
+				runId: extraction.run.id,
+				status: "completed",
+				outputs: candidates.map((candidate) => ({
+					candidateKey: candidate.canonicalKey ?? canonicalUnderstandingKey(candidate.kind, candidate.content),
+					outcome: "rejected"
+				}))
+			});
+			return {
+				proposed: candidates.length,
+				created: 0,
+				deduplicated: 0,
+				rejected: candidates.length,
+				createdRecords: []
+			};
+		}
 		const evidence = createContextEvidence({
 			sourceType: "conversation",
-			sourceRef: params.sessionKey ? `session:${params.sessionKey}:turn:${params.turnId ?? "unknown"}` : `turn:${params.turnId ?? "unknown"}`,
+			sourceRef: params.sessionKey ? `session:${params.sessionKey}:turn:${turnRef}` : `turn:${turnRef}`,
+			sourceRunId: extraction.run.id,
+			...params.sessionKey ? { sessionId: params.sessionKey } : {},
+			turnId: turnRef,
+			contentHash: extractionInputHash(params.userContent),
+			retentionPolicy: "derived_only",
+			processingPolicy: "local_only",
+			extractorId: extraction.run.extractorId,
+			extractorVersion: extraction.run.extractorVersion,
 			redactedExcerpt: redactSensitiveMemoryText(safeCandidates.map((candidate) => candidate.content).join("\n")).slice(0, MAX_CANDIDATE_CHARS),
 			trustLevel: "owner",
 			observedAt: Date.now()
 		});
-		const result = await this.applyCandidates(safeCandidates, {
-			sessionKey: params.sessionKey,
-			workspaceId: params.workspaceId,
-			projectId: params.projectId,
-			evidenceIds: [evidence.id],
-			reviewSource: "turn",
-			supersedesRecordIds: params.correctionTargetRecordIds
+		let result;
+		try {
+			result = await this.applyCandidates(safeCandidates, {
+				sessionKey: params.sessionKey,
+				workspaceId: params.workspaceId,
+				projectId: params.projectId,
+				evidenceIds: [evidence.id],
+				reviewSource: "turn",
+				supersedesRecordIds: params.correctionTargetRecordIds,
+				extractionRunId: extraction.run.id
+			});
+		} catch (error) {
+			finishContextExtractionRun({
+				runId: extraction.run.id,
+				status: "failed",
+				errorCode: "write_failed"
+			});
+			throw error;
+		}
+		finishContextExtractionRun({
+			runId: extraction.run.id,
+			status: "completed",
+			outputs: result.writeOutputs?.map((output) => ({
+				candidateKey: output.candidateKey,
+				objectType: output.objectId ? "understanding" : void 0,
+				objectId: output.objectId,
+				versionId: output.versionId,
+				outcome: output.outcome
+			})) ?? []
 		});
 		return {
 			...result,
@@ -141,24 +214,36 @@ var UserUnderstandingService = class {
 		let created = 0;
 		let deduplicated = 0;
 		const createdRecords = [];
+		const writeOutputs = [];
 		const correctionTarget = context.supersedesRecordIds?.length === 1 ? context.supersedesRecordIds[0] : void 0;
-		const eligible = candidates.slice(0, 10).map((candidate) => {
+		const extractionRun = context.extractionRunId ? getContextExtractionRun(context.extractionRunId) : null;
+		if (context.extractionRunId && !extractionRun) throw new Error("Context extraction run not found");
+		if (context.source?.provider && !extractionRun) throw new Error("External understanding requires an extraction run");
+		const extractionDefinition = extractionRun ? getRegisteredExtractorDefinition(extractionRun.extractorId) : void 0;
+		const prepared = candidates.slice(0, 10).map((candidate) => {
 			const content = normalizeContent(candidate.content);
 			return {
 				candidate,
 				content,
 				sensitivity: effectiveSensitivity(candidate.sensitivity, content),
 				scope: scopeForCandidate(candidate, context),
-				key: candidate.canonicalKey ?? canonicalUnderstandingKey(candidate.kind, content)
+				key: candidate.canonicalKey ?? canonicalUnderstandingKey(candidate.kind, content),
+				explicitness: extractionDefinition?.authorityCeiling === "user_explicit" ? candidate.explicitness : extractionDefinition?.authorityCeiling === "user_observed" ? candidate.explicitness === "explicit" ? "observed" : candidate.explicitness : extractionDefinition ? "inferred" : candidate.explicitness
 			};
-		}).filter(({ candidate, content, sensitivity, scope, key }) => content.length >= 4 && candidate.confidence >= .55 && sensitivity !== "secret" && sensitivity !== "regulated" && !isUnderstandingSuppressed(key, scope));
+		});
+		const eligible = prepared.filter(({ candidate, content, sensitivity, scope, key }) => content.length >= 4 && candidate.confidence >= .55 && sensitivity !== "secret" && sensitivity !== "regulated" && (!extractionDefinition || extractionDefinition.candidateKinds.includes(candidate.kind)) && !isUnderstandingSuppressed(key, scope));
 		let rejected = candidates.length - eligible.length;
+		for (const item of prepared.filter((candidate) => !eligible.includes(candidate))) writeOutputs.push({
+			candidateKey: item.key,
+			outcome: "rejected"
+		});
 		if (!eligible.length) return {
 			proposed: candidates.length,
 			created,
 			deduplicated,
 			rejected,
-			createdRecords
+			createdRecords,
+			writeOutputs
 		};
 		const evidenceIds = [...new Set(context.evidenceIds ?? [])];
 		const sourceItemIds = [context.sourceItemId, ...context.sourceItemIds ?? []].filter((value) => Boolean(value));
@@ -167,13 +252,21 @@ var UserUnderstandingService = class {
 				sourceType: context.source?.provider ? "connector" : "runtime",
 				...context.source?.sourceInstanceId ? { sourceInstanceId: context.source.sourceInstanceId } : {},
 				sourceRef: sourceItemId,
+				...context.extractionRunId ? { sourceRunId: context.extractionRunId } : {},
+				sourceItemId,
+				retentionPolicy: "derived_only",
+				...extractionRun ? { processingPolicy: extractionRun.processingPolicy } : {},
+				...extractionRun ? {
+					extractorId: extractionRun.extractorId,
+					extractorVersion: extractionRun.extractorVersion
+				} : {},
 				...context.sourceText ? { redactedExcerpt: redactSensitiveMemoryText(context.sourceText).slice(0, MAX_CANDIDATE_CHARS) } : {},
 				trustLevel: context.source?.provider ? "untrusted" : "trusted",
 				observedAt: Date.now()
 			});
 			evidenceIds.push(evidence.id);
 		}
-		for (const { candidate, content, sensitivity, scope, key } of eligible) {
+		for (const { candidate, content, sensitivity, scope, key, explicitness } of eligible) {
 			const duplicate = findDuplicateUnderstanding(listUnderstandings(), {
 				kind: candidate.kind,
 				statement: content,
@@ -183,20 +276,29 @@ var UserUnderstandingService = class {
 			if (duplicate) {
 				for (const evidenceId of evidenceIds) linkUnderstandingEvidence(duplicate.versionId, evidenceId, "supports", candidate.confidence);
 				deduplicated += 1;
+				writeOutputs.push({
+					candidateKey: key,
+					objectId: duplicate.id,
+					versionId: duplicate.versionId,
+					outcome: "deduplicated"
+				});
 				continue;
 			}
-			const isExplicit = candidate.explicitness === "explicit";
-			const supersededId = correctionTarget ?? (isExplicit ? findContradictoryUnderstanding(listUnderstandings(), {
+			const isExplicit = explicitness === "explicit" && extractionDefinition?.maxAutomaticStatus !== "candidate";
+			const contradiction = findContradictoryUnderstanding(listUnderstandings(), {
 				kind: candidate.kind,
 				statement: content,
 				scope
-			})?.id : void 0);
+			});
+			const supersededId = isExplicit ? correctionTarget ?? contradiction?.id : void 0;
+			const validFrom = candidateTime(candidate.validFrom);
+			const validTo = candidateTime(candidate.validTo);
 			const record = createUnderstanding({
 				kind: candidate.kind,
 				canonicalKey: key,
 				status: isExplicit ? "active" : "candidate",
 				scope,
-				explicitness: candidate.explicitness,
+				explicitness,
 				durability: candidate.durability,
 				sensitivity,
 				disclosurePolicy: candidate.disclosurePolicy,
@@ -204,12 +306,46 @@ var UserUnderstandingService = class {
 				statement: content,
 				createdBy: context.reviewSource === "background" ? "consolidation" : "runtime",
 				changeReason: context.reviewSource === "background" ? "background synthesis" : "explicit user statement",
-				...candidate.validFrom ? { validFrom: Date.parse(candidate.validFrom) } : {},
-				...candidate.validTo ? { validTo: Date.parse(candidate.validTo) } : {},
+				...validFrom !== void 0 ? { validFrom } : {},
+				...validTo !== void 0 ? { validTo } : {},
 				...supersededId ? { supersedesId: supersededId } : {}
 			});
 			for (const evidenceId of evidenceIds) linkUnderstandingEvidence(record.versionId, evidenceId, "supports", candidate.confidence);
-			if (supersededId && isExplicit) setUnderstandingStatus(supersededId, "archived");
+			const relationTarget = supersededId ? getUnderstanding(supersededId) : contradiction;
+			if (relationTarget) linkContextObjects({
+				subjectType: "understanding",
+				subjectId: record.id,
+				subjectVersionId: record.versionId,
+				predicate: supersededId ? "supersedes" : "contradicts",
+				objectType: "understanding",
+				objectId: relationTarget.id,
+				objectVersionId: relationTarget.versionId,
+				factual: true,
+				...context.extractionRunId ? { extractionRunId: context.extractionRunId } : {}
+			});
+			if (supersededId && isExplicit) {
+				const closedAt = record.validFrom ?? Date.now();
+				closeUnderstandingValidity(supersededId, closedAt);
+				closeTemporalAssertions({
+					objectType: "understanding",
+					objectId: supersededId,
+					validTo: closedAt
+				});
+				setUnderstandingStatus(supersededId, "archived");
+			}
+			const assertionType = record.kind === "current_state" ? "current_state" : record.kind === "routine" ? "routine" : record.kind === "relationship" ? "relationship" : record.kind === "project_context" ? "project_status" : void 0;
+			if (assertionType) createTemporalAssertion({
+				objectType: "understanding",
+				objectId: record.id,
+				objectVersionId: record.versionId,
+				assertionType,
+				value: { statement: record.statement },
+				confidence: record.confidence,
+				...record.validFrom ? { validFrom: record.validFrom } : {},
+				...record.validTo ? { validTo: record.validTo } : {},
+				status: record.status === "active" ? "active" : "candidate",
+				...context.extractionRunId ? { extractionRunId: context.extractionRunId } : {}
+			});
 			created += 1;
 			createdRecords.push({
 				id: record.id,
@@ -217,13 +353,20 @@ var UserUnderstandingService = class {
 				kind: record.kind,
 				status: record.status
 			});
+			writeOutputs.push({
+				candidateKey: key,
+				objectId: record.id,
+				versionId: record.versionId,
+				outcome: "created"
+			});
 		}
 		return {
 			proposed: candidates.length,
 			created,
 			deduplicated,
 			rejected,
-			createdRecords
+			createdRecords,
+			writeOutputs
 		};
 	}
 };

package/dist/src/agent/memory/understanding/types.d.ts

@@ -24,4 +24,10 @@ export interface UnderstandingReviewResult {
         kind: UnderstandingKind;
         status: UserUnderstanding['status'];
     }>;
+    writeOutputs?: Array<{
+        candidateKey: string;
+        objectId?: string;
+        versionId?: string;
+        outcome: 'created' | 'deduplicated' | 'rejected';
+    }>;
 }

package/dist/src/agent/messaging/command-handler.d.ts

@@ -8,6 +8,7 @@ import type { Config } from '../../config/schema.js';
 import type { SessionConfigStore, SessionStore } from '../../session/index.js';
 import type { ThinkLevel } from '../transcript/thinking-types.js';
 import type { CompactionResult } from '../memory/compaction.js';
+import type { AgentSourceContext } from '../source-context/types.js';
 import { type BtwQueryOptions, type CommandStreamEvent } from '../../chat-commands/index.js';
 import type { WorkflowRunServiceLike } from '../../workflows/service/workflow-run-service.types.js';
 import type { SkillInstallToolOptions, SkillInstallToolResult } from '../tools/skill-install-tool.js';
@@ -19,6 +20,7 @@ export interface CommandContext {
     isGroup: boolean;
     /** From inbound message metadata (thread/account, etc.) for continuation routing. */
     inboundMetadata?: Record<string, unknown>;
+    sourceContexts?: AgentSourceContext[];
 }
 export interface CommandHandlerConfig {
     config: Config;

package/dist/src/agent/messaging/command-handler.js

@@ -57,7 +57,7 @@ var CommandHandler = class {
 	*/
 	buildCommandContext(context, recorder, emitEvent) {
 		const skipBusOutbound = shouldSkipBusOutboundForChannel(context.channel);
-		return createCommandContext({
+		const commandContext = createCommandContext({
 			sessionKey: context.sessionKey,
 			source: context.channel,
 			channelId: context.channel,
@@ -141,6 +141,8 @@ var CommandHandler = class {
 			getSessionContextReport: this.getSessionContextReport,
 			workflowRunService: this.getWorkflowRunService?.()
 		});
+		commandContext.sourceContexts = context.sourceContexts;
+		return commandContext;
 	}
 	/**
 	* Execute a command using the unified command system

package/dist/src/agent/service/direct-turn-helpers.d.ts

@@ -7,6 +7,7 @@
  */
 import type { AgentMessage } from '@earendil-works/pi-agent-core';
 import type { ImageContent } from '@earendil-works/pi-ai';
+import type { AgentSourceContext } from '../source-context/types.js';
 import type { CommandHandler } from '../messaging/command-handler.js';
 import type { CommandStreamEvent } from '../../chat-commands/types.js';
 import type { SessionStore } from '../../session/index.js';
@@ -52,6 +53,7 @@ export declare function tryRunSlashCommand(deps: TryRunSlashCommandDeps, ctx: {
 }, content: string, options?: {
     skipResetCommands?: boolean;
     emitEvent?: (event: CommandStreamEvent) => void | Promise<void>;
+    sourceContexts?: AgentSourceContext[];
 }): Promise<SlashCommandTask>;
 export interface RunDirectAgentTurnDeps {
     sessionStore: SessionStore;
@@ -66,6 +68,7 @@ export interface RunDirectAgentTurnInput {
     abortSignal?: AbortSignal;
     deadlineAtMs?: number;
     sourceImages?: ImageContent[];
+    sourceContexts?: AgentSourceContext[];
     onEvent?: (event: EmbeddedStreamEvent) => void;
 }
 export interface RunDirectAgentTurnResult {

package/dist/src/agent/service/direct-turn-helpers.js

@@ -8,6 +8,7 @@ import { parseSlashCommand } from "../../chat-commands/command-parse.js";
 import { commandRegistry } from "../../chat-commands/registry.js";
 import "../../chat-commands/index.js";
 import { runEmbeddedTurnForSession } from "../embedded/run-for-session.js";
+import { injectSourceContextsIntoUserMessage } from "../source-context/injector.js";
 import crypto from "node:crypto";
 //#region src/agent/service/direct-turn-helpers.ts
 /**
@@ -42,6 +43,12 @@ async function tryRunSlashCommand(deps, ctx, content, options) {
 		matched: false,
 		aggregatedText: ""
 	};
+	const command = commandRegistry.findByName(parsed.command);
+	if (options?.sourceContexts?.length && !command?.acceptsContext) return {
+		matched: true,
+		aggregatedText: `Command /${parsed.command} does not accept Note context. Remove the Note reference or use it with a regular prompt.`,
+		command: parsed.command
+	};
 	try {
 		const { aggregatedText, metadata } = await deps.commandHandler.executeCommandAndAggregateReply(parsed.command, parsed.args, {
 			sessionKey: ctx.sessionKey,
@@ -49,7 +56,8 @@ async function tryRunSlashCommand(deps, ctx, content, options) {
 			chatId: ctx.chatId,
 			senderId: ctx.senderId ?? "",
 			isGroup: ctx.isGroup ?? false,
-			inboundMetadata: ctx.inboundMetadata ?? {}
+			inboundMetadata: ctx.inboundMetadata ?? {},
+			sourceContexts: options?.sourceContexts
 		}, { emitEvent: options?.emitEvent });
 		return {
 			matched: true,
@@ -79,7 +87,8 @@ async function runDirectAgentTurn(deps, input) {
 	const turnId = input.runId ?? crypto.randomUUID();
 	const userPlain = extractAgentUserPlainText(input.userMessage);
 	const userContext = await deps.agentManager.prepareUserTurnContext(input.userMessage, input.sessionKey, turnId);
-	const userMessageForModel = prependAgentContext(userContext.modelMessage, buildTaskExecutionDirective(input.sessionKey));
+	const sourceContexts = input.sourceContexts ?? [];
+	const userMessageForModel = prependAgentContext(injectSourceContextsIntoUserMessage(userContext.modelMessage, sourceContexts), buildTaskExecutionDirective(input.sessionKey));
 	if (userContext.consentRequests.length > 0) input.onEvent?.({
 		type: "memory_consent_required",
 		runId: turnId,
@@ -90,7 +99,8 @@ async function runDirectAgentTurn(deps, input) {
 		message: input.userMessage,
 		modelRef
 	});
-	const sourceImages = resolveImageHandlingStrategy(modelRef) === "native" ? input.sourceImages ?? [] : [];
+	const contextImages = sourceContexts.flatMap((context) => context.images ?? []);
+	const sourceImages = resolveImageHandlingStrategy(modelRef) === "native" ? [...input.sourceImages ?? [], ...contextImages] : [];
 	const llmImages = [...llmTurn.images, ...sourceImages];
 	const result = await runEmbeddedTurnForSession({
 		sessionKey: input.sessionKey,

package/dist/src/agent/service/process-direct-streaming.d.ts

@@ -6,7 +6,7 @@ import type { SessionContext } from '../session/index.js';
 import type { AgentInstanceGateway } from '../agent-instance-gateway.js';
 import type { CommandHandler } from '../messaging/command-handler.js';
 import type { ModelManager } from '../models/index.js';
-import { type AgentSourceContextResolver } from '../source-context/types.js';
+import { type AgentSourceContext, type AgentSourceContextResolver } from '../source-context/types.js';
 import { type TranscriptUserMessage } from '../inbound/attachment-pipeline.js';
 export type DirectStreamInboundAttachment = InboundAttachmentInput;
 export type ProcessDirectStreamLog = {
@@ -65,6 +65,7 @@ export interface ProcessDirectStreamingInput {
     thinking?: string;
     signal?: AbortSignal;
     runId?: string;
+    sourceContexts?: AgentSourceContext[];
 }
 export type ProcessDirectStreamEvent = {
     type: string;

package/dist/src/agent/service/process-direct-streaming.js

@@ -9,8 +9,8 @@ import "../../voice/stt/index.js";
 import { abortEmbeddedRun } from "../embedded/runs.js";
 import { isVoiceLikeAttachment, mergeVoiceTranscriptsIntoUserText } from "../../channels/attachments/voice-stt-webchat.js";
 import { applyReasoningVisibility } from "../streaming/reasoning-visibility.js";
-import { injectSourceContextIntoUserMessage } from "../source-context/injector.js";
-import { isSessionSourceBinding } from "../source-context/types.js";
+import { isSessionSourceBinding, summarizeSourceContext } from "../source-context/types.js";
+import { injectSourceContextsIntoUserMessage } from "../source-context/injector.js";
 import { AsyncQueue } from "./async-queue.js";
 import { hydratePerTurnState, runDirectAgentTurn, tryRunSlashCommand } from "./direct-turn-helpers.js";
 //#region src/agent/service/process-direct-streaming.ts
@@ -227,7 +227,8 @@ async function* runProcessDirectStreaming(deps, input) {
 					});
 					const traceRow = reviewTraceContextEntryFromCommandEvent(event, input.runId);
 					if (traceRow) slashTraceRows.push(traceRow);
-				}
+				},
+				sourceContexts: input.sourceContexts
 			});
 			if (slash.matched) {
 				ranSlashCommand = true;
@@ -251,15 +252,14 @@ async function* runProcessDirectStreaming(deps, input) {
 			const skillTurn = deps.agentManager.prepareSkillTurn(sessionKey, mergedUserText);
 			const textForAgent = skillTurn.text;
 			const userMessage = await deps.buildTranscriptUserMessage(textForAgent, prepared, sessionKey);
-			let sourceEnrichedUserMessage = userMessage;
-			let sourceImages;
+			const turnSourceContexts = input.sourceContexts ?? [];
+			const sourceContexts = [...turnSourceContexts];
 			if (deps.sourceContextResolver) {
 				const metadata = await deps.sessionStore.getMetadata(sessionKey).catch(() => null);
 				const sourceBinding = metadata?.customData && typeof metadata.customData === "object" ? metadata.customData.sourceBinding : void 0;
 				if (isSessionSourceBinding(sourceBinding)) {
 					const sourceContext = await deps.sourceContextResolver(sourceBinding, sessionKey);
-					sourceEnrichedUserMessage = injectSourceContextIntoUserMessage(userMessage, sourceContext);
-					sourceImages = sourceContext?.images;
+					if (sourceContext && !sourceContexts.some((context) => context.kind === sourceContext.kind && context.sourceId === sourceContext.sourceId)) sourceContexts.push(sourceContext);
 				}
 			}
 			if (channel === "webchat") {
@@ -267,11 +267,12 @@ async function* runProcessDirectStreaming(deps, input) {
 					type: "user_message",
 					timestamp: userMessage.timestamp ?? Date.now(),
 					content: readAgentMessageContent(userMessage),
-					media: userMessage.media
+					media: userMessage.media,
+					metadata: turnSourceContexts.length > 0 ? { sourceContexts: turnSourceContexts.map(summarizeSourceContext) } : void 0
 				});
 				if (textForAgent.trim()) deps.enqueueProvisionalSessionTitle?.(sessionKey, textForAgent);
 			}
-			const pendingUserMessage = userMessage;
+			const pendingUserMessage = turnSourceContexts.length > 0 ? injectSourceContextsIntoUserMessage(userMessage, turnSourceContexts) : userMessage;
 			setPendingTranscriptUserMessage(sessionKey, pendingUserMessage);
 			try {
 				const result = await deps.agentManager.withSkillCapabilities(sessionKey, skillTurn.activatedCapabilityNames, () => runDirectAgentTurn({
@@ -281,9 +282,9 @@ async function* runProcessDirectStreaming(deps, input) {
 					config: deps.getConfig()
 				}, {
 					sessionKey,
-					userMessage: sourceEnrichedUserMessage,
+					userMessage,
 					abortSignal: signal,
-					sourceImages,
+					sourceContexts,
 					runId: input.runId,
 					onEvent: (embeddedEvent) => {
 						const event = { ...embeddedEvent };

package/dist/src/agent/service.js

@@ -3,10 +3,10 @@ import { init_logger } from "../utils/logger.js";
 import { getUserProfile } from "../storage/sqlite/user-context-repository.js";
 import { parseNoteAttachmentTarget } from "../notes/attachment-ref.js";
 import { getAgentDefaultModelRef, init_schema } from "../config/schema.js";
-import { init_agent_scope, resolveAgentHomeDir, resolveDefaultAgentId } from "./agent-scope.js";
-import { init_providers, resolveModel } from "../providers/index.js";
 import { applyConfigOverrides } from "../config/runtime-overrides.js";
+import { init_agent_scope, resolveAgentHomeDir, resolveDefaultAgentId } from "./agent-scope.js";
 import { extractProfileAgentId } from "../config/agent-profile.js";
+import { init_providers, resolveModel } from "../providers/index.js";
 import { extractTextContent } from "./context/workspace.js";
 import { effectiveWorkspacePathForSession } from "../session/session-workspace.js";
 import { getProjectForSession } from "../projects/workspace.js";

package/dist/src/agent/session/session-config-service.d.ts

@@ -35,6 +35,7 @@ export interface PatchSessionAgentConfigInput {
     verboseLevel?: string;
     workingDirectory?: string;
     responseLanguage?: string | null;
+    userContextMode?: 'enabled' | 'off' | 'temporary';
 }
 export interface PatchSessionAgentConfigResult {
     ok: boolean;

package/dist/src/agent/session/session-config-service.js

@@ -85,6 +85,17 @@ var SessionConfigService = class {
 			}
 			this.opts.agentManager.removeAgent(sessionKey);
 		}
+		if (partial.userContextMode !== void 0) {
+			if (![
+				"enabled",
+				"off",
+				"temporary"
+			].includes(partial.userContextMode)) return {
+				ok: false,
+				error: "Invalid user context mode"
+			};
+			await this.opts.sessionConfigStore.update(sessionKey, { userContextMode: partial.userContextMode });
+		}
 		if (partial.workingDirectory !== void 0) {
 			if (!this.opts.getConfig()) return {
 				ok: false,

package/dist/src/agent/session/session-inspector.d.ts

@@ -56,6 +56,7 @@ export interface SessionAgentConfigView {
     effectiveWorkspacePath: string;
     workingDirectoryLocked: boolean;
     workspaceSource: 'project' | 'session_override' | 'agent_default_root' | 'agent_workspace';
+    userContextMode: 'enabled' | 'off' | 'temporary';
 }
 export declare class SessionInspector {
     private readonly opts;

package/dist/src/agent/session/session-inspector.js

@@ -1,8 +1,8 @@
 import { createLogger } from "../../utils/logger/index.js";
 import { init_logger } from "../../utils/logger.js";
 import { init_workspace_defaults, resolveDefaultAgentWorkspaceDir } from "../../config/workspace-defaults.js";
-import { init_providers, resolveModel } from "../../providers/index.js";
 import { resolveEffectiveAgentProfileForSession } from "../../config/agent-profile.js";
+import { init_providers, resolveModel } from "../../providers/index.js";
 import { effectiveWorkspacePathForSession, projectWorkspacePath } from "../../session/session-workspace.js";
 import { getProjectForSession } from "../../projects/workspace.js";
 import { resolveCompactionPolicy } from "../memory/compaction-policy.js";
@@ -153,6 +153,7 @@ var SessionInspector = class {
 			verboseLevel,
 			effectiveWorkspacePath,
 			workingDirectoryLocked: Boolean(projectWorkspace || hasSessionWorkspaceOverride),
+			userContextMode: sc?.userContextMode ?? "enabled",
 			workspaceSource: projectWorkspace ? "project" : hasSessionWorkspaceOverride ? "session_override" : isDefaultWorkspaceRoot ? "agent_default_root" : "agent_workspace"
 		};
 	}

package/dist/src/agent/skills/hub-lock.js

@@ -1,5 +1,5 @@
-import { init_write_file_atomic, writeTextAtomicSync } from "../../infra/write-file-atomic.js";
 import { init_paths, resolveSkillsLockPath } from "../../config/paths.js";
+import { init_write_file_atomic, writeTextAtomicSync } from "../../infra/write-file-atomic.js";
 import { existsSync, readFileSync } from "node:fs";
 //#region src/agent/skills/hub-lock.ts
 /**

package/dist/src/agent/source-context/budget.d.ts

@@ -0,0 +1,3 @@
+import type { AgentSourceContext } from './types.js';
+export declare const MAX_TURN_CONTEXT_TOKENS = 32000;
+export declare function fitSourceContextsToBudget(contexts: readonly AgentSourceContext[], maxTokens?: number): AgentSourceContext[];

package/dist/src/agent/source-context/budget.js

@@ -0,0 +1,21 @@
+//#region src/agent/source-context/budget.ts
+const MAX_TURN_CONTEXT_TOKENS = 32e3;
+const CHARS_PER_TOKEN_ESTIMATE = 4;
+const TRUNCATION_MARKER = "\n\n[context truncated]";
+function fitSourceContextsToBudget(contexts, maxTokens = MAX_TURN_CONTEXT_TOKENS) {
+	let remainingChars = Math.max(0, maxTokens) * CHARS_PER_TOKEN_ESTIMATE;
+	return contexts.map((context, index) => {
+		const remainingItems = contexts.length - index;
+		const quota = Math.floor(remainingChars / remainingItems);
+		const text = context.text.length <= quota ? context.text : quota <= 21 ? TRUNCATION_MARKER.slice(0, quota) : `${context.text.slice(0, quota - 21)}${TRUNCATION_MARKER}`;
+		remainingChars = Math.max(0, remainingChars - text.length);
+		return {
+			...context,
+			text,
+			tokenEstimate: Math.ceil(text.length / CHARS_PER_TOKEN_ESTIMATE),
+			truncated: context.truncated === true || text.length < context.text.length
+		};
+	});
+}
+//#endregion
+export { MAX_TURN_CONTEXT_TOKENS, fitSourceContextsToBudget };

package/dist/src/agent/source-context/index.js

@@ -1,3 +1,3 @@
-import { injectSourceContextIntoUserMessage } from "./injector.js";
-import { isSessionSourceBinding } from "./types.js";
-export { injectSourceContextIntoUserMessage, isSessionSourceBinding };
+import { isSessionSourceBinding, isTurnContextRef, parseTurnContextRefs, summarizeSourceContext } from "./types.js";
+import { injectSourceContextsIntoUserMessage } from "./injector.js";
+export { injectSourceContextsIntoUserMessage, isSessionSourceBinding, isTurnContextRef, parseTurnContextRefs, summarizeSourceContext };

package/dist/src/agent/source-context/injector.d.ts

@@ -1,3 +1,3 @@
 import type { AgentMessage } from '@earendil-works/pi-agent-core';
-import type { AgentSourceContext } from './types.js';
-export declare function injectSourceContextIntoUserMessage(message: AgentMessage, sourceContext: AgentSourceContext | null): AgentMessage;
+import { type AgentSourceContext } from './types.js';
+export declare function injectSourceContextsIntoUserMessage(message: AgentMessage, sourceContexts: readonly AgentSourceContext[]): AgentMessage;