Summary

A single match-based router for per-turn model/provider selection based on a caller-supplied context. Replaces two previously-separate ideas (per-platform and per-source-identity overrides) with one generic hook.

Example config:

model:
  default: my-fast-model
  routes:
    - match: { source_kind: owner }         # owner everywhere
      model: my-strong-model
      api_key: sk-owner
    - match: { platform: hub }              # all Hub peers
      model: my-fast-model
    - match: { source_kind: cron }
      model: my-fast-model
    - match: { platform: discord, source_kind: stranger }   # compound
      model: some-other

First match wins. No match → base model: block used. Partial overrides are supported (missing fields inherit base). Empty fields ("", None, []) do not overwrite — explicit empty is treated as "no opinion" so base values survive.

Backwards compatibility

Two shorthand forms are honored via an internal normalizer that synthesizes routes entries at match time:

Explicit routes always evaluate first, so any existing model.platforms.* config keeps working unchanged; a new routes: entry can be added alongside and will take precedence.

Why unified

Routing by platform and routing by source identity are orthogonal — same function, different predicates. Shipping them as separate hooks (each with its own config key and function call) means _resolve_session_agent_runtime grows a new layer every time a new predicate is added, and the config surface grows with it. One matcher with a structured predicate is cleaner, and lets users compose (platform + source_kind) without any code change.

Why source_kind matters on top of platform

Per-platform alone can't distinguish the operator from a random stranger on Telegram; per-source alone can't distinguish Hub from Telegram. Both axes together cover the common needs:

• "Owner on any channel gets the strong model."
• "Agent-to-agent Hub traffic uses the cheap model."
• "Strangers on Discord get isolated to a compliance-friendly provider."

How it works

• New agent.smart_model_routing.apply_route(model, runtime_kwargs, model_config, context) — pure helper. Normalizes legacy shorthand, iterates routes, returns (model, runtime_kwargs).
• New GatewayRuntime._classify_source_kind(source) — classifies owner (home-channel DM match), hub_peer (platform value \"hub\" — forward-compatible with any enum definition), stranger (everything else).
• New GatewayRuntime._build_routing_context(source) — assembles {platform, source_kind}.
• Hook point: _resolve_session_agent_runtime calls apply_route as the final layer, below session /model overrides and above base config. Silent fallback on exception — never blocks a turn.
• Cron scheduler and HermesCLI apply apply_route with their own hardcoded context ({platform: cron, source_kind: cron} / {platform: cli, source_kind: owner}) before resolve_turn_route.

The existing message-text-based router (resolve_turn_route / smart_model_routing.cheap_model) is untouched — it's a peer hook on a different axis. AIAgent construction signature, session keys, agent caching, and sub-agent inheritance are all unchanged.

Tests

14 new unit tests for apply_route:

• empty context, no routes, null config (all no-op)
• platform-only match, source_kind-only match, compound match
• first-match-wins ordering
• partial overrides (base fields preserved)
• empty fields don't overwrite
• missing context key → no match
• legacy platforms shim (string shorthand + dict)
• legacy by_source shim
• explicit routes beat legacy shims on the same predicate

All 6 existing smart_model_routing tests still pass. 20/20 green.

Test plan

• Unit: 20/20 pass (pytest tests/agent/test_smart_model_routing.py)
• Live: verified end-to-end on a test VM — CLI turn with a matching routes entry swaps both model and base_url in the outbound API request; default model path unchanged for unmatched auxiliary calls.
• Parse-check on all modified files.

🤖 Generated with Claude Code