Support OpenAI prompt_cache_breakpoint on Responses API input content

[brandon-julio-t]

Support OpenAI prompt_cache_breakpoint on Responses API input content

Summary

@effect/ai-openai currently has no way to mark an explicit OpenAI prompt-cache breakpoint on a Responses API input content block.

OpenAI's GPT-5.6 prompt-caching API supports prompt_cache_breakpoint on input_text, input_image, and input_file blocks. This is distinct from prompt_cache_key, which is a request-level cache-routing control.

Version checked

• @effect/ai-openai@4.0.0-beta.102
• main at c9b56ab
• OpenAI documentation checked on 2026-08-01

Why this matters

GPT-5.6 and later cache exact prefixes at cache breakpoints. With the default implicit policy, the service places a breakpoint at the latest user or tool message. If a stable system prompt or document is followed by changing content, the implicit breakpoint can repeatedly select a changing prefix instead of the stable reusable prefix.

An explicit breakpoint lets an application mark the end of the stable prefix. Combined with prompt_cache_options.mode: "explicit", it can also prevent writes for changing suffixes.

See OpenAI's current documentation for the behavior and supported blocks:

• Caching behavior when migrating to GPT-5.6
• Prompt cache breakpoints

Evidence in Effect

The high-level Responses content schemas have no breakpoint field:

• InputTextContent, InputImageContent, and InputFileContent contain the supported content data but no prompt_cache_breakpoint.
• InputContent is the union of those three schemas.

The prompt translator constructs those blocks without a breakpoint:

• System messages are converted to an input_text block.
• User text and image parts are converted to input_text and input_image blocks.
• PDF parts are converted to input_file blocks.

A repository-wide search of packages/ai/openai and packages/ai/openai-compat at c9b56ab507f224426ee8388dc450da447ec4715f finds no prompt_cache_breakpoint or prompt_cache_options support.

Expected behavior

Effect prompt content should provide an OpenAI-specific way to request:

{
  "type": "input_text",
  "text": "stable reusable instructions",
  "prompt_cache_breakpoint": {
    "mode": "explicit"
  }
}

The same capability should be representable for input_image and input_file parts supported by OpenAI.

The exact Effect API could use provider options on prompt parts or another provider-specific mechanism. The important behavior is that the marker survives prompt conversion and is emitted on the intended content block.

Request-level prompt_cache_key and prompt_cache_options support is tracked separately in #6830 because those fields belong to OpenAiLanguageModel.Config rather than individual prompt content blocks.

Related work

• #6342 reported that encoding system messages as strings prevented OpenAI cache hits.
• #6549 changed system-message encoding to an input_text block, which is one of the content types on which OpenAI now supports explicit breakpoints.
• #6504 / #6519 added the cache-write usage accounting needed to measure explicit caching behavior.

[pullfrog]

  ^{｜ Build this ➔ ｜ Make a plan ➔}