fix(adapters): forward prompt_cache_key through openai-chat adapter (#217) (#224)

* fix(adapters): forward prompt_cache_key through openai-chat adapter (#217)

The Responses parser writes prompt_cache_key to options.promptCacheKey,
but the openai-chat adapter's buildRequest() never copied it into the
outbound /chat/completions body. OpenAI's Chat Completions API accepts
prompt_cache_key as an optional string for prompt-cache affinity grouping.

Copy parsed.options.promptCacheKey to body.prompt_cache_key when set,
omit when unset. The openai-responses passthrough adapter already
preserves it via _rawBody forwarding.

Add two tests: one asserting the field is forwarded when present,
one asserting it is absent when not provided.

* fix(adapters): gate prompt_cache_key behind provider opt-in flag

The previous unconditional copy forwarded prompt_cache_key to every
openai-chat backend. Strict providers (Groq, Cerebras, etc.) reject
unknown body fields, so this could break those routed requests.

Add an opt-in promptCacheKey boolean flag to OcxProviderConfig and
ProviderRegistryEntry, wired through router scalar backfill. The
adapter now only forwards body.prompt_cache_key when the provider
explicitly opts in. Default off, so no built-in provider is affected.

The built-in OpenAI provider uses openai-responses (passthrough),
which already preserves prompt_cache_key via _rawBody forwarding.
This flag is for user-configured openai-chat providers that document
prompt_cache_key support.

Tests updated to cover opt-in, opt-out, and unset cases.

Author: Wibias

src/adapters/openai-chat.ts

@@ -502,6 +502,11 @@ export function createOpenAIChatAdapter(provider: OcxProviderConfig): ProviderAd
       if (parsed.options.frequencyPenalty !== undefined && !modelInList(provider.noPenaltyModels, parsed.modelId)) {
         body.frequency_penalty = parsed.options.frequencyPenalty;
       }
+      // prompt_cache_key is an OpenAI-specific chat extension; strict backends (Groq,
+      // Cerebras, etc.) reject unknown fields. Only forward when the provider opts in.
+      if (provider.promptCacheKey && parsed.options.promptCacheKey !== undefined) {
+        body.prompt_cache_key = parsed.options.promptCacheKey;
+      }
 
       if (tools) {
         // Default-ON for chat-completions providers (user decision 260709): the buffered

src/providers/registry.ts

@@ -65,6 +65,8 @@ export interface ProviderRegistryEntry {
   noPenaltyModels?: string[];
   /** Opt this provider into parallel tool calls (see OcxProviderConfig.parallelToolCalls). */
   parallelToolCalls?: boolean;
+  /** Opt this provider into forwarding prompt_cache_key (OpenAI-specific; strict backends reject it). */
+  promptCacheKey?: boolean;
   autoToolChoiceOnlyModels?: string[];
   preserveReasoningContentModels?: string[];
   thinkingToggleModels?: string[];

src/router.ts

@@ -182,6 +182,7 @@ function routedProviderConfig(providerName: string, provider: OcxProviderConfig)
     // Scalar backfill: a persisted config created before the flag shipped inherits the registry
     // opt-in, while an explicit user `false` keeps overriding registry `true`.
     ...(provider.parallelToolCalls === undefined && registryEntry.parallelToolCalls !== undefined ? { parallelToolCalls: registryEntry.parallelToolCalls } : {}),
+    ...(provider.promptCacheKey === undefined && registryEntry.promptCacheKey !== undefined ? { promptCacheKey: registryEntry.promptCacheKey } : {}),
     ...(modelContextWindows ? { modelContextWindows } : {}),
     ...(modelInputModalities ? { modelInputModalities } : {}),
     ...(modelMaxInputTokens ? { modelMaxInputTokens } : {}),

src/types.ts

@@ -692,6 +692,12 @@ export interface OcxProviderConfig {
    * only on explicit `true`. See devlog/_plan/260709_parallel_tool_calls.
    */
   parallelToolCalls?: boolean;
+  /**
+   * Opt-in: forward `prompt_cache_key` to the upstream `/chat/completions` body.
+   * OpenAI-specific extension; strict backends (Groq, Cerebras, etc.) reject unknown
+   * fields. Default off; only enable for providers that document this parameter.
+   */
+  promptCacheKey?: boolean;
   /** Model ids whose tool_choice only accepts `auto` or `none`; forced/named choices are downgraded. */
   autoToolChoiceOnlyModels?: string[];
   /** Model ids that expect prior assistant `reasoning_content` to be preserved in chat history. */

tests/openai-chat-hardening.test.ts

@@ -129,4 +129,32 @@ describe("openai-chat credential hardening", () => {
       Authorization: "Bearer sk-litellm",
     });
   });
+
+  test("forwards prompt_cache_key to the outbound chat body when the provider opts in", () => {
+    const adapter = createOpenAIChatAdapter(provider({ promptCacheKey: true }));
+    const req = parsed();
+    req.options.promptCacheKey = "shared-prefix-v1";
+
+    const body = JSON.parse(adapter.buildRequest(req).body);
+
+    expect(body.prompt_cache_key).toBe("shared-prefix-v1");
+  });
+
+  test("does not forward prompt_cache_key when the provider has not opted in", () => {
+    const adapter = createOpenAIChatAdapter(provider());
+    const req = parsed();
+    req.options.promptCacheKey = "shared-prefix-v1";
+
+    const body = JSON.parse(adapter.buildRequest(req).body);
+
+    expect(body).not.toHaveProperty("prompt_cache_key");
+  });
+
+  test("omits prompt_cache_key from the outbound chat body when unset", () => {
+    const adapter = createOpenAIChatAdapter(provider({ promptCacheKey: true }));
+
+    const body = JSON.parse(adapter.buildRequest(parsed()).body);
+
+    expect(body).not.toHaveProperty("prompt_cache_key");
+  });
 });