feat: add prompt caching support (Anthropic cache_control + OpenAI cached_tokens)

- Add CacheControl struct and optional cacheControl field to Message
- Add cacheCreationTokens and cacheReadTokens fields to Usage
- Anthropic: serialize system prompt as content blocks array with cache_control ephemeral
- Anthropic: add cache_control on last tool definition for prompt caching
- Anthropic: parse cache_creation_input_tokens and cache_read_input_tokens from usage (both streaming and non-streaming)
- OpenAI: add stream_options include_usage for accurate token counting in streams
- OpenAI: parse cached_tokens from prompt_tokens_details in usage
- Version bump to 0.2.3

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

Author: Sunrisepeak

src/providers/anthropic.cppm

@@ -101,6 +101,8 @@ public:
                         }
                         if (msg.contains("usage")) {
                             result.usage.inputTokens = msg["usage"].value("input_tokens", 0);
+                            result.usage.cacheCreationTokens = msg["usage"].value("cache_creation_input_tokens", 0);
+                            result.usage.cacheReadTokens = msg["usage"].value("cache_read_input_tokens", 0);
                         }
                     }
                 } else if (event.event == "content_block_start") {
@@ -324,7 +326,13 @@ private:
         auto [systemText, msgArray] = extract_system_and_messages_(messages);
 
         if (!systemText.empty()) {
-            payload["system"] = systemText;
+            Json sysBlocks = Json::array();
+            Json block;
+            block["type"] = "text";
+            block["text"] = systemText;
+            block["cache_control"] = Json{{"type", "ephemeral"}};
+            sysBlocks.push_back(block);
+            payload["system"] = sysBlocks;
         }
         payload["messages"] = msgArray;
 
@@ -348,7 +356,8 @@ private:
         // Tools — Anthropic format (no function wrapper)
         if (params.tools.has_value() && !params.tools->empty()) {
             Json tools = Json::array();
-            for (const auto& tool : *params.tools) {
+            for (std::size_t i = 0; i < params.tools->size(); ++i) {
+                const auto& tool = (*params.tools)[i];
                 Json t;
                 t["name"] = tool.name;
                 t["description"] = tool.description;
@@ -357,6 +366,10 @@ private:
                 } else {
                     t["input_schema"] = Json{{"type", "object"}};
                 }
+                // Add cache_control on last tool
+                if (i == params.tools->size() - 1) {
+                    t["cache_control"] = Json{{"type", "ephemeral"}};
+                }
                 tools.push_back(t);
             }
             payload["tools"] = tools;
@@ -428,6 +441,8 @@ private:
             result.usage.inputTokens = usage.value("input_tokens", 0);
             result.usage.outputTokens = usage.value("output_tokens", 0);
             result.usage.totalTokens = result.usage.inputTokens + result.usage.outputTokens;
+            result.usage.cacheCreationTokens = usage.value("cache_creation_input_tokens", 0);
+            result.usage.cacheReadTokens = usage.value("cache_read_input_tokens", 0);
         }
 
         return result;

src/providers/openai.cppm

@@ -133,6 +133,9 @@ public:
                     result.usage.inputTokens = usage.value("prompt_tokens", 0);
                     result.usage.outputTokens = usage.value("completion_tokens", 0);
                     result.usage.totalTokens = result.usage.inputTokens + result.usage.outputTokens;
+                    if (usage.contains("prompt_tokens_details") && usage["prompt_tokens_details"].is_object()) {
+                        result.usage.cacheReadTokens = usage["prompt_tokens_details"].value("cached_tokens", 0);
+                    }
                 }
             } catch (const Json::exception&) {
                 // Skip malformed chunks
@@ -303,6 +306,7 @@ private:
 
         if (stream) {
             payload["stream"] = true;
+            payload["stream_options"] = Json{{"include_usage", true}};
         }
 
         if (params.temperature.has_value()) {
@@ -425,6 +429,9 @@ private:
             result.usage.inputTokens = usage.value("prompt_tokens", 0);
             result.usage.outputTokens = usage.value("completion_tokens", 0);
             result.usage.totalTokens = result.usage.inputTokens + result.usage.outputTokens;
+            if (usage.contains("prompt_tokens_details") && usage["prompt_tokens_details"].is_object()) {
+                result.usage.cacheReadTokens = usage["prompt_tokens_details"].value("cached_tokens", 0);
+            }
         }
 
         return result;

src/types.cppm

@@ -40,11 +40,16 @@ export using ContentPart =
     std::variant<TextContent, ImageContent, AudioContent, ToolUseContent, ToolResultContent>;
 export using Content = std::variant<std::string, std::vector<ContentPart>>;
 
+export struct CacheControl {
+    std::string type {"ephemeral"};
+};
+
 // Message
 export struct Message {
     Role role;
     Content content;
     std::string name;
+    std::optional<CacheControl> cacheControl;
 
     static Message system(std::string_view text) {
         return Message{.role = Role::System, .content = std::string{text}};
@@ -111,6 +116,8 @@ export struct Usage {
     int inputTokens{0};
     int outputTokens{0};
     int totalTokens{0};
+    int cacheCreationTokens{0};
+    int cacheReadTokens{0};
 };
 
 // Chat response
@@ -251,6 +258,9 @@ inline Json messageToJson(const Message& msg) {
             j["content"] = arr;
         }
     }, msg.content);
+    if (msg.cacheControl) {
+        j["cache_control"] = Json{{"type", msg.cacheControl->type}};
+    }
     return j;
 }
 
@@ -267,6 +277,9 @@ inline Message messageFromJson(const Json& j) {
         }
         msg.content = std::move(parts);
     }
+    if (j.contains("cache_control") && j["cache_control"].is_object()) {
+        msg.cacheControl = CacheControl{.type = j["cache_control"].value("type", "ephemeral")};
+    }
     return msg;
 }
 
@@ -277,7 +290,7 @@ void Conversation::save(std::string_view filePath) const {
         j["messages"].push_back(messageToJson(msg));
     }
     std::ofstream out{std::string{filePath}};
-    out << j.dump(2);
+    out << j.dump(2, ' ', false, Json::error_handler_t::replace);
 }
 
 Conversation Conversation::load(std::string_view filePath) {

xmake.lua

@@ -1,5 +1,5 @@
 set_languages("c++23")
-set_version("0.2.0")
+set_version("0.2.3")
 set_policy("build.c++.modules", true)
 
 add_repositories("mcpplibs-index https://github.com/mcpplibs/mcpplibs-index.git")