Support OpenAI prompt cache breakpoints

Author: hsyntax

.changeset/openai-text-prompt-cache.md

@@ -0,0 +1,6 @@
+---
+"@effect/ai-openai": patch
+"effect": patch
+---
+
+Support OpenAI prompt cache request options and explicit breakpoints on system, developer, and user input text, and correct message constructor provider option types.

packages/ai/openai/src/OpenAiLanguageModel.ts

@@ -58,6 +58,8 @@ export type Model = typeof ResponseModelIds.Encoded | typeof SharedModelIds.Enco
  */
 type ImageDetail = "auto" | "low" | "high"
 
+type PromptCacheBreakpoint = { readonly mode: "explicit" }
+
 // =============================================================================
 // Configuration
 // =============================================================================
@@ -127,6 +129,24 @@ export class Config extends Context.Service<
 // =============================================================================
 
 declare module "effect/unstable/ai/Prompt" {
+  /**
+   * OpenAI-specific options for system messages.
+   *
+   * @category models
+   * @since 4.0.0
+   */
+  export interface SystemMessageOptions extends ProviderOptions {
+    /**
+     * Provider-specific system message options for the OpenAI Responses API.
+     */
+    readonly openai?: {
+      /**
+       * Marks the system input text as the end of a reusable prompt prefix.
+       */
+      readonly promptCacheBreakpoint?: PromptCacheBreakpoint | null
+    } | null
+  }
+
   /**
    * OpenAI-specific options for file prompt parts.
    *
@@ -244,6 +264,10 @@ declare module "effect/unstable/ai/Prompt" {
        * A list of annotations that apply to the output text.
        */
       readonly annotations?: ReadonlyArray<typeof OpenAiSchema.Annotation.Encoded> | null
+      /**
+       * Marks the input text as the end of a reusable prompt prefix.
+       */
+      readonly promptCacheBreakpoint?: PromptCacheBreakpoint | null
     } | null
   }
 }
@@ -817,9 +841,16 @@ const prepareMessages = Effect.fnUntraced(
     for (const message of prompt.content) {
       switch (message.role) {
         case "system": {
+          const promptCacheBreakpoint = getPromptCacheBreakpoint(message)
           messages.push({
             role: getSystemMessageMode(config.model as string),
-            content: [{ type: "input_text", text: message.content }]
+            content: [{
+              type: "input_text",
+              text: message.content,
+              ...(Predicate.isNotNull(promptCacheBreakpoint)
+                ? { prompt_cache_breakpoint: promptCacheBreakpoint }
+                : undefined)
+            }]
           })
           break
         }
@@ -832,7 +863,14 @@ const prepareMessages = Effect.fnUntraced(
 
             switch (part.type) {
               case "text": {
-                content.push({ type: "input_text", text: part.text })
+                const promptCacheBreakpoint = getPromptCacheBreakpoint(part)
+                content.push({
+                  type: "input_text",
+                  text: part.text,
+                  ...(Predicate.isNotNull(promptCacheBreakpoint)
+                    ? { prompt_cache_breakpoint: promptCacheBreakpoint }
+                    : undefined)
+                })
                 break
               }
 
@@ -2910,6 +2948,10 @@ const getEncryptedContent = (
 
 const getImageDetail = (part: Prompt.FilePart): ImageDetail => part.options.openai?.imageDetail ?? "auto"
 
+const getPromptCacheBreakpoint = (
+  input: Prompt.SystemMessage | Prompt.TextPart
+): PromptCacheBreakpoint | null => input.options.openai?.promptCacheBreakpoint ?? null
+
 const makeItemIdMetadata = (itemId: string | undefined) => Predicate.isNotUndefined(itemId) ? { itemId } : {}
 
 const makeEncryptedContentMetadata = (encryptedContent: string | null | undefined) =>

packages/ai/openai/src/OpenAiSchema.ts

@@ -19,6 +19,10 @@ const MessageRole = Schema.Literals(["system", "developer", "user", "assistant"]
 
 const ImageDetail = Schema.Literals(["low", "high", "auto"])
 
+const PromptCacheBreakpoint = Schema.Struct({
+  mode: Schema.Literal("explicit")
+})
+
 /**
  * Schema for optional `include` values supported by the local handwritten
  * Responses client schema.
@@ -76,7 +80,8 @@ export type MessageStatus = typeof MessageStatus.Type
 
 const InputTextContent = Schema.Struct({
   type: Schema.Literal("input_text"),
-  text: Schema.String
+  text: Schema.String,
+  prompt_cache_breakpoint: Schema.optional(PromptCacheBreakpoint)
 })
 
 const InputImageContent = Schema.Struct({
@@ -640,7 +645,7 @@ export type TextResponseFormatConfiguration = typeof TextResponseFormatConfigura
  * Validates the Responses API request payload, including input content, model
  * selection, instructions, reasoning options, text output format, tools,
  * `tool_choice`, streaming, storage, response continuation, sampling options,
- * and optional response fields requested through `include`.
+ * prompt caching, and optional response fields requested through `include`.
  *
  * **Gotchas**
  *
@@ -659,6 +664,11 @@ export const CreateResponse = Schema.Struct({
   temperature: Schema.optional(Schema.Finite),
   top_p: Schema.optional(Schema.Finite),
   user: Schema.optional(Schema.String),
+  prompt_cache_key: Schema.optional(Schema.String),
+  prompt_cache_options: Schema.optional(Schema.Struct({
+    mode: Schema.optional(Schema.Literals(["implicit", "explicit"])),
+    ttl: Schema.optional(Schema.Literal("30m"))
+  })),
   service_tier: Schema.optional(Schema.String),
   previous_response_id: Schema.optional(Schema.String),
   model: Schema.optional(Schema.String),

packages/ai/openai/test/OpenAiLanguageModel.test.ts

@@ -31,6 +31,51 @@ describe("OpenAiLanguageModel", () => {
 
   describe("generateText", () => {
     describe("message preparation", () => {
+      it.effect("forwards prompt cache configuration and text breakpoints", () =>
+        Effect.gen(function*() {
+          const breakpoint = { mode: "explicit" } as const
+          yield* LanguageModel.generateText({
+            prompt: Prompt.make([
+              Prompt.systemMessage({
+                content: "Stable instructions",
+                options: { openai: { promptCacheBreakpoint: breakpoint } }
+              }),
+              Prompt.userMessage({
+                content: [Prompt.textPart({
+                  text: "Stable context",
+                  options: { openai: { promptCacheBreakpoint: breakpoint } }
+                })]
+              })
+            ])
+          }).pipe(
+            Effect.provide(OpenAiLanguageModel.model("gpt-5.6", {
+              prompt_cache_key: "assistant:v1",
+              prompt_cache_options: { mode: "explicit", ttl: "30m" }
+            }))
+          )
+
+          const requests = yield* MockHttpClient.requests
+          const body = yield* getRequestBody(requests[0])
+
+          strictEqual(body.prompt_cache_key, "assistant:v1")
+          deepStrictEqual(body.prompt_cache_options, { mode: "explicit", ttl: "30m" })
+          deepStrictEqual(body.input, [{
+            role: "developer",
+            content: [{
+              type: "input_text",
+              text: "Stable instructions",
+              prompt_cache_breakpoint: breakpoint
+            }]
+          }, {
+            role: "user",
+            content: [{
+              type: "input_text",
+              text: "Stable context",
+              prompt_cache_breakpoint: breakpoint
+            }]
+          }])
+        }).pipe(Effect.provide(makeTestLayer({ body: { model: "gpt-5.6" as any } }))))
+
       describe("system messages", () => {
         it.effect("uses system role for standard models", () =>
           Effect.gen(function*() {

packages/effect/src/unstable/ai/Prompt.ts

@@ -1098,7 +1098,7 @@ export type MessageConstructorParams<M extends Message> = Omit<M, typeof Message
   /**
    * Optional provider-specific options for this message.
    */
-  readonly options?: Part["options"] | undefined
+  readonly options?: M["options"] | undefined
 }
 
 /**