@xopcai/xopc 0.0.201 → 0.0.203

package/dist/src/providers/prompt-cache-payload.js

@@ -1,15 +1,25 @@
 import { splitPromptCacheBoundary, stripPromptCacheBoundary } from "../agent/prompt/cache-boundary.js";
-import { createHash } from "node:crypto";
+import { canonicalizeCacheValue, digestCacheText } from "./prompt-cache-fingerprint.js";
+import { resolvePromptCachePolicy, resolvePromptCacheProviderMode } from "./prompt-cache-plan.js";
+import { applyGoogleManagedPromptCache } from "./google-managed-prompt-cache.js";
 //#region src/providers/prompt-cache-payload.ts
 function asRecord(value) {
 	return value !== null && typeof value === "object" && !Array.isArray(value) ? value : void 0;
 }
-function supportsPromptCacheKey(model) {
-	if (model.api === "openai-codex-responses" || model.api === "azure-openai-responses") return true;
-	if (model.api !== "openai-completions" && model.api !== "openai-responses") return false;
-	return model.provider === "openai" || model.baseUrl?.includes("api.openai.com") === true;
+function buildPromptCacheKey(model, context, reasoning) {
+	const stablePrompt = context.systemPrompt ? splitPromptCacheBoundary(context.systemPrompt)?.stablePrefix ?? stripPromptCacheBoundary(context.systemPrompt) : "";
+	return `xopc-v2-${digestCacheText(`v2\0${model.provider}\0${model.id}\0${reasoning ?? ""}\0${stablePrompt}\0${canonicalizeCacheValue(context.tools ?? [])}`)}`;
 }
-function splitAnthropicSystem(payload) {
+function buildPromptCachePlan(model, context, policyInput, reasoning) {
+	const policy = resolvePromptCachePolicy(policyInput);
+	const providerMode = resolvePromptCacheProviderMode(model, policy);
+	return {
+		policy,
+		providerMode,
+		...providerMode === "implicit" || providerMode === "explicit" ? { cacheKey: buildPromptCacheKey(model, context, reasoning) } : {}
+	};
+}
+function splitAnthropicSystem(payload, lifetime) {
 	const record = asRecord(payload);
 	if (!record || !Array.isArray(record.system)) return payload;
 	let changed = false;
@@ -23,7 +33,11 @@ function splitAnthropicSystem(payload) {
 		return [{
 			...rest,
 			type: block.type ?? "text",
-			text: split.stablePrefix
+			text: split.stablePrefix,
+			cache_control: lifetime === "long" ? {
+				type: "ephemeral",
+				ttl: "1h"
+			} : { type: "ephemeral" }
 		}, ...split.dynamicSuffix ? [{
 			type: block.type ?? "text",
 			text: split.dynamicSuffix
@@ -34,6 +48,54 @@ function splitAnthropicSystem(payload) {
 		system
 	} : payload;
 }
+function addAnthropicHistoryBreakpoint(payload, lifetime) {
+	const record = asRecord(payload);
+	if (!record || !Array.isArray(record.messages)) return payload;
+	const messages = [...record.messages];
+	const cacheControl = lifetime === "long" ? {
+		type: "ephemeral",
+		ttl: "1h"
+	} : { type: "ephemeral" };
+	for (let index = messages.length - 1; index >= 0; index -= 1) {
+		const message = asRecord(messages[index]);
+		if (!message || message.role !== "user") continue;
+		const blocks = Array.isArray(message.content) ? [...message.content] : void 0;
+		const containsToolResult = blocks?.some((block) => asRecord(block)?.type === "tool_result") ?? false;
+		if (index === messages.length - 1 && !containsToolResult) continue;
+		if (!blocks) {
+			if (typeof message.content !== "string") continue;
+			messages[index] = {
+				...message,
+				content: [{
+					type: "text",
+					text: message.content,
+					cache_control: cacheControl
+				}]
+			};
+			return {
+				...record,
+				messages
+			};
+		}
+		for (let blockIndex = blocks.length - 1; blockIndex >= 0; blockIndex -= 1) {
+			const block = asRecord(blocks[blockIndex]);
+			if (!block) continue;
+			blocks[blockIndex] = {
+				...block,
+				cache_control: cacheControl
+			};
+			messages[index] = {
+				...message,
+				content: blocks
+			};
+			return {
+				...record,
+				messages
+			};
+		}
+	}
+	return payload;
+}
 function splitBedrockSystem(payload) {
 	const record = asRecord(payload);
 	if (!record || !Array.isArray(record.system)) return payload;
@@ -56,7 +118,7 @@ function splitBedrockSystem(payload) {
 		if (next?.cachePoint) {
 			system.push(next);
 			index += 1;
-		}
+		} else system.push({ cachePoint: { type: "default" } });
 		if (split.dynamicSuffix) system.push({ text: split.dynamicSuffix });
 	}
 	return changed ? {
@@ -64,20 +126,128 @@ function splitBedrockSystem(payload) {
 		system
 	} : payload;
 }
-function transformPromptCachePayload(model, payload) {
-	if (model.api === "anthropic-messages") return splitAnthropicSystem(payload);
-	if (model.api === "bedrock-converse-stream") return splitBedrockSystem(payload);
+function addBedrockHistoryBreakpoint(payload) {
+	const record = asRecord(payload);
+	if (!record || !Array.isArray(record.messages)) return payload;
+	const messages = [...record.messages];
+	for (let index = messages.length - 1; index >= 0; index -= 1) {
+		const message = asRecord(messages[index]);
+		if (!message || message.role !== "user" || !Array.isArray(message.content)) continue;
+		const content = [...message.content];
+		const containsToolResult = content.some((block) => "toolResult" in (asRecord(block) ?? {}));
+		if (index === messages.length - 1 && !containsToolResult) continue;
+		content.push({ cachePoint: { type: "default" } });
+		messages[index] = {
+			...message,
+			content
+		};
+		return {
+			...record,
+			messages
+		};
+	}
 	return payload;
 }
-function canonicalJson(value) {
-	if (Array.isArray(value)) return `[${value.map(canonicalJson).join(",")}]`;
-	const record = asRecord(value);
-	if (record) return `{${Object.keys(record).sort().map((key) => `${JSON.stringify(key)}:${canonicalJson(record[key])}`).join(",")}}`;
-	return JSON.stringify(value) ?? "null";
+function addBreakpointToContent(content) {
+	if (typeof content === "string") return [{
+		type: "input_text",
+		text: content,
+		prompt_cache_breakpoint: { mode: "explicit" }
+	}];
+	if (!Array.isArray(content)) return content;
+	const blocks = [...content];
+	for (let index = blocks.length - 1; index >= 0; index -= 1) {
+		const block = asRecord(blocks[index]);
+		if (!block) continue;
+		blocks[index] = {
+			...block,
+			prompt_cache_breakpoint: { mode: "explicit" }
+		};
+		return blocks;
+	}
+	return content;
 }
-function buildPromptCacheKey(model, context) {
-	const stablePrompt = context.systemPrompt ? splitPromptCacheBoundary(context.systemPrompt)?.stablePrefix ?? stripPromptCacheBoundary(context.systemPrompt) : "";
-	return `xopc-${createHash("sha256").update(`${model.provider}\0${model.id}\0${stablePrompt}\0${canonicalJson(context.tools ?? [])}`).digest("base64url")}`;
+function addOpenAIHistoryBreakpoint(items) {
+	if (!Array.isArray(items)) return items;
+	const next = [...items];
+	for (let index = next.length - 1; index >= 0; index -= 1) {
+		const item = asRecord(next[index]);
+		if (!item) continue;
+		if (item.type === "function_call_output") {
+			next[index] = {
+				...item,
+				output: addBreakpointToContent(item.output)
+			};
+			return next;
+		}
+		if (!("content" in item)) continue;
+		if (index === next.length - 1 && item.role === "user") continue;
+		const content = addBreakpointToContent(item.content);
+		if (content === item.content) continue;
+		next[index] = {
+			...item,
+			content
+		};
+		return next;
+	}
+	return items;
+}
+function applyOpenAIExplicitCache(payload, context, cacheKey) {
+	const record = asRecord(payload);
+	if (!record) return payload;
+	const split = splitPromptCacheBoundary(context.systemPrompt ?? "");
+	const stablePrompt = split?.stablePrefix ?? stripPromptCacheBoundary(context.systemPrompt ?? "");
+	const dynamicPrompt = split?.dynamicSuffix ?? "";
+	const stableContent = [{
+		type: "input_text",
+		text: stablePrompt,
+		prompt_cache_breakpoint: { mode: "explicit" }
+	}];
+	const dynamicContent = [{
+		type: "input_text",
+		text: dynamicPrompt
+	}];
+	if (Array.isArray(record.input)) {
+		const expectedInstructions = stripPromptCacheBoundary(context.systemPrompt ?? "");
+		const canReplaceInstructions = record.instructions === void 0 || record.instructions === expectedInstructions;
+		return {
+			...record,
+			...canReplaceInstructions ? { instructions: [{
+				type: "message",
+				role: "system",
+				content: stableContent
+			}, ...dynamicPrompt ? [{
+				type: "message",
+				role: "system",
+				content: dynamicContent
+			}] : []] } : {},
+			input: addOpenAIHistoryBreakpoint(record.input),
+			prompt_cache_key: cacheKey,
+			prompt_cache_options: {
+				mode: "explicit",
+				ttl: "30m"
+			}
+		};
+	}
+	return {
+		...record,
+		prompt_cache_key: cacheKey,
+		prompt_cache_options: {
+			mode: "explicit",
+			ttl: "30m"
+		}
+	};
+}
+function transformPromptCachePayload(model, payload, plan = buildPromptCachePlan(model, {}), context = {}) {
+	if (plan.providerMode === "none" || plan.providerMode === "managed") return payload;
+	if (model.api === "anthropic-messages") return addAnthropicHistoryBreakpoint(splitAnthropicSystem(payload, plan.policy.lifetime), plan.policy.lifetime);
+	if (model.api === "bedrock-converse-stream") return addBedrockHistoryBreakpoint(splitBedrockSystem(payload));
+	if (plan.providerMode === "explicit" && plan.cacheKey) return applyOpenAIExplicitCache(payload, context, plan.cacheKey);
+	const record = asRecord(payload);
+	return record && plan.cacheKey ? {
+		...record,
+		prompt_cache_key: plan.cacheKey
+	} : payload;
 }
 function preparePromptCacheContext(model, context) {
 	if (model.api === "anthropic-messages" || model.api === "bedrock-converse-stream") return context;
@@ -87,24 +257,27 @@ function preparePromptCacheContext(model, context) {
 		systemPrompt: stripPromptCacheBoundary(context.systemPrompt)
 	};
 }
-function withPromptCachePayloadTransform(model, context, options) {
-	const explicitBoundary = model.api === "anthropic-messages" || model.api === "bedrock-converse-stream";
-	const openAiCacheKey = supportsPromptCacheKey(model) && options?.cacheRetention !== "none";
-	if (!explicitBoundary && !openAiCacheKey) return options;
+function withPromptCachePayloadTransform(model, context, options, policyInput) {
+	const plan = buildPromptCachePlan(model, context, policyInput, options?.reasoning);
 	const upstream = options?.onPayload;
-	const promptCacheKey = openAiCacheKey ? buildPromptCacheKey(model, context) : void 0;
+	const cacheRetention = model.api === "anthropic-messages" || model.api === "bedrock-converse-stream" ? plan.providerMode === "none" ? "none" : plan.policy.lifetime : "none";
 	return {
 		...options,
+		cacheRetention,
 		onPayload: async (payload, payloadModel) => {
 			const upstreamPayload = await upstream?.(payload, payloadModel);
-			const transformed = transformPromptCachePayload(model, upstreamPayload === void 0 ? payload : upstreamPayload);
-			const record = asRecord(transformed);
-			return record && promptCacheKey ? {
-				...record,
-				prompt_cache_key: promptCacheKey
-			} : transformed;
+			const transformed = transformPromptCachePayload(model, upstreamPayload === void 0 ? payload : upstreamPayload, plan, context);
+			if (plan.providerMode !== "managed") return transformed;
+			return applyGoogleManagedPromptCache({
+				model,
+				context,
+				payload: transformed,
+				policy: plan.policy,
+				apiKey: options?.apiKey,
+				fetchImpl: options?.fetch
+			});
 		}
 	};
 }
 //#endregion
-export { buildPromptCacheKey, preparePromptCacheContext, transformPromptCachePayload, withPromptCachePayloadTransform };
+export { buildPromptCacheKey, buildPromptCachePlan, preparePromptCacheContext, transformPromptCachePayload, withPromptCachePayloadTransform };

package/dist/src/providers/prompt-cache-plan.d.ts

@@ -0,0 +1,15 @@
+import type { Api, Model } from '@earendil-works/pi-ai';
+export interface PromptCachePolicy {
+    mode: 'off' | 'auto';
+    lifetime: 'short' | 'long';
+}
+export type PromptCacheProviderMode = 'none' | 'implicit' | 'explicit' | 'managed';
+export interface PromptCachePlan {
+    policy: PromptCachePolicy;
+    providerMode: PromptCacheProviderMode;
+    cacheKey?: string;
+}
+export declare const DEFAULT_PROMPT_CACHE_POLICY: PromptCachePolicy;
+export declare function resolvePromptCachePolicy(policy?: Partial<PromptCachePolicy>): PromptCachePolicy;
+export declare function isOfficialOpenAIModel(model: Model<Api>): boolean;
+export declare function resolvePromptCacheProviderMode(model: Model<Api>, policy: PromptCachePolicy): PromptCacheProviderMode;

package/dist/src/providers/prompt-cache-plan.js

@@ -0,0 +1,29 @@
+//#region src/providers/prompt-cache-plan.ts
+const DEFAULT_PROMPT_CACHE_POLICY = {
+	mode: "auto",
+	lifetime: "short"
+};
+function resolvePromptCachePolicy(policy) {
+	return {
+		mode: policy?.mode ?? DEFAULT_PROMPT_CACHE_POLICY.mode,
+		lifetime: policy?.lifetime ?? DEFAULT_PROMPT_CACHE_POLICY.lifetime
+	};
+}
+function isOfficialOpenAIModel(model) {
+	if (model.api === "openai-codex-responses" || model.api === "azure-openai-responses") return true;
+	if (model.api !== "openai-completions" && model.api !== "openai-responses") return false;
+	return model.provider === "openai" || model.baseUrl?.includes("api.openai.com") === true;
+}
+function supportsExplicitOpenAICache(model) {
+	return model.api === "openai-responses" && isOfficialOpenAIModel(model) && /^gpt-5\.6(?:-|$)/.test(model.id);
+}
+function resolvePromptCacheProviderMode(model, policy) {
+	if (policy.mode === "off") return "none";
+	if (supportsExplicitOpenAICache(model)) return "explicit";
+	if (isOfficialOpenAIModel(model)) return "implicit";
+	if (model.api === "anthropic-messages" || model.api === "bedrock-converse-stream") return "explicit";
+	if (model.api === "google-generative-ai") return "managed";
+	return "none";
+}
+//#endregion
+export { DEFAULT_PROMPT_CACHE_POLICY, isOfficialOpenAIModel, resolvePromptCachePolicy, resolvePromptCacheProviderMode };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xopcai/xopc",
-  "version": "0.0.201",
+  "version": "0.0.203",
   "description": "Local-first AI system that remembers context, coordinates AI, and sustains long-term progress.",
   "type": "module",
   "main": "dist/src/index.js",
@@ -164,8 +164,8 @@
     "vue": "^3.5.35",
     "@xopcai/gateway-contract": "0.0.0",
     "@xopcai/endpoint-tools-protocol": "0.0.0",
-    "@xopcai/realtime-protocol": "0.0.0",
-    "@xopcai/realtime-client": "0.0.0"
+    "@xopcai/realtime-client": "0.0.0",
+    "@xopcai/realtime-protocol": "0.0.0"
   },
   "scripts": {
     "assets:brand": "node scripts/generate-brand-assets.mjs",