@xopcai/xopc 0.0.202 → 0.0.204

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

@@ -0,0 +1,44 @@
+import { createHash } from "node:crypto";
+//#region src/providers/prompt-cache-fingerprint.ts
+function asRecord(value) {
+	return value !== null && typeof value === "object" && !Array.isArray(value) ? value : void 0;
+}
+const MAX_FINGERPRINT_DEPTH = 64;
+const MAX_FINGERPRINT_NODES = 2e4;
+const MAX_FINGERPRINT_STRING_CHARS = 1e5;
+function canonicalize(value, state, depth) {
+	state.nodes += 1;
+	if (depth > MAX_FINGERPRINT_DEPTH || state.nodes > MAX_FINGERPRINT_NODES) return "\"[fingerprint-limit]\"";
+	if (typeof value === "string" && value.length > MAX_FINGERPRINT_STRING_CHARS) return JSON.stringify(`${value.slice(0, MAX_FINGERPRINT_STRING_CHARS)}[fingerprint-limit]`);
+	if (Array.isArray(value)) {
+		if (state.seen.has(value)) return "\"[circular]\"";
+		state.seen.add(value);
+		const result = `[${value.map((entry) => canonicalize(entry, state, depth + 1)).join(",")}]`;
+		state.seen.delete(value);
+		return result;
+	}
+	const record = asRecord(value);
+	if (record) {
+		if (state.seen.has(record)) return "\"[circular]\"";
+		state.seen.add(record);
+		const result = `{${Object.keys(record).sort().map((key) => `${JSON.stringify(key)}:${canonicalize(record[key], state, depth + 1)}`).join(",")}}`;
+		state.seen.delete(record);
+		return result;
+	}
+	return JSON.stringify(value) ?? "null";
+}
+/** Canonical JSON used only for bounded prompt-cache fingerprints. */
+function canonicalizeCacheValue(value) {
+	return canonicalize(value, {
+		nodes: 0,
+		seen: /* @__PURE__ */ new WeakSet()
+	}, 0);
+}
+function digestCacheValue(value) {
+	return createHash("sha256").update(canonicalizeCacheValue(value)).digest("base64url");
+}
+function digestCacheText(value) {
+	return createHash("sha256").update(value).digest("base64url");
+}
+//#endregion
+export { canonicalizeCacheValue, digestCacheText, digestCacheValue };

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

@@ -0,0 +1,9 @@
+import type { Api, Model } from '@earendil-works/pi-ai';
+import type { PromptCachePolicy } from './prompt-cache-plan.js';
+export declare function resolvePromptCacheTtlMs(model: Model<Api>, policy: PromptCachePolicy): number;
+export declare function recordPromptCacheTouch(sessionKey: string, model: Model<Api>, usage: {
+    cacheRead?: number;
+    cacheWrite?: number;
+}, now?: number): void;
+export declare function isPromptCacheExpired(sessionKey: string, model: Model<Api>, policy: PromptCachePolicy, now?: number): boolean;
+export declare function clearPromptCacheTouches(): void;

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

@@ -0,0 +1,31 @@
+//#region src/providers/prompt-cache-lifecycle.ts
+const cacheTouchByScope = /* @__PURE__ */ new Map();
+const MAX_CACHE_TOUCHES = 512;
+function scopeKey(sessionKey, model) {
+	return `${sessionKey}\0${model.provider}/${model.id}`;
+}
+function resolvePromptCacheTtlMs(model, policy) {
+	if (model.api === "openai-responses" && /^gpt-5\.6(?:-|$)/.test(model.id)) return 30 * 6e4;
+	return policy.lifetime === "long" ? 60 * 6e4 : 5 * 6e4;
+}
+function recordPromptCacheTouch(sessionKey, model, usage, now = Date.now()) {
+	if ((usage.cacheRead ?? 0) <= 0 && (usage.cacheWrite ?? 0) <= 0) return;
+	const key = scopeKey(sessionKey, model);
+	cacheTouchByScope.delete(key);
+	cacheTouchByScope.set(key, now);
+	while (cacheTouchByScope.size > MAX_CACHE_TOUCHES) {
+		const oldest = cacheTouchByScope.keys().next().value;
+		if (typeof oldest !== "string") break;
+		cacheTouchByScope.delete(oldest);
+	}
+}
+function isPromptCacheExpired(sessionKey, model, policy, now = Date.now()) {
+	if (policy.mode === "off") return false;
+	const touchedAt = cacheTouchByScope.get(scopeKey(sessionKey, model));
+	return touchedAt !== void 0 && now - touchedAt >= resolvePromptCacheTtlMs(model, policy);
+}
+function clearPromptCacheTouches() {
+	cacheTouchByScope.clear();
+}
+//#endregion
+export { clearPromptCacheTouches, isPromptCacheExpired, recordPromptCacheTouch, resolvePromptCacheTtlMs };

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

@@ -0,0 +1,20 @@
+import type { Api, Model } from '@earendil-works/pi-ai';
+export type PromptCacheChangeReason = 'model_changed' | 'reasoning_changed' | 'system_changed' | 'dynamic_context_changed' | 'tools_changed';
+export interface PromptCacheSnapshot {
+    modelRef: string;
+    api: string;
+    reasoning?: string;
+    stableSystemDigest: string;
+    dynamicSystemDigest: string;
+    toolDigest: string;
+    toolCount: number;
+}
+export declare function buildPromptCacheSnapshot(params: {
+    model: Model<Api>;
+    systemPrompt?: string;
+    tools?: unknown[];
+    reasoning?: string;
+}): PromptCacheSnapshot;
+export declare function diffPromptCacheSnapshots(previous: PromptCacheSnapshot | undefined, next: PromptCacheSnapshot): PromptCacheChangeReason[];
+export declare function observePromptCacheSnapshot(scope: string, snapshot: PromptCacheSnapshot): PromptCacheChangeReason[];
+export declare function clearPromptCacheObservations(): void;

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

@@ -0,0 +1,44 @@
+import { splitPromptCacheBoundary, stripPromptCacheBoundary } from "../agent/prompt/cache-boundary.js";
+import { digestCacheText, digestCacheValue } from "./prompt-cache-fingerprint.js";
+//#region src/providers/prompt-cache-observability.ts
+const MAX_TRACKED_SCOPES = 512;
+const previousByScope = /* @__PURE__ */ new Map();
+function buildPromptCacheSnapshot(params) {
+	const rawPrompt = params.systemPrompt ?? "";
+	const split = splitPromptCacheBoundary(rawPrompt);
+	return {
+		modelRef: `${params.model.provider}/${params.model.id}`,
+		api: params.model.api,
+		...params.reasoning ? { reasoning: params.reasoning } : {},
+		stableSystemDigest: digestCacheText(split?.stablePrefix ?? stripPromptCacheBoundary(rawPrompt)),
+		dynamicSystemDigest: digestCacheText(split?.dynamicSuffix ?? ""),
+		toolDigest: digestCacheValue(params.tools ?? []),
+		toolCount: params.tools?.length ?? 0
+	};
+}
+function diffPromptCacheSnapshots(previous, next) {
+	if (!previous) return [];
+	const reasons = [];
+	if (previous.modelRef !== next.modelRef || previous.api !== next.api) reasons.push("model_changed");
+	if (previous.reasoning !== next.reasoning) reasons.push("reasoning_changed");
+	if (previous.stableSystemDigest !== next.stableSystemDigest) reasons.push("system_changed");
+	if (previous.dynamicSystemDigest !== next.dynamicSystemDigest) reasons.push("dynamic_context_changed");
+	if (previous.toolDigest !== next.toolDigest) reasons.push("tools_changed");
+	return reasons;
+}
+function observePromptCacheSnapshot(scope, snapshot) {
+	const reasons = diffPromptCacheSnapshots(previousByScope.get(scope), snapshot);
+	previousByScope.delete(scope);
+	previousByScope.set(scope, snapshot);
+	while (previousByScope.size > MAX_TRACKED_SCOPES) {
+		const oldest = previousByScope.keys().next().value;
+		if (typeof oldest !== "string") break;
+		previousByScope.delete(oldest);
+	}
+	return reasons;
+}
+function clearPromptCacheObservations() {
+	previousByScope.clear();
+}
+//#endregion
+export { buildPromptCacheSnapshot, clearPromptCacheObservations, diffPromptCacheSnapshots, observePromptCacheSnapshot };

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

@@ -1,13 +1,20 @@
 import type { Api, Model, SimpleStreamOptions } from '@earendil-works/pi-ai';
-export declare function transformPromptCachePayload(model: Model<Api>, payload: unknown): unknown;
+import { type PromptCachePlan, type PromptCachePolicy } from './prompt-cache-plan.js';
 export declare function buildPromptCacheKey(model: Model<Api>, context: {
     systemPrompt?: string;
     tools?: unknown[];
-}): string;
+}, reasoning?: string): string;
+export declare function buildPromptCachePlan(model: Model<Api>, context: {
+    systemPrompt?: string;
+    tools?: unknown[];
+}, policyInput?: PromptCachePolicy, reasoning?: string): PromptCachePlan;
+export declare function transformPromptCachePayload(model: Model<Api>, payload: unknown, plan?: PromptCachePlan, context?: {
+    systemPrompt?: string;
+}): unknown;
 export declare function preparePromptCacheContext<T extends {
     systemPrompt?: string;
 }>(model: Model<Api>, context: T): T;
 export declare function withPromptCachePayloadTransform(model: Model<Api>, context: {
     systemPrompt?: string;
     tools?: unknown[];
-}, options: SimpleStreamOptions | undefined): SimpleStreamOptions | undefined;
+}, options: SimpleStreamOptions | undefined, policyInput?: PromptCachePolicy): SimpleStreamOptions;

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/dist/src/realtime/runtime.js

@@ -241,7 +241,7 @@ var RealtimeRuntime = class {
 				socket.close(4400, "Invalid endpoint message");
 			}
 		});
-		socket.on("close", () => {
+		socket.on("close", (code, reasonBuffer) => {
 			clearTimeout(helloTimer);
 			clearInterval(heartbeatTimer);
 			releaseBudget();
@@ -249,7 +249,14 @@ var RealtimeRuntime = class {
 			for (const handle of subscriptions.values()) handle.unsubscribe();
 			subscriptions.clear();
 			if (endpointId && connectionId) this.endpointTools?.remove(endpointId, connectionId);
-			if (connectionId) log.info({ connectionId }, "Realtime client disconnected");
+			if (connectionId) {
+				const reason = reasonBuffer.toString();
+				log.info({
+					connectionId,
+					code,
+					...reason ? { reason } : {}
+				}, `Realtime client disconnected (${code}${reason ? `: ${reason}` : ""})`);
+			}
 		});
 	}
 	rawDataToText(data) {

package/dist/src/realtime/writer.js

@@ -26,6 +26,11 @@ var RealtimeSocketWriter = class {
 			data,
 			bytes: Buffer.byteLength(data)
 		};
+		if (item.bytes > MAX_QUEUED_BYTES) {
+			this.socket.close(1009, "Realtime event exceeds delivery limit");
+			this.close();
+			return false;
+		}
 		if (this.queuedBytes + item.bytes > MAX_QUEUED_BYTES) {
 			this.socket.close(4413, "Realtime client is too slow");
 			this.close();

package/package.json

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