@gajae-code/ai 0.12.13 → 0.12.15

package/CHANGELOG.md

@@ -2,11 +2,19 @@
 
 ## [Unreleased]
 
+## [0.12.15] - 2026-08-06
+
+### Fixed
+
+- Anthropic requests rejected with `A maximum of 4 blocks with cache_control may be provided. Found N.` now retry once with generated caching suppressed, instead of dying on the first attempt (#3934). An Anthropic-compatible gateway may attach its own block-level cache markers before forwarding, and those never appear in the params we serialize, so the total is unpredictable locally and the rejection itself is the only usable signal. The retry keeps generated caching off for the rest of the provider session so later turns do not re-trigger the same 400. Only a genuine breakpoint-overflow `invalid_request_error` is claimed — other `cache_control` complaints, unrelated 400s, non-400 statuses, and our own pre-flight validation failure still surface immediately. The classifier is exported as `isAnthropicCacheBreakpointOverflowError`.
+
+## [0.12.14] - 2026-08-06
+
 ## [0.12.13] - 2026-08-06
 
 ### Changed
 
-- Anthropic prompt caching now defaults to top-level automatic caching (`cache_control: { type: "ephemeral" }`) for every Claude-family model, including through non-canonical Anthropic-compatible gateways (Cloudflare AI Gateway, GitHub Copilot, GitLab Duo, Vercel AI Gateway, zenmux, etc.), instead of only `api.anthropic.com`. Non-Claude models on unknown compatible endpoints keep the previous no-cache default; `compat.promptCacheMode: "none"`, `compat.promptCacheMode: "explicit"`, and configured or per-request `cacheRetention: "none"` still opt out. Non-canonical Claude models get the default ~5m cache lifetime unless the endpoint sets `compat.supportsLongCacheRetention: true`.
+- Anthropic prompt caching now defaults to top-level automatic caching (`cache_control: { type: "ephemeral" }`) on the canonical Anthropic API and explicit block-level caching for Claude-family models on non-canonical Anthropic-compatible gateways (Cloudflare AI Gateway, GitHub Copilot, GitLab Duo, Vercel AI Gateway, zenmux, CLIProxyAPI, etc.). Explicit mode is the safer compatible default because gateways commonly inject, rewrite, or reject the top-level field; verified gateways can opt into it with `compat.promptCacheMode: "automatic"`. Non-Claude models on unknown compatible endpoints keep the no-cache default; `promptCacheMode: "none"` and configured or per-request `cacheRetention: "none"` still opt out. Non-canonical Claude models get the default ~5m lifetime unless the endpoint sets `compat.supportsLongCacheRetention: true`.
 
 ### Fixed
 

package/dist/types/providers/anthropic.d.ts

@@ -63,6 +63,19 @@ export declare function isAnthropicThinkingSignatureInvalidError(error: unknown)
  * treating it as a thinking-replay rejection.
  */
 export declare function isAnthropicMaskedProxyRejection(error: unknown): boolean;
+/**
+ * Anthropic rejects a request carrying more than four `cache_control`
+ * breakpoints. An Anthropic-compatible gateway may attach its own block-level
+ * markers before forwarding, and those never appear in the params we serialize,
+ * so no amount of local counting can predict the total. The rejection is the
+ * only evidence that our generated marker is one too many, and it is worth
+ * exactly one retry with generated caching suppressed.
+ *
+ * Our own pre-flight `validateCacheControls` failure is deliberately not
+ * matched: it carries no `invalid_request_error` wording, so a local bug stays
+ * loud instead of being silently retried.
+ */
+export declare function isAnthropicCacheBreakpointOverflowError(error: unknown): boolean;
 export declare const claudeCodeVersion = "2.1.219";
 export declare const claudeCodeEntrypoint = "sdk-cli";
 export declare const claudeToolPrefix: string;

package/dist/types/types.d.ts

@@ -790,10 +790,10 @@ export interface AnthropicCompat extends ToolChoiceCompat {
     supportsLongCacheRetention?: boolean;
     /**
      * Prompt-cache transport accepted by this Anthropic-compatible endpoint.
-     * Canonical Anthropic and Claude-family models default to `"automatic"`;
-     * noncanonical non-Claude endpoints default to `"none"`. Set `"automatic"` to
-     * opt an otherwise unknown compatible endpoint into top-level caching, `"none"`
-     * to opt out, or `"explicit"` for endpoints that require block-level markers.
+     * Canonical Anthropic defaults to `"automatic"`; Claude-family models on
+     * noncanonical compatible endpoints default to `"explicit"`; non-Claude
+     * compatible endpoints default to `"none"`. Set `"automatic"` to opt into
+     * top-level caching, `"none"` to opt out, or `"explicit"` for block markers.
      */
     promptCacheMode?: "none" | "explicit" | "automatic";
 }

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@gajae-code/ai",
-	"version": "0.12.13",
+	"version": "0.12.15",
 	"description": "Unified LLM API with automatic model discovery and provider configuration",
 	"homepage": "https://gajae-code.com",
 	"author": "Yeachan-Heo and Gajae Code Contributors",
@@ -40,7 +40,7 @@
 	"dependencies": {
 		"@anthropic-ai/sdk": "^0.94.0",
 		"@bufbuild/protobuf": "^2.12.0",
-		"@gajae-code/utils": "0.12.13",
+		"@gajae-code/utils": "0.12.15",
 		"openai": "^6.36.0",
 		"partial-json": "^0.1.7",
 		"zod": "4.4.3"

package/src/providers/anthropic.ts

@@ -319,15 +319,18 @@ const ANTHROPIC_PROVIDER_SESSION_STATE_KEY = "anthropic-messages";
 type AnthropicProviderSessionState = ProviderSessionState & {
 	strictToolsDisabled: boolean;
 	fastModeDisabled: boolean;
+	generatedCachingDisabled: boolean;
 };
 
 function createAnthropicProviderSessionState(): AnthropicProviderSessionState {
 	const state: AnthropicProviderSessionState = {
 		strictToolsDisabled: false,
 		fastModeDisabled: false,
+		generatedCachingDisabled: false,
 		close: () => {
 			state.strictToolsDisabled = false;
 			state.fastModeDisabled = false;
+			state.generatedCachingDisabled = false;
 		},
 	};
 	return state;
@@ -456,6 +459,28 @@ export function isAnthropicMaskedProxyRejection(error: unknown): boolean {
 	return /"type"\s*:\s*"api_error"/.test(message) && /an error occurred while processing/i.test(message);
 }
 
+/**
+ * Anthropic rejects a request carrying more than four `cache_control`
+ * breakpoints. An Anthropic-compatible gateway may attach its own block-level
+ * markers before forwarding, and those never appear in the params we serialize,
+ * so no amount of local counting can predict the total. The rejection is the
+ * only evidence that our generated marker is one too many, and it is worth
+ * exactly one retry with generated caching suppressed.
+ *
+ * Our own pre-flight `validateCacheControls` failure is deliberately not
+ * matched: it carries no `invalid_request_error` wording, so a local bug stays
+ * loud instead of being silently retried.
+ */
+export function isAnthropicCacheBreakpointOverflowError(error: unknown): boolean {
+	if (!isAnthropicInvalidRequestStatus(error)) return false;
+	const message = error instanceof Error ? error.message : String(error);
+	if (!/invalid_request_error/i.test(message)) return false;
+	if (!/cache_control/i.test(message)) return false;
+	// Observed: "A maximum of 4 blocks with cache_control may be provided. Found 5."
+	// Stay tolerant of phrasing drift around the limit and the reported total.
+	return /maximum of \d+ blocks/i.test(message) || /at most \d+ blocks/i.test(message);
+}
+
 function hasStrictAnthropicTools(params: MessageCreateParamsStreaming): boolean {
 	const tools = params.tools as Array<{ strict?: unknown }> | undefined;
 	return tools?.some(tool => tool.strict === true) ?? false;
@@ -493,7 +518,12 @@ function getCacheControl(
 	model: Model<"anthropic-messages">,
 	baseUrl: string,
 	cacheRetention?: CacheRetention,
+	suppressGeneratedCaching = false,
 ): { mode: AnthropicCacheMode; cacheControl?: AnthropicCacheControl } {
+	// A gateway already at Anthropic's four-breakpoint limit rejected our
+	// generated marker on a previous attempt. The extra markers are invisible
+	// here, so the only safe retry is to add none of our own.
+	if (suppressGeneratedCaching) return { mode: "none" };
 	const retention = resolveCacheRetention(cacheRetention ?? model.cacheRetention, "long");
 	if (retention === "none") return { mode: "none" };
 
@@ -504,9 +534,13 @@ function getCacheControl(
 			? "none"
 			: promptCacheMode === "explicit"
 				? "explicit"
-				: promptCacheMode === "automatic" || isCanonicalApi || isClaudeFamilyModel(model)
+				: promptCacheMode === "automatic"
 					? "automatic"
-					: "none";
+					: isCanonicalApi
+						? "automatic"
+						: isClaudeFamilyModel(model)
+							? "explicit"
+							: "none";
 	if (mode === "none") return { mode };
 
 	const supportsLongCacheRetention = isCanonicalApi
@@ -1411,16 +1445,23 @@ export const streamAnthropic: StreamFunction<"anthropic-messages"> = (
 			let droppedForcedToolChoice = false;
 			let repairLatestAssistantThinking = false;
 			let repairAllAssistantThinking = false;
+			let suppressGeneratedCaching = providerSessionState?.generatedCachingDisabled ?? false;
 			const prepareParams = async (): Promise<MessageCreateParamsStreaming> => {
 				// Degradation state is cumulative: every fallback rebuild must merge all
 				// repairs activated so far. Rebuilding from only the immediate call lets
 				// a later strict/forced-tool/fast-mode fallback reintroduce the rejected
 				// shape (e.g. invalid thinking signatures or forced tool_choice), and
 				// the one-shot thinking-repair guard then blocks recovery.
-				let nextParams = buildParams(model, baseUrl, context, isOAuthToken, options, disableStrictTools, {
-					repairLatestAssistantThinking,
-					repairAllAssistantThinking,
-				});
+				let nextParams = buildParams(
+					model,
+					baseUrl,
+					context,
+					isOAuthToken,
+					options,
+					disableStrictTools,
+					{ repairLatestAssistantThinking, repairAllAssistantThinking },
+					suppressGeneratedCaching,
+				);
 				if (droppedForcedToolChoice) {
 					delete nextParams.tool_choice;
 				}
@@ -1933,6 +1974,29 @@ export const streamAnthropic: StreamFunction<"anthropic-messages"> = (
 						resetOutputForRetry();
 						continue;
 					}
+					if (
+						!options?.fallbackManaged &&
+						!suppressGeneratedCaching &&
+						firstTokenTime === undefined &&
+						isAnthropicCacheBreakpointOverflowError(streamFailure)
+					) {
+						// The gateway's own markers already fill Anthropic's four slots, so
+						// our generated breakpoint is the fifth. We cannot see the others,
+						// which makes the rejection itself the only usable signal; retry
+						// once with generated caching off and keep it off for the session.
+						logger.debug("anthropic: cache breakpoint limit exceeded, retrying without generated caching", {
+							model: model.id,
+							error: streamFailure instanceof Error ? streamFailure.message : String(streamFailure),
+						});
+						if (providerSessionState) {
+							providerSessionState.generatedCachingDisabled = true;
+						}
+						suppressGeneratedCaching = true;
+						params = await prepareParams();
+						providerRetryAttempt = 0;
+						resetOutputForRetry();
+						continue;
+					}
 					const isTransientEnvelopeFailure =
 						isTransientStreamParseError(streamFailure) || isTransientStreamEnvelopeError(streamFailure);
 					const canRetryTransientEnvelopeFailure = isTransientEnvelopeFailure && !streamedReplayUnsafeContent;
@@ -2396,6 +2460,7 @@ function enforceCacheControlLimit(params: MessageCreateParamsStreaming, maxBreak
 	if (maxBreakpoints !== 4) throw new Error("Anthropic supports exactly four cache breakpoints");
 	validateCacheControls(params as AnthropicCacheParams);
 }
+
 function buildParams(
 	model: Model<"anthropic-messages">,
 	baseUrl: string,
@@ -2404,8 +2469,14 @@ function buildParams(
 	options?: AnthropicOptions,
 	disableStrictTools = false,
 	thinkingRepair?: { repairLatestAssistantThinking?: boolean; repairAllAssistantThinking?: boolean },
+	suppressGeneratedCaching = false,
 ): MessageCreateParamsStreaming {
-	const { mode: cacheMode, cacheControl } = getCacheControl(model, baseUrl, options?.cacheRetention);
+	const { mode: cacheMode, cacheControl } = getCacheControl(
+		model,
+		baseUrl,
+		options?.cacheRetention,
+		suppressGeneratedCaching,
+	);
 
 	const params: AnthropicSamplingParams = {
 		model: model.id,

package/src/types.ts

@@ -951,10 +951,10 @@ export interface AnthropicCompat extends ToolChoiceCompat {
 	supportsLongCacheRetention?: boolean;
 	/**
 	 * Prompt-cache transport accepted by this Anthropic-compatible endpoint.
-	 * Canonical Anthropic and Claude-family models default to `"automatic"`;
-	 * noncanonical non-Claude endpoints default to `"none"`. Set `"automatic"` to
-	 * opt an otherwise unknown compatible endpoint into top-level caching, `"none"`
-	 * to opt out, or `"explicit"` for endpoints that require block-level markers.
+	 * Canonical Anthropic defaults to `"automatic"`; Claude-family models on
+	 * noncanonical compatible endpoints default to `"explicit"`; non-Claude
+	 * compatible endpoints default to `"none"`. Set `"automatic"` to opt into
+	 * top-level caching, `"none"` to opt out, or `"explicit"` for block markers.
 	 */
 	promptCacheMode?: "none" | "explicit" | "automatic";
 }