feat: per-provider max_tokens via custom_providers models.<model>.max_tokens

[pty819]

Summary

Adds per-provider max_tokens support to custom_providers, mirroring the existing context_length pattern. This allows users to set a provider-scoped output-token cap without affecting fallback providers.

Problem

model.max_tokens in config.yaml is global — it applies to all providers including fallbacks. There is no way to scope max_tokens to a specific provider, unlike context_length which already supports per-provider overrides.

Changes

hermes_cli/config.py

• Adds get_custom_provider_max_tokens() — mirrors get_custom_provider_context_length() exactly. Matches by base_url + model name, returns models.<model>.max_tokens if present and valid.
• Adds "max_tokens" to _KNOWN_KEYS in _normalize_custom_provider_entry so the top-level key is not flagged as unknown (defensive, for users who had it at top level).

agent/agent_init.py

• After the global model.max_tokens fallback (and before context_length resolution), adds a second fallback that checks custom_providers for a per-provider max_tokens when agent.max_tokens is still None.

Usage

custom_providers:
  - name: My Provider
    base_url: https://example.com/v1
    api_key: ...
    model: my-model
    api_mode: chat_completions
    models:
      my-model:
        context_length: 1000000
        max_tokens: 131072       # ← new per-provider field

Related

Closes #28782

[teknium1]

Thanks for the focused patch. The underlying gap still exists on current main for custom_providers[].models.<model>.max_tokens, but this implementation needs rework before it is safe to salvage.

Problems

• The patch resolves the nested cap only during agent initialization. Current main sends agent.max_tokens on later requests (agent/chat_completion_helpers.py:650, :750, :782), while fallback activation and model switching change provider/model without recomputing that cap (agent/chat_completion_helpers.py:1045, agent/agent_runtime_helpers.py:1446). That can leak the primary custom provider's cap onto fallbacks, which is the behavior this PR is trying to avoid.
• The new assignment is placed after the init path records _session_init_model_config["max_tokens"]; on current main the analogous write is agent/agent_init.py:1343, so the session metadata would not reflect the effective cap.
• There is no regression coverage. Current main only tests the adjacent top-level provider cap path in tests/gateway/test_max_tokens_propagation.py:77.

Suggested changes

• Move the lookup into a shared resolution helper used by startup, /model switch, and fallback activation.
• Keep current precedence: explicit/env override > global model.max_tokens > provider/model-specific cap > None.
• Add targeted tests for nested per-model config, invalid values, global override precedence, and fallback/switch non-leakage.

Automated hermes-sweeper review.

[teknium1]

Resolving this only during init makes agent.max_tokens a sticky session-wide value; fallback activation and /model switching later change provider/model without recomputing this cap, so the primary provider's cap can still leak onto fallback providers.

[teknium1]

Because _session_init_model_config["max_tokens"] was written just above this block, the session metadata will still record None when this nested provider cap is applied. Either resolve before recording the metadata or update the metadata after assigning agent.max_tokens.

[teknium1]

This helper mirrors context_length lookup, but max_tokens has a stronger non-leakage requirement across fallback/switch paths. It should probably be part of a shared max_tokens resolution path rather than only called from startup.

[teknium1]

Thanks for the focused configuration work. This automated hermes-sweeper review is closing it under the standing policy against new user-facing max_tokens configuration knobs.

• The proposed custom_providers[].models.<model>.max_tokens is a new per-model output-cap setting, which matches the max-tokens-knob policy.
• Current main already supports the narrower provider-wide alternative: hermes_cli/runtime_provider.py:592 accepts custom_providers[].max_output_tokens or max_tokens, and gateway/run.py:1875 applies it only when global model.max_tokens is unset.
• That provider-level path shipped in 14275d7baa1a48844e58671f63ab49c4823c7cc0 (fix(gateway): honor per-provider max_output_tokens in max_tokens chain).

For provider-wide caps, please use the existing max_output_tokens configuration rather than adding another max-token configuration surface.

---

Closed as not-planned per standing maintainer policy (max-tokens-knob). This is a design-direction decision, not a code-quality judgment — see the Contribution Rubric in AGENTS.md for what the project is looking for. If you believe this policy was misapplied to your change, comment here and a maintainer will take a look.