fix: stamp provider usage at the adapter boundary and close the compact accounting gap

[Q1hangL]

Fixes #520. Split out from #1787 per the review discussion — this is the focused branch from current main; #1787 stays as the reference implementation and becomes follow-ups (see below).

Scope (the smallest coherent set for #520)

• Provider usage stamping at the adapter boundary: OpenAICompatibleLLM snapshots resp.usage once and stamps a top-level usage key on all six chat/vision return sites (inherited by DeepSeek/DashScope/OpenRouter/Azure); Zhipu/Gemini/Claude text paths return the same {type, content, usage} envelope the streaming path already emits instead of bare strings; Xinference stamps on every envelope branch. Cache metrics (cached_input_tokens, Claude's cache_write_input_tokens) ride the stamp when non-zero.
• PatternRuntime usage resolution: _resolve_usage_payload shared by _extract_token_usage and _extract_cached_tokens — top-level first, then one level under raw, fail-open on unknown shapes; strict counter coercion (_coerce_usage_int) rejects bools, non-finite, negative, and non-integral values instead of truncating or crashing.
• Compact-path freshness handling: compaction usage records carry synthetic_purpose and are excluded from the context-freshness baseline (_latest_freshness_baseline_call), so a stamped-but-failed LLM compaction can no longer suppress the truncation fallback; the field round-trips through checkpoints with a backward-compatible default.
• Direct consumer fixes required by the envelope change: shared unwrap_chat_text / classify_chat_response for the three hand-written unwrapping call sites (ContextBuilder._compact_*, optimize_instructions) so tool_call envelopes fail explicitly instead of being repr()ed into compacted context, and the ReAct finalize fallback surfaces the envelope's text rather than the envelope itself.
• Docs: BaseLLM.chat()/vision_chat() docstrings describe the envelope contract, with raw marked provider-dependent/optional.

Moved to follow-ups (preserved in #1787)

• usage_attempts / billed-retry-attempt accounting (RetryWrapper merge, OpenRouter internal retries, exception carriers, multi-attempt cache scope)
• Remaining Callers of chat() stringify tool_call envelopes, and providers disagree on whitespace-only content #1714 repr-leak cleanup beyond the directly required consumers
• Vision response normalization (_normalize_vision_response delegation) and the default stream_chat boundary/usage-chunk work

Test plan

• tests/core/agent/test_compact_llm_usage_contract.py (41 tests): per adapter family, responses built with real SDK types (e.g. ChatCompletion with populated CompletionUsage), only the SDK client patched, real adapter driven through the real compact path — asserting action_end_llm (purpose=context_compaction) token fields, get_total_token_usage(), and end-to-end cached_input_tokens; plus extractor edge shapes (string raw, top-level usage_metadata, all-zero usage), checkpoint round-trip, the truncation-suppression scenario, and a no-double-counting guard between the contextvar ledger and llm_calls.
• Local: 1707 passed, 0 failed across agent / model.chat / web suites (2 pre-existing environment failures in test_executor.py / test_browser_tools.py, red on clean main too). mypy clean on touched files; ruff check / ruff format clean.
• Key fixes mutation-verified on this branch: deleting the raw fallback turns the extractor parametrization red; dropping the synthetic-record skip turns the truncation-suppression test red.

Known boundaries

• Zhipu/Gemini contract fixtures use field-accurate stand-ins rather than real SDK types (offline construction unreliable); the Zhipu stand-in exercises the production model_dump() branch, as the real zai-sdk response is pydantic.
• BaseLLM's default stream_chat still treats any dict as a tool_call envelope — no current adapter triggers it (all override stream_chat; PatternRuntime bypasses the default); the fix lives in the follow-up.
• Callers of chat() stringify tool_call envelopes, and providers disagree on whitespace-only content #1714 problem 2 (whitespace-only content / exception-type divergence) is untouched, as is Zhipu's non-retryable blank-response error.
• Existing adapter tests asserting bare-string returns were updated to the envelope contract — intentional contract change, consumer audit in fix: stamp provider usage on chat() responses and converge text unwrapping #1787.

cc @rogercloud

[gemini-code-assist]

Code Review

This pull request introduces structural classification of LLM chat response shapes to prevent raw response envelopes (such as tool calls) from being stringified and leaked into transcripts or compacted contexts. It adds a new classification helper, stamps top-level usage payloads onto result envelopes across various adapters, and introduces a synthetic purpose marker to prevent internal compaction calls from hijacking the context-size freshness baseline. The review feedback correctly identifies opportunities to record cached input tokens in the token ledger for both the Claude and Gemini adapters.

[gemini-code-assist]

The add_token_usage call currently does not record the extracted cached input tokens (cache_read) to the global/context token ledger. Passing cached_input_tokens=int(cache_read or 0) ensures that the context-local token ledger accurately tracks prompt-cache hits for Claude, while safely coercing missing or null values to 0 to prevent exceptions in token accounting.

Suggested change

	add_token_usage(
	input_tokens=input_tokens,
	output_tokens=output_tokens,
	add_token_usage(
	input_tokens=input_tokens,
	output_tokens=output_tokens,
	cached_input_tokens=int(cache_read or 0),

References

1. For token accounting helpers, prefer fail-open behavior (coercing missing or null values to 0) rather than raising exceptions, to ensure LLM calls do not break due to accounting issues.

[Q1hangL]

Verified against the current head — this is already handled. The add_token_usage call a few lines below (claude.py:677-685) passes both cached_input_tokens=cache_read and cache_write_input_tokens=cache_write; the two values come from _anthropic_input_usage's normalization of Anthropic's usage. So the ledger does record Claude's prompt-cache hits, and this suggestion would double-pass the same field. Dropping as verified-safe.

[gemini-code-assist]

The add_token_usage call currently does not record the extracted cached input tokens (cached_tokens) to the global/context token ledger. Passing cached_input_tokens=int(cached_tokens or 0) ensures that the context-local token ledger accurately tracks prompt-cache hits for Gemini, while preferring fail-open behavior by coercing missing or null values to 0.

Suggested change

	add_token_usage(
	input_tokens=input_tokens,
	output_tokens=output_tokens,
	add_token_usage(
	input_tokens=input_tokens,
	output_tokens=output_tokens,
	cached_input_tokens=int(cached_tokens or 0),

References

1. For token accounting helpers, prefer fail-open behavior (coercing missing or null values to 0) rather than raising exceptions, to ensure LLM calls do not break due to accounting issues.

[Q1hangL]

Verified against the current head — already handled. The add_token_usage call at gemini.py:597-602 passes cached_input_tokens=cached_tokens, where cached_tokens = getattr(usage_metadata, "cached_content_token_count", 0) or 0 (gemini.py:584-586) — i.e. it already fails open to 0 for missing/None values. The stamp above additionally guards the comparison by type so an unexpected non-numeric value can never raise out of chat(). Dropping as verified-safe.