feat: subscription-aware routing (discount covered models by observed quota headroom)

[steventohme]

What

When a caller presents a subscription (ChatGPT/Codex or Claude Pro/Max), bias routing toward the models that subscription already pays for — priced by the actual remaining rate-limit headroom, not full catalog cost. Today the scorer prices every model at full catalog cost and the sub only changes billing after a model wins, so a pre-paid GPT turn still loses to cheap OSS on the cost axis (e.g. a real opencode turn scored deepseek-v4-pro 1.67 vs gpt-5.5 0.89 and routed to deepseek).

These quotas are perishable (reset every window), so unused headroom has zero salvage value: the marginal cost of a covered turn is ~0 while the window has slack and rises to full price only as it binds — use-it-or-lose-it / bid-price control. (Design doc: router-internal/docs/plans/SUBSCRIPTION_AWARE_ROUTING.md.)

How

• internal/proxy/usage (new, pure/inner-ring): parses the quota headroom both backends already report on every response — Codex x-codex-{primary,secondary}-* and Anthropic anthropic-ratelimit-unified-{5h,weekly}-* — into per-credential window state. CostFactor maps utilization u → ε + (1−ε)·u^γ: ~ε when the window has slack (covered model ~free), →1 (full catalog price, no subsidy) as it binds. The tighter of the two windows governs. In-memory, TTL-evicted, salted credential keys.
• providers: a context-carried UpstreamHeaderObserver (no Client-interface change); the anthropic + openai clients surface resp.Header after every upstream call (including 429s, where headroom matters most).
• proxy: records headroom keyed by the resolved subscription credential; pre-routing computes per-covered-model cost factors (Codex → conservative headline GPT set the backend bills; Claude → catalog Anthropic models) and sets them on router.Request.
• scorer: blendScoresV2 multiplies a covered model's cost term by its factor — so it rides the same per-cluster α/λ blend as the base cost.

Safety / rollout

• Off by default, behind ROUTER_SUBSCRIPTION_AWARE_ROUTING (+ _COST_EPSILON default 0.05, _COST_GAMMA default 2, _OBSERVATION_TTL default 10m). Feature-off path is byte-identical (no observer installed, no factors computed).
• Cold start = full price: no subsidy until the first response populates the observer for that credential — never a blind discount.
• ε > 0, not 0: a covered model never reads as strictly free (avoids dominating quality ties / burning quota early then throttling on hard later turns).

Testing

• usage: header parsing (both families), shadow-price monotonicity (slack→ε, binding→full price, tighter window governs), observer record/TTL/keying.
• scorer: no-op guard (factor 1.0 ≡ baseline decision + score).
• go build ./... + full go test ./... green.
• Validation gate before enabling the flag: offline screen on cost-weighted production traffic (share shift toward sub-covered models + quality delta), per ROUTER_MODEL_LIFECYCLE.

Follow-ups (documented, out of scope)

• Pace-aware shadow price using window reset time (this v1 uses utilization u^γ, which already encodes the perishability bias).
• Claude Code inbound-bearer observation (v1 keys on the dedicated X-Weave-*-Subscription headers — the opencode dual-sub path).

🤖 Generated with Claude Code

[greptile-apps]

Comments Outside Diff (1)

1. internal/proxy/subsidy.go, line 211-219 (link)

   claudeCoveredModels() iterates over catalog.Models and allocates a fresh []string on every call to subsidyFactors. When the Anthropic subscription path is active, this runs on every routed request in the hot path. The catalog is static after startup; this could be a package-level var (initialized once via an init or a sync.Once) to avoid the per-request allocation and loop.

   Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!

_{Reviews (1): Last reviewed commit: "feat(proxy): subscription-aware routing ..." | Re-trigger Greptile}

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit f4d5f7a. Configure here.}