feat: expose cumulative token usage per ExecuteTools run

[localai-bot]

Summary

Adds a way to read the cumulative token usage of a whole ExecuteTools run (and therefore of each spawned sub-agent), where previously only the last LLM call's usage was retained on Status.LastUsage.

• New Status.CumulativeUsage LLMUsage field, summed across every LLM call in a run.
• A small counting LLM decorator (newCountingLLM) that accumulates usage from both CreateChatCompletion and Ask. It preserves StreamingLLM so wrapping never disables the streaming code path.
• ExecuteTools wraps its llm once (after the sub-agent fallback agentLLM is captured, so a sub-agent's tokens are not folded into the parent) and stamps the total onto the returned fragment via a deferred named return — covering all exit paths.

Because each sub-agent runs its own ExecuteTools and runAgent assigns that fragment to AgentState.Fragment before firing the completion callback, AgentState.Fragment.Status.CumulativeUsage is populated per sub-agent for embedders to report.

Known limitation

The bundled stream clients don't yet populate StreamEvent.Usage on the done event, so streaming-path tokens read as zero until they request usage from the API (e.g. StreamOptions{IncludeUsage: true}). The non-streaming path is fully counted. This is documented in usage_counter.go.

Test Plan

• usage_counter_internal_test.go: decorator sums both Ask + CreateChatCompletion; newCountingLLM yields a StreamingLLM iff the inner LLM is one.
• tools_cumulative_test.go: a multi-call ExecuteTools run reports CumulativeUsage equal to the summed dispensed usage and greater than LastUsage.
• Streaming regression (TestAskWithStreaming*) passes — the wrap preserves streaming.
• Full non-e2e suite green. (One pre-existing background-spawn mock race is unrelated and present at the base commit.)

🤖 Generated with Claude Code