fix(agents): add prompt cache compatibility opt-out

Add compat.supportsPromptCacheKey for OpenAI Responses prompt_cache_key handling, update generated config baseline, changelog, and A2UI dependency-layout test compatibility.

src/agents/provider-attribution.test.ts

@@ -620,6 +620,55 @@ describe("provider attribution", () => {
     });
   });
 
+  it("respects compat.supportsPromptCacheKey override on prompt cache stripping", () => {
+    // compat.supportsPromptCacheKey = true disables the strip even on a
+    // proxy-like endpoint that would otherwise trigger it.
+    expect(
+      resolveProviderRequestCapabilities({
+        provider: "custom-proxy",
+        api: "openai-responses",
+        baseUrl: "https://proxy.example.com/v1",
+        capability: "llm",
+        transport: "stream",
+        compat: { supportsPromptCacheKey: true },
+      }),
+    ).toMatchObject({
+      endpointClass: "custom",
+      shouldStripResponsesPromptCache: false,
+    });
+
+    // compat.supportsPromptCacheKey = false forces the strip even on a
+    // native OpenAI endpoint that would otherwise forward the field.
+    expect(
+      resolveProviderRequestCapabilities({
+        provider: "openai",
+        api: "openai-responses",
+        baseUrl: "https://api.openai.com/v1",
+        capability: "llm",
+        transport: "stream",
+        compat: { supportsPromptCacheKey: false },
+      }),
+    ).toMatchObject({
+      endpointClass: "openai-public",
+      shouldStripResponsesPromptCache: true,
+    });
+
+    // compat.supportsPromptCacheKey unset preserves the existing default
+    // (strip on proxy-like responses endpoints, preserving the fix from
+    // #48155 for providers that reject the field).
+    expect(
+      resolveProviderRequestCapabilities({
+        provider: "custom-proxy",
+        api: "openai-responses",
+        baseUrl: "https://proxy.example.com/v1",
+        capability: "llm",
+        transport: "stream",
+      }),
+    ).toMatchObject({
+      shouldStripResponsesPromptCache: true,
+    });
+  });
+
   it("resolves shared compat families and native streaming-usage gates", () => {
     expect(
       resolveProviderRequestCapabilities({

src/agents/provider-attribution.ts

@@ -92,6 +92,7 @@ export type ProviderRequestCapabilitiesInput = ProviderRequestPolicyInput & {
   modelId?: string | null;
   compat?: {
     supportsStore?: boolean;
+    supportsPromptCacheKey?: boolean;
   } | null;
 };
 
@@ -607,8 +608,20 @@ export function resolveProviderRequestCapabilities(
       OPENAI_RESPONSES_APIS.has(api) &&
       OPENAI_RESPONSES_PROVIDERS.has(provider) &&
       policy.usesKnownNativeOpenAIEndpoint,
+    // Default strip behavior (proxy-like endpoints with responses APIs) is
+    // preserved as a safety net for providers that reject prompt_cache_key —
+    // see #48155 (Volcano Engine DeepSeek). Operators running their payload
+    // through an OpenAI-compatible proxy known to forward the field
+    // (CLIProxy, LiteLLM, etc.) can opt out via compat.supportsPromptCacheKey
+    // to recover prompt caching; providers known to reject the field can
+    // force the strip with compat.supportsPromptCacheKey = false even on
+    // native endpoints.
     shouldStripResponsesPromptCache:
-      api !== undefined && OPENAI_RESPONSES_APIS.has(api) && policy.usesExplicitProxyLikeEndpoint,
+      input.compat?.supportsPromptCacheKey === true
+        ? false
+        : input.compat?.supportsPromptCacheKey === false
+          ? api !== undefined && OPENAI_RESPONSES_APIS.has(api)
+          : api !== undefined && OPENAI_RESPONSES_APIS.has(api) && policy.usesExplicitProxyLikeEndpoint,
     // Native endpoint class is the real signal here. Users can point a generic
     // provider key at Moonshot or DashScope and still need streaming usage.
     supportsNativeStreamingUsageCompat:

src/agents/provider-request-config.ts

@@ -162,6 +162,7 @@ type ResolveProviderRequestPolicyConfigParams = {
   authHeader?: boolean;
   compat?: {
     supportsStore?: boolean;
+    supportsPromptCacheKey?: boolean;
   } | null;
   modelId?: string | null;
   allowPrivateNetwork?: boolean;

src/config/schema.base.generated.ts

@@ -2798,6 +2798,9 @@ export const GENERATED_BASE_CONFIG_SCHEMA: BaseConfigSchemaResponse = {
                           supportsStore: {
                             type: "boolean",
                           },
+                          supportsPromptCacheKey: {
+                            type: "boolean",
+                          },
                           supportsDeveloperRole: {
                             type: "boolean",
                           },

src/config/types.models.ts

@@ -37,6 +37,7 @@ type SupportedThinkingFormat =
 export type ModelCompatConfig = SupportedOpenAICompatFields & {
   thinkingFormat?: SupportedThinkingFormat;
   supportsTools?: boolean;
+  supportsPromptCacheKey?: boolean;
   requiresStringContent?: boolean;
   toolSchemaProfile?: string;
   unsupportedToolSchemaKeywords?: string[];

src/config/zod-schema.core.ts

@@ -186,6 +186,7 @@ export const ModelApiSchema = z.enum(MODEL_APIS);
 export const ModelCompatSchema = z
   .object({
     supportsStore: z.boolean().optional(),
+    supportsPromptCacheKey: z.boolean().optional(),
     supportsDeveloperRole: z.boolean().optional(),
     supportsReasoningEffort: z.boolean().optional(),
     supportsUsageInStreaming: z.boolean().optional(),