Add cacheRetention provider config for 1-hour Anthropic prompt cache TTL

Add configurable prompt cache retention for the Anthropic provider.
Set `"cacheRetention": "long"` on the provider config to use 1-hour TTL
instead of the default 5-minute TTL. Only applies when hitting the
direct Anthropic API (not proxies).

Ref: #396

🤖 Generated with [eca](https://eca.dev)

Co-Authored-By: eca <git@eca.dev>

Author: ericdallo

CHANGELOG.md

@@ -2,6 +2,8 @@
 
 ## Unreleased
 
+- Add `cacheRetention` provider config for Anthropic to support 1-hour prompt cache TTL. Set to `"long"` for sessions with pauses longer than 5 minutes.
+
 ## 0.124.0
 
 - Add `chatRetentionDays` config to control chat and cache cleanup retention period, default changed from 7 to 14 days. Set to 0 to disable cleanup. #393

docs/config.json

@@ -559,6 +559,13 @@
           "additionalProperties": {
             "$ref": "#/definitions/model"
           }
+        },
+        "cacheRetention": {
+          "type": "string",
+          "description": "Prompt cache retention for Anthropic. 'short' uses 5-min TTL (default), 'long' uses 1-hour TTL at higher write cost. Only applies when hitting the direct Anthropic API.",
+          "markdownDescription": "Prompt cache retention for Anthropic. `short` uses 5-min TTL (default), `long` uses 1-hour TTL at higher write cost. Only applies when hitting the direct Anthropic API.",
+          "enum": ["short", "long"],
+          "default": "short"
         }
       },
       "additionalProperties": false

docs/config/models.md

@@ -84,6 +84,7 @@ Schema:
 | `models <model> extraHeaders`     | map     | Extra headers sent to LLM request                                                                            | No       |
 | `models <model> modelName`        | string  | Override model name, useful to have multiple models with different configs and names that use same LLM model | No       |
 | `models <model> reasoningHistory` | string  | Controls reasoning in conversation history: `"all"` (default), `"turn"`, or `"off"`                          | No       |
+| `cacheRetention`                  | string  | Prompt cache retention for Anthropic: `"short"` (5-min, default) or `"long"` (1-hour, higher write cost). Only applies to direct Anthropic API. | No       |
 | `fetchModels`                     | boolean | Enable/disable automatic model loading from `models.dev` (enabled by default when `api` is set)              | No       |
 
 _* url and key will be searched as envs `<provider>_API_URL` and `<provider>_API_KEY`, they require the env to be found or config to work._
@@ -279,7 +280,19 @@ When a retry rule matches, the chat shows a progress message like:
     5. Paste and send the code and done!
 
     Warning: Using your Claude Pro/Max subscription in ECA is not officially supported by [Anthropic](https://anthropic.com) and ECA are not responsible for any actions on your account.
-    
+
+    **Cache retention:** By default, Anthropic prompt cache uses a 5-minute TTL. If your sessions have frequent pauses longer than 5 minutes, you can set `"cacheRetention": "long"` on the provider config to use a 1-hour TTL. This costs 2× base input price for cache writes (vs 1.25× for 5-min) but avoids full re-write costs after pauses. Only applies when using the direct Anthropic API (not proxies).
+
+    ```javascript title="~/.config/eca/config.json"
+    {
+      "providers": {
+        "anthropic": {
+          "cacheRetention": "long"
+        }
+      }
+    }
+    ```
+
 === "Azure OpenAI"
 
     1. Login via the chat command `/login`.

src/eca/llm_api.clj

@@ -237,6 +237,7 @@
           :api-key api-key
           :auth-type auth-type
           :cancelled? cancelled?
+          :cache-retention (:cacheRetention provider-config)
           :stream-idle-timeout-seconds (:streamIdleTimeoutSeconds config)}
          callbacks)
 

src/eca/llm_providers/anthropic.clj

@@ -68,14 +68,24 @@
                       :name "web_search"
                       :max_uses 10})))
 
+(defn ^:private cache-control-value
+  "Returns the cache_control map based on cache retention config and API URL.
+   Only applies 1-hour TTL when hitting the direct Anthropic API."
+  [api-url cache-retention]
+  (if (and (= "long" cache-retention)
+           (or (nil? api-url)
+               (string/includes? api-url "api.anthropic.com")))
+    {:type "ephemeral" :ttl "1h"}
+    {:type "ephemeral"}))
+
 (defn ^:private add-cache-to-last-tool
   "Adds cache_control to the last tool in the tools array, ensuring
    the full tools list is part of the cached prefix."
-  [tools]
+  [tools cache-control]
   (if (seq tools)
     (shared/update-last
      (vec tools)
-     (fn [tool] (assoc tool :cache_control {:type "ephemeral"})))
+     (fn [tool] (assoc tool :cache_control cache-control)))
     tools))
 
 (defn ^:private base-request! [{:keys [rid body api-url api-key auth-type url-relative-path content-block* on-error on-stream http-client extra-headers cancelled? stream-idle-timeout-seconds]}]
@@ -288,7 +298,7 @@
    []
    messages))
 
-(defn ^:private add-cache-to-last-message [messages]
+(defn ^:private add-cache-to-last-message [messages cache-control]
   ;; TODO add cache_control to last non thinking message
   (shared/update-last
    (vec messages)
@@ -297,35 +307,36 @@
        (if (string? content)
          (assoc-in message [:content] [{:type :text
                                         :text content
-                                        :cache_control {:type "ephemeral"}}])
-         (assoc-in message [:content (dec (count content)) :cache_control] {:type "ephemeral"}))))))
+                                        :cache_control cache-control}])
+         (assoc-in message [:content (dec (count content)) :cache_control] cache-control))))))
 
 (defn chat!
   [{:keys [model user-messages instructions max-output-tokens
            api-url api-key auth-type url-relative-path reason? past-messages
            tools web-search extra-payload extra-headers supports-image? http-client cancelled?
-           stream-idle-timeout-seconds]}
+           stream-idle-timeout-seconds cache-retention]}
    {:keys [on-message-received on-error on-reason on-prepare-tool-call on-tools-called on-usage-updated on-server-web-search] :as callbacks}]
   (let [messages (-> (concat past-messages (fix-non-thinking-assistant-messages user-messages))
                      group-parallel-tool-calls
                      (normalize-messages supports-image?)
                      merge-adjacent-assistants
                      merge-adjacent-tool-results)
         stream? (boolean callbacks)
+        cache-control (cache-control-value api-url cache-retention)
         {:keys [static dynamic]} (if (map? instructions)
                                     instructions
                                     {:static instructions :dynamic nil})
         system-blocks (cond-> [{:type "text" :text "You are Claude Code, Anthropic's official CLI for Claude."}
-                               {:type "text" :text static :cache_control {:type "ephemeral"}}]
+                               {:type "text" :text static :cache_control cache-control}]
                         (not (string/blank? dynamic))
-                        (conj {:type "text" :text dynamic :cache_control {:type "ephemeral"}}))
+                        (conj {:type "text" :text dynamic :cache_control cache-control}))
         body (merge
               (assoc-some
                {:model model
-                :messages (add-cache-to-last-message messages)
+                :messages (add-cache-to-last-message messages cache-control)
                 :max_tokens (or max-output-tokens 32000)
                 :stream stream?
-                :tools (add-cache-to-last-tool (->tools tools web-search))
+                :tools (add-cache-to-last-tool (->tools tools web-search) cache-control)
                 :system system-blocks}
                :thinking (when reason?
                            {:type "enabled" :budget_tokens 2048}))
@@ -441,7 +452,7 @@
                                                                     (normalize-messages supports-image?)
                                                                     merge-adjacent-assistants
                                                                     merge-adjacent-tool-results
-                                                                    add-cache-to-last-message)]
+                                                                    (add-cache-to-last-message cache-control))]
                                                    (reset! content-block* {})
                                                    (base-request!
                                                     {:rid (llm-util/gen-rid)

test/eca/llm_providers/anthropic_test.clj

@@ -330,35 +330,58 @@
                        {:type "tool_result" :tool_use_id "c2" :content "content-b\n"}]}]
            result)))))
 
+(deftest cache-control-value-test
+  (let [cache-control #'llm-providers.anthropic/cache-control-value]
+    (testing "default 5-min TTL when no cache-retention set"
+      (is (= {:type "ephemeral"} (cache-control "https://api.anthropic.com" nil)))
+      (is (= {:type "ephemeral"} (cache-control nil nil))))
+    (testing "default 5-min TTL for short retention"
+      (is (= {:type "ephemeral"} (cache-control "https://api.anthropic.com" "short"))))
+    (testing "1-hour TTL for long retention on direct Anthropic API"
+      (is (= {:type "ephemeral" :ttl "1h"} (cache-control "https://api.anthropic.com" "long")))
+      (is (= {:type "ephemeral" :ttl "1h"} (cache-control "https://api.anthropic.com/v1" "long"))))
+    (testing "1-hour TTL when api-url is nil (default direct API)"
+      (is (= {:type "ephemeral" :ttl "1h"} (cache-control nil "long"))))
+    (testing "falls back to 5-min when using a proxy"
+      (is (= {:type "ephemeral"} (cache-control "https://my-proxy.example.com" "long"))))))
+
 (deftest add-cache-to-last-message-test
-  (is (match?
-       []
-       (#'llm-providers.anthropic/add-cache-to-last-message [])))
-  (testing "when message content is a vector"
-    (is (match?
-         [{:role "user" :content [{:type :text :text "Hey" :cache_control {:type "ephemeral"}}]}]
-         (#'llm-providers.anthropic/add-cache-to-last-message
-          [{:role "user" :content [{:type :text :text "Hey"}]}])))
-    (is (match?
-         [{:role "user" :content [{:type :text :text "Hey"}]}
-          {:role "user" :content [{:type :text :text "Ho" :cache_control {:type "ephemeral"}}]}]
-         (#'llm-providers.anthropic/add-cache-to-last-message
-          [{:role "user" :content [{:type :text :text "Hey"}]}
-           {:role "user" :content [{:type :text :text "Ho"}]}]))))
-  (testing "when message content is string"
-    (is (match?
-         [{:role "user" :content [{:type :text :text "Hey" :cache_control {:type "ephemeral"}}]}]
-         (#'llm-providers.anthropic/add-cache-to-last-message
-          [{:role "user" :content "Hey"}])))
+  (let [default-cache {:type "ephemeral"}]
     (is (match?
-         [{:role "user" :content "Hey"}
-          {:role "user" :content [{:type :text :text "Ho" :cache_control {:type "ephemeral"}}]}]
-         (#'llm-providers.anthropic/add-cache-to-last-message
-          [{:role "user" :content "Hey"}
-           {:role "user" :content "Ho"}])))))
+         []
+         (#'llm-providers.anthropic/add-cache-to-last-message [] default-cache)))
+    (testing "when message content is a vector"
+      (is (match?
+           [{:role "user" :content [{:type :text :text "Hey" :cache_control {:type "ephemeral"}}]}]
+           (#'llm-providers.anthropic/add-cache-to-last-message
+            [{:role "user" :content [{:type :text :text "Hey"}]}] default-cache)))
+      (is (match?
+           [{:role "user" :content [{:type :text :text "Hey"}]}
+            {:role "user" :content [{:type :text :text "Ho" :cache_control {:type "ephemeral"}}]}]
+           (#'llm-providers.anthropic/add-cache-to-last-message
+            [{:role "user" :content [{:type :text :text "Hey"}]}
+             {:role "user" :content [{:type :text :text "Ho"}]}] default-cache))))
+    (testing "when message content is string"
+      (is (match?
+           [{:role "user" :content [{:type :text :text "Hey" :cache_control {:type "ephemeral"}}]}]
+           (#'llm-providers.anthropic/add-cache-to-last-message
+            [{:role "user" :content "Hey"}] default-cache)))
+      (is (match?
+           [{:role "user" :content "Hey"}
+            {:role "user" :content [{:type :text :text "Ho" :cache_control {:type "ephemeral"}}]}]
+           (#'llm-providers.anthropic/add-cache-to-last-message
+            [{:role "user" :content "Hey"}
+             {:role "user" :content "Ho"}] default-cache))))
+    (testing "with 1-hour TTL"
+      (let [long-cache {:type "ephemeral" :ttl "1h"}]
+        (is (match?
+             [{:role "user" :content [{:type :text :text "Hey" :cache_control {:type "ephemeral" :ttl "1h"}}]}]
+             (#'llm-providers.anthropic/add-cache-to-last-message
+              [{:role "user" :content [{:type :text :text "Hey"}]}] long-cache)))))))
 
 (deftest add-cache-to-last-tool-test
-  (let [add-cache #'llm-providers.anthropic/add-cache-to-last-tool]
+  (let [default-cache {:type "ephemeral"}
+        add-cache (fn [tools] (#'llm-providers.anthropic/add-cache-to-last-tool tools default-cache))]
     (testing "empty tools returns empty"
       (is (match? [] (add-cache [])))
       (is (match? nil (add-cache nil))))