@gajae-code/ai 0.5.1 → 0.5.2

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 ## [Unreleased]
 
+## [0.5.2] - 2026-06-15
+
+### Changed
+
+- Changed the Anthropic provider's default prompt-cache retention to `long` (`ttl: "1h"`) when a request and model omit `cacheRetention`. The previous default (~5m) was too fragile for long-running Codex/Gajae-Code subagent workflows, where the cached prefix was frequently evicted between turns. The 1h `ttl` marker is only emitted on the canonical Anthropic API (`api.anthropic.com`) for models advertising `supportsLongCacheRetention`; proxies, gateways, and models without that capability still fall back to the default ephemeral breakpoint (Anthropic services it at ~5m). Explicit request/model `cacheRetention` and the `GJC_CACHE_RETENTION`/`PI_CACHE_RETENTION` env overrides continue to win, and `resolveCacheRetention` now accepts a `fallback` argument (defaulting to `"short"`) so non-Anthropic providers are unaffected.
+
 ## [0.5.1] - 2026-06-14
 
 ### Fixed

package/dist/types/utils.d.ts

@@ -22,7 +22,13 @@ export declare function getOpenAIResponsesHistoryPayload(providerPayload: Provid
 export declare function getOpenAIResponsesHistoryItems(providerPayload: ProviderPayload | undefined, currentProvider: string, fallbackProvider?: string): Array<Record<string, unknown>> | undefined;
 /**
  * Resolve cache retention preference.
- * Defaults to "short" and uses GJC_CACHE_RETENTION, with PI_CACHE_RETENTION as a legacy fallback.
+ *
+ * Resolution order: explicit request value → `GJC_CACHE_RETENTION` →
+ * legacy `PI_CACHE_RETENTION` → `fallback`. Both env vars act as explicit
+ * opt-in (`"long"`) or opt-out (any other value) so a provider-specific
+ * `fallback` only applies when nothing else is configured. `fallback`
+ * defaults to `"short"` to preserve the historical behaviour for callers
+ * that don't pass one.
  */
-export declare function resolveCacheRetention(cacheRetention?: CacheRetention): CacheRetention;
+export declare function resolveCacheRetention(cacheRetention?: CacheRetention, fallback?: CacheRetention): CacheRetention;
 export declare function isAnthropicOAuthToken(key: string): boolean;

package/package.json

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

package/src/providers/anthropic.ts

@@ -353,10 +353,19 @@ function getCacheControl(
 	baseUrl: string,
 	cacheRetention?: CacheRetention,
 ): { retention: CacheRetention; cacheControl?: AnthropicCacheControl } {
-	const retention = resolveCacheRetention(cacheRetention);
+	// Default Anthropic prompt caching to long (1h) retention. The provider
+	// default of ~5m is too fragile for long-running Codex/Gajae-Code subagent
+	// workflows, where the prefix is frequently evicted between turns. Explicit
+	// request/model `cacheRetention` and the GJC_CACHE_RETENTION /
+	// PI_CACHE_RETENTION env overrides still win.
+	const retention = resolveCacheRetention(cacheRetention, "long");
 	if (retention === "none") {
 		return { retention };
 	}
+	// `ttl: "1h"` is only honoured on the canonical Anthropic API for models
+	// that advertise long-cache support. Everywhere else (proxies, gateways,
+	// models without the capability) we fall back to the default ephemeral
+	// breakpoint, which Anthropic services at the standard ~5m TTL.
 	const ttl =
 		retention === "long" && isAnthropicApiBaseUrl(baseUrl) && getAnthropicCompat(model).supportsLongCacheRetention
 			? "1h"

package/src/utils.ts

@@ -153,14 +153,24 @@ export function getOpenAIResponsesHistoryItems(
 
 /**
  * Resolve cache retention preference.
- * Defaults to "short" and uses GJC_CACHE_RETENTION, with PI_CACHE_RETENTION as a legacy fallback.
+ *
+ * Resolution order: explicit request value → `GJC_CACHE_RETENTION` →
+ * legacy `PI_CACHE_RETENTION` → `fallback`. Both env vars act as explicit
+ * opt-in (`"long"`) or opt-out (any other value) so a provider-specific
+ * `fallback` only applies when nothing else is configured. `fallback`
+ * defaults to `"short"` to preserve the historical behaviour for callers
+ * that don't pass one.
  */
-export function resolveCacheRetention(cacheRetention?: CacheRetention): CacheRetention {
+export function resolveCacheRetention(
+	cacheRetention?: CacheRetention,
+	fallback: CacheRetention = "short",
+): CacheRetention {
 	if (cacheRetention) return cacheRetention;
 	if ($env.GJC_CACHE_RETENTION === "long") return "long";
 	if ($env.GJC_CACHE_RETENTION !== undefined) return "short";
 	if ($env.PI_CACHE_RETENTION === "long") return "long";
-	return "short";
+	if ($env.PI_CACHE_RETENTION !== undefined) return "short";
+	return fallback;
 }
 
 export function isAnthropicOAuthToken(key: string): boolean {