feat(test): prepare-request:: cache-control

Author: cablehead

README.md

@@ -14,7 +14,7 @@ A [Nushell](https://www.nushell.sh) scriptable [MCP client](https://modelcontext
 * **Consistent API Across Models:** Connect to Gemini + Search and Anthropic + Search through a single, simple interface. ([Add providers easily.](docs/reference/provider-api.md))
 * **Persistent, Editable Conversations:** [Conversation threads](https://cablehead.github.io/xs/tutorials/threaded-conversations/) are saved across sessions. Review, edit, and control your own context window — no black-box history.
 * **Flexible Tool Integration:** Connect to MCP servers to extend functionality. `gpt2099` already rivals [Claude Code](https://docs.anthropic.com/en/docs/claude-code/overview) for local file editing, but with full provider independence and deeper flexibility.
-* **Document Support:** Upload and reference documents (PDFs, images, text files) directly in conversations with automatic content-type detection and caching.
+* **Document Support:** Upload and reference documents (PDFs, images, text files) directly in conversations with automatic content-type detection and optional caching.
 
 Built on [cross.stream](https://github.com/cablehead/xs) for event-driven processing, `gpt2099` brings modern AI directly into your Nushell workflow — fully scriptable, fully inspectable, all in the terminal.
 

docs/commands.md

@@ -19,7 +19,7 @@ gpt [OPTIONS]
 - `--provider-ptr (-p) <alias>` – Pointer to the provider/model
 - `--json (-j)` – Treat input as JSON
 - `--separator <str>` – Join list input with this separator
-- `--cache` – Enable ephemeral caching for this turn
+- `--cache` – Enable caching for this conversation turn
 
 **Example:**
 ```nushell
@@ -75,12 +75,12 @@ gpt document <PATH> [OPTIONS]
 
 **Options:**
 - `--name (-n) <string>` – Custom name for the document
-- `--cache <string>` – Cache control: "ephemeral" or "none"  
+- `--cache` – Enable caching for this document  
 - `--bookmark (-b) <string>` – Bookmark this document registration
 
 **Example:**
 ```nushell
-gpt document ~/report.pdf --name "Q4 Report" --bookmark "quarterly"
+gpt document ~/report.pdf --name "Q4 Report" --cache --bookmark "quarterly"
 ```
 
 See: [How to work with documents](./how-to/work-with-documents.md)

docs/how-to/work-with-documents.md

@@ -75,13 +75,15 @@ gpt document ~/chart.png --name "Sales Chart"
 
 ## Document Caching
 
-Documents automatically use ephemeral caching with supported providers (like Anthropic) to improve performance on repeated references. You can control caching with the `--cache` flag:
+Documents can signal to the provider that they should be cached to improve performance on repeated references. Enable caching with the `--cache` flag:
 
 ```nushell
-gpt document ~/large-file.pdf --cache ephemeral
-gpt document ~/dynamic-data.json --cache none
+gpt document ~/large-file.pdf --cache
+gpt document ~/dynamic-data.json  # no caching
 ```
 
+**Note:** Caching behavior depends on provider support - Anthropic uses ephemeral caching, while other providers may ignore the cache flag.
+
 ## Thread Management with Documents
 
 Documents integrate seamlessly with conversation threading:

docs/reference/schemas.md

@@ -37,7 +37,6 @@ Content blocks are a union of these types:
 {
   type: "text"
   text: string
-  cache_control?: {type: "ephemeral"}
 }
 ```
 
@@ -50,7 +49,6 @@ Content blocks are a union of these types:
     media_type: string              # MIME type
     data: string                    # Base64-encoded content
   }
-  cache_control?: {type: "ephemeral"}
 }
 ```
 
@@ -77,7 +75,6 @@ Content blocks are a union of these types:
 
 **Schema Notes:**
 - `options.provider_ptr` is required for actual API calls but optional in stored contexts
-- `cache_control` only supported by Anthropic (ignored by Gemini)
 - `tool_use.id` auto-generated if missing (Gemini requirement)
 - `document_block.source.media_type` determines provider-specific handling
 
@@ -114,9 +111,10 @@ Each turn in a thread is stored as a `gpt.turn` frame, with these top-level attr
 : Values: Turn ID(s) or bookmark name(s)
 
 **`cache`**
-: Ephemeral cache flag for this turn
+: Cache flag for this turn
 : Type: `bool`
 : Default: `false`
+: Note: Provider-specific implementation (e.g., Anthropic uses ephemeral caching)
 
 ### Document-Specific Fields
 
@@ -143,10 +141,10 @@ Each turn in a thread is stored as a `gpt.turn` frame, with these top-level attr
 : Size of the document in bytes
 : Type: `int`
 
-**`cache_control`**
-: Caching directive
-: Type: `string`
-: Values: `"ephemeral"` for documents
+**`cache`**
+: Cache flag for this turn
+: Type: `bool`
+: Default: `false`
 
 ## Thread Record Schema
 

gpt/ctx.nu

@@ -32,7 +32,6 @@ def frame-to-turn [frame: record] {
       [
         {
           type: "document"
-          cache_control: {type: "ephemeral"}
           source: {
             type: "base64"
             media_type: $meta.content_type
@@ -43,24 +42,20 @@ def frame-to-turn [frame: record] {
     } else if (($meta | get content_type?) == "application/json") {
       $content_raw | from json
     } else {
-    [
-    (
+      [
         {type: "text" text: $content_raw}
-          | if $cache {
-          insert cache_control {type: "ephemeral"}
-        } else { $in }
-      )
-    ]
-  }
+      ]
+    }
   )
 
   {
     id: $frame.id
     role: $role
     content: $content
     options: $options_delta
-    cache: $cache
-  }
+  } | if $cache {
+    insert cache $cache
+  } else { $in }
 }
 
 # Follow the continues chain to produce a list of turns in chronological order

gpt/mod.nu

@@ -23,7 +23,7 @@ export use ./prep.nu
 export def document [
   path: string # Path to the document file
   --name (-n): string # Optional name for the document (defaults to filename)
-  --cache: string = "ephemeral" # Cache control: "ephemeral" or "none"
+  --cache # Enable caching for this document
   --bookmark (-b): string # Bookmark this document registration
 ] {
   # Validate file exists
@@ -76,7 +76,8 @@ export def document [
     document_name: $document_name
     original_path: ($path | path expand)
     file_size: $file_size
-    cache_control: (if $cache == "ephemeral" { "ephemeral" } else { null })
+  } | conditional-pipe $cache {
+    insert cache true
   } | conditional-pipe ($bookmark | is-not-empty) {
     insert head $bookmark
   }
@@ -95,7 +96,7 @@ export def main [
   --provider-ptr (-p): string # a short alias for provider to going-forward
   --json (-j) # Treat input as JSON formatted content
   --separator: string = "\n\n---\n\n" # Separator used when joining lists of strings
-  --cache # Enable ephemeral caching for this turn
+  --cache # Enable caching for this turn
 ] {
   let content = if $in == null {
     input "Enter prompt: "

gpt/providers/anthropic/mod.nu

@@ -52,77 +52,71 @@ export def provider [] {
 
     prepare-request: {|ctx: record tools?: list<record>|
       # anthropic only supports a single system message as a top level attribute
-      let messages = $ctx.messages | select role content
+      let messages = $ctx.messages
       let system_messages = $messages | where role == "system"
       let messages = $messages | where role != "system"
 
+      # Apply cache control limits at message level FIRST (max 4 breakpoints)
+      # Use reverse approach: reverse -> keep first 4 cache messages -> reverse back
+      let cache_count = $messages | where {|msg| $msg.cache? == true } | length
+
+      let messages = if $cache_count > 4 {
+        $messages
+        | reverse
+        | generate {|msg state = {cache_kept: 0}|
+          if ($msg.cache? == true) and ($state.cache_kept < 4) {
+            {out: $msg next: {cache_kept: ($state.cache_kept + 1)}}
+          } else {
+            {out: ($msg | reject -i cache) next: $state}
+          }
+        }
+        | reverse
+      } else {
+        $messages
+      }
+
+      # THEN process content and apply cache to content blocks
       let messages = $messages | each {|msg|
-        update content {|content|
-          each {|part|
-            match $part.type {
-              "tool_result" => ($part | reject -i name)
-              "document" => {
-                # Convert based on media type
-                let media_type = $part.source.media_type
-                if ($media_type | str starts-with "text/") or ($media_type == "application/json") {
-                  # Decode base64 and convert to text block
-                  let decoded_content = $part.source.data | decode base64 | decode utf-8
-                  {
-                    type: "text"
-                    text: $decoded_content
-                  } | if ($part.cache_control? != null) {
-                    insert cache_control $part.cache_control
-                  } else { $in }
-                } else if ($media_type | str starts-with "image/") {
-                  # Convert images to use type: "image" as per Anthropic API
-                  {
-                    type: "image"
-                    source: $part.source
-                  } | if ($part.cache_control? != null) {
-                    insert cache_control $part.cache_control
-                  } else { $in }
-                } else {
-                  # Keep other binary documents as-is (PDFs, etc.)
-                  $part
+        let has_cache = ($msg.cache? == true)
+        let content = $msg.content | enumerate | each {|item|
+          let part = $item.item
+          let is_last = ($item.index == (($msg.content | length) - 1))
+
+          let converted_part = match $part.type {
+            "tool_result" => ($part | reject -i name)
+            "document" => {
+              # Convert based on media type
+              let media_type = $part.source.media_type
+              if ($media_type | str starts-with "text/") or ($media_type == "application/json") {
+                # Decode base64 and convert to text block
+                let decoded_content = $part.source.data | decode base64 | decode utf-8
+                {
+                  type: "text"
+                  text: $decoded_content
+                }
+              } else if ($media_type | str starts-with "image/") {
+                # Convert images to use type: "image" as per Anthropic API
+                {
+                  type: "image"
+                  source: $part.source
                 }
+              } else {
+                # Keep other binary documents as-is (PDFs, etc.)
+                $part
               }
-              _ => $part
             }
+            _ => $part
           }
-        }
-      }
-
-      # Apply cache control limits across all content blocks (max 4 breakpoints)
-      let all_content = $messages | get content | flatten
-      let cache_indices = $all_content | enumerate | where {|item| $item.item.cache_control? != null } | get index
-      let cache_count = $cache_indices | length
-
-      let messages = if $cache_count > 4 {
-        let remove_count = $cache_count - 4
-        let remove_indices = $cache_indices | first $remove_count
 
-        let limited_content = $all_content | enumerate | each {|item|
-          if $item.index in $remove_indices {
-            $item.item | reject cache_control
+          # Add cache_control to the last content block if message has cache
+          if $has_cache and $is_last {
+            $converted_part | insert cache_control {type: "ephemeral"}
           } else {
-            $item.item
+            $converted_part
           }
         }
 
-        # Rebuild messages with limited cache control
-        let result = $messages | reduce --fold {messages: [] index: 0} {|msg acc|
-          let msg_content_count = $msg.content | length
-          let new_content = $limited_content | skip $acc.index | first $msg_content_count
-          let new_msg = $msg | update content $new_content
-          {
-            messages: ($acc.messages | append $new_msg)
-            index: ($acc.index + $msg_content_count)
-          }
-        }
-
-        $result.messages
-      } else {
-        $messages
+        $msg | update content $content | reject -i cache
       }
 
       let data = {