feat: add TTL support for Anthropic cache control

- Added cache_ttl field to Message interface and schema
- Cache control now accepts object format with ttl option
- Backwards compatible with existing boolean cacheControl usage

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: petrbrzek

CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## 0.16.9
+
+- Added TTL support for Anthropic cache control (`cache_ttl` field)
+- Cache control now accepts object format with `ttl` option: `{ type: "ephemeral", ttl: "1h" }`
+
 ## 0.16.8
 
 - Add GoogleGeminiV1 to ReasoningFormat and update related tests

package.json

@@ -1,6 +1,6 @@
 {
   "name": "langtail",
-  "version": "0.16.8",
+  "version": "0.16.9",
   "description": "",
   "main": "./Langtail.js",
   "packageManager": "pnpm@8.15.6",

src/schemas.ts

@@ -136,6 +136,7 @@ export interface Message {
   // NOTE: dynamic property calculated by the client for the diff view
   hash?: string
   cache_enabled?: boolean
+  cache_ttl?: string
 }
 
 export interface PlaygroundMessage extends Message {
@@ -237,6 +238,7 @@ export const MessageSchema = z.object({
   tool_choice: ToolChoiceSchema.optional(),
   tool_call_id: z.string().optional(),
   cache_enabled: z.boolean().optional(),
+  cache_ttl: z.string().optional(),
   reasoning: z.array(MessageReasoningSchema).optional(),
   reasoning_details: z.array(ReasoningDetailUnionSchema).nullish(),
 }) satisfies z.ZodType<Message>

src/vercel-ai/convert-to-openai-chat-messages.ts

@@ -18,30 +18,42 @@ export function convertToOpenAIChatMessages({
   const messages: OpenAIChatPrompt = []
 
   // Helper function to add a message with cacheControl if needed
-  const addMessage = (message: any, cacheControl: boolean) => {
-    if (cacheControl) {
+  const addMessage = (
+    message: any,
+    cacheEnabled: boolean,
+    cacheTtl?: string,
+  ) => {
+    if (cacheEnabled) {
       message.cache_enabled = true
     }
+    if (cacheTtl) {
+      message.cache_ttl = cacheTtl
+    }
 
     messages.push(message)
   }
 
   for (const { role, content, providerMetadata } of prompt) {
-    const anthropicCacheControl = Boolean(
-      providerMetadata?.anthropic?.cacheControl,
-    )
+    const anthropicCacheControl = providerMetadata?.anthropic?.cacheControl
+    const cacheEnabled = Boolean(anthropicCacheControl)
+    const cacheTtl =
+      typeof anthropicCacheControl === "object" &&
+      anthropicCacheControl !== null
+        ? (anthropicCacheControl as { ttl?: string }).ttl
+        : undefined
 
     switch (role) {
       case "system": {
-        addMessage({ role: "system", content }, anthropicCacheControl)
+        addMessage({ role: "system", content }, cacheEnabled, cacheTtl)
         break
       }
 
       case "user": {
         if (content.length === 1 && content[0].type === "text") {
           addMessage(
             { role: "user", content: content[0].text },
-            anthropicCacheControl,
+            cacheEnabled,
+            cacheTtl,
           )
           break
         }
@@ -78,7 +90,8 @@ export function convertToOpenAIChatMessages({
               }
             }),
           },
-          anthropicCacheControl,
+          cacheEnabled,
+          cacheTtl,
         )
         break
       }
@@ -150,7 +163,8 @@ export function convertToOpenAIChatMessages({
             reasoning_details: reasoningDetails,
             tool_calls: toolCalls.length > 0 ? toolCalls : undefined,
           },
-          anthropicCacheControl,
+          cacheEnabled,
+          cacheTtl,
         )
         break
       }
@@ -203,7 +217,8 @@ export function convertToOpenAIChatMessages({
               tool_call_id: toolResponse.toolCallId,
               content: toolContent,
             },
-            anthropicCacheControl,
+            cacheEnabled,
+            cacheTtl,
           )
         }
         break