@xopcai/xopc 0.0.202 → 0.0.204

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

@@ -1,16 +1,19 @@
 import { createLogger } from "../../utils/logger/index.js";
 import { init_logger } from "../../utils/logger.js";
 import { resolveAgentTurnTimeoutMs, runAgentTurnWithTimeout } from "../orchestration/run-agent-turn-with-timeout.js";
+import { resolvePromptCachePolicy } from "../../providers/prompt-cache-plan.js";
 import { wrapStreamFnForXopcExtensions } from "./xopc-stream-bridge.js";
 import { acquireEmbeddedSessionRunner } from "./session-runner.js";
 import { getAssistantTurnErrorMessage, isAssistantTurnAborted, isAssistantTurnFailed, maybeRetryTurnAfterTransientLlmFailure, stripTrailingErrorAssistantMessages } from "../orchestration/llm-turn-retry.js";
-import { pruneToolResultsToFit } from "../memory/context-budget.js";
+import { projectContextForModel } from "../memory/context-budget.js";
 import { abortEmbeddedRun, queueEmbeddedSteer, registerEmbeddedRun, unregisterEmbeddedRun } from "./runs.js";
 import { lastAssistantPlainText, subscribeEmbeddedSessionEvents } from "./subscribe-session.js";
 import { detectToolLoops } from "../orchestration/loop-guard.js";
 import { tryApplySessionTranscriptHygiene } from "../transcript/transcript-hygiene.js";
 import { createSqliteTranscriptRuntime } from "./transcript-runtime.js";
 import { isContextOverflowError } from "../orchestration/context-overflow.js";
+import { buildPromptCacheSnapshot, observePromptCacheSnapshot } from "../../providers/prompt-cache-observability.js";
+import { isPromptCacheExpired, recordPromptCacheTouch } from "../../providers/prompt-cache-lifecycle.js";
 //#region src/agent/embedded/run-turn.ts
 init_logger();
 const log = createLogger("EmbeddedRun");
@@ -98,6 +101,7 @@ async function runXopcEmbeddedTurn(params) {
 	const { sessionKey, runId, userMessage, model, tools, systemPrompt, thinkingLevel, workspaceDir, sessionStore, onEvent } = params;
 	const timeoutMs = params.timeoutMs || resolveAgentTurnTimeoutMs();
 	const resolvedModel = requireEmbeddedModel(model, params.modelRef);
+	const promptCachePolicy = resolvePromptCachePolicy(params.promptCachePolicy);
 	const transcriptRuntime = params.transcriptRuntime ?? (sessionStore ? await createSqliteTranscriptRuntime({
 		sessionKey,
 		sessionStore
@@ -119,7 +123,7 @@ async function runXopcEmbeddedTurn(params) {
 		});
 		const { session, reused } = runner;
 		runner.piSm.setActiveTurnId?.(runId);
-		const streamFnWithXopcExtensions = wrapStreamFnForXopcExtensions(session.agent.streamFunction);
+		const streamFnWithXopcExtensions = wrapStreamFnForXopcExtensions(session.agent.streamFunction, params.promptCachePolicy);
 		const loggingStreamFn = (streamModel, context, options) => {
 			const sourceMessages = [...context.messages];
 			const hygienicMessages = tryApplySessionTranscriptHygiene(sourceMessages, streamModel);
@@ -141,26 +145,35 @@ async function runXopcEmbeddedTurn(params) {
 					tools: contextTools
 				};
 			}
-			const pruned = pruneToolResultsToFit({
+			const projection = projectContextForModel({
 				messages: effectiveContext.messages,
 				contextWindow: streamModel.contextWindow ?? 128e3,
 				systemPrompt: effectiveContext.systemPrompt,
 				tools: effectiveContext.tools,
-				canCompact: false
+				canCompact: false,
+				reason: isPromptCacheExpired(sessionKey, streamModel, promptCachePolicy) ? "cache_expired" : "normal"
 			});
-			if (pruned.prunedToolResults > 0) {
+			if (projection.prunedToolResults > 0 || projection.prunedImages > 0) {
 				effectiveContext = {
 					...effectiveContext,
-					messages: pruned.messages
+					messages: projection.messages
 				};
 				log.warn({
 					sessionKey,
 					runId,
-					prunedToolResults: pruned.prunedToolResults,
-					estimatedTokens: pruned.evaluation.estimatedTokens,
-					hardLimitTokens: pruned.evaluation.hardLimitTokens
-				}, "Pruned old tool results to fit the model context window");
+					prunedToolResults: projection.prunedToolResults,
+					prunedImages: projection.prunedImages,
+					estimatedTokens: projection.evaluation.estimatedTokens,
+					hardLimitTokens: projection.evaluation.hardLimitTokens
+				}, "Projected a smaller provider context");
 			}
+			const promptCacheSnapshot = buildPromptCacheSnapshot({
+				model: streamModel,
+				systemPrompt: effectiveContext.systemPrompt,
+				tools: effectiveContext.tools,
+				reasoning: options?.reasoning
+			});
+			const promptCacheChanges = observePromptCacheSnapshot(sessionKey, promptCacheSnapshot);
 			log.debug({
 				sessionKey,
 				runId,
@@ -173,20 +186,20 @@ async function runXopcEmbeddedTurn(params) {
 				lastUserMessagePreview: getLastUserMessagePreview(effectiveContext.messages),
 				loopWarningInjected: !!loopGuard.injection,
 				hiddenToolCount: loopGuard.hiddenTools.size,
+				promptCache: promptCacheSnapshot,
+				promptCacheChanges,
 				...process.env.XOPC_LOG_LLM_PAYLOAD === "true" ? { effectiveContext: {
 					systemPrompt: effectiveContext.systemPrompt,
 					messages: effectiveContext.messages,
 					tools: effectiveContext.tools
 				} } : {}
 			}, "Sending messages to AI");
-			return streamFnWithXopcExtensions(streamModel, effectiveContext, {
-				...options,
-				...params.cacheRetention ? { cacheRetention: params.cacheRetention } : {}
-			});
+			return streamFnWithXopcExtensions(streamModel, effectiveContext, { ...options });
 		};
 		session.agent.streamFunction = loggingStreamFn;
-		if (onEvent) unsubscribe = subscribeEmbeddedSessionEvents(session, (event) => {
-			onEvent({
+		unsubscribe = subscribeEmbeddedSessionEvents(session, (event) => {
+			if (event.type === "message_end" && event.message.role === "assistant") recordPromptCacheTouch(sessionKey, resolvedModel, event.message.usage);
+			onEvent?.({
 				...event,
 				runId
 			});

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

@@ -1,5 +1,5 @@
 import type { AgentMessage, AgentToolResult, ThinkingLevel } from '@earendil-works/pi-agent-core';
-import type { AssistantMessageEvent, Model, Api, CacheRetention, ImageContent } from '@earendil-works/pi-ai';
+import type { AssistantMessageEvent, Model, Api, ImageContent } from '@earendil-works/pi-ai';
 import type { SessionStore } from '../../session/store.js';
 import type { EmbeddedTranscriptRuntime } from './transcript-runtime.js';
 export type EmbeddedStreamEvent = {
@@ -92,7 +92,7 @@ export type RunXopcEmbeddedTurnParams = {
     tools: import('@earendil-works/pi-agent-core').AgentTool[];
     systemPrompt: string;
     thinkingLevel?: ThinkingLevel;
-    cacheRetention?: CacheRetention;
+    promptCachePolicy?: import('../../providers/prompt-cache-plan.js').PromptCachePolicy;
     workspaceDir: string;
     sessionStore?: SessionStore;
     transcriptRuntime?: EmbeddedTranscriptRuntime;

package/dist/src/agent/embedded/xopc-stream-bridge.d.ts

@@ -1,4 +1,5 @@
 import type { StreamFn } from '@earendil-works/pi-agent-core';
+import type { PromptCachePolicy } from '../../providers/prompt-cache-plan.js';
 /**
  * pi-coding-agent's default {@link createAgentSession} streamFn always routes through
  * pi-ai's HTTP `streamSimple`, so xopc plugin providers (whose models carry the sentinel
@@ -8,4 +9,4 @@ import type { StreamFn } from '@earendil-works/pi-agent-core';
  *
  * Use this by reassigning {@link Agent.streamFunction} after `createAgentSession` returns.
  */
-export declare function wrapStreamFnForXopcExtensions(originalStreamFn: StreamFn): StreamFn;
+export declare function wrapStreamFnForXopcExtensions(originalStreamFn: StreamFn, promptCachePolicy?: PromptCachePolicy): StreamFn;

package/dist/src/agent/embedded/xopc-stream-bridge.js

@@ -13,11 +13,11 @@ init_providers();
 *
 * Use this by reassigning {@link Agent.streamFunction} after `createAgentSession` returns.
 */
-function wrapStreamFnForXopcExtensions(originalStreamFn) {
+function wrapStreamFnForXopcExtensions(originalStreamFn, promptCachePolicy) {
 	const extensionStreamFn = createExtensionAwareStreamFn();
 	return ((model, context, options) => {
 		if (model.baseUrl === "extension://provider-plugin") return extensionStreamFn(model, preparePromptCacheContext(model, context), options);
-		return originalStreamFn(model, preparePromptCacheContext(model, context), withPromptCachePayloadTransform(model, context, options));
+		return originalStreamFn(model, preparePromptCacheContext(model, context), withPromptCachePayloadTransform(model, context, options, promptCachePolicy));
 	});
 }
 //#endregion

package/dist/src/agent/memory/compaction-planner.js

@@ -136,13 +136,29 @@ function planCompactionChunks(messages, maxChunkTokens) {
 	flush();
 	return chunks;
 }
-const IDENTIFIER_PATTERN = /(?:\/?[\w.-]+\/)+(?:[\w.@-]+)|https?:\/\/[^\s)>]+|\b[0-9a-f]{8,64}\b|\b\d{4}-\d{2}-\d{2}\b|\bport\s+\d{2,5}\b/gi;
+const IDENTIFIER_PATTERNS = [
+	/https?:\/\/[^\s)>]+/gi,
+	/(?<![\w:/])\/(?:[\w.@-]+\/)*[\w.@-]+/g,
+	/(?<![\w./-])(?:[\w.@-]+\/)+[\w.@-]+\.[a-z0-9]{1,10}\b/gi,
+	/\b(?:release|feature|fix|hotfix|bugfix|chore)\/[\w.@-]+\b/gi,
+	/\b[0-9a-f]{8,64}\b/gi,
+	/\b\d{4}-\d{2}-\d{2}\b/g,
+	/\bport\s+\d{2,5}\b/gi
+];
 function extractExactIdentifiers(messages, limit = 12) {
 	const text = messages.map(serializeMessageForCompaction).join("\n");
-	const found = /* @__PURE__ */ new Set();
-	for (const match of text.matchAll(IDENTIFIER_PATTERN)) {
+	const matches = [];
+	for (const pattern of IDENTIFIER_PATTERNS) for (const match of text.matchAll(pattern)) {
 		const identifier = match[0].trim();
-		if (identifier.length < 4) continue;
+		if (identifier.length < 4 || match.index == null) continue;
+		matches.push({
+			identifier,
+			index: match.index
+		});
+	}
+	matches.sort((left, right) => left.index - right.index);
+	const found = /* @__PURE__ */ new Set();
+	for (const { identifier } of matches) {
 		found.add(identifier);
 		if (found.size >= limit) break;
 	}

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

@@ -102,6 +102,18 @@ function summaryAudit(summary, identifiers) {
 	if (missingIdentifiers.length > 0) issues.push(`missing exact identifiers: ${missingIdentifiers.join(", ")}`);
 	return issues;
 }
+function enforceSummaryContract(summary, identifiers) {
+	let normalized = summary.trim();
+	for (const heading of REQUIRED_SUMMARY_HEADINGS) if (!new RegExp(`^#{1,3}\\s+${heading.replace(/[.*+?^${}()|[\\]\\]/g, "\\$&")}\\s*$`, "im").test(normalized)) normalized = `${normalized}\n\n## ${heading}\nNone`.trim();
+	const missingIdentifiers = identifiers.filter((identifier) => !normalized.includes(identifier));
+	if (missingIdentifiers.length === 0) return normalized;
+	const exactHeading = /^#{1,3}\s+Exact identifiers\s*$/im.exec(normalized);
+	if (!exactHeading) return normalized;
+	const insertAt = exactHeading.index + exactHeading[0].length;
+	const identifierList = missingIdentifiers.map((identifier) => `- \`${identifier}\``).join("\n");
+	const suffix = normalized.slice(insertAt).replace(/^\r?\n[ \t]*None[ \t]*(?=\r?\n#{1,3}\s|$)/i, "");
+	return `${normalized.slice(0, insertAt)}\n${identifierList}${suffix}`;
+}
 function createLinkedAbortSignal(parent, timeoutMs) {
 	const controller = new AbortController();
 	let timeoutTriggered = false;
@@ -216,7 +228,7 @@ Do not omit facts already present and do not invent new facts.
 ${summary}
 </summary_to_repair>`;
 				const repaired = await this.callSummaryModels(models, repairPrompt, signal);
-				summary = repaired.summary;
+				summary = enforceSummaryContract(repaired.summary, identifiers);
 				summaryModelRef = repaired.modelRef;
 				const remaining = summaryAudit(summary, identifiers);
 				if (remaining.length > 0) throw new Error(`Compaction summary failed quality audit: ${remaining.join("; ")}`);
@@ -233,7 +245,7 @@ ${summary}
 			if (parentSignal?.aborted) throw parentSignal.reason;
 			const linked = createLinkedAbortSignal(parentSignal, this.config.summaryTimeoutMs);
 			try {
-				const summary = extractSummaryText(await completeWithResolvedCredentials(model, {
+				const result = await completeWithResolvedCredentials(model, {
 					systemPrompt: COMPACTION_SYSTEM_PROMPT,
 					messages: [{
 						role: "user",
@@ -243,10 +255,16 @@ ${summary}
 				}, {
 					maxTokens: this.config.summaryMaxTokens,
 					temperature: .2,
+					reasoning: "low",
 					signal: linked.signal,
 					sessionId: COMPACTION_CACHE_SESSION_ID
-				}));
-				if (!summary) throw new Error("Compaction model returned an empty summary");
+				});
+				const summary = extractSummaryText(result);
+				if (!summary) {
+					const response = result;
+					const contentTypes = Array.isArray(response.content) ? response.content.map((block) => String(block?.type ?? "unknown")) : [];
+					throw new Error(`Compaction model returned an empty summary (stopReason=${String(response.stopReason ?? "unknown")}, rawStopReason=${String(response.rawStopReason ?? "unknown")}, contentTypes=${contentTypes.join(",") || "none"}, outputTokens=${String(response.usage?.output ?? "unknown")}, reasoningTokens=${String(response.usage?.reasoning ?? "unknown")})`);
+				}
 				return {
 					summary,
 					modelRef: `${model.provider}/${model.id}`

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

@@ -16,6 +16,7 @@ export interface ContextBudgetInput {
     minToolResultKeepChars?: number;
     canCompact?: boolean;
 }
+export type ContextProjectionReason = 'normal' | 'cache_expired' | 'hard_limit';
 export interface ContextBudgetEvaluation {
     route: ContextBudgetRoute;
     estimatedTokens: number;
@@ -33,8 +34,12 @@ export declare function estimateTextTokens(text: string): number;
 export declare function estimateMessageTokens(message: AgentMessage): number;
 export declare function estimateMessagesTokens(messages: readonly AgentMessage[]): number;
 export declare function evaluateContextBudget(input: ContextBudgetInput): ContextBudgetEvaluation;
-export declare function pruneToolResultsToFit(input: ContextBudgetInput): {
+export declare function projectContextForModel(input: ContextBudgetInput & {
+    reason: ContextProjectionReason;
+    recentTurns?: number;
+}): {
     messages: AgentMessage[];
     evaluation: ContextBudgetEvaluation;
     prunedToolResults: number;
+    prunedImages: number;
 };

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

@@ -73,7 +73,7 @@ function evaluateContextBudget(input) {
 		usagePercent: estimatedTokens / contextWindow
 	};
 }
-function pruneToolResultsToFit(input) {
+function truncateToolResultsToFit(input) {
 	const initial = evaluateContextBudget(input);
 	if (initial.estimatedTokens <= initial.hardLimitTokens || initial.reducibleToolResultTokens === 0) return {
 		messages: input.messages,
@@ -101,5 +101,97 @@ function pruneToolResultsToFit(input) {
 		prunedToolResults
 	};
 }
+function protectedRecentTurnStart(messages, recentTurns) {
+	let remaining = recentTurns;
+	for (let index = messages.length - 1; index >= 0; index -= 1) {
+		if (messages[index].role !== "assistant") continue;
+		remaining -= 1;
+		if (remaining === 0) return index;
+	}
+	return 0;
+}
+function replaceOldImages(message) {
+	const content = message.content;
+	if (!Array.isArray(content)) return {
+		message,
+		removed: 0
+	};
+	let removed = 0;
+	const nextContent = content.map((block) => {
+		if (!block || typeof block !== "object" || block.type !== "image") return block;
+		removed += 1;
+		return {
+			type: "text",
+			text: "[Earlier image omitted from the model context.]"
+		};
+	});
+	return removed > 0 ? {
+		message: {
+			...message,
+			content: nextContent
+		},
+		removed
+	} : {
+		message,
+		removed: 0
+	};
+}
+function projectContextForModel(input) {
+	const initial = evaluateContextBudget(input);
+	const mustFit = input.reason === "hard_limit" || initial.estimatedTokens > initial.hardLimitTokens;
+	if (input.reason !== "cache_expired" && !mustFit) return {
+		messages: input.messages,
+		evaluation: initial,
+		prunedToolResults: 0,
+		prunedImages: 0
+	};
+	if (input.reason === "cache_expired" && initial.usagePercent < .3 && !mustFit) return {
+		messages: input.messages,
+		evaluation: initial,
+		prunedToolResults: 0,
+		prunedImages: 0
+	};
+	const protectedStart = protectedRecentTurnStart(input.messages, input.recentTurns ?? 3);
+	let prunedToolResults = 0;
+	let prunedImages = 0;
+	let messages = input.messages.map((message, index) => {
+		if (index >= protectedStart) return message;
+		const imageProjection = replaceOldImages(message);
+		prunedImages += imageProjection.removed;
+		if (getToolResultTextLength(imageProjection.message) <= 3e3) return imageProjection.message;
+		prunedToolResults += 1;
+		return truncateToolResultMessage(imageProjection.message, 3e3, { minKeepChars: 1500 });
+	});
+	let evaluation = evaluateContextBudget({
+		...input,
+		messages
+	});
+	if (input.reason === "cache_expired" && evaluation.usagePercent > .5) {
+		messages = messages.map((message, index) => {
+			if (index >= protectedStart || getToolResultTextLength(message) <= 400) return message;
+			prunedToolResults += 1;
+			return truncateToolResultMessage(message, 400, { minKeepChars: 200 });
+		});
+		evaluation = evaluateContextBudget({
+			...input,
+			messages
+		});
+	}
+	if (evaluation.estimatedTokens > evaluation.hardLimitTokens) {
+		const fitted = truncateToolResultsToFit({
+			...input,
+			messages
+		});
+		messages = fitted.messages;
+		prunedToolResults += fitted.prunedToolResults;
+		evaluation = fitted.evaluation;
+	}
+	return {
+		messages,
+		evaluation,
+		prunedToolResults,
+		prunedImages
+	};
+}
 //#endregion
-export { estimateMessageTokens, estimateMessagesTokens, estimateTextTokens, evaluateContextBudget, pruneToolResultsToFit };
+export { estimateMessageTokens, estimateMessagesTokens, estimateTextTokens, evaluateContextBudget, projectContextForModel };

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

@@ -1,8 +1,8 @@
-import { buildMemoryRuntime } from "../../agent-runtime/memory-runtime.js";
 import { isMemorySubsystemEnabled } from "./memory-config.js";
 import { BuiltinMemoryProvider } from "./builtin-provider.js";
 import { MemoryManager } from "./manager.js";
 import { loadMemoryPluginProviders } from "./plugin-discovery.js";
+import { buildMemoryRuntime } from "../../agent-runtime/memory-runtime.js";
 //#region src/agent/memory/create-memory-manager.ts
 function createMemoryManagerFromConfig(config) {
 	const routing = resolveMemoryManagerOptions(config);

package/dist/src/agent/prompt/cache-boundary.d.ts

@@ -22,3 +22,5 @@ export declare function splitPromptCacheBoundary(text: string): {
  * Trims trailing whitespace per line, normalizes line endings, trims overall.
  */
 export declare function normalizePromptSection(text: string): string;
+/** Add stable content immediately before the cache boundary. */
+export declare function appendStablePromptSection(systemPrompt: string, section: string): string;

package/dist/src/agent/prompt/cache-boundary.js

@@ -31,5 +31,14 @@ function splitPromptCacheBoundary(text) {
 function normalizePromptSection(text) {
 	return text.replace(/\r\n?/g, "\n").replace(/[ \t]+$/gm, "").trim();
 }
+/** Add stable content immediately before the cache boundary. */
+function appendStablePromptSection(systemPrompt, section) {
+	const normalizedSection = normalizePromptSection(section);
+	if (!normalizedSection) return systemPrompt;
+	const split = splitPromptCacheBoundary(systemPrompt);
+	if (!split) return [normalizePromptSection(systemPrompt), normalizedSection].filter(Boolean).join("\n\n");
+	const stablePrefix = [split.stablePrefix, normalizedSection].filter(Boolean).join("\n\n");
+	return split.dynamicSuffix ? `${stablePrefix}${PROMPT_CACHE_BOUNDARY}${split.dynamicSuffix}` : `${stablePrefix}${PROMPT_CACHE_BOUNDARY}`;
+}
 //#endregion
-export { PROMPT_CACHE_BOUNDARY, normalizePromptSection, splitPromptCacheBoundary, stripPromptCacheBoundary };
+export { PROMPT_CACHE_BOUNDARY, appendStablePromptSection, normalizePromptSection, splitPromptCacheBoundary, stripPromptCacheBoundary };

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

@@ -1,16 +1,13 @@
 import type { EmbeddedContextFile } from '../../bootstrap/types.js';
 export declare const CONTEXT_FILE_ORDER: Map<string, number>;
-export declare const DYNAMIC_CONTEXT_FILE_BASENAMES: Set<string>;
 export declare const DEFAULT_HEARTBEAT_PROMPT_CONTEXT_BLOCK = "Default heartbeat prompt:\n`Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.`";
 export declare function normalizeContextFilePath(pathValue: string): string;
 export declare function getContextFileBasename(pathValue: string): string;
-export declare function isDynamicContextFile(pathValue: string): boolean;
 export declare function sanitizeContextFileContentForPrompt(content: string): string;
 export declare function sortContextFilesForPrompt(contextFiles: EmbeddedContextFile[]): EmbeddedContextFile[];
 export declare function buildProjectContextSection(params: {
     files: EmbeddedContextFile[];
     heading: string;
-    dynamic: boolean;
 }): string[];
-/** Whether HEARTBEAT.md is injected as dynamic context (vs behavior-only section). */
+/** Heartbeat content belongs to the heartbeat user turn, never the system prompt. */
 export declare function isHeartbeatContextFile(pathValue: string): boolean;

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

@@ -9,7 +9,6 @@ const CONTEXT_FILE_ORDER = new Map([
 	["bootstrap.md", 60],
 	["memory.md", 70]
 ]);
-const DYNAMIC_CONTEXT_FILE_BASENAMES = new Set(["heartbeat.md"]);
 const DEFAULT_HEARTBEAT_PROMPT_CONTEXT_BLOCK = "Default heartbeat prompt:\n`Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.`";
 function normalizeContextFilePath(pathValue) {
 	return pathValue.trim().replace(/\\/g, "/");
@@ -18,9 +17,6 @@ function getContextFileBasename(pathValue) {
 	const normalizedPath = normalizeContextFilePath(pathValue);
 	return (normalizedPath.split("/").pop() ?? normalizedPath).toLowerCase();
 }
-function isDynamicContextFile(pathValue) {
-	return DYNAMIC_CONTEXT_FILE_BASENAMES.has(getContextFileBasename(pathValue));
-}
 function sanitizeContextFileContentForPrompt(content) {
 	return content.replaceAll(DEFAULT_HEARTBEAT_PROMPT_CONTEXT_BLOCK, "").replace(/\n{3,}/g, "\n\n");
 }
@@ -38,19 +34,16 @@ function sortContextFilesForPrompt(contextFiles) {
 function buildProjectContextSection(params) {
 	if (params.files.length === 0) return [];
 	const lines = [params.heading, ""];
-	if (params.dynamic) lines.push("The following frequently-changing project context files are kept below the cache boundary when possible:", "");
-	else {
-		const hasSoulFile = params.files.some((file) => getContextFileBasename(file.path) === "soul.md");
-		lines.push("The following project context files have been loaded:");
-		if (hasSoulFile) lines.push("If SOUL.md is present, embody its persona and tone. Avoid stiff, generic replies; follow its guidance unless higher-priority instructions override it.");
-		lines.push("");
-	}
+	const hasSoulFile = params.files.some((file) => getContextFileBasename(file.path) === "soul.md");
+	lines.push("The following project context files have been loaded:");
+	if (hasSoulFile) lines.push("If SOUL.md is present, embody its persona and tone. Avoid stiff, generic replies; follow its guidance unless higher-priority instructions override it.");
+	lines.push("");
 	for (const file of params.files) lines.push(`## ${file.path}`, "", sanitizeContextFileContentForPrompt(file.content), "");
 	return lines;
 }
-/** Whether HEARTBEAT.md is injected as dynamic context (vs behavior-only section). */
+/** Heartbeat content belongs to the heartbeat user turn, never the system prompt. */
 function isHeartbeatContextFile(pathValue) {
 	return getContextFileBasename(pathValue) === DEFAULT_HEARTBEAT_FILENAME.toLowerCase();
 }
 //#endregion
-export { CONTEXT_FILE_ORDER, DEFAULT_HEARTBEAT_PROMPT_CONTEXT_BLOCK, DYNAMIC_CONTEXT_FILE_BASENAMES, buildProjectContextSection, getContextFileBasename, isDynamicContextFile, isHeartbeatContextFile, normalizeContextFilePath, sanitizeContextFileContentForPrompt, sortContextFilesForPrompt };
+export { CONTEXT_FILE_ORDER, DEFAULT_HEARTBEAT_PROMPT_CONTEXT_BLOCK, buildProjectContextSection, getContextFileBasename, isHeartbeatContextFile, normalizeContextFilePath, sanitizeContextFileContentForPrompt, sortContextFilesForPrompt };

package/dist/src/agent/prompt/service-prompt-builder.js

@@ -7,6 +7,7 @@ import { getInteractionState } from "../../storage/sqlite/interaction-state-repo
 import { DEFAULT_USER_TRUST_LEVEL } from "../../user-context/trust-policy.js";
 import { getUserTrustPolicy } from "../../storage/sqlite/user-trust-repository.js";
 import "../../storage/sqlite/index.js";
+import { appendStablePromptSection } from "./cache-boundary.js";
 import { resolveSystemPromptBuildParams } from "./system-prompt-params.js";
 import { buildSystemPrompt } from "./system-prompt.js";
 import { resolveResponseLanguageForSession } from "./response-language.js";
@@ -85,7 +86,7 @@ var SystemPromptBuilder = class {
 			customInstructions: options.customInstructions
 		});
 		const skillPrompt = options.skillPromptText !== void 0 ? options.skillPromptText : this.skillManager.getPromptForSkillAllowlist(options.skillAllowlist, options.registeredToolNames);
-		const fullPrompt = skillPrompt ? `${basePrompt}\n\n${skillPrompt}` : basePrompt;
+		const fullPrompt = skillPrompt ? appendStablePromptSection(basePrompt, skillPrompt) : basePrompt;
 		log.debug({
 			baseLength: basePrompt.length,
 			skillLength: skillPrompt?.length || 0,

package/dist/src/agent/prompt/system-prompt.d.ts

@@ -12,7 +12,7 @@ import type { ProviderSystemPromptContribution } from './contribution.js';
 import { type RuntimeInfoInput } from './sections/workspace-runtime.js';
 import type { MemoryCitationsMode, PromptMode, SilentReplyPromptMode } from './types.js';
 export type { MemoryCitationsMode } from './types.js';
-export { getContextFileBasename, isDynamicContextFile, sortContextFilesForPrompt, } from './sections/project-context.js';
+export { getContextFileBasename, sortContextFilesForPrompt, } from './sections/project-context.js';
 export interface SystemPromptOptions {
     contextFiles?: EmbeddedContextFile[];
     promptMode?: PromptMode;
@@ -21,8 +21,6 @@ export interface SystemPromptOptions {
     /** Registered tool names for Tooling section and memory/skills gating. */
     toolNames?: string[];
     toolSummaries?: Record<string, string>;
-    /** @deprecated Prefer toolNames — kept for skill-section gating compatibility. */
-    availableTools?: string[];
     memoryCitationsMode?: MemoryCitationsMode;
     includeMemorySection?: boolean;
     userTimezone?: string;

package/dist/src/agent/prompt/system-prompt.js

@@ -3,7 +3,7 @@ import { PROMPT_CACHE_BOUNDARY, splitPromptCacheBoundary } from "./cache-boundar
 import { buildAestheticSection, buildExecutionBiasSection, buildHumanCollaborationSection, buildProblemSolvingSection, buildSafetySection, buildToolCallStyleSection, buildWorkContinuitySection } from "./sections/behavior.js";
 import { buildExternalMemorySection, buildMemorySection, buildSkillsSection } from "./sections/memory-skills.js";
 import { buildHeartbeatBehaviorSection, buildMessagingSection, buildOutputDirectivesSection, buildSilentRepliesSection, buildTimeSection } from "./sections/messaging-runtime.js";
-import { buildProjectContextSection, getContextFileBasename, isDynamicContextFile, sortContextFilesForPrompt } from "./sections/project-context.js";
+import { buildProjectContextSection, getContextFileBasename, isHeartbeatContextFile, sortContextFilesForPrompt } from "./sections/project-context.js";
 import { buildToolingSection, hasSkillsTools } from "./sections/tooling.js";
 import { buildRuntimeSection, buildWorkspaceFilesIntroSection, buildWorkspaceSection } from "./sections/workspace-runtime.js";
 import { buildResponseLanguageSection } from "./sections/response-language.js";
@@ -16,7 +16,7 @@ function joinSections(sections) {
 * Build system prompt with bootstrap Project Context integration.
 */
 function buildSystemPrompt(workspaceDir, options = {}) {
-	const { contextFiles = [], promptMode = "full", heartbeatEnabled = false, heartbeatPrompt, toolNames: toolNamesOption, toolSummaries, availableTools = [], memoryCitationsMode = "on", includeMemorySection, userTimezone, runtime, agentId, channels = [], externalMemoryInstructions, ttsSystemHint, extraSystemPrompt, activeProjectContext, silentReplyPromptMode = "generic", promptContribution, includeProblemSolving = true, includeToneSection = true, actionTrustLevel, responseLanguage = "auto", customInstructions } = options;
+	const { contextFiles = [], promptMode = "full", heartbeatEnabled = false, heartbeatPrompt, toolNames = [], toolSummaries, memoryCitationsMode = "on", includeMemorySection, userTimezone, runtime, agentId, channels = [], externalMemoryInstructions, ttsSystemHint, extraSystemPrompt, activeProjectContext, silentReplyPromptMode = "generic", promptContribution, includeProblemSolving = true, includeToneSection = true, actionTrustLevel, responseLanguage = "auto", customInstructions } = options;
 	if (promptMode === "none") return joinSections([
 		"You are a personal AI assistant running inside xopc.",
 		customInstructions?.trim() ? `<custom_instructions>\n${customInstructions.trim()}\n</custom_instructions>` : void 0,
@@ -24,13 +24,10 @@ function buildSystemPrompt(workspaceDir, options = {}) {
 		activeProjectContext
 	]);
 	const isMinimal = promptMode === "minimal";
-	const toolNames = toolNamesOption ?? availableTools;
 	const normalizedTools = new Set(toolNames.map((tool) => tool.toLowerCase()));
 	const effectiveAgentId = agentId ?? runtime?.agentId;
 	const sectionOverrides = promptContribution?.sectionOverrides ?? {};
-	const orderedContextFiles = sortContextFilesForPrompt(contextFiles.filter((file) => file.path.trim().length > 0));
-	const stableContextFiles = orderedContextFiles.filter((file) => !isDynamicContextFile(file.path));
-	const dynamicContextFiles = orderedContextFiles.filter((file) => isDynamicContextFile(file.path));
+	const orderedContextFiles = sortContextFilesForPrompt(contextFiles.filter((file) => file.path.trim().length > 0 && !isHeartbeatContextFile(file.path)));
 	const hasProfileMemory = orderedContextFiles.some((file) => getContextFileBasename(file.path) === "memory.md");
 	const stableSections = [
 		"You are a personal AI assistant running inside xopc.",
@@ -79,20 +76,14 @@ function buildSystemPrompt(workspaceDir, options = {}) {
 	}));
 	if (!isMinimal && ttsSystemHint?.trim()) stableSections.push(`## Voice (TTS)\n\n${ttsSystemHint.trim()}`);
 	stableSections.push(joinSections(buildProjectContextSection({
-		files: stableContextFiles,
-		heading: "# Project Context",
-		dynamic: false
+		files: orderedContextFiles,
+		heading: "# Project Context"
 	})));
 	if (!isMinimal) stableSections.push(buildSilentRepliesSection({
 		isMinimal,
 		silentReplyPromptMode
 	}));
 	const dynamicSections = [];
-	dynamicSections.push(joinSections(buildProjectContextSection({
-		files: dynamicContextFiles,
-		heading: stableContextFiles.length > 0 ? "# Dynamic Project Context" : "# Project Context",
-		dynamic: true
-	})));
 	if (extraSystemPrompt?.trim()) {
 		const contextHeader = isMinimal ? "## Subagent Context" : "## Group Chat Context";
 		dynamicSections.push(`${contextHeader}\n\n${extraSystemPrompt.trim()}`);
@@ -129,4 +120,4 @@ function splitBuiltSystemPrompt(text) {
 	return splitPromptCacheBoundary(text);
 }
 //#endregion
-export { buildSystemPrompt, getContextFileBasename, isDynamicContextFile, sortContextFilesForPrompt, splitBuiltSystemPrompt };
+export { buildSystemPrompt, getContextFileBasename, sortContextFilesForPrompt, splitBuiltSystemPrompt };

package/dist/src/agent/tools/cache-stability.d.ts

@@ -0,0 +1,3 @@
+import type { AgentTool } from '@earendil-works/pi-agent-core';
+/** Provider-visible tool order is part of the cached prompt prefix. */
+export declare function sortToolsForPromptCache<T extends Pick<AgentTool, 'name' | 'description'>>(tools: readonly T[]): T[];

package/dist/src/agent/tools/cache-stability.js

@@ -0,0 +1,19 @@
+//#region src/agent/tools/cache-stability.ts
+const TOOL_ORDER = new Map([
+	["xopc_tool_search", 10],
+	["xopc_tool_describe", 20],
+	["xopc_tool_execute", 30]
+]);
+/** Provider-visible tool order is part of the cached prompt prefix. */
+function sortToolsForPromptCache(tools) {
+	return [...tools].sort((left, right) => {
+		const leftOrder = TOOL_ORDER.get(left.name) ?? Number.MAX_SAFE_INTEGER;
+		const rightOrder = TOOL_ORDER.get(right.name) ?? Number.MAX_SAFE_INTEGER;
+		if (leftOrder !== rightOrder) return leftOrder - rightOrder;
+		const byName = left.name.localeCompare(right.name);
+		if (byName !== 0) return byName;
+		return left.description.localeCompare(right.description);
+	});
+}
+//#endregion
+export { sortToolsForPromptCache };

package/dist/src/agent/tools/factory.js

@@ -55,6 +55,7 @@ import { mergeTtsConfigFromAppConfig } from "../../voice/tts/merge-config.js";
 import { createTextToSpeechTool } from "./tts-tool.js";
 import { getAgentCapabilityToolNames } from "../capabilities/registry.js";
 import "../capabilities/index.js";
+import { sortToolsForPromptCache } from "./cache-stability.js";
 //#region src/agent/tools/factory.ts
 init_agent_scope();
 init_logger();
@@ -352,7 +353,7 @@ var AgentToolsFactory = class {
 		return ["create_desktop_pet"];
 	}
 	createAllTools(coreOptions) {
-		return wrapToolsWithProtection(this.createCoreTools(coreOptions), this.deps.toolExecutorConfig);
+		return sortToolsForPromptCache(wrapToolsWithProtection(this.createCoreTools(coreOptions), this.deps.toolExecutorConfig));
 	}
 };
 function filterToolsByDisabledSet(tools, disabled) {