feat(schema): track LLM cache-creation (write) tokens in PromptTokenDetails

[marwan38]

Is your feature request related to a problem? Please describe.

schema.PromptTokenDetails models only CachedTokens (cache read). There's no field for cache write (creation) tokens. Multiple providers bill cache writes at a premium and report a distinct count - Anthropic cache_creation_input_tokens (1.25x/2x), OpenAI cache_write_tokens (newer manual-cache models, 1.25x), AWS Bedrock cacheWriteInputTokens - but eino has nowhere to put it, so bindings fold it into PromptTokens. The total is preserved, but the distinct write count isn't surfaced:

promptTokens := int(usage.InputTokens + usage.CacheReadInputTokens + usage.CacheCreationInputTokens)
PromptTokenDetails{ CachedTokens: int(usage.CacheReadInputTokens) } // write count not surfaced

Result: write tokens are counted, but unattributable - they land in the input bucket and get priced at 1x instead of the provider's write rate, so cost tracking under-reports the write premium and can't break out write volume.

Describe the solution you'd like

type PromptTokenDetails struct {
    CachedTokens        int `json:"cached_tokens"`          // cache read
    CacheCreationTokens int `json:"cache_creation_tokens"`  // cache write
}

Describe alternatives you've considered

• Compute downstream - impossible; the write count is already summed into PromptTokens at the binding and can't be separated back out.
• Carry via ResponseMeta.Extra - works but unshaped and per-consumer; a typed field is the right home.

Additional context

Every other provider-agnostic framework already models write separately and provider-neutrally: LangChain / LangChain.js (input_token_details.cache_creation), Vercel AI SDK (inputTokens.cacheWrite), LlamaIndex (cache_creation_input_tokens). Gemini is the one provider with no per-request write count (write billed in a separate caches.create call) — a neutral field simply stays zero there.

[March-77]

Hi, I would like to work on this. I plan to add the provider-neutral CacheCreationTokens field to both schema.PromptTokenDetails and the model callback token-details DTO, preserve it through the existing streaming usage merge paths, and add regression coverage for JSON serialization and both message concatenation flows.

[ArielFishLich]

We ran into what looks like a similar issue in our own environment — our Langfuse traces for Claude agents don't seem to reflect cache-write cost, and digging into it led me here. A provider-neutral CacheCreationTokens on PromptTokenDetails (and the model callback DTO in #1158) seems like a sensible foundation for fixing it.

I had a question about scope. If I'm reading it right, the schema field on its own wouldn't yet surface cache-write to an observability backend, since something still has to read it and map it out. I was mostly looking at the Langfuse path, where the flow seems to be roughly:

provider usage (e.g. Anthropic cache_creation_input_tokens)
  → model adapter        → schema.PromptTokenDetails.CacheCreationTokens   ← #1158 adds the field
  → callback adapters    → each observability backend's usage payload      ← doesn't seem wired yet

A couple of things I think are true (please correct me if I've misread):

Producer side (eino-ext). The Claude adapter currently seems to expose cache-creation only via message.Extra (eino-ext#929). If so, it might also need to populate the new schema.PromptTokenDetails.CacheCreationTokens from resp.Usage.CacheCreationInputTokens once #1158 lands, alongside the existing CachedTokens (read).

Consumer side (eino-ext callbacks/*). From a quick look, the observability adapters each map token usage independently, and I didn't spot any of them forwarding cache-write yet. Rough state as I understood it (I may well have missed something):

Adapter	Maps usage in	cache-read today	cache-write today
callbacks/langfuse	utils.go (mapUsageDetail)	CachedTokens	—
callbacks/cozeloop	data_parser.go	InputCachedTokens	—
callbacks/langsmith	langsmith.go	(input/output/total only)	—
callbacks/apmplus	apmplus.go (OTel histogram)	—	—

If that's accurate, even the two that handle cache-read would drop cache-write until their mappers (and, for Langfuse, the libs/acl/langfuse PromptTokensDetails struct) pick up the field. The reason I care about it is cost accuracy — as you mention, providers bill cache writes at a premium (Anthropic 1.25×/2×), so folding them into PromptTokens seems to under-price them and hide the write volume.

So mostly I wanted to ask: is that downstream wiring — the model-adapter population and the callbacks/* mappers — something you'd see as part of #1150 / #1158, or would it make more sense as separate follow-ups in eino-ext after the schema field merges? I don't have a strong opinion on where it belongs.