hermes - 💡(How to fix) Fix Bug: cache_read_tokens and cache_write_tokens missing from API Server SSE usage events

Bug Description

The cache_read_tokens and cache_write_tokens fields are tracked internally by the agent (stored in Session objects and SQLite state.db) but are not included in the usage object of SSE responses from the API Server. This causes downstream consumers (dashboards, WebUIs) to always report cache_read_tokens = 0 and cache_hit_rate = 0%, even when prompt caching is actively working.

Steps to Reproduce

1. Start a gateway with a provider that supports prompt caching (e.g., Anthropic Claude)
2. Send a multi-turn conversation via the Responses API (POST /v1/responses, stream: true)
3. Observe the response.completed event in the SSE stream
4. Check the usage object — it only contains input_tokens, output_tokens, total_tokens
5. cache_read_tokens and cache_write_tokens are missing

Expected Behavior

The usage object in all SSE completion events should include cache_read_tokens and cache_write_tokens, since the agent already tracks these values internally.

Actual Behavior

"usage": {
    "input_tokens": 1234,
    "output_tokens": 567,
    "total_tokens": 1801
}

cache_read_tokens and cache_write_tokens are absent.

Root Cause

In gateway/platforms/api_server.py, there are 7 locations where usage dicts are constructed for SSE events. None of them include cache token fields, even though usage.get("cache_read_tokens", 0) would return the correct value from the agent's internal tracking.

Affected locations:

• Chat completions streaming finish chunk (~line 1289)
• Chat completions non-streaming response (~line 1420)
• Responses API incomplete event (~line 1612)
• Responses API failed event (~line 1955)
• Responses API completed event (~line 1979)
• Responses API failed event (streaming, ~line 2045)
• Responses API non-streaming completed response (~line 2315)

Fix

Add cache_read_tokens and cache_write_tokens to all 7 usage dict constructions:

"usage": {
    "input_tokens": usage.get("input_tokens", 0),
    "output_tokens": usage.get("output_tokens", 0),
    "total_tokens": usage.get("total_tokens", 0),
    "cache_read_tokens": usage.get("cache_read_tokens", 0),   # ← added
    "cache_write_tokens": usage.get("cache_write_tokens", 0), # ← added
}

This is a low-risk, additive change — existing consumers that don't use these fields are unaffected.

Environment

• Hermes Agent: latest main (42c428841)
• Python: 3.11+
• Provider: Any with prompt caching support

Related

PR with fix: coming from fork darvsum/hermes-agent:fix/cache-tokens-in-sse-usage