fix(session): recover cache tokens from openai-compatible metadata usage fallback

[ulises-jeremias]

Issue for this PR

Closes #30663

Type of change

• Bug fix
• New feature
• Refactor / code improvement
• Documentation

What does this PR do?

Custom baseURL providers using the openai-compatible SDK may report cache tokens through provider metadata (e.g. prompt_tokens_details.cached_tokens) rather than the standard usage.cacheReadInputTokens / usage.cacheWriteInputTokens fields. Without the metadata fallback, these providers report zero cache tokens for subagent sessions, leading to incorrect cost reporting.

The fix extends getUsage to probe provider metadata for cache read/write token counts when the standard usage fields are missing. It adds helper functions metadataNumber, metadataRecord, and metadataUsage to safely navigate deeply nested metadata structures. Existing metadata fallbacks (anthropic, vertex, bedrock, venice) are preserved.

How did you verify your code works?

• bun test test/session/llm.test.ts — 30 tests pass including 3 new tests for metadata cache token extraction
• bun typecheck — clean

Screenshots / recordings

N/A (no UI changes)

Checklist

• I have tested my changes locally
• I have not included unrelated changes in this PR

[github-actions]

The following comment was made by an LLM, it may be inaccurate:

Potential duplicate found:

• PR fix(opencode): read cache write tokens from raw usage #36752: fix(opencode): read cache write tokens from raw usage
  • fix(opencode): read cache write tokens from raw usage #36752
  • Why related: This PR directly addresses cache token recovery, specifically handling cache write tokens from raw usage. It appears to be working on the same issue space as PR fix(session): recover cache tokens from openai-compatible metadata usage fallback #36861, which extends cache token handling to include openai-compatible provider metadata fallbacks. These PRs likely overlap in scope or address related aspects of the same cache token reporting problem.

[ulises-jeremias]

Thanks for flagging. These PRs are complementary, not conflicting:

• fix(opencode): read cache write tokens from raw usage #36752 prioritizes cache_creation_input_tokens from item.raw in the AI SDK adapter layer — this covers the raw response path before metadata extraction.
• fix(session): recover cache tokens from openai-compatible metadata usage fallback #36861 falls back to providerMetadata in getUsage() when the standard usage.cache{Read,Write}InputTokens fields are missing — this covers the metadata path that persists after the adapter.

They handle different stages of the pipeline. If #36752 merges first, #36861 still adds value for the metadata path (especially cacheReadInputTokens from prompt_tokens_details.cached_tokens, which #36752 doesn't handle).