@oh-my-pi/pi-ai 18.3.4 → 18.3.5

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 ## [Unreleased]
 
+## [18.3.5] - 2026-09-27
+
+### Breaking Changes
+
+- Removed the stream-level Anthropic prompt-cache keep-alive: `StreamOptions.anthropicCacheRefresh`, `StreamOptions.anthropicCacheRefreshRequest`, and the zero-output refresh request path. Prompt-cache warming now lives in the coding agent's session-level cache warmer ([#12699](https://github.com/can1357/oh-my-pi/pull/12699) by [@KamijoToma](https://github.com/KamijoToma)).
+
 ## [18.3.4] - 2026-09-27
 
 ### Fixed

package/dist/types/index.d.ts

@@ -38,6 +38,7 @@ export type * from "./providers/openai-completions.js";
 export type * from "./providers/openai-responses.js";
 export type * from "./providers/synthetic.js";
 export * from "./registry/index.js";
+export { resolveCacheRetention } from "./utils.js";
 export * from "./stream.js";
 export * from "./types.js";
 export * from "./usage.js";

package/dist/types/types.d.ts

@@ -237,21 +237,11 @@ export interface StreamOptions {
     /** @internal Stored credential row serving this request, when known. */
     credentialId?: number;
     cacheRetention?: CacheRetention;
-    /**
-     * Keep Anthropic's 5-minute prompt cache warm across bounded idle gaps.
-     *
-     * This is an ownership flag, not a general provider default: exactly one
-     * primary agent loop sharing `providerSessionState` should enable it.
-     * Side-channel and advisor requests must leave it unset.
-     */
-    anthropicCacheRefresh?: boolean;
     /**
      * Anthropic preserved-thinking behavior when a signed block no longer matches
      * its conversation prefix. Binding-capable models default to `"drop_block"`.
      */
     anthropicPrefixMismatchBehavior?: "drop_block" | "error";
-    /** @internal Marks a replay-only Anthropic request that must use non-streaming `max_tokens: 0`. */
-    anthropicCacheRefreshRequest?: boolean;
     /**
      * Anthropic on-demand compaction (`compact-2026-09-04` beta). Sends a
      * top-level `compaction: { type: "summarize", instructions? }` request; the

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@oh-my-pi/pi-ai",
-	"version": "18.3.4",
+	"version": "18.3.5",
 	"description": "Unified LLM API with automatic model discovery and provider configuration",
 	"keywords": [
 		"ai",
@@ -155,11 +155,11 @@
 		"fmt": "oxfmt --no-error-on-unmatched-pattern 'src/**/*.{ts,tsx}' '{test,bench,examples,scripts}/**/*.ts' '*.ts'"
 	},
 	"dependencies": {
-		"@oh-my-pi/omptype": "18.3.4",
-		"@oh-my-pi/pi-catalog": "18.3.4",
-		"@oh-my-pi/pi-natives": "18.3.4",
-		"@oh-my-pi/pi-utils": "18.3.4",
-		"@oh-my-pi/pi-wire": "18.3.4"
+		"@oh-my-pi/omptype": "18.3.5",
+		"@oh-my-pi/pi-catalog": "18.3.5",
+		"@oh-my-pi/pi-natives": "18.3.5",
+		"@oh-my-pi/pi-utils": "18.3.5",
+		"@oh-my-pi/pi-wire": "18.3.5"
 	},
 	"devDependencies": {
 		"@types/bun": "^1.3.14"

package/src/index.ts

@@ -39,6 +39,7 @@ export type * from "./providers/openai-completions";
 export type * from "./providers/openai-responses";
 export type * from "./providers/synthetic";
 export * from "./registry";
+export { resolveCacheRetention } from "./utils";
 export * from "./stream";
 export * from "./types";
 export * from "./usage";

package/src/providers/anthropic.ts

@@ -1590,31 +1590,6 @@ export function applyAnthropicUsageExtras(usage: Usage, source: AnthropicUsageLi
 	}
 }
 
-function parseAnthropicWireUsage(value: unknown): AnthropicWireUsage | undefined {
-	if (!isRecord(value)) return undefined;
-	const cacheCreation = isRecord(value.cache_creation)
-		? {
-				...(typeof value.cache_creation.ephemeral_5m_input_tokens === "number"
-					? { ephemeral_5m_input_tokens: value.cache_creation.ephemeral_5m_input_tokens }
-					: {}),
-				...(typeof value.cache_creation.ephemeral_1h_input_tokens === "number"
-					? { ephemeral_1h_input_tokens: value.cache_creation.ephemeral_1h_input_tokens }
-					: {}),
-			}
-		: undefined;
-	return {
-		...(typeof value.input_tokens === "number" ? { input_tokens: value.input_tokens } : {}),
-		...(typeof value.output_tokens === "number" ? { output_tokens: value.output_tokens } : {}),
-		...(typeof value.cache_read_input_tokens === "number"
-			? { cache_read_input_tokens: value.cache_read_input_tokens }
-			: {}),
-		...(typeof value.cache_creation_input_tokens === "number"
-			? { cache_creation_input_tokens: value.cache_creation_input_tokens }
-			: {}),
-		...(cacheCreation === undefined ? {} : { cache_creation: cacheCreation }),
-	};
-}
-
 function parseAnthropicFallbackWireBlock(value: unknown): AnthropicFallbackContent | undefined {
 	if (!isRecord(value) || value.type !== "fallback") return undefined;
 	const from = isRecord(value.from) && typeof value.from.model === "string" ? value.from.model : undefined;
@@ -2071,7 +2046,6 @@ const streamAnthropicOnce = (
 				});
 			}
 
-			const zeroOutputCacheRefresh = options?.anthropicCacheRefreshRequest === true;
 			let client: AnthropicMessagesClientLike;
 			let isOAuthToken: boolean;
 			// Retained so a Claude Code version bump can rebuild the client's fingerprint headers.
@@ -2207,7 +2181,7 @@ const streamAnthropicOnce = (
 					model,
 					apiKey,
 					extraBetas,
-					stream: !zeroOutputCacheRefresh,
+					stream: true,
 					interleavedThinking: options?.interleavedThinking ?? true,
 					headers: options?.headers,
 					dynamicHeaders: copilotDynamicHeaders?.headers,
@@ -2321,89 +2295,6 @@ const streamAnthropicOnce = (
 			const requestTimeoutMs =
 				firstEventTimeoutMs !== undefined && firstEventTimeoutMs > 0 ? firstEventTimeoutMs : undefined;
 
-			if (zeroOutputCacheRefresh) {
-				const refreshParams: MessageCreateParams = { ...params, max_tokens: 0, stream: false };
-				// Anthropic rejects `tool_choice: {type:"tool"|"any"}` with `max_tokens: 0`
-				// ("tool_choice ... cannot be used when max_tokens is 0", #12597). A refresh
-				// replays the captured turn's payload, which can carry a forced selector
-				// (e.g. a forced yield). A zero-output keep-alive produces no tokens, so the
-				// forced choice is meaningless here — drop it so the request is accepted.
-				const refreshChoiceType = refreshParams.tool_choice?.type;
-				if (refreshChoiceType === "tool" || refreshChoiceType === "any") {
-					delete refreshParams.tool_choice;
-				}
-				rawRequestDump = {
-					provider: model.provider,
-					api: output.api,
-					model: model.id,
-					method: "POST",
-					url: `${baseUrl}/v1/messages${isOAuthToken ? "?beta=true" : ""}`,
-					body: refreshParams,
-				};
-				const { requestSignal } = activeAbortTracker;
-				// A replayed compaction block needs the beta on injected clients too.
-				// Route by the client's own endpoint when it exposes one.
-				const refreshBetaRouteUrl =
-					options?.client !== undefined ? (injectedClientBaseUrl(options.client) ?? baseUrl) : baseUrl;
-				let refreshHeaders: Record<string, string> | undefined;
-				if (options?.client !== undefined && !isVertexRawPredictUrl(refreshBetaRouteUrl)) {
-					if (carriesSignedCompaction(refreshParams)) {
-						refreshHeaders = mergeAnthropicBetaHeader(refreshHeaders ?? mergedCallerHeaders, COMPACTION_BETA);
-					}
-					if (carriesLegacyCompactionEdit(refreshParams)) {
-						refreshHeaders = mergeAnthropicBetaHeader(
-							refreshHeaders ?? mergedCallerHeaders,
-							LEGACY_COMPACTION_BETA,
-						);
-					}
-				}
-				const requestOptions = {
-					...createSdkStreamRequestOptions(requestSignal, requestTimeoutMs),
-					maxRetries: 0,
-					...(refreshHeaders ? { headers: refreshHeaders } : {}),
-				};
-				const request: unknown =
-					isOAuthToken && client.beta
-						? client.beta.messages.create(refreshParams, requestOptions)
-						: client.messages.create(refreshParams, requestOptions);
-				if (!hasAnthropicRawResponseRequest(request)) {
-					throw new AIError.AnthropicStreamEnvelopeError(
-						"Anthropic cache refresh request did not expose a raw response",
-					);
-				}
-				const response = await request.asResponse();
-				await notifyProviderResponse(options, response, model, response.headers.get("request-id"));
-				const body: unknown = await response.json();
-				if (!isRecord(body)) {
-					throw new AIError.AnthropicStreamEnvelopeError("Anthropic cache refresh returned a malformed response");
-				}
-				const wireUsage = parseAnthropicWireUsage(body.usage);
-				if (!wireUsage) {
-					throw new AIError.AnthropicStreamEnvelopeError("Anthropic cache refresh response omitted usage");
-				}
-				if (typeof body.id === "string") output.responseId = body.id;
-				applyReportedInputTransformations(
-					output,
-					params,
-					providerSessionState,
-					body.input_transformations,
-					seenInputTransformations,
-				);
-				output.usage.input = wireUsage.input_tokens ?? 0;
-				output.usage.output = wireUsage.output_tokens ?? 0;
-				output.usage.cacheRead = wireUsage.cache_read_input_tokens ?? 0;
-				output.usage.cacheWrite = wireUsage.cache_creation_input_tokens ?? 0;
-				applyAnthropicUsageExtras(output.usage, wireUsage);
-				output.usage.totalTokens =
-					output.usage.input + output.usage.output + output.usage.cacheRead + output.usage.cacheWrite;
-				calculateCost(model, output.usage, output.timestamp);
-				output.duration = performance.now() - startTime;
-				stream.push({ type: "start", partial: output });
-				stream.push({ type: "done", reason: "stop", message: output });
-				stream.end();
-				return;
-			}
-
 			// Opt-in flag: the response parser only honors `fallback` content
 			// blocks and `usage.iterations` when the current request opted into
 			// server-side-fallback beta chain. Leaving `fallbacks` unset preserves

package/src/stream.ts

@@ -24,7 +24,6 @@ import { isConcurrencyCapExclusion, isUsageLimitOutcome } from "./error/rate-lim
 import type { BedrockOptions } from "./providers/amazon-bedrock";
 import type { AnthropicOptions } from "./providers/anthropic";
 import type { AppleFoundationModelsOptions } from "./providers/apple-foundation-models";
-import type { MessageCreateParamsStreaming } from "./providers/anthropic-wire";
 import type { CursorOptions } from "./providers/cursor";
 import type { DevinOptions } from "./providers/devin";
 import { streamGitLabDuo } from "./providers/gitlab-duo";
@@ -62,7 +61,6 @@ import type {
 	FetchImpl,
 	Model,
 	OptionsForApi,
-	ProviderSessionState,
 	SimpleStreamOptions,
 	StreamOptions,
 	ThinkingBudgets,
@@ -1205,285 +1203,6 @@ function emitBufferedEvents(stream: AssistantMessageEventStream, events: Assista
 		stream.push(event);
 	}
 }
-
-const ANTHROPIC_CACHE_TTL_MS = 5 * 60_000;
-const ANTHROPIC_CACHE_REFRESH_LEAD_MS = 15_000;
-const ANTHROPIC_CACHE_REFRESH_LIMIT = 3;
-const ANTHROPIC_CACHE_REFRESH_STATE_KEY = "anthropic-cache-refresh";
-
-interface AnthropicCacheRefreshPlan {
-	refresh(controller: AbortController): Promise<number | undefined>;
-}
-
-class AnthropicCacheRefreshState implements ProviderSessionState {
-	#controller: AbortController | undefined;
-	#generation = 0;
-	#plan: AnthropicCacheRefreshPlan | undefined;
-	#refreshesRemaining = 0;
-	#timer: NodeJS.Timeout | undefined;
-
-	cancel(): void {
-		this.#generation++;
-		if (this.#timer !== undefined) {
-			clearTimeout(this.#timer);
-			this.#timer = undefined;
-		}
-		this.#controller?.abort();
-		this.#controller = undefined;
-		this.#plan = undefined;
-		this.#refreshesRemaining = 0;
-	}
-
-	arm(plan: AnthropicCacheRefreshPlan, cacheTouchedAtMs: number): void {
-		this.cancel();
-		this.#plan = plan;
-		this.#refreshesRemaining = ANTHROPIC_CACHE_REFRESH_LIMIT;
-		this.#schedule(cacheTouchedAtMs, this.#generation);
-	}
-
-	close(): void {
-		this.cancel();
-	}
-
-	#schedule(cacheTouchedAtMs: number, generation: number): void {
-		const refreshAtMs = cacheTouchedAtMs + ANTHROPIC_CACHE_TTL_MS - ANTHROPIC_CACHE_REFRESH_LEAD_MS;
-		this.#timer = setTimeout(
-			() => {
-				this.#timer = undefined;
-				void this.#refresh(generation);
-			},
-			Math.max(0, refreshAtMs - Date.now()),
-		);
-		this.#timer.unref?.();
-	}
-
-	async #refresh(generation: number): Promise<void> {
-		const plan = this.#plan;
-		if (generation !== this.#generation || !plan || this.#refreshesRemaining <= 0) return;
-
-		const controller = new AbortController();
-		this.#controller = controller;
-		let cacheTouchedAtMs: number | undefined;
-		try {
-			cacheTouchedAtMs = await plan.refresh(controller);
-		} catch (error) {
-			if (generation === this.#generation && !controller.signal.aborted) {
-				logger.debug("Anthropic prompt-cache refresh failed", { error: String(error) });
-			}
-		}
-		if (generation !== this.#generation) return;
-
-		this.#controller = undefined;
-		if (cacheTouchedAtMs === undefined) {
-			this.#plan = undefined;
-			this.#refreshesRemaining = 0;
-			return;
-		}
-
-		this.#refreshesRemaining--;
-		if (this.#refreshesRemaining <= 0) {
-			this.#plan = undefined;
-			return;
-		}
-		this.#schedule(cacheTouchedAtMs, generation);
-	}
-}
-
-function supportsAnthropicCacheRefresh<TApi extends Api>(model: Model<TApi>): boolean {
-	return (
-		model.api === "anthropic-messages" &&
-		model.provider === "anthropic" &&
-		model.transport !== "pi-native" &&
-		isLeakedThinkingHealExempt(model)
-	);
-}
-
-function isAnthropicRefreshPayload(payload: unknown): payload is MessageCreateParamsStreaming {
-	return (
-		typeof payload === "object" &&
-		payload !== null &&
-		"messages" in payload &&
-		Array.isArray(payload.messages) &&
-		"max_tokens" in payload &&
-		typeof payload.max_tokens === "number"
-	);
-}
-
-function isShortAnthropicCacheControl(cacheControl: unknown): boolean {
-	return (
-		typeof cacheControl === "object" &&
-		cacheControl !== null &&
-		"type" in cacheControl &&
-		cacheControl.type === "ephemeral" &&
-		(!("ttl" in cacheControl) || cacheControl.ttl !== "1h")
-	);
-}
-
-function hasShortAnthropicMessageBreakpoint(payload: MessageCreateParamsStreaming): boolean {
-	for (const message of payload.messages) {
-		if (!Array.isArray(message.content)) continue;
-		for (const block of message.content) {
-			if ("cache_control" in block && isShortAnthropicCacheControl(block.cache_control)) return true;
-		}
-	}
-	return false;
-}
-
-function isAnthropicGenerationEvent(event: AssistantMessageEvent): boolean {
-	switch (event.type) {
-		case "text_start":
-		case "thinking_start":
-		case "toolcall_start":
-		case "image_end":
-			return true;
-		case "text_delta":
-		case "thinking_delta":
-		case "toolcall_delta":
-			return event.delta.length > 0;
-		default:
-			return false;
-	}
-}
-
-function isAnthropicThinkingActive(model: Model<Api>, payload: MessageCreateParamsStreaming): boolean {
-	if (payload.thinking) return payload.thinking.type !== "disabled";
-	return model.thinking?.mode === "anthropic-adaptive" && payload.output_config?.effort != null;
-}
-
-function createAnthropicCacheRefreshPlan<TApi extends Api>(
-	model: Model<TApi>,
-	context: Context,
-	options: SimpleStreamOptions | undefined,
-	payload: MessageCreateParamsStreaming,
-): AnthropicCacheRefreshPlan {
-	const thinkingEnabled = isAnthropicThinkingActive(model, payload);
-	return {
-		async refresh(controller) {
-			let cacheRead = 0;
-			let cacheWrite = 0;
-			let cacheTouchedAtMs: number | undefined;
-			let canceledAfterGenerationStarted = false;
-			const response = streamSimpleRequest(model, context, {
-				...options,
-				acceptEmptyResponse: true,
-				anthropicCacheRefreshRequest: !thinkingEnabled,
-				cacheRetention: "short",
-				maxTokens: thinkingEnabled ? options?.maxTokens : 0,
-				onPayload: () => ({
-					...payload,
-					max_tokens: thinkingEnabled ? payload.max_tokens : 0,
-				}),
-				onResponse: () => {
-					cacheTouchedAtMs = Date.now();
-				},
-				onSseEvent: undefined,
-				signal: controller.signal,
-			});
-
-			for await (const event of response) {
-				if ("partial" in event) {
-					cacheRead = event.partial.usage.cacheRead;
-					cacheWrite = event.partial.usage.cacheWrite;
-				}
-				if (event.type === "error") return undefined;
-				if (event.type === "done") {
-					cacheRead = event.message.usage.cacheRead;
-					cacheWrite = event.message.usage.cacheWrite;
-					return cacheTouchedAtMs !== undefined && cacheRead > 0 && cacheWrite === 0
-						? cacheTouchedAtMs
-						: undefined;
-				}
-				if (thinkingEnabled && isAnthropicGenerationEvent(event)) {
-					canceledAfterGenerationStarted = true;
-					controller.abort();
-					break;
-				}
-			}
-
-			if (canceledAfterGenerationStarted) {
-				try {
-					await response.result();
-				} catch (error) {
-					if (!controller.signal.aborted) throw error;
-				}
-			}
-			return cacheTouchedAtMs !== undefined && cacheRead > 0 && cacheWrite === 0 ? cacheTouchedAtMs : undefined;
-		},
-	};
-}
-
-function streamSimpleWithAnthropicCacheRefresh<TApi extends Api>(
-	model: Model<TApi>,
-	context: Context,
-	options: SimpleStreamOptions | undefined,
-): AssistantMessageEventStream {
-	const providerSessionState = options?.providerSessionState;
-	if (!options?.anthropicCacheRefresh || !providerSessionState) {
-		return streamSimpleRequest(model, context, options);
-	}
-
-	const existingState = providerSessionState.get(ANTHROPIC_CACHE_REFRESH_STATE_KEY);
-	if (existingState instanceof AnthropicCacheRefreshState) {
-		existingState.cancel();
-	} else if (existingState) {
-		return streamSimpleRequest(model, context, options);
-	}
-	if (!supportsAnthropicCacheRefresh(model) || resolveCacheRetention(options.cacheRetention) !== "short") {
-		return streamSimpleRequest(model, context, options);
-	}
-
-	const refreshState = existingState ?? new AnthropicCacheRefreshState();
-	if (!existingState) providerSessionState.set(ANTHROPIC_CACHE_REFRESH_STATE_KEY, refreshState);
-
-	let cacheTouchedAtMs: number | undefined;
-	let capturedPayload: MessageCreateParamsStreaming | undefined;
-	const inner = streamSimpleRequest(model, context, {
-		...options,
-		onPayload: async (payload, payloadModel) => {
-			const replacement = await options?.onPayload?.(payload, payloadModel);
-			const finalPayload = replacement ?? payload;
-			if (isAnthropicRefreshPayload(finalPayload)) capturedPayload = finalPayload;
-			return replacement;
-		},
-		onResponse: async (response, responseModel) => {
-			cacheTouchedAtMs = Date.now();
-			await options?.onResponse?.(response, responseModel);
-		},
-	});
-	const outer = new AssistantMessageEventStream();
-	const armRefresh = (message: AssistantMessage): void => {
-		if (
-			message.stopReason === "error" ||
-			message.stopReason === "aborted" ||
-			message.usage.cacheRead + message.usage.cacheWrite <= 0 ||
-			cacheTouchedAtMs === undefined ||
-			capturedPayload === undefined ||
-			!hasShortAnthropicMessageBreakpoint(capturedPayload)
-		) {
-			return;
-		}
-		refreshState.arm(createAnthropicCacheRefreshPlan(model, context, options, capturedPayload), cacheTouchedAtMs);
-	};
-
-	void (async () => {
-		try {
-			for await (const event of inner) {
-				if (event.type === "done") armRefresh(event.message);
-				outer.push(event);
-				if (outer.done) return;
-			}
-			if (!outer.done) {
-				const result = await inner.result();
-				armRefresh(result);
-				outer.end(result);
-			}
-		} catch (error) {
-			outer.fail(error);
-		}
-	})();
-	return outer;
-}
-
 function withInferenceSessionId(options?: SimpleStreamOptions): SimpleStreamOptions {
 	if (options?.sessionId) return options;
 	return { ...options, sessionId: crypto.randomUUID() };
@@ -1496,7 +1215,7 @@ export function streamSimple<TApi extends Api>(
 ): AssistantMessageEventStream {
 	const sessionOptions = withInferenceSessionId(options);
 	if (!model.requiresGlyphTokenization) {
-		return streamSimpleWithAnthropicCacheRefresh(model, context, sessionOptions);
+		return streamSimpleRequest(model, context, sessionOptions);
 	}
 	const codec = applyGlyphCodec(context);
 	const execHandlers = sessionOptions.cursorExecHandlers ?? sessionOptions.execHandlers;
@@ -1509,7 +1228,7 @@ export function streamSimple<TApi extends Api>(
 					execHandlers: wrappedExecHandlers,
 					cursorExecHandlers: wrappedExecHandlers,
 				};
-	return codec.wrap(streamSimpleWithAnthropicCacheRefresh(model, codec.context, wireOptions));
+	return codec.wrap(streamSimpleRequest(model, codec.context, wireOptions));
 }
 
 /**
@@ -2093,7 +1812,6 @@ function mapOptionsForApi<TApi extends Api>(
 		fetch: options?.fetch,
 		fallbacks: options?.fallbacks,
 		acceptEmptyResponse: options?.acceptEmptyResponse,
-		anthropicCacheRefreshRequest: options?.anthropicCacheRefreshRequest,
 		anthropicPrefixMismatchBehavior: options?.anthropicPrefixMismatchBehavior,
 		anthropicCompaction: options?.anthropicCompaction,
 		anthropicSlowMode: options?.anthropicSlowMode,

package/src/types.ts

@@ -428,21 +428,11 @@ export interface StreamOptions {
 	/** @internal Stored credential row serving this request, when known. */
 	credentialId?: number;
 	cacheRetention?: CacheRetention;
-	/**
-	 * Keep Anthropic's 5-minute prompt cache warm across bounded idle gaps.
-	 *
-	 * This is an ownership flag, not a general provider default: exactly one
-	 * primary agent loop sharing `providerSessionState` should enable it.
-	 * Side-channel and advisor requests must leave it unset.
-	 */
-	anthropicCacheRefresh?: boolean;
 	/**
 	 * Anthropic preserved-thinking behavior when a signed block no longer matches
 	 * its conversation prefix. Binding-capable models default to `"drop_block"`.
 	 */
 	anthropicPrefixMismatchBehavior?: "drop_block" | "error";
-	/** @internal Marks a replay-only Anthropic request that must use non-streaming `max_tokens: 0`. */
-	anthropicCacheRefreshRequest?: boolean;
 	/**
 	 * Anthropic on-demand compaction (`compact-2026-09-04` beta). Sends a
 	 * top-level `compaction: { type: "summarize", instructions? }` request; the