Context
Follow-up carved out of the OpenAI Responses API migration design
(prd/docs/superpowers/specs/2026-07-10-openai-responses-api-migration-design.md).
That migration will send a stable auto-derived prompt_cache_key on every
Responses request (implicit caching mode, default). GPT-5.6 also supports
explicit prompt caching — prompt_cache_options.mode: "explicit" plus
prompt_cache_breakpoint: { mode: "explicit" } markers on content blocks that
pin the exact end of the cached prefix. The migration intentionally defers
this, because there is no way today to express a cache breakpoint from the
task / message layer.
The problem
OpenAI's explicit breakpoints are positional — they attach to a content block in
the request input. Our provider builds that input from workglow messages via
toOpenAIMessages + buildResponsesInput, so the task/message layer currently
has no vocabulary to say "the cached prefix ends here" (typically after a long,
stable system prompt + tools, or a fixed RAG preamble).
What to figure out
- A marker the message/port layer can carry (e.g. a flag on a message or a
dedicated boundary marker) that buildResponsesInput translates into
prompt_cache_breakpoint on the right content block.
- Whether this stays OpenAI-specific or is modeled generically (Anthropic has an
analogous cache_control breakpoint concept, so a provider-neutral marker may
be worth it).
- Defaulting: implicit mode with an auto-derived
prompt_cache_key should remain
the default; explicit breakpoints are an opt-in optimization for long stable
prefixes.
Why it matters
On GPT-5.6 cache writes now bill at 1.25× the uncached input rate, so precise
prefix pinning on long stable prefixes (RAG/system) has real cost upside beyond
latency.
Not blocking
The migration ships with implicit caching + prompt_cache_key. This issue is the
deferred explicit-breakpoint design only.
Context
Follow-up carved out of the OpenAI Responses API migration design
(
prd/docs/superpowers/specs/2026-07-10-openai-responses-api-migration-design.md).That migration will send a stable auto-derived
prompt_cache_keyon everyResponses request (implicit caching mode, default). GPT-5.6 also supports
explicit prompt caching —
prompt_cache_options.mode: "explicit"plusprompt_cache_breakpoint: { mode: "explicit" }markers on content blocks thatpin the exact end of the cached prefix. The migration intentionally defers
this, because there is no way today to express a cache breakpoint from the
task / message layer.
The problem
OpenAI's explicit breakpoints are positional — they attach to a content block in
the request
input. Our provider builds thatinputfrom workglow messages viatoOpenAIMessages+buildResponsesInput, so the task/message layer currentlyhas no vocabulary to say "the cached prefix ends here" (typically after a long,
stable system prompt + tools, or a fixed RAG preamble).
What to figure out
dedicated boundary marker) that
buildResponsesInputtranslates intoprompt_cache_breakpointon the right content block.analogous
cache_controlbreakpoint concept, so a provider-neutral marker maybe worth it).
prompt_cache_keyshould remainthe default; explicit breakpoints are an opt-in optimization for long stable
prefixes.
Why it matters
On GPT-5.6 cache writes now bill at 1.25× the uncached input rate, so precise
prefix pinning on long stable prefixes (RAG/system) has real cost upside beyond
latency.
Not blocking
The migration ships with implicit caching +
prompt_cache_key. This issue is thedeferred explicit-breakpoint design only.