fix(usage): preserve existing request_usage_entries on Usage.add

[adityasingh2400]

Summary

Usage.add(other) discards any pre-populated other.request_usage_entries when other also has requests == 1 and total_tokens > 0, replacing them with a freshly synthesized entry built from only the top-level fields. Nested details such as cached_tokens / reasoning_tokens carried by the existing entries are silently lost.

The two branches in add() were ordered so the synthesizer wins over an explicit per-request breakdown. The fix swaps them: if other already has an authoritative breakdown, merge it; otherwise fall back to synthesizing one from the top-level fields.

Repro (before the fix)

u1 = Usage()
u2 = Usage(
    requests=1, input_tokens=100, output_tokens=50, total_tokens=150,
    request_usage_entries=[
        RequestUsage(
            input_tokens=100, output_tokens=50, total_tokens=150,
            input_tokens_details=InputTokensDetails(cached_tokens=10),
            output_tokens_details=OutputTokensDetails(reasoning_tokens=5),
        )
    ],
)
u1.add(u2)
# u1.request_usage_entries[0].input_tokens_details.cached_tokens == 0   (was 10)
# u1.request_usage_entries[0].output_tokens_details.reasoning_tokens == 0   (was 5)

Changes

• src/agents/usage.py — reorder the add() branches so an explicit request_usage_entries list is preferred over a synthesized entry built from top-level fields.
• tests/test_usage.py — regression test (test_usage_add_preserves_existing_entries_when_top_level_also_set).

Test plan

• New regression test fails on main, passes after the fix.
• Full tests/test_usage.py passes (14/14).
• tests/test_agent_runner_streamed.py::test_streamed_run_preserves_request_usage_entries_after_retry and the conversation-locked variant still pass — these exercise the synthesize path with requests == 2, which the fix does not touch.
• ruff check clean on touched files.

[seratch]

@codex review

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. Swish!

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".