feat(router): add max_output_tokens condition to ModelRoute - #3898

Description

ModelRoute could bound the estimated input size (max_input_tokens) but had no condition on the request's own max_tokens. That meant a tiny prompt asking for a long answer (for example, max_tokens: 4000) still matched a "trivial turn" downshift rule and was sent to the cheaper model.

This PR adds max_output_tokens, using the shape proposed in the issue. A rule with it set matches only when the request's max_tokens is <= N. As with the other conditions, None means "ignore this condition", set conditions AND together, and the first matching rule wins.

Open question from the issue, decided here: a request with no max_tokens, or with a non-integer or boolean value, does not match. An unbounded response is not a trivial turn, so the rule can never widen to cover unbounded requests. This follows the same fail-closed approach as the existing parser.

Closes #2765

Type of Change

• Bug fix (non-breaking change that fixes an issue)
• New feature (non-breaking change that adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• Documentation update
• Performance improvement
• Code refactoring (no functional changes)

Changes Made

• headroom/proxy/model_router.py: new ModelRoute.max_output_tokens field. matches() and ModelRouter.select() take an optional max_tokens keyword, which defaults to None, so existing callers are unchanged. max_tokens is added to the decision reason. max_output_tokens is added to the allowed route keys and parsed with the existing _strict_opt_int, so a malformed, boolean or negative value skips the route. New request_max_tokens(body) helper.
• headroom/proxy/handlers/anthropic.py: _maybe_route_model passes request_max_tokens(body) to the router.
• docs/content/docs/configuration.mdx: new field in the rule table, plus a note on combining it with max_input_tokens.
• Tests for matching, absent budget, select and reason, env parsing (valid and malformed), the helper, and handler wiring.

Testing

• Unit tests pass (pytest)
• Linting passes (ruff check .)
• Type checking passes (mypy headroom): not run successfully. My local mypy stops on an unrelated numpy stub syntax error in this env
• New tests added for new functionality
• Manual testing performed

Test Output

$ pytest tests/test_proxy/test_model_router.py tests/test_proxy/test_model_router_wiring.py -q
54 passed, 1 warning in 5.22s

$ pytest tests/test_proxy -q -k "anthropic or router"
119 passed, 237 deselected, 1 warning in 14.41s

$ ruff check headroom/proxy/model_router.py headroom/proxy/handlers/anthropic.py tests/test_proxy/test_model_router*.py
All checks passed!

Real Behavior Proof

• Environment: macOS, Python 3.12, branch head
• Exact command / steps: the rule from the issue (from_models: [claude-opus-4-8], max_input_tokens: 4096, max_output_tokens: 512, require_no_tools, to_model: claude-haiku-4-5) built via ModelRouterConfig.from_env. I then ran select() for the issue's "Reply with the single word OK." prompt with three different max_tokens values.
• Observed result: max_tokens=4000 stays on claude-opus-4-8, max_tokens=256 routes to claude-haiku-4-5, and a request with no max_tokens stays on claude-opus-4-8:

  max_tokens=4000: routed_model=claude-opus-4-8 reason=no rule matched
  max_tokens=256:  routed_model=claude-haiku-4-5 reason=matched rule 'trivial-opus->haiku': claude-opus-4-8 -> claude-haiku-4-5 (input_tokens=7, has_tools=False, max_tokens=256)
  max_tokens=None: routed_model=claude-opus-4-8 reason=no rule matched
  

• Not tested: an end-to-end request through a running proxy against a live upstream.

Runtime Rollout Safety

• Rollout-managed feature(s): none. This only extends the opt-in model router (HEADROOM_MODEL_ROUTER_ENABLED).
• Minimum rollout channel: N/A
• Stable/default behavior changed: No. The router is still off by default, and rules without max_output_tokens behave exactly as before.
• Kill switch / disable path: unset HEADROOM_MODEL_ROUTER_ENABLED, or remove the field from the rule.
• Unsafe override required: No
• Qualification impact: None
• Rollback path: revert this PR

Review Readiness

• I have performed a self-review
• This PR is ready for human review

Checklist

• My code follows the project's style guidelines
• I have performed a self-review of my code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes
• I did not edit CHANGELOG.md

Additional Notes

Routing still only applies on the Anthropic /v1/messages path, where max_tokens is required. If routing is later extended to the OpenAI paths (#2354), request_max_tokens is the single place to add max_completion_tokens / max_output_tokens.