feat(utils): collect per-run token/time/step usage from SDK traces

[keli-wen]

Summary

Adds usage_scope, a small quantmind/utils/ helper that reports token, time, and LLM-step usage for one flow run by collecting the spans the Agents SDK already emits — no hand-rolled accounting, no cost, no budget enforcement. This delivers the tokens/time/steps observability half of #127.

usage_scope(name) opens one SDK trace (a minted trace_id) so a run's N+1 Runner.run calls — a paper summary's fan-out researchers plus the reducer, plus any structured-output fallback retry — nest into a single tree; on exit it reads and evicts that trace's spans into a frozen RunUsage:

from quantmind.utils.usage import usage_scope

with usage_scope("quantmind.paper") as run:
    tree = await PaperFlow(cfg).build(input)

print(run.usage.total_tokens, run.usage.requests, run.usage.wall_seconds)
for step in run.usage.steps:
    print(step.label, step.model, step.total_tokens, step.duration_seconds)

RunUsage carries input/output/total_tokens, requests (the llm-steps count), wall_seconds (end-to-end latency) versus busy_seconds (sum of per-step durations — the gap shows how much the fan-out actually overlapped, the signal for tuning concurrency), and a per-step UsageStep list (label, model, tokens, ISO timestamps, and span ids for a waterfall).

Design decisions: a process-global SpanCollector is registered additively via add_trace_processor (it never replaces the SDK's processors and never touches the default backend exporter — whether spans also reach an external dashboard stays the caller's own global tracing config) and buckets spans by trace_id, so concurrent scopes and batch_run fan-out stay isolated. Aggregation counts only leaf generation/response spans (skipping task/turn aggregate spans to avoid double-counting), resolves each step's label from its nearest agent span, and tolerates both usage-dict shapes (input/output and prompt/completion) plus response.usage. Cost, pricing, and budget enforcement are intentionally out of scope. The full rationale lives in contexts/design/utils/usage.md.

This PR also bundles a small, orthogonal docs-convention change that writing the design context motivated: contexts pages no longer hard-wrap prose at a fixed width (fixed-width wrapping is for code, not prose), matching the existing no-hard-wrap rule for GitHub bodies. The rule is flipped in write-contexts.md (both skill mirrors) and github-writing.md, and the existing hard-wrapped contexts pages are reflowed to one paragraph or list item per line — line breaks only, no prose added, removed, or changed (verified by whitespace-normalized comparison). The three commits are cleanly separable for commit-by-commit review, and I am happy to split the convention change into its own PR if you prefer.

Related Issue

Part of #127 (surface token usage and cost for runs and batch_run) — this PR delivers the tokens/time/steps observability; cost and budget are deliberately left out. Also part of #71 (Agents SDK migration).

Verification

• bash scripts/verify.sh — green: ruff format --check, ruff check, basedpyright, lint-imports, and pytest --cov (405 passed, 85.66% total coverage; quantmind/utils/usage.py at 95%).
• End-to-end wiring exercised with real Agents SDK spans (real trace() plus agent_span/generation_span flowing through add_trace_processor → SpanCollector → aggregation): three steps, correct labels and models, correct token sums, and wall-versus-busy timing.
• No live-network smoke test applies: the helper reads local traces and makes no network call of its own.

Checklist

• The title uses English Conventional Commit format: type(scope): summary.
• The related issue or design discussion is linked when applicable.
• bash scripts/verify.sh passes.
• Every applicable live-network component smoke test passes, or this PR states why none applies.
• Public behavior has focused tests, an example, and documentation where applicable.
• The PR is complete, small, and contains no unrelated changes. (Bundles an orthogonal contexts-wrapping convention change; can be split on request.)

[wanghaoxue0]

all good!

[wanghaoxue0]

all good!