feat(widget): context-usage meter backed by the agent manager

[AmitAvital1]

Stack 1/3 · base: main

Adds a token-budget meter (assistant-ui ContextDisplay shape) to the widget. All computation is on the backend — the agent manager exposes GET /conversations/{id}/usage returning used/max tokens, percent, and a BudgetSeverity (normal/warning/critical) as the single source of truth. The FE only renders; it does no token math. Severity is a StrEnum reused across domain + schema so thresholds live in one place.

The number is the conversation's cumulative token spend (every turn's input + output, summed) measured against context_max_tokens — the budget the service actually enforces with a 429. It is deliberately not a context-window gauge, and the naming says so throughout (review feedback, e4705b0).

Verified: make lint + mypy clean, 472 tests pass, widget typecheck + Playwright e2e green.

🤖 Generated with Claude Code

[Asaf-prog]

PR #58

The implementation is clean, but I think the current naming is misleading.

The backend calculates usage by summing input_tokens + output_tokens across the entire conversation. That represents cumulative token consumption, not the size of the context currently being sent to the model. Since previous messages may be included again in later inputs, the same content can effectively be counted multiple times.

We should either:

1. Rename this to something like Conversation token budget, or
2. Calculate the tokens in the current bounded context and compare them against the model’s context-window limit.

I would prefer resolving this before merging, because the UI currently presents the value as Context usage, which gives the user a different meaning from what is actually calculated.

Also, should the critical threshold use >= 85 rather than > 85?

[AmitAvital1]

Good catch — agreed, and fixed in e4705b0.

You're right about what the number is: it's the cumulative sum of every turn's input_tokens + output_tokens, so history that gets re-sent is counted again each turn. Calling it "context usage" told the user something it doesn't mean.

I went with option 1 (rename) rather than option 2, because the cumulative figure is the one the backend actually enforces — prepare_turn refuses a turn with ConversationTokenBudgetExceeded → 429 once the sum passes context_max_tokens. Measuring the current bounded context against the model's window would show a number nothing acts on, and would leave the real wall invisible. So the meter now names the wall it's warning about:

• ContextUsage → TokenBudgetUsage, ContextSeverity → BudgetSeverity, ContextUsageResponse → TokenBudgetResponse, ContextMeter → BudgetMeter, context-* CSS → budget-*
• popover reads Token budget, aria-label reads "Token budget N% used"
• the domain object carries a docstring saying explicitly that this is cumulative, not the context window, and why
• CONTEXT_MAX_TOKENS in the starter .env.example is now documented the same way (kept the env var and the GET .../usage route names — both pre-existing API)

And yes on the threshold: warning was >= 65 while critical was > 85. Both are inclusive now, with the boundary pinned:

assert TokenBudgetUsage.from_totals(849, 1000).severity == "warning"
assert TokenBudgetUsage.from_totals(850, 1000).severity == "critical"

Also rebased onto main (#57 has merged) and set this PR's base to main, so the stack is in order again.

make lint + mypy clean, 472 tests pass, widget typecheck + 17 Playwright e2e green.