feat(agent): add getUsage() aggregate usage accessor to ModelResult

[LukasParke]

Closes #10

The gap

Reported against getItemsStream() with a multi-round tool-calling run: "I only get the last generation with stop. I don't get the generations with tool_calls."

Two things compound:

• getResponse() returns only the final round. finalResponse is the last response the loop materialized, so response.usage accounts for the closing stop generation alone. Every intermediate tool_calls generation's tokens are unreachable through it.
• getItemsStream() carries output items only. It yields message / function_call / reasoning / function_call_output items and never surfaces the response.completed events that hold each round's usage block. So a caller who consumes items and then calls getResponse() gets the final round twice over, and nothing else.

Net effect: no pull-based way to answer "what did this run cost?"

What already existed

• PostModelCall hook — fires once per completed model response with turnType / turnNumber / usage. Correct per-call granularity, but push-based: you must register a hook before the run.
• SessionEnd.totalUsage — the aggregate, already computed and already the right shape (SessionUsageTotals). Also push-based, and only emitted at teardown.
• getFullResponsesStream() — does surface each round's response.completed, so per-round usage is technically reachable, but only by consuming the raw event stream instead of the items stream.
• allToolExecutionRounds — retains each round's full response.

The aggregate the issue wants was therefore already being computed on every run and simply had no public reader.

What this adds

ModelResult.getUsage(): Promise<SessionUsageTotals> — reuses the existing hook type/schema rather than inventing a shape, so getUsage() and SessionEnd.totalUsage are the same numbers by construction (both read one new private snapshotSessionUsage() helper).

const result = callModel(client, { model, input, tools });

for await (const item of result.getItemsStream()) {
  render(item);
}

const usage = await result.getUsage();
console.log(usage.modelCalls, usage.totalTokens, usage.cost);

Covers the initial request, each tool-round follow-up, the empty-final retry, the allowFinalResponse final turn, and approval-resume requests.

Two supporting fixes

The aggregate was previously only correct when hooks were configured — accumulation ran as a side effect of hook emission:

• emitPostModelCall now folds usage in before the hooksManager short-circuit; only the emit stays gated.
• finishHooksSessionForStream now materializes the parked model-call telemetry before its hooksManager guard. This is the only site that folds the no-tools streaming response into the aggregate, so without this a hook-less getItemsStream() / getTextStream() run reported modelCalls: 0.

Neither changes hook-facing behavior (a test asserts getUsage() equals the SessionEnd.totalUsage payload); all 651 existing agent tests pass unchanged.

Judgment calls

• Awaits completion, like getResponse(). Gates on initStreamGuarded() + executeToolsIfNeeded(), mirroring getDoomLoopVerdict(). So the totals are final whether you await it directly, after getResponse(), or after draining any streaming getter.
• Never rejects. A failed run still consumed tokens, and cost accounting typically runs in a finally/catch where a second throw would mask the run's original error. A failed/paused run returns totals accrued so far; modelCalls: 0 with zeroed tokens when nothing completed. Await the run itself if you need to observe the failure.
• cost stays optional, matching the hook payload — a summed 0 from cost-less responses would read as "free" rather than "unknown".
• No per-round accessor (getRounds()) in this PR. It does not drop out cleanly: both allToolExecutionRounds.push sites store the response that produced the tool calls, so the closing stop round and the final / retry turns are never in that array. An accessor over it would silently under-report exactly the rounds the issue is about. Per-round usage is already reachable via the PostModelCall hook or getFullResponsesStream()'s response.completed; a dedicated accessor would want its own per-call ledger and is better as a follow-up.

Testing

Written red-first — all 8 failed with result.getUsage is not a function before implementation, then green. packages/agent/tests/unit/get-usage.test.ts covers the multi-round sum (asserting the same run's getResponse() still reports only 300 of 450 tokens), the streaming path via a fully-consumed getItemsStream() (both tool-loop and no-tools), the no-hooks path, agreement with SessionEnd.totalUsage, usage-less responses, and a failed run.

Build, typecheck, lint, and the full suite (754 tests) all green. Changeset included (minor — new public API).

🤖 Generated with Claude Code

[cortex-github-agent]

cortex review — 48404c4

✅ Security · 💬 Experience (DX · UX · A11y) (3) · ✅ Performance (1)

Experience (DX · UX · A11y)

🟡 minor · packages/agent/src/lib/model-result.ts:4938-4950
getUsage() swallows the run failure with no diagnostic at all. A caller whose only interaction with the run is await result.getUsage() (a plausible pattern for a cost-accounting sidecar, and exercised by the test "awaits run completion when called without awaiting getResponse() first") gets { modelCalls: 0, totalTokens: 0 } on a totally failed run and has no way — no thrown error, no flag, not even a console.warn — to distinguish "the API was down" from "the run was genuinely free". Every other never-throw path in this file logs its swallowed cause (finishHooksSessionForStream → console.warn('[SessionEnd] error during stream teardown:', …), sealDoomLoopStop/doom-loop fallbacks). Suggest a console.warn('[getUsage] run failed; reporting partial totals:', error) in the catch so the 2am debugging session has a thread to pull, rather than an empty catch {}.

🟡 minor · packages/agent/src/lib/model-result.ts:4920-4936
JSDoc promises totals are "final" while the resume path deliberately does not drive the loop. The doc says "Gates on run completion the same way getResponse() does, so totals are final whether you await it directly…", but the implementation skips executeToolsIfNeeded() when isResumingFromApproval (model-result.ts:4949-4952), unlike getResponse(), which always awaits it. The PR's own test ("does not advance an approval-resumed run when read before the loop") shows the resumed run still in_progress after getUsage() resolves — so on an approval resume the returned totals can be mid-run and the caller cannot tell partial from final. Either scope the sentence (e.g. "…except on an approval-resumed run, where reading usage never advances the loop; await getResponse()/getText() first for final totals") or mirror getDoomLoopVerdict()'s narrower wording.

⚪ nit · packages/agent/README.md:71-73
The corrected "FINAL round only" caveat landed in the README but not in getResponse()'s JSDoc. The README now says // Await the full response with usage data (the FINAL round only), yet getResponse()'s own doc comment still reads "Get the complete response object including usage information … Returns the full OpenResponsesResult with usage data (inputTokens, outputTokens, cachedTokens, etc.)" — which is the exact misconception issue #10 reported, and the IDE hover is where most developers will read it. Adding one line pointing at getUsage() there (as was done for getItemsStream()) closes the loop for editor users.

Performance

🟡 minor · packages/agent/src/lib/model-result.ts:1963-1975
Hook-less streaming runs now pay an extra full pass over the retained event buffer at teardown. Moving the telemetry materialization above the if (!this.hooksManager) return; guard means every no-tools streaming run (the common, hook-free case) now calls consumeStreamForCompletion(this.reusableStream) in finishHooksSessionForStream, which creates a fresh ReusableReadableStream consumer and walks the whole buffered event array again looking for response.completed (packages/agent/src/lib/stream-transformers.ts:520-546). Each replayed event costs one async next() microtask hop (packages/agent/src/lib/reusable-stream.ts:60-120), so a token-level stream with tens of thousands of delta events adds a second O(events) pass — single-digit-to-tens of ms — inside the finally of getTextStream()/getItemsStream(), i.e. before the caller's iteration settles. Previously this was zero work without hooks. Cheap fix: capture the completion response (or just its usage block) once during the single existing pass — e.g. latch the last response.completed/response.incomplete event on ReusableReadableStream while pumping — instead of replaying the buffer to find it.

_{Automatic first-pass review · updated in place on every push}