feat: Add OpenRouter prompt caching support with usage tracking

Backend (api.rs):
- Add usage: {include: true} to OpenRouter requests (streaming and non-streaming)
- Extract and log cached_tokens from prompt_tokens_details
- Log cache hit ratio when tokens are cached

SDK (llm.py):
- Add cached_tokens, prompt_tokens, completion_tokens fields to LLMResponse
- Extract cached_tokens from usage.prompt_tokens_details
- Log cache hit percentage when available

This enables proper cost tracking with Anthropic prompt caching via OpenRouter.
The cost returned by OpenRouter already includes the cache discount.

Author: echobt

sdk/python/term_sdk/llm.py

@@ -103,14 +103,31 @@ def __str__(self) -> str:
 
 @dataclass
 class LLMResponse:
-    """Response from LLM."""
+    """Response from LLM.
+    
+    Attributes:
+        text: The response text content
+        model: The model used
+        tokens: Total tokens used
+        cost: Cost in USD (after cache discount if applicable)
+        latency_ms: Response latency in milliseconds
+        function_calls: List of function/tool calls
+        raw: Raw response data
+        cached_tokens: Number of tokens read from cache (reduces cost)
+        prompt_tokens: Number of input/prompt tokens
+        completion_tokens: Number of output/completion tokens
+    """
     text: str
     model: str
     tokens: int = 0
     cost: float = 0.0
     latency_ms: int = 0
     function_calls: List[FunctionCall] = field(default_factory=list)
     raw: Optional[Dict[str, Any]] = None
+    # Cache info (OpenRouter with usage: {include: true})
+    cached_tokens: int = 0
+    prompt_tokens: int = 0
+    completion_tokens: int = 0
 
     def json(self) -> Optional[Dict]:
         """Parse response text as JSON."""
@@ -1939,15 +1956,24 @@ def _parse_platform_response(self, data: Dict, model: str, start: float) -> LLMR
         completion_tokens = usage.get("completion_tokens", 0)
         total_tokens = usage.get("total_tokens", prompt_tokens + completion_tokens)
 
-        cost = data.get("cost_usd", 0.0)
+        # Extract cached tokens from prompt_tokens_details (OpenRouter with usage: {include: true})
+        prompt_details = usage.get("prompt_tokens_details", {}) or {}
+        cached_tokens = prompt_details.get("cached_tokens", 0) or 0
+        
+        cost = data.get("cost_usd", 0.0) or 0.0
         latency_ms = int((time.time() - start) * 1000)
 
         self.total_tokens += total_tokens
         self.total_cost += cost
         self.request_count += 1
         self._update_model_stats(response_model, total_tokens, cost)
 
-        _log(f"[platform] {response_model}: {total_tokens} tokens, ${cost:.4f}, {latency_ms}ms")
+        # Log with cache info if available
+        if cached_tokens > 0:
+            cache_pct = (cached_tokens / prompt_tokens * 100) if prompt_tokens > 0 else 0
+            _log(f"[platform] {response_model}: {total_tokens} tokens ({cached_tokens} cached, {cache_pct:.0f}%), ${cost:.4f}, {latency_ms}ms")
+        else:
+            _log(f"[platform] {response_model}: {total_tokens} tokens, ${cost:.4f}, {latency_ms}ms")
 
         # Parse function calls / tool calls if present in platform response
         function_calls = []
@@ -2010,6 +2036,9 @@ def _parse_platform_response(self, data: Dict, model: str, start: float) -> LLMR
             latency_ms=latency_ms,
             function_calls=function_calls,
             raw=data,
+            cached_tokens=cached_tokens,
+            prompt_tokens=prompt_tokens,
+            completion_tokens=completion_tokens,
         )
 
     def _parse_response(self, data: Dict, model: str, start: float) -> LLMResponse:
@@ -2038,17 +2067,26 @@ def _parse_response(self, data: Dict, model: str, start: float) -> LLMResponse:
         completion_tokens = usage.get("completion_tokens", 0)
         total_tokens = prompt_tokens + completion_tokens
 
+        # Extract cached tokens from prompt_tokens_details (OpenRouter with usage: {include: true})
+        prompt_details = usage.get("prompt_tokens_details", {}) or {}
+        cached_tokens = prompt_details.get("cached_tokens", 0) or 0
+        
         # Use provider-reported cost if available (OpenRouter returns usage.cost)
         # OpenAI doesn't return cost, so default to 0
-        cost = usage.get("cost", 0.0)
+        cost = usage.get("cost", 0.0) or 0.0
         latency_ms = int((time.time() - start) * 1000)
 
         self.total_tokens += total_tokens
         self.total_cost += cost
         self.request_count += 1
         self._update_model_stats(model, total_tokens, cost)
 
-        _log(f"{model}: {total_tokens} tokens, ${cost:.4f}, {latency_ms}ms")
+        # Log with cache info if available
+        if cached_tokens > 0:
+            cache_pct = (cached_tokens / prompt_tokens * 100) if prompt_tokens > 0 else 0
+            _log(f"{model}: {total_tokens} tokens ({cached_tokens} cached, {cache_pct:.0f}%), ${cost:.4f}, {latency_ms}ms")
+        else:
+            _log(f"{model}: {total_tokens} tokens, ${cost:.4f}, {latency_ms}ms")
 
         return LLMResponse(
             text=text,
@@ -2058,6 +2096,9 @@ def _parse_response(self, data: Dict, model: str, start: float) -> LLMResponse:
             latency_ms=latency_ms,
             function_calls=function_calls,
             raw=data,
+            cached_tokens=cached_tokens,
+            prompt_tokens=prompt_tokens,
+            completion_tokens=completion_tokens,
         )
 
     def _update_model_stats(self, model: str, tokens: int, cost: float):

src/api.rs

@@ -3892,6 +3892,15 @@ async fn make_llm_request(
         }
     }
 
+    // For OpenRouter: add usage: {include: true} to get cost and cache info in response
+    // This enables prompt_tokens_details.cached_tokens and usage.cost fields
+    // See: https://openrouter.ai/docs/guides/guides/usage-accounting
+    if provider == "openrouter" {
+        if let Some(base) = body.as_object_mut() {
+            base.insert("usage".to_string(), serde_json::json!({"include": true}));
+        }
+    }
+
     // Transform request for Anthropic Messages API format
     // Only for direct Anthropic API - OpenRouter handles the transformation itself
     // OpenRouter uses OpenAI-compatible format (messages array with system role)
@@ -4016,6 +4025,24 @@ async fn make_llm_request(
     // If provider doesn't report cost, it will be None (SDK will use 0)
     let cost_usd = provider_cost;
 
+    // Log cache information if available (OpenRouter with usage: {include: true})
+    // cached_tokens = tokens read from cache (reduces cost)
+    let cached_tokens = json["usage"]["prompt_tokens_details"]["cached_tokens"]
+        .as_u64()
+        .unwrap_or(0);
+    if cached_tokens > 0 {
+        let prompt_tokens = json["usage"]["prompt_tokens"].as_u64().unwrap_or(0);
+        let cache_hit_ratio = if prompt_tokens > 0 {
+            (cached_tokens as f64 / prompt_tokens as f64) * 100.0
+        } else {
+            0.0
+        };
+        info!(
+            "LLM cache hit: {} cached of {} prompt tokens ({:.1}% hit rate)",
+            cached_tokens, prompt_tokens, cache_hit_ratio
+        );
+    }
+
     // Extract tool_calls if present (OpenAI/OpenRouter format)
     let tool_calls = json["choices"][0]["message"]["tool_calls"]
         .as_array()
@@ -4372,6 +4399,15 @@ async fn make_llm_stream_request(
         }
     }
 
+    // For OpenRouter: add usage: {include: true} to get cost and cache info in final SSE chunk
+    // This enables prompt_tokens_details.cached_tokens and usage.cost fields
+    // See: https://openrouter.ai/docs/guides/guides/usage-accounting
+    if provider == "openrouter" {
+        if let Some(base) = body.as_object_mut() {
+            base.insert("usage".to_string(), serde_json::json!({"include": true}));
+        }
+    }
+
     // Transform request for Anthropic Messages API format
     // (system messages must be top-level `system` param, not in messages array)
     // Skip if using Responses API