Generic HTTP usageLimitSources kind for gateway / proxy spending budgets

[ZaBug]

Problem

Many teams run Claude Code (and other agents) through an internal LLM gateway (LiteLLM Proxy, a corporate API platform, etc.) via ANTHROPIC_BASE_URL. The real limit for those users is a monthly spending budget enforced by the gateway, not a provider subscription window.

Today in T3 Code:

• Usage → Limits reads limits from the provider (Claude get_usage, Codex, …). Behind a gateway, nothing reports the budget that actually applies.
• Usage shows an "API estimate" priced from LiteLLM's public table. That's useful, but it isn't the gateway's figure, and users can't tell whether it matches what they're billed.

As a result, gateway users keep a separate terminal script or status line running just to see "$42 of $1000 used, resets Nov 1".

Proposal

Add a second UsageLimitSourceConfig kind next to cliproxy. UsageLimitSourceSnapshot.kind already anticipates more kinds. The new kind is a generic HTTP JSON source with field mapping, so T3 doesn't need per-gateway integrations:

"usageLimitSources": {
  "team-gateway": {
    "kind": "http",
    "label": "Team LLM gateway",
    "url": "https://gateway.example.com/user/info?user_id=jdoe",
    "authHeader": "Bearer …",            // stored in the secret store, redacted like managementKey
    "pollIntervalSecs": 300,
    "fields": {                           // dot paths into the JSON response
      "used":      "spend",
      "limit":     "budget_table.max_budget",
      "softLimit": "budget_table.soft_budget",   // optional
      "resetsAt":  "budget_table.budget_reset_at" // optional, ISO date
    },
    "currency": "USD",
    "windowKind": "monthly"               // session | weekly | monthly | other
  }
}

Example response from a LiteLLM-style gateway that this config maps:

{
  "spend": 42.5,
  "budget_table": {
    "soft_budget": 800.0,
    "max_budget": 1000.0,
    "budget_duration": "1mo",
    "budget_reset_at": "2026-11-01T00:00:00Z"
  }
}

The source publishes one window (usedPercent = used / limit, plus amounts and resetsAt). It goes through the existing pipeline: secret storage, poll interval, Refresh button, error state when the probe fails. Amounts would follow the shape #14911 introduces for Claude Enterprise monthly_spend, so both render the same way.

Configured from the UI

The JSON above is only how the source is stored. Users set it up entirely in Settings → Providers → usage hubs, by extending the existing AddUsageLimitSourceDialog:

Add usage source
  Type            ( ) CLIProxyAPI hub   (•) HTTP endpoint
  Label           [ Team LLM gateway                       ]
  URL             [ https://gateway.example.com/user/info  ]
  Auth header     [ ••••••••••••  ]   (sent once, kept in the secret store)
  ── Field mapping ─────────────────────────────────────────
  Used            [ spend                     ]
  Limit           [ budget_table.max_budget   ]
  Soft limit      [ budget_table.soft_budget  ]  optional
  Resets at       [ budget_table.budget_reset_at ] optional
  Window          [ Monthly ▾ ]   Currency [ USD ]
  [ Test ]  →  ✓ $42.50 of $1000.00 (4%) · soft $800 · resets Nov 1
                                            [ Cancel ] [ Save ]

Test runs the request once on the server and shows the parsed values, or the exact path that failed (for example budget_table.max_budget not found), before anything is saved. Existing rows keep the current edit, disable and remove actions.

Where it shows

• Usage → Limits: a card for the source, like CLIProxyAPI accounts today.
• Context Window popover and composer: a compact "Monthly budget $42 / $1000" line. Details are in Show the current thread's cost in the Context Window popover (follow-up to #9136 after V2) #15043.

Why generic, not per-gateway

PR #10904 (OpenRouter balance as its own kind) was closed pending scope approval. A single mapped HTTP kind covers OpenRouter, LiteLLM, Portkey and in-house gateways without adding a new integration for each.

Open questions for maintainers

1. Should the auth header be a stored secret only, or may it reference an env var the provider already has (for example reusing ANTHROPIC_AUTH_TOKEN)?
2. Should there be one source per window, or a windows: [...] array of mappings in a single source?
3. Do you want to show the soft limit as a marker on the bar, or leave it out?

---

Related: #15043 (per-thread cost in the Context Window popover).

[ZaBug]

I built a working prototype of this on my fork to check the shape before asking for approval. Screenshots use a local mock gateway with dummy data.

Settings → Providers → Add source → HTTP endpoint. Field paths default to LiteLLM's /user/info; Test runs the request once on the server and shows the parsed values before anything is saved:

Usage → Limits shows the source like a CLIProxyAPI account, using the amount shape from #14911:

Context Window popover gets a compact budget line (the thread-cost part is tracked in #13073):

One compatibility note: today an undecodable usageLimitSources entry fails the whole settings.json decode, so an older build that sees an http source falls back to default settings. A PR would make that record tolerant of unknown kinds.

Would you approve this direction? If yes, I'll open a PR with only the budget-source commits. The open questions above still stand, especially whether the auth header should be a stored secret only.

[domondi1]

+1 to the generic http kind. One data point from a different gateway shape, since the field-path design is meant to cover more than LiteLLM's /user/info:

Not every gateway returns one object per user. Inferrail (the gateway I maintain, open source) holds budgets per run, per project or globally, and its spend endpoint returns a list, one entry per budget, with money as decimal strings:

GET /v1/local/budgets/spend
Authorization: Bearer <local api token>

[
  {"budget_id": "project:jdoe:monthly", "limit_usd": "1000", "spent_usd": "42.500000", "has_unpriced_usage": false},
  {"budget_id": "work_id:fix-loop-17:per_work", "limit_usd": "25", "spent_usd": "3.120000", "has_unpriced_usage": false}
]

Two small additions would make the proposed config map that without a per-gateway adapter:

1. A selector for list responses, e.g. "select": {"budget_id": "project:jdoe:monthly"} (pick the first array element whose fields match) before the dot paths apply. Then "used": "spent_usd", "limit": "limit_usd" work as-is.
2. Accept numeric strings for used / limit. Decimal-as-string is common for money fields, precisely to avoid float rounding.

resetsAt being optional already covers gateways that don't report a reset time (this one doesn't), and has_unpriced_usage: true is worth surfacing if you ever add a "floor, not total" hint, since it means some usage had no known price.

On the Claude Code side, it routes through this gateway with ANTHROPIC_BASE_URL, and a per-session or per-loop budget can ride on ANTHROPIC_CUSTOM_HEADERS (since 0.4.14), so the same budget the gateway enforces would be the one T3 displays. Happy to test your fork against it if that's useful.