Expose OpenAI Responses safety and prompt-cache request options through OpenAiLanguageModel.Config

[brandon-julio-t]

Expose OpenAI Responses safety and prompt-cache request options through OpenAiLanguageModel.Config

Summary

@effect/ai-openai's high-level Responses language model cannot currently set several OpenAI request fields related to end-user safety identification and prompt caching.

In particular, OpenAiLanguageModel.Config does not expose:

• safety_identifier
• prompt_cache_key
• prompt_cache_retention for models before GPT-5.6
• prompt_cache_options for GPT-5.6 and later

Version checked

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

Evidence

OpenAiLanguageModel.Config derives its request fields from the handwritten OpenAiSchema.CreateResponse schema:

• OpenAiLanguageModel.Config derives from OpenAiSchema.CreateResponse.Encoded
• The handwritten OpenAiSchema.CreateResponse request schema omits all four fields above.
• The request builder forwards the remaining configuration into the OpenAI request, so adding the fields to the high-level schema should make the request-level options representable and forwardable.

There is already evidence of schema drift inside the package:

• The generated OpenAI CreateResponse request type includes safety_identifier, prompt_cache_key, and prompt_cache_retention.
• The generated schemas describe safety_identifier and prompt_cache_key.

OpenAI's current documentation establishes the intended semantics:

• Safety identifiers recommends a stable, privacy-preserving safety_identifier for applications serving individual end users.
• Prompt caching documents prompt_cache_key as a request-level cache-routing control.
• GPT-5.6 migration guidance recommends prompt_cache_options for GPT-5.6 and later.
• Prompt cache retention distinguishes prompt_cache_options.ttl for GPT-5.6 and later from the legacy prompt_cache_retention policy for earlier models.

Expected behavior

It should be possible to configure the supported request-level fields through the high-level language model API, for example:

OpenAiLanguageModel.model("gpt-5.6", {
  safety_identifier: hashedUserId,
  prompt_cache_key: "reviewer:v1",
  prompt_cache_options: {
    mode: "implicit",
    ttl: "30m"
  }
})

Earlier models should remain able to use prompt_cache_retention where supported.

Related work

• #6342 / #6549 fixed the Responses system-message encoding that prevented cache hits.
• #6504 / #6519 preserved cache_write_tokens usage accounting.
• #6187 corrected the prompt_cache_retention enum spelling.

Explicit content-level prompt_cache_breakpoint support is tracked separately in #6831 because it requires changes to prompt content schemas and translation rather than only request-level configuration.

[pullfrog]

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